Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Document protocol capabilities and client acceptance checks

Rach Pradhanb146de5cad73
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a323876..9ad314c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -51,6 +51,7 @@ current is part of cutting a release.
### ACP and desktop integration
+- The [ACP compatibility contract](docs/acp-compatibility.md) records the stable protocol target, supported capabilities, extensions and client acceptance checks.
- ACP initialization and embedded resources follow protocol v1. Initialization metadata is validated per response, and duplicate live session creation cannot replace existing history.
- `session/new` and `session/load` expose supported effort options. `session/set_config_option` changes the same effort state as `/effort`; updates during a prompt apply after the active turn.
- Agent-originated model and effort changes publish configuration updates for clients. The desktop picker uses capability-derived values and labels.
diff --git a/docs/acp-compatibility.md b/docs/acp-compatibility.md
new file mode 100644
index 00000000..69eaa995
--- /dev/null
+++ b/docs/acp-compatibility.md
@@ -0,0 +1,50 @@
+# ACP compatibility
+
+Graff implements ACP wire protocol **v1**. The upstream repository identifies
+v1 as stable; v2 is a draft and is not a compatibility target for this release.
+Protocol versions are negotiated through `initialize.protocolVersion`, not
+inferred from SDK package versions.
+
+References:
+
+- [Upstream versioning](https://github.com/agentclientprotocol/agent-client-protocol#versioning)
+- [Stable v1 schema](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/schema/v1/schema.json)
+- [Protocol documentation](https://agentclientprotocol.com/protocol/overview)
+- [DeepWiki overview](https://deepwiki.com/agentclientprotocol/agent-client-protocol)
+
+The upstream schema is authoritative when a secondary explanation differs.
+Optional capabilities must be negotiated; supporting ACP does not mean every
+optional feature or draft extension is enabled.
+
+## Release contract
+
+| Surface | Behavior and scope | Regression coverage |
+| --- | --- | --- |
+| Initialization | Return protocol version 1 and explicit capabilities. Clients must reject a version they cannot speak. | `src/acp_protocol.zig`, `scripts/test-acp-startup.py`, `sdk/ts/acp.test.ts` |
+| Authentication | Credential-free initialization is available. Operations requiring a live agent remain authentication-gated. | `scripts/test-acp-preauth.py` |
+| Sessions | Create a session in its selected workspace. A live process owns one session; duplicate creation cannot replace its history. Load is advertised only when the live implementation can replay saved history. | `scripts/test-acp-session-load.py`, `scripts/test-acp-released-fixes.py` |
+| Prompt lifecycle | Stream session-scoped updates and return the terminal stop reason. Cancellation interrupts the active turn and cannot grant a pending permission. | `scripts/test-acp-failure.py`, `scripts/test-acp-permissions.py` |
+| Tool calls | Preserve call identity, status and terminal results. Tool-like prose is not execution evidence. | `src/acp_stream.zig`, `src/agent_steps_tests.zig` |
+| Permissions | Send the advertised choices to the active client and await its response. Clients must honor an explicit rejection or cancellation; automatic approval is a separate user setting. | `scripts/test-acp-permissions.py` |
+| Effort configuration | Expose supported `thought_level` values in session configuration. Validate setters, return the full option list, and emit `config_option_update` when agent-originated changes alter that state. | `scripts/test-acp-effort-config.py`, `src/acp_config.zig` |
+| Configuration timing | Client changes arriving during a prompt are queued for after that turn. An effort-tool result applies on the owning agent thread before the next model request; clients refresh the affected session's controls. | `src/acp_idle.zig`, `src/jev_effort_state.zig`, `apps/native/lib/acp-client-stream.test.ts` |
+| Content | Text, resource links and supported embedded text resources are accepted. Image and audio prompt capabilities are currently advertised as false. | `src/acp_protocol.zig` |
+| Client filesystem and terminals | These are optional negotiated ACP facilities, not a requirement that local harness tools be replaced by client tools. The local tool implementation does not imply support for every client-side method. | Capability negotiation and the upstream v1 schema |
+| Usage | Connection usage is a namespaced extension. It preserves unknown totals and is not a standard ACP v1 billing contract. | `scripts/test-acp-usage.py`, ADR 0182 |
+| Transport | ACP uses JSON-RPC over stdio. HTTP/2 checks exercise the model request transport behind ACP; they do not redefine ACP as an HTTP/2 protocol. | `scripts/test-acp-http2.py`, `scripts/test-acp-http2-retry.py` |
+
+## Client acceptance checklist
+
+A replacement client should be exercised against the release binary for
+initialization, new and loaded sessions, prompt streaming, cancellation,
+permission allow/reject/cancel, tool completion and effort configuration.
+It must scope every response and notification to the correct session, reject
+stale updates after a session is replaced, and retain unknown usage as unknown.
+A displayed effort control must track `config_option_update`, including changes
+that did not originate from a slash command.
+
+These checks describe the supported contract and its regression coverage.
+They are not a claim of exhaustive upstream conformance or support for every
+optional capability. Release acceptance also requires the client's own build,
+packaging and platform tests; protocol compatibility alone does not validate
+a desktop distribution.