Arthur/acp client provider v2 20260701

.agents/skills/codex-auth-helper/examples/codex_chat_openai_graph.py

@@ -11,7 +11,6 @@
 
 def describe_codex_surface() -> str:
     """Describe the LangChain-facing Codex helper seam."""
-
     return (
         "This graph uses codex-auth-helper to build a LangChain ChatOpenAI model "
         "backed by the local Codex login."

.gitignore

@@ -94,6 +94,8 @@ scripts/check_releases.py
 # Scripts
 connect*.py
 expose*.py
+probe*.py
+pydantic_test*.py
 CHANGELOG
 .acprouter-state
 .deepagents-graph

CHANGELOG.md

@@ -3,6 +3,26 @@
 ACP Kit uses synchronized versions for `acpkit`, `pydantic-acp`, `langchain-acp`,
 `codex-auth-helper`, and `acpremote`.
 
+## [1.1.0] - 2026-07-07
+
+### Added
+
+- Pydantic AI v2 ACP client provider bridge (`AcpProvider`, `AcpModel`,
+  `AcpHostBridge`) in `pydantic-acp`, enabling ACP agents to be consumed as
+  Pydantic AI providers with model profiles, streaming, tool calls, approvals,
+  sessions, and projections.
+- Public export of the provider bridge surface from `pydantic_acp`.
+
+### Changed
+
+- `pydantic-acp` now requires Pydantic AI v2.
+- Dev dependency aligned with Pydantic AI v2.
+- Workspace packages synchronized to `1.1.0`.
+
+### Fixed
+
+- Type-safety and forward-reference handling in the ACP provider bridge.
+
 ## [1.0.0] - 2026-07-03
 
 This is the first stable release of the synchronized ACP Kit workspace.
@@ -46,4 +66,5 @@ This is the first stable release of the synchronized ACP Kit workspace.
   failure paths close every owned resource deterministically.
 - CLI target import failures retain actionable root-cause details.
 
+[1.1.0]: https://github.com/vcoderun/acpkit/releases/tag/v1.1.0
 [1.0.0]: https://github.com/vcoderun/acpkit/releases/tag/v1.0.0

README.md

@@ -277,6 +277,32 @@ Host-facing utilities include:
 - `BlackBoxHarness` for ACP boundary integration tests
 - `CompatibilityManifest` for documenting the ACP surface an integration truly supports
 
+## ACP Client Provider Bridge
+
+`pydantic-acp` also includes the inverse bridge: an ACP agent can be consumed as a Pydantic AI v2 provider/model pair via `AcpProvider` and `AcpModel`.
+
+```python
+from pydantic_ai import Agent
+from pydantic_acp import AcpProvider
+
+# `remote_acp_agent` can be any object implementing the ACP Agent interface.
+provider = AcpProvider(agent=remote_acp_agent, cwd="/workspace")
+model = provider.model("zed-agent")
+agent = Agent(model)
+
+result = await agent.run("Summarize the current workspace state.")
+print(result.output)
+```
+
+This keeps ownership boundaries explicit:
+
+- Pydantic AI owns the outer agent run, output validation, and normal model/provider lifecycle.
+- ACP owns the delegated agent session, ACP-visible updates, and any editor or host capabilities requested by that agent.
+- `AcpHostBridge` records ACP `session_update` messages and can delegate filesystem, terminal, approval, and extension callbacks to a real ACP host client when one is supplied.
+- Pydantic AI function tools are intentionally not executed directly by `AcpModel`; register tools on the ACP agent or expose host capabilities through ACP.
+
+Use this bridge when the thing you have is already an ACP agent and you want it to participate in code that expects a Pydantic AI provider/model. It is not another ACP server adapter and it does not replace `create_acp_agent(...)`.
+
 ## What `langchain-acp` Supports
 
 `langchain-acp` keeps ACP Kit's adapter seams intact while staying graph-centric on the upstream side.

VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

examples/langchain/codex_graph.py

@@ -22,9 +22,9 @@
     "MODEL_NAME",
     "acp_agent",
     "build_graph",
+    "codex_instructions",
     "config",
     "describe_codex_surface",
-    "codex_instructions",
     "graph",
     "graph_from_session",
     "main",
@@ -48,7 +48,6 @@
 
 def codex_instructions(*, mode_id: str) -> str:
     """Return the Codex Responses instructions used by this example graph."""
-
     base = (
         "You are a precise workspace assistant. "
         "Use the available tools when they help, keep answers concise, "
@@ -63,14 +62,13 @@ def codex_instructions(*, mode_id: str) -> str:
 
 def describe_codex_surface() -> str:
     """Summarize the Codex-backed LangChain example surface."""
-
     return "\n".join(
         (
             "Codex graph features:",
             "- LangChain ChatOpenAI wired through codex-auth-helper",
             "- OpenAI Responses API transport through local Codex auth state",
             "- ready for `langchain-acp` exposure through `run_acp(graph=...)`",
-        )
+        ),
     )
 
 

examples/langchain/deepagents_graph.py

@@ -32,8 +32,8 @@
     "MODEL_NAME",
     "WORKSPACE_ROOT",
     "acp_agent",
-    "config",
     "codex_instructions",
+    "config",
     "graph",
     "graph_from_session",
     "list_workspace_files",
@@ -74,7 +74,6 @@
 
 def codex_instructions(*, mode_id: str) -> str:
     """Return the Codex Responses instructions used by the DeepAgents example."""
-
     base = (
         "You are a workspace agent that can inspect and update files in the current demo workspace. "
         "Use tools for concrete file work, keep changes scoped, and summarize what changed."
@@ -126,7 +125,7 @@ def _resolve_workspace_path(path: str, *, root: Path | None = None) -> Path:
                         if relative_to_parent.parts
                         and relative_to_parent.parts[0] == workspace_root.name
                         else relative_to_parent.parts
-                    )
+                    ),
                 )
                 candidate = (workspace_root / relative_to_parent).resolve()
         else:
@@ -152,13 +151,11 @@ def _normalized_mock_path(path: str) -> str:
 
 def list_workspace_files() -> str:
     """List mocked workspace files exposed by the DeepAgents example."""
-
     return "\n".join(sorted(MOCK_WORKSPACE_FILES))
 
 
 def read_file(path: str) -> str:
     """Read a mocked file from the DeepAgents example workspace."""
-
     normalized = _normalized_mock_path(path)
     content = MOCK_WORKSPACE_FILES.get(normalized)
     if content is None:
@@ -168,7 +165,6 @@ def read_file(path: str) -> str:
 
 def write_file(path: str, content: str) -> str:
     """Pretend to write a file in the DeepAgents example workspace."""
-
     normalized = _normalized_mock_path(path)
     del content
     return f"Mock write accepted for {normalized}"
@@ -212,7 +208,7 @@ def _write_file(path: str, content: str) -> str:
 def graph_from_session(session: AcpSessionContext) -> CompiledAgentGraph:
     if not _deepagents_available():
         raise RuntimeError(
-            'Install the optional DeepAgents dependency first: uv add "langchain-acp[deepagents]"'
+            'Install the optional DeepAgents dependency first: uv add "langchain-acp[deepagents]"',
         )
     workspace_root = _ensure_workspace(_session_workspace_root(session)).resolve()
     model_name = session.session_model_id or DEFAULT_MODEL_ID or MODEL_NAME
@@ -221,7 +217,7 @@ def graph_from_session(session: AcpSessionContext) -> CompiledAgentGraph:
 
     tools: Sequence[DeepAgentTool] = [
         *_bind_workspace_tools(workspace_root),
-        *cast(Sequence[DeepAgentTool], native_plan_tools()),
+        *cast("Sequence[DeepAgentTool]", native_plan_tools()),
     ]
     return create_deep_agent(
         model=create_codex_chat_openai(

examples/langchain/workspace_graph.py

@@ -23,8 +23,8 @@
     "MODEL_NAME",
     "WORKSPACE_ROOT",
     "acp_agent",
-    "config",
     "codex_instructions",
+    "config",
     "describe_workspace_surface",
     "graph",
     "graph_from_session",
@@ -56,7 +56,6 @@
 
 def codex_instructions(*, mode_id: str) -> str:
     """Return the Codex Responses instructions used by the workspace graph."""
-
     base = (
         "You are a careful workspace assistant operating inside a small demo workspace. "
         "Prefer reading files before changing them, keep edits focused, "
@@ -111,27 +110,24 @@ def _workspace_surface_summary() -> str:
             "- session-aware `graph_from_session(...)` for per-session graph construction",
             "- file read and write projection through `FileSystemProjectionMap`",
             "- a seeded workspace that keeps ACP rendering deterministic",
-        )
+        ),
     )
 
 
 def list_workspace_files() -> str:
     """List seeded workspace files that the demo graph can read."""
-
     root = _ensure_workspace()
     files = sorted(path.relative_to(root).as_posix() for path in root.rglob("*") if path.is_file())
     return "\n".join(files)
 
 
 def describe_workspace_surface() -> str:
     """Summarize the ACP-facing features exposed by the workspace graph example."""
-
     return _workspace_surface_summary()
 
 
 def read_workspace_note(path: str) -> str:
     """Read a workspace note and return its text content."""
-
     note_path = _resolve_workspace_path(path)
     if not note_path.exists():
         raise ValueError(f"File not found: {path}")
@@ -140,7 +136,6 @@ def read_workspace_note(path: str) -> str:
 
 def write_workspace_note(path: str, content: str) -> str:
     """Write a workspace note and return the saved relative path."""
-
     root = _ensure_workspace()
     return _write_workspace_note(root, path, content)
 

examples/pydantic/finance_agent.py

@@ -171,35 +171,32 @@ def persist_plan_state(
 @agent.tool_plain
 def describe_finance_surface() -> str:
     """Summarize the ACP-facing features available in this finance example."""
-
     return "\n".join(
         (
             "Finance example features:",
             "- ask/plan/trade tool modes via PrepareToolsBridge",
             "- structured native plan generation in plan mode",
             "- approval-gated note writes with ACP file diffs",
             "- persisted plan snapshots under .acpkit/plans/",
-        )
+        ),
     )
 
 
 @agent.tool_plain(name=_WATCHLIST_TOOL)
 def list_watchlist() -> str:
     """List the seeded watchlist and workspace note files."""
-
     finance_root = _finance_root(Path.cwd())
     return "\n\n".join(
         (
             "Seeded symbols:\n" + "\n".join(f"- {symbol}" for symbol in sorted(_QUOTE_BOOK)),
             "Workspace files:\n" + _list_market_files(finance_root),
-        )
+        ),
     )
 
 
 @agent.tool_plain(name=_QUOTE_TOOL)
 def quote_symbol(symbol: str) -> str:
     """Return a deterministic demo quote for a watchlist symbol."""
-
     normalized_symbol = symbol.strip().upper()
     try:
         return _QUOTE_BOOK[normalized_symbol]
@@ -210,14 +207,12 @@ def quote_symbol(symbol: str) -> str:
 @agent.tool_plain(name=_READ_NOTE_TOOL)
 def read_market_note(path: str, max_chars: int = _READ_PREVIEW_CHARS) -> str:
     """Read a finance workspace note relative to the current working directory."""
-
     return _read_market_note(_finance_root(Path.cwd()), path, max_chars=max_chars)
 
 
 @agent.tool_plain(name=_WRITE_NOTE_TOOL, requires_approval=True)
 def save_market_note(path: str, content: str) -> str:
     """Write a finance note inside the local workspace."""
-
     return _save_market_note(_finance_root(Path.cwd()), path, content)
 
 
@@ -258,7 +253,7 @@ def save_market_note(path: str, content: str) -> str:
         FileSystemProjectionMap(
             default_read_tool=_READ_NOTE_TOOL,
             default_write_tool=_WRITE_NOTE_TOOL,
-        )
+        ),
     ],
 )
 acp_agent = create_acp_agent(agent=agent, config=config)

examples/pydantic/mock_harness_agent.py

@@ -108,7 +108,7 @@ def _harness_model(*, instructions: str = _INSTRUCTIONS) -> str | Model[Any]:
     except ModuleNotFoundError as exc:
         raise ModuleNotFoundError(
             "Install `codex-auth-helper`, unset `ACP_HARNESS_CODEX_MODEL`, or set "
-            "`ACP_HARNESS_MODEL` to a pydantic-ai model name before running the harness example."
+            "`ACP_HARNESS_MODEL` to a pydantic-ai model name before running the harness example.",
         ) from exc
     return create_codex_responses_model(
         configured_codex_model or _DEFAULT_CODEX_MODEL,
@@ -130,7 +130,6 @@ def _build_config(*, include_code_mode: bool) -> AdapterConfig:
 
 def _build_agent(session: AcpSessionContext, *, include_code_mode: bool) -> Agent[None, str]:
     """Build a real model-backed agent wired with pydantic-ai-harness capabilities."""
-
     _ensure_workspace()
     harness_bridges = _build_harness_bridges(
         _WORKSPACE_ROOT,

examples/pydantic/travel_agent.py

@@ -104,7 +104,8 @@ def _prompt_has_binary_media(prompt: Sequence[AgentPromptBlock]) -> bool:
                 return True
             continue
         if isinstance(block, EmbeddedResourceContentBlock) and isinstance(
-            block.resource, BlobResourceContents
+            block.resource,
+            BlobResourceContents,
         ):
             return True
     return False
@@ -204,29 +205,26 @@ async def observe_write_result(
 @agent.tool_plain
 def describe_travel_surface() -> str:
     """Summarize the ACP-facing surfaces available in this travel example."""
-
     return "\n".join(
         (
             "Travel example features:",
             "- existing Hooks capability introspection rendered through HookProjectionMap",
             "- approval-gated file writes with ACP diffs",
             "- prompt-model override provider for image and audio prompts",
-        )
+        ),
     )
 
 
 @agent.tool_plain
 def list_trip_files() -> str:
     """List the demo travel files available in the local workspace."""
-
     _ensure_travel_workspace()
     return "\n".join(sorted(path.name for path in _TRAVEL_ROOT.iterdir() if path.is_file()))
 
 
 @agent.tool_plain(name=_READ_TOOL)
 def read_trip_file(path: str, max_chars: int = 4000) -> str:
     """Read a travel file and return a bounded preview."""
-
     if max_chars <= 0:
         raise ValueError("max_chars must be positive.")
     _ensure_travel_workspace()
@@ -239,7 +237,6 @@ def read_trip_file(path: str, max_chars: int = 4000) -> str:
 @agent.tool_plain(name=_WRITE_TOOL, requires_approval=True)
 def write_trip_file(path: str, content: str) -> str:
     """Write a travel file inside the local demo workspace."""
-
     _ensure_travel_workspace()
     file_path = _resolve_trip_path(Path(path).name if Path(path).is_absolute() else path)
     file_path.write_text(content, encoding="utf-8")
@@ -261,7 +258,7 @@ def write_trip_file(path: str, content: str) -> str:
         FileSystemProjectionMap(
             default_read_tool=_READ_TOOL,
             default_write_tool=_WRITE_TOOL,
-        )
+        ),
     ],
 )
 acp_agent = create_acp_agent(agent=agent, config=config)