Skip to content

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

Python
2.8 KB
Raw Blame

ACP client behavior and limits

Written against the desktop app that used to live in this repository. The desktop app is now Harness, which drives graff over the same ACP surface.

The live graff acp process speaks ACP v1. The desktop is its client: it sends prompts and renders session/update notifications. A streamed tool row is identified by toolCallId; updates change that row, and a new content array replaces its prior content. The turn ends when the original session/prompt request responds with a stopReason, including cancelled after cancellation. Tool calls and prompt turns define those wire rules.

The desktop restores its own saved chat view and starts a replacement agent with --resume <name>. Separately, a v1 client may use session/load when the live agent advertises loadSession: the session ID is a saved conversation name in the selected workspace, and the agent replays retained user messages, assistant messages, and tool results before responding. Replay is display history; it does not rerun tools or revive shell jobs. The live process owns one active session and rejects a second session/new; start another process for another session. The in-process embed has no durable store and does not advertise loadSession. ACP session setup specifies the capability and replay order.

The desktop defaults to --yolo; setting GRAFF_YOLO=0 opts into client permission decisions. Pending permission requests must receive a response, including a cancelled outcome if the turn is cancelled. ACP permission flow defines the request and outcomes. A transport event alone does not establish that the visible desktop control was exercised, so permission UI needs end-to-end verification.

The agent's shell tool uses its own job handles. These are separate from ACP's optional client-owned terminal/create, terminal/output, terminal/kill, and terminal/release surface, which this desktop does not advertise. After a shell host restart, an old job handle must fail closed; restoring a conversation cannot make it live again. ACP terminals describes the separate terminal capability.

Process reliability remains a distinct limit: issue #1193 tracks an unverified ACP process exit during concurrent network activity. A client should report that interruption and keep completed, saved work visible; ACP protocol support alone does not prove the desktop can finish every active turn.