graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
ACP permission ownership model
The desktop transport modeled here was the desktop app that used to live in this repository. The desktop app is now Harness; the server-side half of the model still describes
graff acp.
AcpPermissions.tla checks the permission decision path across a server bridge and the desktop transport. The finite baseline has two worker generations. Both use the same saved session name and the same server request ID (1); their token atoms differ. This makes a stale desktop response meaningful even when ordinary ID and session checks would pass. The token atoms abstract unpredictable, distinct UUIDs, not their random number generator.
The model separates parsing a server request (FrontendReceive) from delivering it to the GUI (GuiDeliver), choosing a response (FrontendRespond), and reading that response on server stdin (ServerAccept). It also separates frontend cancellation (FrontendCancel) from server cancellation (ServerCancel). This allows a response to be accepted before cancel, or to be queued and rejected after cancel. Restart changes the active worker and clears its live token while leaving a historical GUI token available for a stale-click test. A queued wire response remains addressed to its original transport.
| Model step or guard | Current implementation |
|---|---|
ServerAsk, one pending request, offered choices |
src/acp_permission.zig Bridge.ask, especially the closed/pending check, sequence assignment, and option array |
FrontendReceive, transport-local token |
The ACP client (Harness; formerly this repository's desktop app) creates a token and stores request ID, session, and offered options per transport |
GuiDeliver |
The ACP client shows the request for prompt and idle streams |
FrontendRespond and token consumption |
The ACP client answers against the current chat; it checks token, session, option, and failure, and deletes the token before writing |
ServerAccept |
src/acp_permission.zig Bridge.accept checks the pending server ID, closed/decision state, and offered allow_always; an unknown result becomes denial |
FrontendCancel |
AcpTransport.notify("session/cancel"), clearPermissions, transport failure, or prompt completion clears live tokens |
ServerCancel |
Bridge.cancel, called from src/acp_inbox.zig on cancellation or EOF and from src/acp_live_turn.zig on turn exit |
Restart |
The route's current chat slot can point to a replacement AcpTransport; an old token is absent from its map even if the saved session and server ID recur |
StaleTransportNeverGrants checks every recorded grant's token owner against the worker that granted it. CancelNeverGrantsLate checks the pending and cancellation state at acceptance; it does not say that a later cancel revokes a completed grant or tool execution. UnofferedNeverGrants checks the server's independent allowlist with InjectUnoffered, an invalid allow_always response that bypasses the frontend. TokenConsumedAtMostOnce checks frontend token consumption. The first three inspect a grant history rather than merely restating state types. There is no liveness claim: a client may disconnect or never answer, and the source does not promise eventual approval or rejection without an external event.
The normal configuration is AcpPermissions.cfg. Three targeted negative controls change transition guards: AcpPermissionsNoTokenOwner.cfg lets a previously delivered token be sent through a replacement transport and violates StaleTransportNeverGrants; AcpPermissionsNoCancelGuard.cfg lets an in-flight response grant after server cancellation and violates CancelNeverGrantsLate; AcpPermissionsNoConsume.cfg retains a token after sending and allows a second send, violating TokenConsumedAtMostOnce. Each counterexample uses the same action sequence as the baseline until the removed guard matters.
This is a state-machine abstraction, not a proof of the Zig or TypeScript implementations. It assumes serial processing within each bridge/transport, correctly scoped chat lookup, and distinct generated tokens; it abstracts JSON parsing, OS process lifetime, write errors, clock time, persistent approvals, and engine policy checks. It fixes the session name to the same value in both generations, so it exercises the harder repeated-session restart case but does not check wrong-session input. It bounds one request per worker generation and one in-flight wire response; arbitrary duplicate server replies are outside the state space, while duplicate desktop clicks are rejected by token removal. A direct client with stdin access is the ACP trust boundary: the server can accept a valid pending allow_once response without a desktop token. The model's token-ownership property therefore applies to the desktop route, while the server's pending-ID and option checks are modeled separately. Bridge.begin is used only after the previous ask has retired; this is an explicit source/lifecycle assumption, not a property established by this model.