Skip to content

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

Python
11.5 KB
Raw Blame

ACP compatibility

Graff implements ACP wire protocol v1. The upstream repository identifies v1 as stable. The v2 draft is available as a preview: a client that sends protocolVersion 2 or higher to a graff started with GRAFF_ACP_V2=1 gets the v2 shapes (ADR 0206); every other connection gets v1, unchanged. Protocol versions are negotiated through initialize.protocolVersion, not inferred from SDK package versions.

References:

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
Workspace and worktrees session/new and session/load adopt the client's absolute cwd; naming the checkout that owns a -w or auto-isolated tree keeps that tree. Replies carry _meta["graff/worktree"] (name, path, branch, base, baseSha, root, generated, or null in a main checkout). A workspace switch emits session_info_update with the same _meta plus graff/cwd, right after the workspace tool result (before the next call), or before the reply for /workspace use. scripts/test-acp-workspace.py, src/acp_workspace.zig, ADR 0202
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
Questions (ask_user) A client that advertises clientCapabilities.elicitation.form gets a standard elicitation/create form request (one required answer string, an enum when the model offered choices); accept returns the answer, decline/cancel end the question. A client that opts in with _meta["graff/askUser"] gets graff's gui_ask_user and answers with session/answer. Any other client cannot show the question, so ask_user returns at once and tells the model to assume or ask in its reply; it never waits on a client that cannot answer. scripts/test-acp-ask-user.py, src/acp_elicit.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
Content Text, resource links and supported embedded text resources are accepted. image blocks (data + mimeType) are accepted and advertised (promptCapabilities.image); they reach the next model request when the model accepts images and are skipped otherwise, the same as @[path] attachments. Audio is advertised as false. src/acp_protocol.zig, src/acp_images.zig, scripts/test-acp-images.py
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
Context meter Standard usage_update (stable in ACP v1): used tokens in context and the model's size, plus cost {amount, currency: "USD"} only when every call so far was priced. Sent after tool steps whenever the count moved (so it drops visibly after compaction) and at the end of each prompt turn. src/acp_context_meter.zig, src/acp_engine_test.zig
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
Subagents Default: a top-level subagent streams its work onto the parent tool call as standard tool_call_update content (a rolling log of its tool calls, failures and message tail), with no status change, a tool title containing the resolved worker model, and _meta["graff/subagent"] = {sessionId, name, state, provider, model}; GRAFF_ACP_SUBAGENT_PROGRESS=0 disables it. Opt-in preview: the proposed child-session stream (client subagents capability plus GRAFF_ACP_DRAFT_SUBAGENTS=1) replaces it for foreground children. Detached workers also keep graff/agents inspection. Child history is not yet replayed on session/load. scripts/test-acp-subagent-update.py, ADR 0194, ADR 0205
Session-changing commands /resume SOURCE (and --branch DEST) moves the live session onto another save while the connection keeps its session ID. The session/prompt result then carries _meta["graff/durableSessionId"]: the save the session now writes. A host that restores sessions should keep that ID and pass it to session/load after a restart; the old ID may name no save, or a save from before the switch. v1 only. scripts/test-acp-resume-identity.py, src/acp_engine.zig (#1529)
Resent prompts session/prompt may carry a client message id as messageId or _meta["graff/messageId"]. Resending a prompt this process already finished for that session answers with the first turn's stopReason instead of starting another turn; a failed turn is not recorded, so its resend runs. The last 32 ids are kept in memory. graff serve and remote control take the same id as message_id on the request body and replay the first request's events. src/resend.zig, scripts/test-serve-resume.py
Saved views A completed tool_call_update whose result saved a render_html page or an MCP Apps result also carries _meta["graff/view"] = {kind: "html" | "mcp_app", id, path}. id is the 32-hex snapshot name under .graff/views or .graff/mcp-apps; resolve by id and treat path as informational. The [Rendered view](…) / [MCP app](…) text link stays in the content. Replayed on session/load. scripts/test-acp-view-meta.py, src/acp_view_meta.zig
Compaction When the root agent compacts (automatically, /compact, or server-side), graff sends compaction_update {compactionId, status}: in_progress, then one of completed (a local summary rides summary as a text block), failed (with error) or cancelled. A provider that compacted in-stream gets one completed. ACP v1 marks this unstable, so it is sent only to clients that advertise clientCapabilities.session.compaction; ACP v2 clients always get it. src/acp_compaction.zig, scripts/test-acp-compaction.py
Client profiles A client whose clientInfo.name starts with t3-code gets the T3 Code profile: a slash command is the first prompt block, the session cwd is never swapped for an auto-isolated tree, a model-category config option lists reachable models (<provider>/<model>), and /model and /yolo are not advertised. src/acp_t3_tests.zig, ADR 0278
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

ACP v2 preview (GRAFF_ACP_V2=1)

Surface v2 behavior Coverage
Initialization protocolVersion: 2, info, and object-marker capabilities.session (prompt.image/embeddedContext, mcp.stdio/http); graff extensions in capabilities._meta. authMethods uses methodId, and the terminal login is listed only when the client sends capabilities.auth.terminal. src/acp_v2.zig, scripts/test-acp-v2.py
Prompt lifecycle session/prompt is answered with {messageId} once the user message is inserted, before the turn runs. Then user_message (same ID), state_update running, the turn's updates, and state_update idle with stopReason. A turn that fails after acceptance idles with stopReason: "_error" and _meta["graff/error"]. Agent-started turns (peer mail) use the same updates with no request. src/acp_v2_prompt.zig, scripts/test-acp-v2.py
Messages Every chunk has a messageId. A new ID starts when output switches between thought and text or after a tool event, so later text never appends above an earlier tool row. src/acp_v2.zig
Tool calls No tool_call: the first tool_call_update for an ID creates the row. Subagent progress keeps replacing that call's content. src/acp_stream.zig
Permissions state_update requires_action while a session/request_permission is pending, running once it is answered. src/acp_permission.zig
Usage usage_update {used, size} replaces gui_context_meter. Graff-only session updates are _-prefixed (_gui_ask_user). src/acp_engine.zig
Sessions session/close cancels any running turn and answers {}. session/resume restores a saved session without replay, and replays it only for replayFrom: {type: "start"}. src/acp_session_load.zig

Not yet: stable message IDs across replay (replayed messages get fresh IDs), session/list, auth/login / auth/logout, plan_update, structured diffs, terminal updates, JSON-RPC batches, the draft child-session stream, and subagent progress after the prompt goes idle.

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.