Repository navigation
ACP external-client verification #118
Description
Proposal
Parent: Phase 1 (ACP modernization). Completes the fluent-SDK migration landed on branch
skein2/acp-sdk-1.8 (docs/skein-2/01-acp-migration.md). Proves charter Scenario A.
Why
The ACP migration to the fluent SDK 1.8.0 is implemented and unit-tested, but the
compatibility tests mock the client side. The charter (§6.4) requires "compatibility with
at least one independent ACP client" and "validate against the actual external protocol,
not only unit tests that mock every method." Until a real external client drives a real
session over the wire, the migration is not proven, and the deprecated
AgentSideConnection compatibility switch cannot be removed with confidence.
Research (R1, answered): ACP's current stable protocol version is 1. Official SDKs
exist in TypeScript, Python, Rust, Kotlin, and Java; Zed is the primary client. To avoid a
shared-SDK bug masking a wire mismatch, the verifying client is built on a different
official SDK than the agent's TypeScript SDK — Python or Rust.
What Changes
- Add an integration test that drives a real opencode-skein ACP agent with an
independent ACP client (Python or Rust official SDK, protocol v1), over the real
wire — no mocked client. - The test performs the full Scenario A sequence: initialize + capability negotiation,
create session, submit a coding prompt, receive streamed updates, respond to a
permission request (both accept and deny), and cancel an active turn. - Record the chosen client (SDK + version) and the negotiated
protocolVersionas
evidence, with the request/response transcript captured as an artifact. - Gate removal of the deprecated
AgentSideConnectioncompatibility switch on this test
passing.
Non-goals
- No ACP v2 (charter §6.4: evaluate separately; not a prerequisite for Skein 2.0).
- No changes to the agent's business logic — this is a verification harness.
- No Zed GUI automation (heavy); the SDK client is the primary instrument. Zed remains an
optional manual smoke check.
Risks
- SDK skew. The independent SDK may differ from the agent's SDK on a message.
Mitigation: pin both to protocol v1 and record versions; a mismatch is a finding to
report, not a test failure to hide. - Permission/cancel timing is racy. Mitigation: bounded waits with explicit timeouts
and captured transcripts as evidence.
Impact
New test harness (e.g. packages/opencode/test/acp-external/ or a standalone script), a
CI job, and evidence artifacts. No production code changes expected; any fix discovered is
filed as a follow-up commit referencing this change.
Tasks
Phase 0: Choose and pin the independent client
- 0.1 Pick the independent client SDK (Python or Rust official ACP SDK, protocol v1)
and record its version. It MUST be a different official SDK than the agent's
TypeScript SDK. - 0.2 Confirm the agent negotiates
protocolVersion1 and record the value. - 0.3 Stand up a minimal real opencode-skein ACP agent under test (reuse the
skein2/acp-sdk-1.8agent; no business-logic changes).
Phase 1: Scenario A sequence
- 1.1 initialize + capability negotiation succeeds.
- 1.2 newSession creates a session; a session id is returned.
- 1.3 prompt streams at least one assistant update to the client.
- 1.4 permission request: client accepts; the tool proceeds.
- 1.5 permission request: client denies; the tool is blocked and the denial is
reported. - 1.6 cancel an active turn; the agent stops and reports cancellation.
- 1.7 client disconnects mid-session; the agent session is handled per policy
(preserved or cleaned) without crashing.
Phase 2: Evidence and gate
- 2.1 Capture the full request/response transcript as a test artifact.
- 2.2 Wire the test into CI against the agent on
skein2/acp-sdk-1.8. - 2.3 On green: remove the deprecated
AgentSideConnectioncompatibility switch in a
separate commit that references this change. - 2.4 Record evidence in
findings.md: client SDK + version, negotiated
protocolVersion, transcript path, CI run id.
Activity