code quality improvements

fswair · fswair · commit 1c0ac680e28d · 2026-05-08T22:48:24.000+03:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -33,7 +33,7 @@ jobs:
           enable-cache: true
 
       - name: Install Dependencies
-        run: uv sync --all-extras
+        run: uv sync --frozen --all-extras
 
       - name: Check Formatting
         run: uv run ruff format --check
@@ -65,9 +65,9 @@ jobs:
             local pyproject_path="$project_dir/pyproject.toml"
 
             if grep -Eq '^\[project\.optional-dependencies\]' "$pyproject_path"; then
-              uv sync --project "$project_dir" --all-extras
+              uv sync --project "$project_dir" --frozen --all-extras
             else
-              uv sync --project "$project_dir"
+              uv sync --project "$project_dir" --frozen
             fi
           }
 
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: read
+  id-token: write
 
 concurrency:
   group: publish-${{ github.workflow }}-${{ github.ref }}
@@ -17,8 +18,6 @@ jobs:
   publish:
     name: Build And Publish Workspace
     runs-on: ubuntu-latest
-    env:
-      UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
     steps:
       - name: Check Out Repository
         uses: actions/checkout@v6
@@ -35,7 +34,7 @@ jobs:
 
       - name: Validate Release
         run: |
-          uv sync --all-extras
+          uv sync --frozen --all-extras
           make prod
 
       - name: Build And Publish Root, Adapter, Helper, And Transport Projects
@@ -59,9 +58,9 @@ jobs:
             local pyproject_path="$project_dir/pyproject.toml"
 
             if grep -Eq '^\[project\.optional-dependencies\]' "$pyproject_path"; then
-              uv sync --project "$project_dir" --all-extras
+              uv sync --project "$project_dir" --frozen --all-extras
             else
-              uv sync --project "$project_dir"
+              uv sync --project "$project_dir" --frozen
             fi
           }
 
@@ -70,5 +69,5 @@ jobs:
             sync_project "$project_dir"
             rm -rf "$project_dir/dist"
             uv build --project "$project_dir" --out-dir "$project_dir/dist"
-            uv publish "$project_dir"/dist/*
+            uv publish --trusted-publishing always "$project_dir"/dist/*
           done < <(project_dirs)
diff --git a/COVERAGE b/COVERAGE
@@ -1,2 +1,2 @@
-Line coverage: 100.00% (8953 / 8953)
-Branch coverage: 100.00% (2996 / 2996)
+Line coverage: 100.00% (8999 / 8999)
+Branch coverage: 100.00% (3012 / 3012)
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 ACP Kit is the adapter toolkit and monorepo for exposing existing agent runtimes through ACP without inventing runtime features that are not really there.
 
-Today the repo ships two production-grade adapter families:
+Today the repo ships two maintained adapter families:
 
 - `pydantic-acp`
 - `langchain-acp`
@@ -444,6 +444,7 @@ Top-level docs:
 - [LangChain ACP Overview](https://vcoderun.github.io/acpkit/langchain-acp/)
 - [Helpers](https://vcoderun.github.io/acpkit/helpers/)
 - [acpremote Overview](https://vcoderun.github.io/acpkit/acpremote/)
+- [Security Guidance](https://vcoderun.github.io/acpkit/security/)
 - [AdapterConfig](https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config/)
 - [Plans, Thinking, and Approvals](https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/)
 - [Prompt Resources and Context](https://vcoderun.github.io/acpkit/pydantic-acp/prompt-resources/)
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.9.4
+0.9.5
diff --git a/docs/about/index.md b/docs/about/index.md
@@ -25,9 +25,9 @@ Today it ships:
 The repository currently contains two adapter packages, a root CLI package, and two helper packages:
 
 - `pydantic-acp`
-  production-grade ACP adapter for `pydantic_ai.Agent`
+  maintained ACP adapter for `pydantic_ai.Agent`
 - `langchain-acp`
-  production-grade ACP adapter for LangChain, LangGraph, and DeepAgents graphs
+  maintained ACP adapter for LangChain, LangGraph, and DeepAgents graphs
 - `acpkit`
   root CLI, target resolver, and launch helpers
 - `codex-auth-helper`
diff --git a/docs/index.md b/docs/index.md
@@ -8,7 +8,7 @@ title: ACP Kit
 
 ACP Kit is the adapter toolkit and monorepo for exposing existing agent runtimes through ACP without inventing runtime behavior the source framework does not actually own.
 
-Today the repo ships two production-grade adapter families:
+Today the repo ships two maintained adapter families:
 
 - [`pydantic-acp`](pydantic-acp.md) for `pydantic_ai.Agent`
 - [`langchain-acp`](langchain-acp.md) for LangChain, LangGraph, and DeepAgents graphs
@@ -34,7 +34,7 @@ Three ideas drive the SDK:
 
 | Package | Purpose | Start here |
 |---|---|---|
-| [`pydantic-acp`](pydantic-acp.md) | production-grade ACP adapter for `pydantic_ai.Agent` | If your runtime starts from a `pydantic_ai.Agent` |
+| [`pydantic-acp`](pydantic-acp.md) | maintained ACP adapter for `pydantic_ai.Agent` | If your runtime starts from a `pydantic_ai.Agent` |
 | [`langchain-acp`](langchain-acp.md) | graph-centric ACP adapter for LangChain, LangGraph, and DeepAgents | If your runtime already produces a compiled graph |
 | [`acpkit`](cli.md) | CLI target resolution, launch helpers, adapter dispatch | If you want `acpkit run ...` or `acpkit launch ...` |
 | [`helpers`](helpers.md) | supporting packages such as `codex-auth-helper` and `acpremote` | If you need transport or model-construction helpers around an adapter |
diff --git a/docs/langchain-acp/session-state.md b/docs/langchain-acp/session-state.md
@@ -34,6 +34,10 @@ Stored session state includes:
 - session-local mode id
 - config values
 - plan state
+
+`FileSessionStore` persists those values as local JSON files. File-backed session ids are restricted
+to ASCII letters, digits, `_`, and `-`, with a 128-character limit, so a client-supplied session id
+cannot escape the configured store root.
 - MCP server definitions
 - transcript updates
 - metadata
diff --git a/docs/pydantic-acp.md b/docs/pydantic-acp.md
@@ -1,6 +1,6 @@
 # Pydantic ACP Overview
 
-`pydantic-acp` is the production ACP adapter in ACP Kit.
+`pydantic-acp` is the primary Pydantic AI adapter in ACP Kit.
 
 Its job is simple: keep your existing `pydantic_ai.Agent` surface intact, then expose it as an ACP server without inventing runtime state the underlying agent cannot actually honor.
 
diff --git a/docs/pydantic-acp/session-state.md b/docs/pydantic-acp/session-state.md
@@ -70,6 +70,7 @@ This is the recommended default for local tools and editor integrations.
 Current behavior:
 
 - writes use a temp file, `fsync`, and atomic replace
+- session ids are restricted to ASCII letters, digits, `_`, and `-`, with a 128-character limit
 - the store takes a process-local lock and a filesystem advisory lock when available
 - malformed or partially-written session files are skipped by public load/list flows instead of crashing the whole operation
 - stale temp files from interrupted writes are cleaned up on startup
diff --git a/docs/security.md b/docs/security.md
@@ -0,0 +1,56 @@
+# Security Guidance
+
+ACP Kit exposes existing agent runtimes. The adapter should stay honest about what the underlying
+runtime can enforce, and deployment code should treat host files, credentials, and remote command
+execution as privileged surfaces.
+
+## File Session Stores
+
+`FileSessionStore` is a local durable store, not a distributed database or a multi-host
+coordination layer.
+
+Use it when an editor, CLI, or local service needs sessions to survive process restarts. Do not
+share the same store root between unrelated users or untrusted processes.
+
+File-backed session ids are validated before they become filenames:
+
+- allowed characters are ASCII letters, digits, `_`, and `-`
+- the maximum length is 128 characters
+- path separators, dots, whitespace, and shell metacharacters are rejected
+- malformed JSON files are skipped by load/list flows instead of crashing the adapter
+
+Store roots should live in a directory owned by the service user. If session content can include
+sensitive prompts, tool results, or workspace paths, apply normal host-level file permissions and
+backup policies.
+
+## Codex Auth State
+
+`codex-auth-helper` reads and refreshes local Codex credentials. Treat its auth state file like a
+credential store.
+
+Current writes use a private temp file, `fsync`, atomic replace, and `0600` permissions on POSIX
+systems. Operators should still keep the parent directory private and avoid copying auth state into
+logs, examples, test fixtures, or container images.
+
+## acpremote
+
+`acpremote` is transport infrastructure. It can expose an existing ACP agent or a stdio command over
+WebSocket, so deployment policy matters.
+
+Recommended defaults:
+
+- bind to loopback unless a reverse proxy owns TLS and authentication
+- allowlist command-backed servers instead of accepting arbitrary command strings
+- keep environment overrides minimal and avoid forwarding secrets that the child process does not need
+- configure command termination timeouts for command-backed transports
+- monitor long-running remote sessions and close idle connections at the hosting layer
+
+Command-backed transports terminate the child process when the WebSocket flow ends and fall back to
+`kill` after the configured timeout. This prevents normal disconnect cleanup from waiting forever on
+a process that ignores termination.
+
+## Release Workflow
+
+Project CI and publish workflows should install from `uv.lock` with `uv sync --frozen`. Package
+publishing should use PyPI trusted publishing rather than long-lived API tokens whenever the target
+PyPI project is configured for it.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -118,6 +118,7 @@ nav:
       - Compatibility Matrix Template: compatibility-matrix-template.md
       - Projection Cookbook: projection-cookbook.md
       - Integration Readiness: integration-readiness.md
+      - Security Guidance: security.md
   - Examples:
       - Overview: examples/index.md
       - Finance Agent: examples/finance.md
diff --git a/packages/adapters/langchain-acp/VERSION b/packages/adapters/langchain-acp/VERSION
@@ -1 +1 @@
-0.9.4
+0.9.5
diff --git a/packages/adapters/langchain-acp/src/langchain_acp/_version.py b/packages/adapters/langchain-acp/src/langchain_acp/_version.py
@@ -2,4 +2,4 @@
 
 __all__ = ("__version__",)
 
-__version__ = "0.9.4"
+__version__ = "0.9.5"
diff --git a/packages/adapters/langchain-acp/src/langchain_acp/session/store.py b/packages/adapters/langchain-acp/src/langchain_acp/session/store.py
@@ -22,6 +22,10 @@
 
 __all__ = ("FileSessionStore", "MemorySessionStore", "SessionStore")
 
+_MAX_SESSION_ID_LENGTH = 128
+_SESSION_ID_SAFE_CHARS = frozenset(
+    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"
+)
 _STORE_LOCKS: dict[str, threading.RLock] = {}
 _STORE_LOCKS_GUARD = threading.Lock()
 
@@ -79,6 +83,7 @@ class FileSessionStore:
     _lock_path: Path = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
+        self.root = self.root.expanduser().resolve()
         self.root.mkdir(parents=True, exist_ok=True)
         self._process_lock = _store_lock(self.root)
         self._lock_path = self.root / ".acpkit-session-store.lock"
@@ -111,6 +116,10 @@ def list_sessions(self) -> list[AcpSessionContext]:
         with self._locked():
             sessions: list[AcpSessionContext] = []
             for path in sorted(self.root.glob("*.json")):
+                try:
+                    _validate_session_id(path.stem)
+                except ValueError:
+                    continue
                 session = self._load_session_unlocked(path.stem)
                 if session is not None:
                     sessions.append(session)
@@ -182,10 +191,12 @@ def _parse_datetime(self, value: str) -> datetime:
         return datetime.fromisoformat(value)
 
     def _session_path(self, session_id: str) -> Path:
-        return self.root / f"{session_id}.json"
+        safe_session_id = _validate_session_id(session_id)
+        return _store_child_path(self.root, f"{safe_session_id}.json")
 
     def _temp_session_path(self, session_id: str) -> Path:
-        return self.root / f".acpkit-session-{session_id}-{uuid4().hex}.tmp"
+        safe_session_id = _validate_session_id(session_id)
+        return _store_child_path(self.root, f".acpkit-session-{safe_session_id}-{uuid4().hex}.tmp")
 
     def _cleanup_stale_temp_files(self) -> None:
         for path in self.root.glob(".acpkit-session-*.tmp"):
@@ -246,3 +257,21 @@ def _store_lock(root: Path) -> threading.RLock:
             lock = threading.RLock()
             _STORE_LOCKS[key] = lock
         return lock
+
+
+def _validate_session_id(session_id: str) -> str:
+    if not session_id:
+        raise ValueError("session_id must not be empty")
+    if len(session_id) > _MAX_SESSION_ID_LENGTH:
+        raise ValueError(f"session_id must be at most {_MAX_SESSION_ID_LENGTH} characters")
+    if any(char not in _SESSION_ID_SAFE_CHARS for char in session_id):
+        raise ValueError("session_id may only contain ASCII letters, digits, '_' and '-'")
+    return session_id
+
+
+def _store_child_path(root: Path, filename: str) -> Path:
+    resolved_root = root.resolve()
+    path = (resolved_root / filename).resolve()
+    if path.parent != resolved_root:
+        raise ValueError("session path must stay inside FileSessionStore root")
+    return path
diff --git a/packages/adapters/pydantic-acp/VERSION b/packages/adapters/pydantic-acp/VERSION
@@ -1 +1 @@
-0.9.4
+0.9.5
diff --git a/packages/adapters/pydantic-acp/src/pydantic_acp/_version.py b/packages/adapters/pydantic-acp/src/pydantic_acp/_version.py
@@ -2,4 +2,4 @@
 
 __all__ = ("__version__",)
 
-__version__ = "0.9.4"
+__version__ = "0.9.5"
diff --git a/packages/adapters/pydantic-acp/src/pydantic_acp/session/store.py b/packages/adapters/pydantic-acp/src/pydantic_acp/session/store.py
@@ -22,6 +22,10 @@
 
 __all__ = ("FileSessionStore", "MemorySessionStore", "SessionStore")
 
+_MAX_SESSION_ID_LENGTH = 128
+_SESSION_ID_SAFE_CHARS = frozenset(
+    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"
+)
 _STORE_LOCKS: dict[str, threading.RLock] = {}
 _STORE_LOCKS_GUARD = threading.Lock()
 
@@ -79,6 +83,7 @@ class FileSessionStore:
     _lock_path: Path = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
+        self.root = self.root.expanduser().resolve()
         self.root.mkdir(parents=True, exist_ok=True)
         self._process_lock = _store_lock(self.root)
         self._lock_path = self.root / ".acpkit-session-store.lock"
@@ -111,6 +116,10 @@ def list_sessions(self) -> list[AcpSessionContext]:
         with self._locked():
             sessions: list[AcpSessionContext] = []
             for path in sorted(self.root.glob("*.json")):
+                try:
+                    _validate_session_id(path.stem)
+                except ValueError:
+                    continue
                 session = self._load_session_unlocked(path.stem)
                 if session is not None:
                     sessions.append(session)
@@ -182,10 +191,12 @@ def _parse_datetime(self, value: str) -> datetime:
         return datetime.fromisoformat(value)
 
     def _session_path(self, session_id: str) -> Path:
-        return self.root / f"{session_id}.json"
+        safe_session_id = _validate_session_id(session_id)
+        return _store_child_path(self.root, f"{safe_session_id}.json")
 
     def _temp_session_path(self, session_id: str) -> Path:
-        return self.root / f".acpkit-session-{session_id}-{uuid4().hex}.tmp"
+        safe_session_id = _validate_session_id(session_id)
+        return _store_child_path(self.root, f".acpkit-session-{safe_session_id}-{uuid4().hex}.tmp")
 
     def _cleanup_stale_temp_files(self) -> None:
         for path in self.root.glob(".acpkit-session-*.tmp"):
@@ -246,3 +257,21 @@ def _store_lock(root: Path) -> threading.RLock:
             lock = threading.RLock()
             _STORE_LOCKS[key] = lock
         return lock
+
+
+def _validate_session_id(session_id: str) -> str:
+    if not session_id:
+        raise ValueError("session_id must not be empty")
+    if len(session_id) > _MAX_SESSION_ID_LENGTH:
+        raise ValueError(f"session_id must be at most {_MAX_SESSION_ID_LENGTH} characters")
+    if any(char not in _SESSION_ID_SAFE_CHARS for char in session_id):
+        raise ValueError("session_id may only contain ASCII letters, digits, '_' and '-'")
+    return session_id
+
+
+def _store_child_path(root: Path, filename: str) -> Path:
+    resolved_root = root.resolve()
+    path = (resolved_root / filename).resolve()
+    if path.parent != resolved_root:
+        raise ValueError("session path must stay inside FileSessionStore root")
+    return path
diff --git a/packages/helpers/codex-auth-helper/VERSION b/packages/helpers/codex-auth-helper/VERSION
@@ -1 +1 @@
-0.9.4
+0.9.5
diff --git a/packages/helpers/codex-auth-helper/src/codex_auth_helper/_version.py b/packages/helpers/codex-auth-helper/src/codex_auth_helper/_version.py
@@ -2,4 +2,4 @@
 
 __all__ = ("__version__",)
 
-__version__ = "0.9.4"
+__version__ = "0.9.5"
diff --git a/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py b/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py
diff --git a/packages/transports/acpremote/VERSION b/packages/transports/acpremote/VERSION
diff --git a/packages/transports/acpremote/src/acpremote/_version.py b/packages/transports/acpremote/src/acpremote/_version.py
diff --git a/packages/transports/acpremote/src/acpremote/command.py b/packages/transports/acpremote/src/acpremote/command.py
diff --git a/src/acpkit/_version.py b/src/acpkit/_version.py
diff --git a/tests/acpremote/test_helpers.py b/tests/acpremote/test_helpers.py
diff --git a/tests/codex_auth_helper/test_auth.py b/tests/codex_auth_helper/test_auth.py
diff --git a/tests/langchain/test_low_level_helpers.py b/tests/langchain/test_low_level_helpers.py
diff --git a/tests/pydantic/test_low_level_helpers.py b/tests/pydantic/test_low_level_helpers.py
