examples/agent: keep the approval signature across the turn

The worker signs every approval it asks for. It has to: the
conversation lives in the terminal, so an answer arrives as a claim the
client makes about something the operator supposedly did, and on that
claim rests the write access the command is about to be given. The AI
SDK checks the signature before it will run the tool call, which is
what stops an approval that was never issued.

The terminal UI throws the signature away. Recording an answer replaces
part.approval rather than adding to it, so what goes back is unsigned
and the turn dies with AI_InvalidToolApprovalSignatureError: missing
signature. Every published @ai-sdk/tui through 1.0.52 does this, so
every approval in this example failed, which is to say the flow the
example exists to show did not work.

Wrap the transport instead of forking the UI. It notes the signature on
each approval request passing through, and restores it on the answer
that comes back. This is a repair, not a loophole: a signature is not a
secret but a MAC only the worker can produce or check, the cache can
only supply one the worker itself issued for that exact approval id, and
carrying it across a turn it was always meant to survive gives the
client nothing it did not already have. A forged approval still has
nothing to present.

Author: Antoni T

examples/agent/README.md

@@ -107,6 +107,27 @@ 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.
 
+## The approval has to survive the trip
+
+The conversation lives in the terminal, not in the Durable Object. An
+answer to an approval therefore arrives as a claim the client makes
+about something you supposedly did, and on that claim rests the write
+access the command is about to get. So the worker signs every approval
+it asks for, with a per-object key it keeps in storage, and the AI SDK
+checks the signature before it will run the tool call. An approval that
+was never issued has nothing to present.
+
+The terminal UI drops the signature. Recording your answer replaces the
+approval rather than adding to it, so what goes back is unsigned and
+the turn dies with `missing signature`. That is true of every published
+`@ai-sdk/tui` through 1.0.52, so the client wraps its transport to
+remember the signatures it saw and put them back:
+[`cli/approval-signatures.mjs`](cli/approval-signatures.mjs). The
+repair belongs in the transport because a signature is not a secret —
+it is a MAC only the worker can produce or check — and carrying one
+across a turn it was always meant to survive gives the client nothing
+it did not already have.
+
 ## Running it
 
 ```bash

examples/agent/cli/approval-signatures.mjs

@@ -0,0 +1,78 @@
+/**
+ * A chat transport that remembers the signatures on the approvals it
+ * saw, and puts them back on the answers it sends.
+ *
+ * The worker signs every approval it asks for, because the conversation
+ * lives in this process: an answer arrives as a claim the client makes
+ * about something you supposedly did, and the signature is what makes
+ * that claim checkable. The AI SDK verifies it before it will run the
+ * tool call.
+ *
+ * The terminal UI drops it. Recording an answer replaces the whole
+ * approval object rather than adding to it:
+ *
+ *     part.approval = { id: request.approvalId, approved, ...reason };
+ *
+ * so the signature the worker issued is gone by the time the answer is
+ * posted back, and the turn dies with
+ * `AI_InvalidToolApprovalSignatureError: missing signature`. That is
+ * true of every published @ai-sdk/tui through 1.0.52.
+ *
+ * A signature is not a secret — it is a MAC the worker issued over an
+ * approval id, and only the worker can make or check one. Carrying it
+ * across a turn it was always meant to survive grants this client
+ * nothing it did not already have, which is why the repair belongs
+ * here, in the transport, rather than in a fork of the UI. The cache
+ * only ever supplies a signature the worker itself sent for that exact
+ * approval id, so a forged approval still has nothing to present.
+ */
+
+/**
+ * Wrap a chat transport so approval signatures survive the round trip.
+ *
+ * @template {{ sendMessages: (options: any) => Promise<ReadableStream<any>> }} T
+ * @param {T} transport
+ * @returns {T}
+ */
+export function withApprovalSignatures(transport) {
+  /** @type {Map<string, string>} */
+  const signatures = new Map();
+
+  return Object.create(transport, {
+    sendMessages: {
+      value: async (options) => {
+        for (const message of options.messages ?? []) {
+          for (const part of message.parts ?? []) restore(part, signatures);
+        }
+        const stream = await transport.sendMessages(options);
+        return stream.pipeThrough(remember(signatures));
+      },
+    },
+  });
+}
+
+/**
+ * Re-attach the signature for an answered approval, if we have one and
+ * the answer is missing it.
+ */
+function restore(part, signatures) {
+  const approval = part?.approval;
+  if (!approval || approval.signature !== undefined) return;
+  const signature = signatures.get(approval.id);
+  if (signature !== undefined) approval.signature = signature;
+}
+
+/**
+ * Note the signature on every approval the worker asks for, passing the
+ * stream through untouched.
+ */
+function remember(signatures) {
+  return new TransformStream({
+    transform(chunk, controller) {
+      if (chunk?.type === "tool-approval-request" && chunk.signature !== undefined) {
+        signatures.set(chunk.approvalId, chunk.signature);
+      }
+      controller.enqueue(chunk);
+    },
+  });
+}

examples/agent/cli/approval-signatures.test.mjs

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { withApprovalSignatures } from "./approval-signatures.mjs";
+
+function streamOf(chunks) {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  });
+}
+
+async function drain(stream) {
+  const reader = stream.getReader();
+  const out = [];
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return out;
+    out.push(value);
+  }
+}
+
+// Stands in for the worker: hands back whatever chunks the test names
+// and remembers the messages it was asked to send.
+function fakeTransport(chunks = []) {
+  const transport = {
+    sent: [],
+    async sendMessages(options) {
+      transport.sent.push(options);
+      return streamOf(chunks);
+    },
+    async reconnectToStream() {
+      return null;
+    },
+  };
+  return transport;
+}
+
+const request = {
+  type: "tool-approval-request",
+  approvalId: "aitxt-1",
+  toolCallId: "call-1",
+  signature: "sig-1",
+};
+
+// The exact mutation @ai-sdk/tui performs on a "yes": the whole
+// approval object is replaced, so the signature the worker issued does
+// not survive. See applyToolApprovalResponse in @ai-sdk/tui.
+function answerLikeTheTUI(part, approved) {
+  part.state = "approval-responded";
+  part.approval = { id: part.approval.id, approved };
+}
+
+function respondedMessage(approved = true) {
+  const part = {
+    type: "tool-exec",
+    toolCallId: "call-1",
+    state: "approval-requested",
+    input: { command: "rm /workspace/x" },
+    approval: { id: "aitxt-1", signature: "sig-1" },
+  };
+  answerLikeTheTUI(part, approved);
+  return { id: "m1", role: "assistant", parts: [part] };
+}
+
+describe("withApprovalSignatures", () => {
+  it("passes the worker's chunks through untouched", async () => {
+    const inner = fakeTransport([{ type: "start" }, request]);
+    const stream = await withApprovalSignatures(inner).sendMessages({ messages: [] });
+    expect(await drain(stream)).toEqual([{ type: "start" }, request]);
+  });
+
+  it("puts back the signature the terminal UI dropped", async () => {
+    const inner = fakeTransport([request]);
+    const transport = withApprovalSignatures(inner);
+
+    // Turn one: the worker asks, and the signature goes by on the wire.
+    await drain(await transport.sendMessages({ messages: [] }));
+
+    // Turn two: the answer comes back without it.
+    await transport.sendMessages({ messages: [respondedMessage(true)] });
+
+    const part = inner.sent[1].messages[0].parts[0];
+    expect(part.approval).toEqual({ id: "aitxt-1", approved: true, signature: "sig-1" });
+  });
+
+  it("signs a refusal too, so a no is as checkable as a yes", async () => {
+    const inner = fakeTransport([request]);
+    const transport = withApprovalSignatures(inner);
+    await drain(await transport.sendMessages({ messages: [] }));
+
+    await transport.sendMessages({ messages: [respondedMessage(false)] });
+
+    const part = inner.sent[1].messages[0].parts[0];
+    expect(part.approval).toMatchObject({ approved: false, signature: "sig-1" });
+  });
+
+  it("leaves an approval alone when it never saw a signature for it", async () => {
+    const inner = fakeTransport([]);
+    const transport = withApprovalSignatures(inner);
+
+    await transport.sendMessages({ messages: [respondedMessage(true)] });
+
+    const part = inner.sent[0].messages[0].parts[0];
+    expect(part.approval).toEqual({ id: "aitxt-1", approved: true });
+  });
+
+  it("does not overwrite a signature that survived", async () => {
+    const inner = fakeTransport([request]);
+    const transport = withApprovalSignatures(inner);
+    await drain(await transport.sendMessages({ messages: [] }));
+
+    const message = respondedMessage(true);
+    message.parts[0].approval.signature = "sig-from-elsewhere";
+    await transport.sendMessages({ messages: [message] });
+
+    expect(inner.sent[1].messages[0].parts[0].approval.signature).toBe("sig-from-elsewhere");
+  });
+
+  it("keeps signatures apart when a turn asks about two commands", async () => {
+    const second = { ...request, approvalId: "aitxt-2", toolCallId: "call-2", signature: "sig-2" };
+    const inner = fakeTransport([request, second]);
+    const transport = withApprovalSignatures(inner);
+    await drain(await transport.sendMessages({ messages: [] }));
+
+    const message = respondedMessage(true);
+    const other = {
+      type: "tool-exec",
+      toolCallId: "call-2",
+      state: "approval-requested",
+      approval: { id: "aitxt-2", signature: "sig-2" },
+    };
+    answerLikeTheTUI(other, true);
+    message.parts.push(other);
+    await transport.sendMessages({ messages: [message] });
+
+    const parts = inner.sent[1].messages[0].parts;
+    expect(parts[0].approval.signature).toBe("sig-1");
+    expect(parts[1].approval.signature).toBe("sig-2");
+  });
+
+  it("delegates the rest of the transport", async () => {
+    const inner = fakeTransport([]);
+    expect(await withApprovalSignatures(inner).reconnectToStream({})).toBeNull();
+  });
+});

examples/agent/cli/chat.mjs

@@ -11,13 +11,16 @@
  * There is deliberately very little here. The AI SDK's terminal UI
  * already knows how to render a pending approval and send the answer
  * back, and the worker speaks the UI message stream that
- * `DefaultChatTransport` posts to, so the whole client is a URL.
+ * `DefaultChatTransport` posts to, so the client is a URL and one
+ * wrapper.
  *
  * The conversation lives in this process rather than on the server,
  * which is why the worker signs its approval requests: an approval
  * comes back as a claim this client makes about something you
  * supposedly did, and the signature is what makes that claim checkable
- * rather than merely plausible.
+ * rather than merely plausible. The wrapper is there because the
+ * terminal UI throws that signature away when it records your answer;
+ * ./approval-signatures.mjs explains what it does about it.
  *
  * The worker has to be running first (`npm run dev`, default
  * http://127.0.0.1:8787). Point somewhere else with --worker or the
@@ -39,6 +42,7 @@
 import { argv, env, exit, stderr } from "node:process";
 import { runAgentTUI } from "@ai-sdk/tui";
 import { DefaultChatTransport } from "ai";
+import { withApprovalSignatures } from "./approval-signatures.mjs";
 
 const { workerUrl, name, title } = parseArgs(argv.slice(2));
 
@@ -55,7 +59,10 @@ const api = new URL(`/c/${encodeURIComponent(name)}/agent`, base).toString();
 stderr.write(`talking to ${api}\n`);
 
 await runAgentTUI({
-  transport: new DefaultChatTransport({ api }),
+  // The wrapper is not decoration: the terminal UI drops the signature
+  // off an approval when it records your answer, and the worker will
+  // not run an unsigned one. See ./approval-signatures.mjs.
+  transport: withApprovalSignatures(new DefaultChatTransport({ api })),
   title: title ?? `computer-agent · ${name}`,
 });