Add an example agent that asks before it writes

[AntoniTok]

Builds on #43, which added a per-command write flag plus a gate and an audit hook. This is a worked example of all three, because those seams are hard to judge in the abstract.

Three things it shows.

First, write access and human approval are one decision rather than two. A command runs with write access if and only if a human approved it. That holds by construction rather than by two pieces of code agreeing with each other.

Second, one workspace over all three backends. A withheld flag is enforced in a different place in each, and the difference changes how much you can trust it.

Third, a gate installed on the workspace rather than around the agent, checking that rule from the other side. The tool layer only covers the model's path, and the workspace has other callers.

There are two ways to keep a model from wrecking a workspace, and only one of them is a real boundary. You can read the command and decide, which is a guess. Or you can withhold write access, so an unapproved command runs against a filesystem handle that cannot write and its writes fail whatever anybody believed. Before #43 only the first was available, which is why its holes mattered. An early version of the matcher here waved through find /workspace -mindepth 1 -delete, because the verb was on the allowlist and its flags were not.

Putting the flag underneath shrinks the matcher's job from stopping damage to asking fewer questions. It also makes the two ways of being wrong very different. Call a read a write, and someone answers a needless question. Call a write a read, and the command runs read-only and fails in the open. Neither loses a file, which is the only reason a verb allowlist and a few regular expressions belong anywhere near the decision.

So both decisions come from one function.

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

That reads backwards until you notice when it runs. The AI SDK does not call a tool's execute until approval has been granted. Asking for write access exactly when approval was required is what ties the two together. Only two of the four combinations can happen.

	a human was asked	nobody was asked
runs with writable: true	the write path, approval was required and granted	cannot happen
runs with writable: false	cannot happen	the read path, a known read that ran on its own

The empty cells are the point. Write access without a question would mean the matcher handed it out, which is what this example exists to avoid. A question followed by no write access would mean somebody was interrupted for nothing. Neither can happen, because there is one decision rather than two that could drift apart.

flowchart TD
  M["model emits exec('rm -rf /workspace')"]
  D{"decideApproval(command, backend)<br/>backend rule first, then the matcher"}
  PAUSE["turn pauses, the human is asked"]
  H{"human answers"}
  YES["runs with write access"]
  NO["command never runs,<br/>the model is told why"]
  AUTO["runs read-only,<br/>nobody was asked"]
  GATE{"gate checks the rule again"}
  NARROW["narrowed to read-only"]
  AUDIT["audit records what happened,<br/>including the access actually held"]

  M --> D
  D -->|needs approval| PAUSE --> H
  H -->|approved| YES --> GATE
  H -->|denied| NO
  D -->|a known read| AUTO --> GATE
  GATE -->|access the matcher backs| AUDIT
  GATE -->|"a read that arrived asking to write"| NARROW --> AUDIT

Loading

The three backends differ in where a refused write is caught, which is why they do not get the same rule.

Backend	Runs	A refused write lands	Default rule
worker-shell	just-bash in a Dynamic Worker	inside the command, as a read-only error	matcher decides
worker-javascript	a module in a Dynamic Worker	inside the module, the same way	always ask
container-shell	real coreutils under computerd	on the way back, as skipped entries	always ask

Only worker-shell gets the matcher. A bash line is the one language here whose effect you can read off its text with any confidence. The container runs real binaries with public network access, and it is also where a refusal lands late, so it is the worst place to be guessing. The JavaScript backend runs a module whose effects follow from what it imports rather than from any verb.

The gate is not a second copy of the approval decision, and it cannot be. It runs once the action exists, and there is nowhere to pause a running command that does not risk a half-finished result. What it does is check the rule from the other side.

Gate sees	Matcher	Gate does
shell.exec without write access	never runs	allow, nothing to check
shell.exec with write access	needs approval	allow, the access was earned
shell.exec with write access	a known read	narrow to read-only
a filesystem action	never runs	allow, and record it

The third row cannot happen through the tool layer, since that route goes through the matcher. A command holding write access the matcher would not have asked about came from somewhere else, either a new caller or an edited resolver. Narrowing costs it nothing the matcher says it needed. Filesystem actions are allowed because nothing the model can call reaches them. The routes that do are how the workspace gets seeded.

To try it, run this from the repo root.

npm run build
npm run dev --workspace @example/computer-agent

wrangler dev builds the container image before it starts, so a machine that cannot build it gets none of the example. There is a second configuration without the container. It behaves the same except that asking for the container backend fails.

npm run dev:local --workspace @example/computer-agent

Then, in another terminal, give it something to look at and start talking.

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 so you can approve or refuse. That only happens once the model actually issues the command, and a small model may look around first or decline to run it at all. The tests pin the decision itself, so it does not depend on which model you get. Either way GET /c/default/audit shows what the workspace recorded, including the write access each command actually held.

Four test files, run with npm test --workspace @example/computer-agent. One pins what the matcher says, one pins the rule above and the gate's narrowing, and one pins the signature repair. The third is the one that earns its place. It runs every command the policy would allow through just-bash itself, against a filesystem that records every change, and fails if any of them wrote. That is 630 commands generated, 475 allowed on their own, none writing. Tests for a matcher are written from the same blind spot as the matcher, so they find the cases somebody already thought of. Both real defects in this policy were found by running the agent by hand instead. The corpus builds its verbs from the allowlist rather than from a copy, so a verb added later comes under test without anyone remembering to.

Running it against wrangler dev turned up two defects, both fixed here. Nothing created /workspace on a fresh object when no bucket was mounted under it, and every approval failed on a dropped signature. The container backend is the one path still untested locally, because building its image needs network this machine does not have.

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. 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 approval chapter points at it from the section on asking a human, and the continuous integration matrix picks the workspace up.

Why the approval has to be signed, and why the client repairs it (not core to the example)

The conversation lives in the terminal, not in the durable object. So an answer to an approval is just a claim the client makes. On that claim rests the write access the command is about to get. The worker therefore signs every approval it asks for, and checks the signature before the tool call runs. The key is made per object and kept in that object's own storage. An approval that was never issued has nothing to present, and there is nothing to configure and nothing to leak through a binding.

Recording an answer in the terminal interface replaces the approval rather than adding to it. That throws the signature away and kills the turn. Every published @ai-sdk/tui through 1.0.52 does this, so the client wraps its transport to note signatures on the way in and put them back on the way out. That wrapper is the difference between the approval flow working and every approval failing. The repair belongs in the transport because a signature is not a secret. Only the worker can make one or check one, so carrying it across a turn gives the client nothing it did not already have.

The container's weaker enforcement, and a probe for fixing it later (not core to the example)

script/container-mount-probe.sh is not a fix. It is the question the container's late refusal keeps raising. A read-only mount inside a private mount view would stop the write up front there too. The kernel refuses before the write reaches a file, so nothing lands. The view belongs to one process, so a read-only command cannot disarm a writable one beside it. That is the same shape as two filesystem handles over one store, with the kernel holding the flag.

Whether a container can make a mount view depends on the runtime rather than on this repository, so the script asks. It works under an unprivileged user namespace with no added rights, wherever the syscall filter allows the call. Worth knowing before anyone argues the container's rule should be anything other than always asking.

[pkg-pr-new]

Open in StackBlitz

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

commit: f60e2c2