acpkit 0.8.2__tar.gz → 0.9.0__tar.gz

acpkit-0.9.0/.agents/skills/acpkit-sdk/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: "acpkit-sdk"
+description: "Use for ACP Kit root-package work: CLI target resolution, `acpkit run`, `acpkit serve`, `acpkit launch`, cross-package routing, and end-to-end flows that span adapters plus transport."
+---
+
+# acpkit Root Skill
+
+Use this skill when the task is primarily about the root `acpkit` package.
+
+This skill owns the repo-level orchestration layer:
+
+- CLI entrypoints
+- Python target loading
+- adapter auto-dispatch
+- native ACP passthrough
+- `--addr` remote mirror entrypoints
+- Toad launch integration
+- end-to-end flows that combine the root package with adapters and transport
+
+It does not own the detailed runtime semantics of the adapter packages.
+
+## Start Here
+
+If you only need the shortest high-signal path:
+
+1. read `Quick Routing`
+2. open the [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) for command-shape questions
+3. open the [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) for execution-path questions
+4. open the [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) for adapter-selection questions
+
+## Quick Routing
+
+| If the task is about... | Use this skill? | Open first |
+| --- | --- | --- |
+| `acpkit run ...` or `acpkit serve ...` | Yes | [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
+| `module` vs `module:attribute` target resolution | Yes | [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
+| missing adapter install hints | Yes | [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) |
+| native ACP passthrough | Yes | [adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py), [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) |
+| `acpkit launch ...` or `launch --command ...` | Yes | [runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py), [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) |
+| `pydantic_ai.Agent` runtime behavior | No, pair with `pydantic-acp` | [Pydantic adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) |
+| LangGraph / DeepAgents runtime behavior | No, pair with `langchain-acp` | [LangChain adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/langchain-acp) |
+| WebSocket transport or remote mirroring | No, pair with `acpremote` | [Remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) |
+
+## Package Boundary
+
+`acpkit` is not an adapter and not a transport package.
+
+It is the root runtime package that:
+
+1. accepts CLI input
+2. resolves a target from Python import space or remote address
+3. selects the correct runtime lane
+4. dispatches to the relevant package
+
+That means it owns control flow, not framework semantics.
+
+What it owns:
+
+- CLI parsing
+- target loading
+- adapter detection
+- dispatch to `pydantic-acp` or `langchain-acp`
+- direct passthrough for already-materialized ACP agents
+- remote mirror startup through `--addr`
+- Toad launch wrapping
+
+What it does not own:
+
+- Pydantic plan/approval/projection details
+- LangChain graph/provider/projection details
+- WebSocket transport behavior
+- Codex auth parsing
+
+## Primary References
+
+Root-package references:
+
+- [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md)
+- [Raw CLI docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/cli.md)
+- [Raw examples index](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/index.md)
+- [Rendered CLI docs](https://vcoderun.github.io/acpkit/cli/)
+- [Source tree](https://github.com/vcoderun/acpkit/tree/main/src/acpkit)
+
+Cross-package references often needed from this skill:
+
+- [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md)
+- [LangChain adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md)
+- [Remote transport skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md)
+- [Codex helper skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md)
+
+## Public Entry Points
+
+User-facing commands:
+
+- `acpkit run TARGET`
+- `acpkit run --addr ws://...`
+- `acpkit serve TARGET`
+- `acpkit launch TARGET`
+- `acpkit launch --command "..."`
+
+Important runtime helpers:
+
+- `run_target(...)`
+- `serve_target(...)`
+- `launch_target(...)`
+- `run_remote_addr(...)`
+
+Important distinction:
+
+- `run TARGET`
+  starts a local stdio ACP server from a Python target
+- `serve TARGET`
+  materializes a compatible ACP agent and exposes it through `acpremote`
+- `run --addr ...`
+  skips Python target resolution entirely and mirrors a remote ACP endpoint locally
+- `launch`
+  wraps the `run` path through Toad or shells out directly for command mode
+
+## Target Resolution
+
+High-level target resolution flow:
+
+1. add the current working directory to `sys.path`
+2. add any explicit `-p/--path` roots
+3. import the module
+4. if an attribute path exists, resolve it
+5. if no attribute path exists, select the last defined supported target
+
+Current supported target families:
+
+- `pydantic_ai.Agent`
+- LangGraph / LangChain compiled graphs
+- native ACP agents
+
+When debugging target resolution:
+
+1. inspect import roots first
+2. inspect the resolved object type second
+3. inspect adapter installation/import errors third
+
+Do not jump into adapter internals before confirming the root package selected the correct object.
+
+## Adapter Dispatch
+
+The root package decides the runtime lane, then hands off.
+
+Conceptual dispatch:
+
+1. if the target already satisfies the ACP agent boundary, pass it through
+2. if the target is a `pydantic_ai.Agent`, materialize through `pydantic-acp`
+3. if the target is a LangGraph/LangChain graph, materialize through `langchain-acp`
+4. if the user passed `--addr`, bypass target loading and mirror the remote ACP endpoint
+
+`acpkit` should stay explicit about:
+
+- target typing
+- adapter availability
+- dispatch selection
+
+It should stay intentionally ignorant about:
+
+- Pydantic adapter internals
+- LangChain adapter internals
+- WebSocket wire semantics
+
+## Do Not Confuse With
+
+- `acpkit-sdk` vs `pydantic-acp`
+  `acpkit` decides the lane; `pydantic-acp` owns the Pydantic runtime semantics
+- `acpkit-sdk` vs `langchain-acp`
+  `acpkit` resolves and dispatches; `langchain-acp` owns graph adaptation and projection
+- `acpkit-sdk` vs `acpremote`
+  `acpkit` is the root CLI/runtime package; `acpremote` is transport
+
+## Module Guide
+
+| Module | Use it for | Notes |
+| --- | --- | --- |
+| [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py) | Click command definitions, argument validation, help/flag behavior | First stop for CLI UX bugs |
+| [Runtime module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/runtime.py) | `run`, `serve`, `launch`, remote mirror runtime paths | First stop for dispatch behavior after parsing |
+| [Adapter-dispatch module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/adapters.py) | target typing, adapter import/load, native ACP detection | First stop for wrong lane selection |
+| [Compatibility helpers](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/compatibility.py) | compatibility manifest helpers | Not part of normal runtime dispatch |
+| [Compatibility schema](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/_compatibility_schema.py) | manifest schema and validation | Use only for compatibility-surface work |
+| [Console entrypoint](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/__main__.py) | console entrypoint | Usually not the source of behavior bugs |
+
+## Common Workflows
+
+### Run an adapter-backed local ACP server
+
+Pydantic:
+
+```bash
+acpkit run examples.pydantic.finance_agent:agent
+```
+
+LangChain:
+
+```bash
+acpkit run examples.langchain.workspace_graph:graph
+```
+
+### Expose a remote ACP host
+
+```bash
+acpkit serve examples.langchain.workspace_graph:graph --host 0.0.0.0 --port 8080
+```
+
+### Mirror a remote ACP host back into a local ACP boundary
+
+```bash
+acpkit run --addr ws://127.0.0.1:8080/acp/ws
+```
+
+### Launch through Toad
+
+```bash
+acpkit launch examples.pydantic.finance_agent:agent
+acpkit launch examples.langchain.workspace_graph:graph
+```
+
+### Launch a script that already starts ACP itself
+
+```bash
+acpkit launch --command "python3.11 some_script_that_starts_acp.py"
+```
+
+## Cross-Package Workflows
+
+Typical combinations:
+
+- `acpkit` + `pydantic-acp`
+  when the root package resolves and runs or serves a `pydantic_ai.Agent`
+- `acpkit` + `langchain-acp`
+  when the root package resolves and runs or serves a LangChain/LangGraph target
+- `acpkit` + `acpremote`
+  when the root package is part of a remote-host topology via `serve` or `--addr`
+- `pydantic-acp` + `codex-auth-helper`
+  when a Codex-backed Pydantic model is exposed through ACP and then possibly launched through `acpkit`
+
+## Skill-Bundled Recipes
+
+Skill-local recipe index:
+
+- [Skill-local recipe index](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md)
+
+Public adapter examples commonly launched through the root package:
+
+- [Pydantic public examples](https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/pydantic/README.md)
+- [LangChain public examples](https://raw.githubusercontent.com/vcoderun/acpkit/main/examples/langchain/README.md)
+
+Remote pairing examples:
+
+- [Remote command exposure recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py)
+- [Remote mirror recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py)
+
+## Handoff Rules
+
+Switch to a narrower skill when:
+
+- the bug is clearly inside adapter runtime behavior
+- the task is about approvals, plans, projections, or host policy
+- the task is about transport or remote ownership rather than CLI or dispatch
+- the task is about Codex auth refresh or `auth.json`
+
+Stay in this skill when:
+
+- the main question is import resolution
+- the main question is runtime lane selection
+- the main question is CLI behavior
+- the main question is how multiple packages fit together end-to-end
+
+## Guardrails
+
+- Do not claim the root package itself adapts framework runtimes. It routes them.
+- Do not describe `acpremote` as an adapter.
+- Do not describe `codex-auth-helper` as part of target resolution.
+- Do not document a root CLI feature that is not present in the [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py).
+- When the question is about adapter truthfulness, plans, approvals, projections, host ownership,
+  or provider behavior, move to the narrower package skill.

acpkit-0.9.0/.agents/skills/acpkit-sdk/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "ACP Kit"
+  short_description: "Root CLI, dispatch, and ACP app wiring"
+  default_prompt: "Use $acpkit-sdk to update ACP Kit CLI behavior, target resolution, adapter dispatch, or end-to-end root-package flows."
+
+policy:
+  allow_implicit_invocation: true

acpkit-0.9.0/.agents/skills/acpkit-sdk/examples/README.md

@@ -0,0 +1,52 @@
+# acpkit-sdk Examples
+
+These are skill-local operator recipes for the root `acpkit` package.
+
+## Run Adapter-Backed Targets
+
+Pydantic AI:
+
+```bash
+acpkit run examples.pydantic.finance_agent:agent
+acpkit run examples.pydantic.travel_agent:agent
+```
+
+LangChain / LangGraph:
+
+```bash
+acpkit run examples.langchain.workspace_graph:graph
+acpkit run examples.langchain.deepagents_graph:graph
+```
+
+## Serve A Remote ACP Host
+
+Pydantic AI:
+
+```bash
+acpkit serve examples.pydantic.finance_agent:agent --host 0.0.0.0 --port 8080
+```
+
+LangChain / LangGraph:
+
+```bash
+acpkit serve examples.langchain.workspace_graph:graph --host 0.0.0.0 --port 8080
+```
+
+Mirror the remote host back into a local ACP boundary:
+
+```bash
+acpkit run --addr ws://127.0.0.1:8080/acp/ws
+```
+
+## Launch Through Toad
+
+```bash
+acpkit launch examples.pydantic.finance_agent:agent
+acpkit launch examples.langchain.workspace_graph:graph
+```
+
+If a script already starts ACP by itself:
+
+```bash
+acpkit launch --command "python3.11 some_script_that_starts_acp.py"
+```

acpkit-0.9.0/.agents/skills/acpremote/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: "acpremote"
+description: "Use for `acpremote` tasks: exposing ACP agents or stdio ACP commands over WebSocket, mirroring remote ACP endpoints locally, host ownership semantics, metadata/auth routes, and remote transport examples."
+---
+
+# acpremote Skill
+
+Use this skill when the task is about the `acpremote` transport package.
+
+This package is the repo's ACP transport/helper layer. It assumes the runtime already speaks ACP
+and focuses on moving that ACP boundary across WebSocket transport or back into a local ACP proxy.
+
+It is not an adapter.
+
+That distinction matters:
+
+- adapters turn framework runtimes into ACP
+- `acpremote` transports or mirrors an ACP boundary that already exists
+
+## Start Here
+
+If you only need the shortest high-signal path:
+
+1. read `Quick Routing`
+2. open the [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) for exposure-path questions
+3. open the [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py) and the [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) for mirror-path questions
+4. open the [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) only when the upstream runtime is ACP-over-stdio
+
+## Quick Routing
+
+| If the task is about... | Use this skill? | Open first |
+| --- | --- | --- |
+| expose an existing ACP agent over WebSocket | Yes | [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py) |
+| expose a stdio ACP command over WebSocket | Yes | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) |
+| mirror a remote ACP endpoint locally | Yes | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) |
+| bearer auth or metadata routes | Yes | [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py) |
+| remote host ownership or `remote_cwd` | Yes | [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py), [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py) |
+| line buffering / frame relay issues | Yes | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) |
+| adapting a Pydantic or LangChain runtime to ACP | No, pair with adapter skill | adapter packages |
+
+## Package Boundary
+
+`acpremote` owns:
+
+- WebSocket transport
+- stdio-to-WebSocket ACP relaying
+- remote mirror proxy behavior
+- `/acp` metadata
+- `/healthz`
+- bearer-token protection
+- transport latency metadata/projection
+- host-ownership policy for mirrored clients
+
+It does not own:
+
+- adapting `pydantic_ai.Agent`
+- adapting LangGraph/LangChain graphs
+- root CLI target loading
+- Codex auth parsing
+
+## Do Not Confuse With
+
+- `acpremote` vs `acpkit-sdk`
+  `acpremote` is transport; `acpkit` is the root CLI/runtime package
+- `acpremote` vs `pydantic-acp`
+  `acpremote` exposes or mirrors ACP; `pydantic-acp` creates ACP from a Pydantic runtime
+- `acpremote` vs `langchain-acp`
+  `acpremote` transports ACP; `langchain-acp` adapts graph runtimes into ACP
+
+## Primary References
+
+Package references:
+
+- [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md)
+- [Raw transport docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/acpremote.md)
+- [Raw remote-host docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/examples/remote-hosting.md)
+- [Rendered docs](https://vcoderun.github.io/acpkit/acpremote/)
+- [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote)
+
+Cross-skill references:
+
+- [Root package skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md)
+- [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md)
+- [LangChain adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/langchain-acp/SKILL.md)
+
+## Public Surface
+
+Server-side seams:
+
+- `serve_acp(...)`
+- `serve_command(...)`
+- `serve_stdio_command(...)`
+
+Client-side seam:
+
+- `connect_acp(...)`
+
+Support types:
+
+- `TransportOptions`
+- `CommandOptions`
+- `ServerOptions`
+
+Package entrypoint:
+
+- [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/__init__.py)
+
+## Module Guide
+
+| Subsystem | Key files | Use them for |
+| --- | --- | --- |
+| server and routing | [server transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/server.py), [auth helpers](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/auth.py), [metadata module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/metadata.py), [transport config module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/config.py), [limit definitions](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/limits.py) | server startup, mount paths, metadata, health, auth, limits |
+| remote client and proxy behavior | [remote client module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/client.py), [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) | remote connection setup, metadata fetch, local mirroring, host ownership |
+| command-backed transport | [command transport module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/command.py) | stdio ACP commands that need WebSocket exposure |
+| stream plumbing | [stream bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/stream.py) | line buffering, text/binary frame handling, sender/receiver lifecycle |
+
+## Core Transport Shapes
+
+### Shape 1: Existing ACP agent object
+
+Use:
+
+- `serve_acp(...)`
+
+Meaning:
+
+1. some runtime already produced an `acp.interfaces.Agent`
+2. `acpremote` exposes that ACP boundary over WebSocket
+
+### Shape 2: Existing stdio ACP command
+
+Use:
+
+- `serve_command(...)`
+- `serve_stdio_command(...)`
+
+Meaning:
+
+1. the upstream runtime only exposes ACP on stdin/stdout
+2. `acpremote` spawns that command
+3. stdin/stdout ACP frames are bridged onto WebSocket
+
+### Shape 3: Remote ACP mirrored locally
+
+Use:
+
+- `connect_acp(...)`
+
+Meaning:
+
+1. there is an existing remote ACP WebSocket endpoint
+2. `acpremote` opens a remote connection
+3. the local machine gets a proxy ACP agent that mirrors the remote endpoint
+
+## Remote Host Ownership
+
+This is one of the most important rules in the package.
+
+The default should keep the remote host authoritative for:
+
+- `cwd`
+- host-backed filesystem ownership
+- host-backed terminal ownership
+
+That is why the proxy layer:
+
+- prefers remote metadata like `remote_cwd`
+- strips local host-backed capabilities before forwarding `initialize(...)`
+
+Use client passthrough only when the product explicitly wants the local machine to become host
+owner.
+
+If a user reports:
+
+- remote command executed in local cwd
+- local filesystem used instead of remote filesystem
+- remote agent owning the wrong host
+
+inspect the [proxy agent module](https://github.com/vcoderun/acpkit/blob/main/packages/transports/acpremote/src/acpremote/proxy_agent.py) and metadata flow first.
+
+## Metadata and Health Surface
+
+The transport package also owns the lightweight HTTP surface around the WebSocket endpoint:
+
+- `/acp`
+- `/healthz`
+
+Typical uses:
+
+- health checks
+- transport metadata inspection
+- remote `cwd` discovery
+- debugging auth and route configuration
+
+This is transport-level behavior. Do not push it into adapter code.
+
+## Latency and Transport Visibility
+
+`acpremote` can emit transport-observed latency through:
+
+- metadata fields
+- optional visible latency projection
+
+Keep the distinction explicit:
+
+- this is proxy-observed timing
+- it is not a claim of clock-synchronized one-way network truth
+
+## Skill-Bundled Examples
+
+Skill-local examples:
+
+- [Remote command exposure recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/serve_command.py)
+- [Remote mirror recipe](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/mirror_remote.py)
+- [Skill-local example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpremote/examples/README.md)
+
+These demonstrate:
+
+- exposing a stdio ACP command remotely
+- mirroring a remote ACP endpoint locally
+- using `TransportOptions` intentionally
+
+## Handoff Rules
+
+Pair or switch to:
+
+- `acpkit-sdk`
+  when the remote host is reached through `acpkit serve ...` or the local mirror is
+  `acpkit run --addr ...`
+- `pydantic-acp`
+  when a Pydantic agent is adapted first, then exposed remotely
+- `langchain-acp`
+  when a LangGraph or DeepAgents graph is adapted first, then exposed remotely
+
+Common end-to-end references:
+
+- [Root recipe index](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/acpkit-sdk/examples/README.md)
+- [Public Pydantic example](https://github.com/vcoderun/acpkit/blob/main/examples/pydantic/finance_agent.py)
+- [Public LangChain example](https://github.com/vcoderun/acpkit/blob/main/examples/langchain/workspace_graph.py)
+
+## Guardrails
+
+- Do not call `acpremote` an adapter.
+- Do not claim it can adapt a framework runtime by itself.
+- Do not blur ACP adaptation with ACP transport.
+- If the task is really about `acpkit run ...` or `acpkit serve ...`, pair this skill with
+  `acpkit-sdk`.

acpkit-0.9.0/.agents/skills/acpremote/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "ACP Remote"
+  short_description: "Expose and mirror ACP over WebSocket transport"
+  default_prompt: "Use $acpremote to update ACP WebSocket transport, stdio command exposure, remote mirroring, or host-ownership behavior."
+
+policy:
+  allow_implicit_invocation: true

acpkit-0.9.0/.agents/skills/acpremote/examples/README.md

@@ -0,0 +1,32 @@
+# acpremote Examples
+
+`acpremote` examples focus on transport, not runtime adaptation.
+
+## Expose A Stdio ACP Command Over WebSocket
+
+```bash
+uv run python .agents/skills/acpremote/examples/serve_command.py
+```
+
+By default this example exposes:
+
+```bash
+acpkit run examples.langchain.workspace_graph:graph
+```
+
+over:
+
+```text
+ws://127.0.0.1:8080/acp/ws
+```
+
+Override the command with `ACPREMOTE_COMMAND` when needed.
+
+## Mirror A Remote ACP Endpoint Locally
+
+```bash
+ACPREMOTE_URL=ws://127.0.0.1:8080/acp/ws \
+uv run python .agents/skills/acpremote/examples/mirror_remote.py
+```
+
+That starts a local stdio ACP boundary backed by the remote WebSocket server.

acpkit-0.9.0/.agents/skills/acpremote/examples/mirror_remote.py

@@ -0,0 +1,32 @@
+from __future__ import annotations as _annotations
+
+import asyncio
+import os
+
+from acp import run_agent
+from acpremote import TransportOptions, connect_acp
+
+
+def _remote_url() -> str:
+    return os.getenv("ACPREMOTE_URL", "ws://127.0.0.1:8080/acp/ws")
+
+
+def _bearer_token() -> str | None:
+    token = os.getenv("ACPREMOTE_BEARER_TOKEN", "").strip()
+    return token or None
+
+
+async def main() -> None:
+    agent = connect_acp(
+        _remote_url(),
+        bearer_token=_bearer_token(),
+        options=TransportOptions(
+            emit_latency_meta=True,
+            emit_latency_projection=True,
+        ),
+    )
+    await run_agent(agent)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())