feat(acp): add opt-in ACP v2 runtime foundation

book/src/acp.md

@@ -9,6 +9,50 @@ Like `agentkit-mcp`, this crate does not define a parallel protocol vocabulary.
 - **Protocol docs:** [agentclientprotocol.com](https://agentclientprotocol.com/protocol/v1/overview)
 - **Rust SDK:** [`agent-client-protocol` on crates.io](https://crates.io/crates/agent-client-protocol)
 
+## Opt-in ACP v2 runtime
+
+ACP v2 support is additive and disabled by default. Enable it explicitly:
+
+```toml
+agentkit-acp = { version = "0.10.8", features = ["protocol-v2"] }
+```
+
+`protocol-v2` enables the official upstream
+`agent-client-protocol/unstable_protocol_v2` feature. The root API and
+`agentkit_acp::wire` continue to expose stable v1 behavior. Experimental v2
+runtime APIs and official v2 wire types are isolated under
+`agentkit_acp::v2` and `agentkit_acp::v2::wire`; v1 wire types are not part of
+that namespace.
+
+Build a v2 server with `agentkit_acp::v2::AcpHeadlessRuntime`. Its factory is
+called once for each `session/new` and receives a v2 session ID, an agentkit
+session ID, the v2 output observer, and a cancellation handle. Install the
+observer and cancellation handle on the returned agent loop in the same way as
+the v1 factory.
+
+The v2 prompt lifecycle differs from v1: `session/prompt` acknowledges
+acceptance immediately instead of waiting for the turn to finish. The runtime
+then emits, in order:
+
+1. a `user_message` update with a generated stable message ID;
+2. a `running` state update;
+3. streamed agent message or thought chunks with distinct stable message IDs;
+4. tool-call lifecycle updates when tools run;
+5. an `idle` state update with the final stop reason.
+
+Each session has its own worker and loop driver. Independent sessions can make
+progress concurrently, while a second prompt for a running session is rejected.
+`session/cancel` interrupts only the selected session and produces an idle
+`cancelled` update after loop cleanup. `session/close` cooperatively cancels
+work and drops the session worker. `session/list` and `session/resume` cover
+active in-memory sessions; replay is not supported.
+
+The initial v2 foundation routes text, reasoning, and tool lifecycle updates.
+ACP v2 permission callbacks are intentionally deferred; an unsupported approval
+interrupt retains the transcript and ends the prompt with the custom `_error`
+stop reason rather than `refusal`. Upstream labels the v2 protocol unstable, so
+opt-in callers should expect the `v2` namespace to track official SDK changes.
+
 ## Two integration shapes
 
 `agentkit-acp` exposes the same functionality at two levels:

crates/agentkit-acp/Cargo.toml

@@ -4,7 +4,7 @@ homepage.workspace = true
 name = "agentkit-acp"
 readme = "README.md"
 repository.workspace = true
-version = "0.10.7"
+version = "0.10.8"
 edition.workspace = true
 license.workspace = true
 rust-version.workspace = true
@@ -13,17 +13,18 @@ rust-version.workspace = true
 default = ["stdio"]
 stdio = []
 unstable-acp = ["agent-client-protocol/unstable"]
+protocol-v2 = ["agent-client-protocol/unstable_protocol_v2"]
 
 [dependencies]
-agent-client-protocol = "2.0.0"
+agent-client-protocol = "=2.0.0"
 agentkit-core = { version = "0.10.5", path = "../agentkit-core" }
 agentkit-loop = { version = "0.10.5", path = "../agentkit-loop" }
 agentkit-tools-core = { version = "0.10.5", path = "../agentkit-tools-core" }
 async-trait.workspace = true
 base64.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
-tokio = { workspace = true, features = ["sync"] }
+tokio = { workspace = true, features = ["sync", "time"] }
 tracing.workspace = true
 
 [dev-dependencies]

crates/agentkit-acp/README.md

@@ -15,7 +15,36 @@ upstream SDK transport. It handles initialize, session lifecycle, prompt
 conversion, streaming updates, cancellation, and ACP permission requests for
 agentkit approval interrupts.
 
-Run the in-memory end-to-end example with:
+## Opt-in ACP v2 foundation
+
+The crate root, default features, and `wire` module remain ACP v1. To use the
+experimental upstream ACP v2 protocol, enable the additive feature:
+
+```toml
+agentkit-acp = { version = "0.10.8", features = ["protocol-v2"] }
+```
+
+The feature maps directly to the official
+`agent-client-protocol/unstable_protocol_v2` feature. V2 APIs and official v2
+wire types live only under `agentkit_acp::v2` (and
+`agentkit_acp::v2::wire`).
+
+`v2::AcpHeadlessRuntime` supports ACP v2 initialize, new/list/resume
+session, prompt, cancel, session updates, and close. Listing and resume cover
+the runtime's active in-memory sessions; replay is not supported. Each session
+owns a worker and loop driver, so work in one session does not block request
+handling for another. A prompt is accepted before model work completes, then
+the runtime emits ordered `UserMessage`, `Running`, streamed output, and `Idle`
+updates. User, visible-agent, and thought message IDs are distinct and stable
+for the lifetime of a prompt.
+
+This first v2 foundation streams text, reasoning, and tool lifecycle updates.
+The v1 permission bridge is not exposed through v2 wire types. Unsupported
+approval interrupts retain the transcript and therefore end with the custom
+`_error` stop reason rather than `Refusal`. Because upstream marks protocol v2
+unstable, all APIs in the `v2` namespace can evolve with the official SDK.
+
+Run the stable v1 in-memory end-to-end example with:
 
 ```sh
 cargo run -p openrouter-acp-trio

crates/agentkit-acp/src/lib.rs

@@ -41,6 +41,10 @@ pub mod wire {
     pub use agent_client_protocol::schema::v1::*;
 }
 
+/// Opt-in ACP protocol v2 runtime and upstream wire types.
+#[cfg(feature = "protocol-v2")]
+pub mod v2;
+
 const ALLOW_ONCE_OPTION: &str = "allow_once";
 const ALLOW_ALWAYS_OPTION: &str = "allow_always";
 const REJECT_ONCE_OPTION: &str = "reject_once";