Add an example agent that asks before it writes

[AntoniTok]

Builds on #43, which added a per-command write capability plus a gate and an audit hook. This is a worked example of all three, and it exists because those seams are hard to judge in the abstract: the interesting question is not what they do but what they let you stop worrying about.

There are two ways to keep a model from wrecking a workspace, and only one of them is a boundary. You can read the command and decide, which is a heuristic. Or you can withhold the capability, so that a command that was not approved runs against a filesystem handle with no write access and its writes fail whatever anybody believed about them.

Before #43 only the first was available, which is why its holes mattered. This example carries a matcher that was written when it was load-bearing, and an early version of it waved through find /workspace -mindepth 1 -delete, because the verb was on the allowlist and its flags were not.

Putting the capability underneath changes what the matcher is for. Its job shrinks from stopping damage to reducing interruptions, and its failure modes stop being symmetrical. Getting a read wrong costs one question nobody needed to answer. Getting a write wrong means the command runs read-only and fails visibly. Neither loses a file, and that is the only reason a matcher built from a verb allowlist and a few regular expressions belongs anywhere near the decision.

So the two decisions are wired to a single predicate:

writable: (input) => decideApproval(input, policy).needsApproval

which reads backwards until you notice when it runs. The AI SDK does not call a tool's execute until approval has been granted, so asking for write access exactly when approval was required states the property the example is built around: a command runs with write access if and only if a human approved it. Two things that could drift apart are one decision instead.

The example runs one workspace over all three backends, because a withheld capability is enforced in a different place in each. The two Dynamic Worker backends reach the workspace over RPC, so a refused write fails inside the command. The container writes to its own copy of the tree and meets the refusal on write-back, where it surfaces as skipped entries rather than as a failed command. Only the shell backend gets the matcher: the container runs real binaries with public network access and is also where a refusal lands late, so it is the worst place to be guessing, and the JavaScript backend evaluates a module whose effects are not a function of any verb.

The gate and the audit hook are installed on the Workspace rather than around the agent, which is the point of them being there — the tool layer only covers the model's path. The gate is not a second copy of the approval decision, and it cannot be: a gate runs once the action exists, and there is nowhere to suspend a running command that does not risk a partial result. What it does is check the invariant from the other side. A command holding write access should be one the matcher would have raised a question about, since that is the only route to write access through the tool layer. A recognized read that turns up wanting write access did not come that way, and it is narrowed back to read-only, which costs it nothing the matcher says it needed.

Two smaller decisions worth flagging. The conversation lives on the client, so an approval arrives as a claim the client makes about something the user supposedly did; the approval requests are signed and checked on replay, with a key generated per durable object and kept in its own storage, so there is nothing to configure and nothing to leak through a binding. And the model gets read and ls but no write or edit tool, so every mutation goes through the one door the policy watches — an example that asks carefully about find -delete while an unguarded write tool sits next to it would teach the reader something false about where the boundary is.

To try it:

npm run build
npm run dev --workspace @example/computer-agent     # Docker, for the container backend
curl -X PUT --data-binary 'hello world' localhost:8787/c/default/file/workspace/hello.txt
npm run chat --workspace @example/computer-agent

Ask it to read that file and it answers without asking. Ask it to delete everything under /workspace and the turn stops. Either way GET /c/default/audit shows what the workspace recorded, including the write access each command actually held.

Three test files, and the third is the one that earns its place. One pins what the matcher says. One pins the invariant above and the gate's narrowing. The third runs every command the policy would allow through just-bash itself, against a filesystem that records every mutation, and fails if any of them wrote — 630 commands generated, 475 allowed unattended, none of them writing. Assertions about a matcher are written by whoever wrote the matcher, from the same blind spot, so they find the cases somebody thought of; both real defects in this policy were found by running the agent by hand and noticing. The corpus derives its verbs from the allowlist rather than from a copy, so a verb added later comes under test without anybody remembering to.

This supersedes #21, which reached the same conclusion from the other end: it built the matcher, found it wanting, and said the boundary belonged at the capability layer instead. That is now built, so the matcher can be what it should always have been — a way to ask fewer questions.

The example has its own README, the chapter on write access and approval now points at it from the section on asking a human, and the continuous integration example matrix picks the workspace up so its tests and typecheck run.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@44

commit: 1801b49