@buoy-gg/agent-core 7.0.36 → 7.0.39

package/lib/module/engine/runAgentTurn.js

@@ -35,8 +35,11 @@ import { projectReceipt } from "../blocks/receipts";
 import { isAskBlock } from "../blocks/types";
 import { ACQUISITION_CALLS, synthesizeAskBlock, synthesizeShortfallBlock } from "./askGate";
 import { couldBeToolCallEnvelope, parseTextToolCalls, SALVAGE_NOTE } from "./textToolCalls";
-import { budgetForRequest } from "./historyBudget";
-
+import { budgetForRequest, MAX_HISTORY_TOKENS, messageSize } from "./historyBudget";
+import { promptTokensOf, TokenCalibration } from "./tokenCalibration";
+import { truncationMarker } from "./evidence";
+import { retrieveEvidence } from "./retrieve";
+import { verificationTrailer, verifyOutcome } from "./verify";
 /** Beyond this a tool result costs more in tokens than it can possibly be worth. */
 const MAX_RESULT_CHARS = 24_000;
 /**
@@ -71,6 +74,73 @@ function callSignature(calls) {
 const LOOP_WARNING = "[Buoy] You have now made this exact call three times in a row and gotten the same thing back. Repeating it again will not change the answer. Read the result you already have, then either try a different tool or different arguments, or tell the user plainly what you could not get and what you tried.";
 const DEFAULT_MAX_STEPS = 12;
 const DEFAULT_TURN_MS = 180_000;
+
+/**
+ * Retrying a model request — narrowly.
+ *
+ * A 429 from a shared gateway, a 529 / `overloaded_error` from Anthropic, or
+ * a "prompt is too long" 400 used to end the turn with an error card and Try
+ * again — and Try again re-sends the QUESTION, restarting an investigation
+ * that may already have written things. All three fail before a model has
+ * generated anything, so asking again is safe: nothing runs twice, nothing
+ * is billed twice. The rule that makes it safe is enforced, not assumed —
+ * a request is only retried when its stream produced NO text, tool call or
+ * thinking; once anything has come back, the existing no-replay handling
+ * stands (see providers/transport.ts on consumed-exactly-once).
+ *
+ * Throttled: up to two retries, 1 s then 2 s (plus jitter), a `Retry-After`
+ * winning when the endpoint sent one. Overflow: one retry, with the history
+ * ceiling halved first — the proactive budget is chars ÷ 4 and the provider
+ * just said that was optimistic. Both wait inside the turn deadline and stop
+ * on the user's Stop. Small numbers on purpose: this is a phone, not a
+ * server queue.
+ */
+const THROTTLE_RETRIES = 2;
+const OVERFLOW_RETRIES = 1;
+const RETRY_BASE_MS = 1_000;
+const RETRY_JITTER_MS = 250;
+const RETRY_AFTER_CAP_MS = 30_000;
+function sleep(ms, signal) {
+  return new Promise(resolve => {
+    if (signal?.aborted) return resolve();
+    const t = setTimeout(done, ms);
+    function done() {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, {
+      once: true
+    });
+  });
+}
+
+/**
+ * Why the turn ended — the machine-readable half of the notices. The text in
+ * the notice blocks is unchanged (the eval classifier pins it); this is for a
+ * host, the bank and the desktop, which used to have to grep the prose.
+ */
+
+/** Normalise an answer to its parts, so both call sites read one shape. */
+function readAnswer(answer) {
+  if (typeof answer === "boolean") return {
+    approved: answer,
+    trust: false
+  };
+  const reason = answer.reason?.trim();
+  return {
+    approved: answer.approved,
+    ...(reason ? {
+      reason
+    } : {}),
+    trust: answer.trust === true && answer.approved
+  };
+}
+
+/** What the model is told when the user says no — with their note, when they left one. */
+function declinedResult(reason) {
+  return reason ? `The user declined this change and said: "${reason}". Do not retry it as proposed; take their note into account and, if a different change would fit, propose that instead.` : "The user declined this change. Do not retry it; ask what they would prefer.";
+}
 function findDescriptor(catalog, toolId, action) {
   return catalog.find(t => t.toolId === toolId)?.actions.find(a => a.action === action);
 }
@@ -85,15 +155,20 @@ function findDescriptor(catalog, toolId, action) {
  */
 const URL_PROVENANCE_REJECTION = "Rejected: every image URL must be one you read from a tool result in THIS conversation (images.list, a storage value, a response body). Never invent or remember URLs — read them first, then show them.";
 const droppedImageNote = n => ` NOTE: ${n} image ${n === 1 ? "URL was" : "URLs were"} dropped — they were not read from a tool result in this conversation, so the card the user is looking at has no picture there. Do not tell them it does; read the URLs and show it again, or say the artwork is missing.`;
-function encodeResult(value) {
-  let text;
+
+/** The whole result as text — what the evidence store keeps. */
+function fullText(value) {
   try {
-    text = JSON.stringify(value ?? null);
+    return JSON.stringify(value ?? null);
   } catch {
-    text = String(value);
+    return String(value);
   }
+}
+
+/** What the model is sent: the text, cut at the cap with a marker that names where the rest is. */
+function encodeResult(text, ref) {
   if (text.length <= MAX_RESULT_CHARS) return text;
-  return `${text.slice(0, MAX_RESULT_CHARS)}\n\n[truncated — ${text.length} characters total. Ask for a narrower slice if you need more.]`;
+  return `${text.slice(0, MAX_RESULT_CHARS)}${truncationMarker(text.length, ref)}`;
 }
 
 /** A short line for the transcript row, so the UI never renders raw payloads. */
@@ -162,8 +237,14 @@ export async function* runAgentTurn(input) {
     policy,
     isRelease,
     requestApproval,
-    signal
+    signal,
+    evidence,
+    trusted,
+    procedures
   } = input;
+  /** Notes the user left with a decline, by call id — see declinedResult. */
+  const declineReasons = new Map();
+  const calibration = input.calibration ?? new TokenCalibration();
   const messages = [...input.messages];
   const tools = toProviderTools(catalog, {
     availableToolIds: input.availableToolIds,
@@ -187,7 +268,9 @@ export async function* runAgentTurn(input) {
    * much to leave out of a budget. `maxTokens` is multiplied by four because
    * the budget is in characters.
    */
-  const requestReserve = system.length + (systemVolatile?.length ?? 0) + tools.reduce((n, t) => n + t.description.length + JSON.stringify(t.inputSchema).length, 0) + maxTokens * 4;
+  const fixedChars = system.length + (systemVolatile?.length ?? 0) + tools.reduce((n, t) => n + t.description.length + JSON.stringify(t.inputSchema).length, 0);
+  /** The reserve at the ratio believed RIGHT NOW — it moves as usage reports come in. */
+  const requestReserve = () => fixedChars + calibration.chars(maxTokens);
   /**
    * Caps the AGENT's wall-clock, not the user's. Time spent parked on an
    * approval sheet is pushed onto the deadline as it is spent (see the
@@ -196,6 +279,13 @@ export async function* runAgentTurn(input) {
    * for the turn that applied it.
    */
   let deadline = Date.now() + DEFAULT_TURN_MS;
+  /** Retries spent this turn, per kind — the budget is per turn, not per step. */
+  const retries = {
+    throttled: 0,
+    overflow: 0
+  };
+  /** Tightened after an overflow; see budgetForRequest's `cap`. In tokens, so a calibration change re-scales it. */
+  let historyCapTokens = MAX_HISTORY_TOKENS;
 
   // Every http(s) URL that appeared in a tool result in this CONVERSATION.
   // The prompt tells the model image URLs must come from here; this Set is
@@ -241,7 +331,8 @@ export async function* runAgentTurn(input) {
   for (let step = 0; step < maxSteps; step++) {
     if (signal?.aborted) {
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "stopped"
       };
       return messages;
     }
@@ -268,7 +359,8 @@ export async function* runAgentTurn(input) {
         }
       };
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "time-cap"
       };
       return messages;
     }
@@ -286,13 +378,14 @@ export async function* runAgentTurn(input) {
      *
      * The current round is never touched: it is the question being answered.
      */
-    const budgeted = budgetForRequest(messages, requestReserve);
+    const budgeted = budgetForRequest(messages, requestReserve(), calibration.chars(historyCapTokens), calibration.charsPerToken, ledger.liveCallIds());
     if (budgeted.droppedRounds > 0) {
       messages.length = 0;
       messages.push(...budgeted.messages);
       yield {
         type: "history-trimmed",
-        droppedRounds: budgeted.droppedRounds
+        droppedRounds: budgeted.droppedRounds,
+        droppedPinned: budgeted.droppedPinned
       };
     } else if (budgeted.messages !== messages) {
       messages.length = 0;
@@ -318,7 +411,7 @@ export async function* runAgentTurn(input) {
         delta
       };
     };
-    const calls = [];
+    let calls = [];
     /**
      * Recovered from text rather than emitted as calls — see textToolCalls.ts.
      * Tracked by id so each one's result can tell the model to stop doing that;
@@ -335,7 +428,7 @@ export async function* runAgentTurn(input) {
     let holding = true;
     // Carried, never read: Anthropic requires the turn's thinking blocks back
     // verbatim with its tool results. See providers/anthropic.ts note 5.
-    const thinking = [];
+    let thinking = [];
     let failed = false;
     /**
      * What the provider said about how the stream ended.
@@ -348,80 +441,166 @@ export async function* runAgentTurn(input) {
     let outcome;
     /** Set for the two kinds that are recoverable rather than a hard failure. */
     let incomplete;
-    for await (const ev of provider.send({
-      messages,
-      system,
-      systemVolatile,
-      tools,
-      model,
-      maxTokens,
-      signal
-    })) {
-      if (ev.type === "text") {
-        text += ev.delta;
-        if (!holding) {
-          yield textEvent(ev.delta);
-        } else if (couldBeToolCallEnvelope(text)) {
-          held += ev.delta;
-        } else {
-          // Not an envelope after all. Release everything at once and stream
-          // the rest as usual — the reader loses nothing but a few characters
-          // of latency at the very start of the answer.
-          holding = false;
-          held = "";
-          yield textEvent(text);
-        }
-      } else if (ev.type === "tool-call") {
-        calls.push(ev.call);
-      } else if (ev.type === "thinking") {
-        thinking.push(ev.block);
-        // Surfaced as well as carried: the block goes back to the provider
-        // verbatim (note above), and the readable half goes to the UI so a
-        // tester can see WHY a turn did what it did. Redacted blocks have no
-        // readable half and are carried only.
-        if (ev.block.type === "thinking" && ev.block.thinking.trim()) {
-          yield {
-            type: "reasoning",
-            text: ev.block.thinking
-          };
+
+    /**
+     * THE REQUEST, with its retries. One request per pass; a pass that fails
+     * before the model generated anything may be sent again (see
+     * THROTTLE_RETRIES). Everything the pass accumulated is reset first —
+     * there is nothing to keep, by the rule that made the retry safe.
+     */
+    for (;;) {
+      text = "";
+      calls = [];
+      held = "";
+      holding = true;
+      thinking = [];
+      failed = false;
+      outcome = undefined;
+      incomplete = undefined;
+      /** The failure that ended this pass, when it is one the engine may retry. */
+      let retryable;
+      /** What this pass sends, in characters — the numerator of the calibration sample. */
+      const sentChars = fixedChars + messages.reduce((n, m) => n + messageSize(m), 0);
+      for await (const ev of provider.send({
+        messages,
+        system,
+        systemVolatile,
+        tools,
+        model,
+        maxTokens,
+        signal
+      })) {
+        if (ev.type === "text") {
+          text += ev.delta;
+          if (!holding) {
+            yield textEvent(ev.delta);
+          } else if (couldBeToolCallEnvelope(text)) {
+            held += ev.delta;
+          } else {
+            // Not an envelope after all. Release everything at once and stream
+            // the rest as usual — the reader loses nothing but a few characters
+            // of latency at the very start of the answer.
+            holding = false;
+            held = "";
+            yield textEvent(text);
+          }
+        } else if (ev.type === "tool-call") {
+          calls.push(ev.call);
+        } else if (ev.type === "thinking") {
+          thinking.push(ev.block);
+          // Surfaced as well as carried: the block goes back to the provider
+          // verbatim (note above), and the readable half goes to the UI so a
+          // tester can see WHY a turn did what it did. Redacted blocks have no
+          // readable half and are carried only.
+          if (ev.block.type === "thinking" && ev.block.thinking.trim()) {
+            yield {
+              type: "reasoning",
+              text: ev.block.thinking
+            };
+          }
+        } else if (ev.type === "error") {
+          if (ev.kind === "truncated" || ev.kind === "timeout") {
+            // Not a failure the user did anything about, and not one Try again
+            // can fix — re-sending the QUESTION restarts an investigation that
+            // may already have written things. Held back from the error card
+            // (which is what draws Try again) and handled below as a recoverable
+            // stop with a Continue button.
+            incomplete = {
+              message: ev.message
+            };
+          } else if (ev.problem && (ev.problem.kind === "throttled" || ev.problem.kind === "overflow") && text === "" && calls.length === 0 && thinking.length === 0) {
+            // Nothing generated, and a kind that a wait or a trim can fix.
+            // Decided after the stream closes; the adapter returns on error.
+            retryable = {
+              problem: ev.problem,
+              message: ev.message
+            };
+          } else {
+            // A mid-stream error can arrive on an already-committed 200.
+            yield {
+              type: "error",
+              message: ev.message
+            };
+            failed = true;
+          }
+        } else if (ev.type === "done") {
+          outcome = ev.outcome;
+          if (ev.usage) {
+            // The provider just counted this prompt. One sample per request
+            // keeps the chars↔tokens ratio honest for the NEXT budget.
+            calibration.observe(sentChars, promptTokensOf(ev.usage, provider.protocol));
+            // Surfaced so a host can meter cost per seat. Parsed for a long time;
+            // went nowhere anyone could see.
+            yield {
+              type: "usage",
+              ...ev.usage,
+              model: ev.model
+            };
+          }
         }
-      } else if (ev.type === "error") {
-        if (ev.kind === "truncated" || ev.kind === "timeout") {
-          // Not a failure the user did anything about, and not one Try again
-          // can fix — re-sending the QUESTION restarts an investigation that
-          // may already have written things. Held back from the error card
-          // (which is what draws Try again) and handled below as a recoverable
-          // stop with a Continue button.
-          incomplete = {
-            message: ev.message
-          };
+      }
+      if (!retryable) break;
+      const kind = retryable.problem.kind;
+      const maxAttempts = 1 + (kind === "throttled" ? THROTTLE_RETRIES : OVERFLOW_RETRIES);
+      const spent = retries[kind];
+      let waitMs = kind === "throttled" ? Math.min(retryable.problem.retryAfterMs ?? RETRY_BASE_MS * 2 ** spent, RETRY_AFTER_CAP_MS) + Math.floor(Math.random() * RETRY_JITTER_MS) : 0;
+      let giveUp = spent >= maxAttempts - 1 || signal?.aborted === true || Date.now() + waitMs > deadline;
+      if (!giveUp && kind === "overflow") {
+        // Halve the ceiling and trim again. If that changes nothing — the
+        // current round alone is over the limit — a retry would only repeat
+        // the refusal, so report it instead.
+        historyCapTokens = Math.floor(historyCapTokens / 2);
+        const before = messages.reduce((n, m) => n + messageSize(m), 0);
+        const again = budgetForRequest(messages, requestReserve(), calibration.chars(historyCapTokens), calibration.charsPerToken, ledger.liveCallIds());
+        const after = again.messages.reduce((n, m) => n + messageSize(m), 0);
+        if (after >= before) {
+          giveUp = true;
         } else {
-          // A mid-stream error can arrive on an already-committed 200.
-          yield {
-            type: "error",
-            message: ev.message
-          };
-          failed = true;
-        }
-      } else if (ev.type === "done") {
-        outcome = ev.outcome;
-        if (ev.usage) {
-          // Surfaced so a host can meter cost per seat. Parsed for a long time;
-          // went nowhere anyone could see.
-          yield {
-            type: "usage",
-            ...ev.usage,
-            model: ev.model
+          messages.length = 0;
+          messages.push(...again.messages);
+          if (again.droppedRounds > 0) yield {
+            type: "history-trimmed",
+            droppedRounds: again.droppedRounds,
+            droppedPinned: again.droppedPinned
           };
         }
       }
+      if (giveUp) {
+        // Plain words first; the endpoint's own text after, for whoever files
+        // the bug. A user reading "prompt is too long: 213000 tokens" has no
+        // move; "start a new conversation" is one.
+        const plain = kind === "throttled" ? spent > 0 ? `The AI endpoint is rate-limiting requests — tried ${spent + 1} times.` : "The AI endpoint is rate-limiting requests." : "This conversation is too large for the AI endpoint and there was nothing older to trim. Start a new conversation, or ask a shorter question.";
+        yield {
+          type: "error",
+          message: `${plain} (${retryable.message})`
+        };
+        failed = true;
+        break;
+      }
+      retries[kind] += 1;
+      yield {
+        type: "retrying",
+        reason: kind,
+        attempt: retries[kind] + 1,
+        maxAttempts,
+        inMs: waitMs
+      };
+      if (waitMs > 0) await sleep(waitMs, signal);
+      if (signal?.aborted) {
+        yield {
+          type: "done",
+          stopReason: "stopped"
+        };
+        return messages;
+      }
     }
     if (failed) {
       // Whatever was withheld is the model's own words on the way to an error.
       // Show it rather than swallowing it.
       if (held) yield textEvent(held);
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "error"
       };
       return messages;
     }
@@ -477,7 +656,8 @@ export async function* runAgentTurn(input) {
         }
       };
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "incomplete"
       };
       return messages;
     }
@@ -535,7 +715,8 @@ export async function* runAgentTurn(input) {
         };
       }
       yield {
-        type: "done"
+        type: "done",
+        stopReason: asked ? "awaiting-user" : "answered"
       };
       return messages;
     }
@@ -688,6 +869,11 @@ export async function* runAgentTurn(input) {
       barrierRun = true;
       for (const p of planned) {
         if (!p?.gated || decided.has(p.call.id)) continue;
+        if (trusted?.has(`${p.toolId}.${p.action}`)) {
+          // Waived for this conversation: runs like any allowed write, no card.
+          decided.set(p.call.id, true);
+          continue;
+        }
         yield {
           type: "approval-required",
           id: p.call.id,
@@ -705,7 +891,7 @@ export async function* runAgentTurn(input) {
           dispatch,
           catalog
         });
-        const approved = requestApproval ? await requestApproval({
+        const answer = readAnswer(trusted?.has(`${p.toolId}.${p.action}`) ? true : requestApproval ? await requestApproval({
           id: p.call.id,
           toolId: p.toolId,
           action: p.action,
@@ -714,10 +900,13 @@ export async function* runAgentTurn(input) {
           reason: p.reason,
           params: p.params,
           targetDigest
-        }) : false;
+        }) : false);
         // The user's deliberation is not the agent's runtime.
         deadline += Date.now() - askedAt;
+        const approved = answer.approved;
         decided.set(p.call.id, approved);
+        if (answer.trust) trusted?.add(`${p.toolId}.${p.action}`);
+        if (answer.reason) declineReasons.set(p.call.id, answer.reason);
         if (!approved) {
           // One refusal ends the PLAN, not just the call. The remaining
           // changes were proposed together and nothing has run yet, so
@@ -969,7 +1158,7 @@ export async function* runAgentTurn(input) {
         for (const ev of unrunStep("declined")) yield ev;
         results.push({
           toolCallId: call.id,
-          content: decided.get(call.id) === false ? "The user declined this change. Do not retry it; ask what they would prefer." : "Not run — the user declined another change in this same batch, so none of it was applied. Ask what they would prefer before proposing it again.",
+          content: decided.get(call.id) === false ? declinedResult(declineReasons.get(call.id)) : "Not run — the user declined another change in this same batch, so none of it was applied. Ask what they would prefer before proposing it again.",
           isError: true
         });
         continue;
@@ -980,6 +1169,10 @@ export async function* runAgentTurn(input) {
           // The barrier already put this card up, before the batch's first
           // mutation. Asking again would be the same question twice.
           approved = decided.get(call.id);
+        } else if (trusted?.has(`${toolId}.${action}`)) {
+          // Waived for this conversation — see RunTurnInput.trusted.
+          approved = true;
+          decided.set(call.id, true);
         } else {
           // The barrier could not resolve this call (see `planned`), so it was
           // never offered. Ask here, exactly as this always did — a gate that
@@ -1004,7 +1197,7 @@ export async function* runAgentTurn(input) {
             dispatch,
             catalog
           });
-          approved = requestApproval ? await requestApproval({
+          const answer = readAnswer(requestApproval ? await requestApproval({
             id: call.id,
             toolId,
             action,
@@ -1013,11 +1206,14 @@ export async function* runAgentTurn(input) {
             reason: verdict.reason,
             params,
             targetDigest
-          }) : false;
+          }) : false);
           // The user's deliberation is not the agent's runtime. Give the clock
           // back before anything else can trip the deadline check.
           deadline += Date.now() - askedAt;
+          approved = answer.approved;
           decided.set(call.id, approved);
+          if (answer.trust) trusted?.add(`${toolId}.${action}`);
+          if (answer.reason) declineReasons.set(call.id, answer.reason);
         }
         if (!approved) {
           // The row is the whole point here. Without it the bubble read as a
@@ -1027,7 +1223,7 @@ export async function* runAgentTurn(input) {
           for (const ev of unrunStep("declined")) yield ev;
           results.push({
             toolCallId: call.id,
-            content: "The user declined this change. Do not retry it; ask what they would prefer.",
+            content: declinedResult(declineReasons.get(call.id)),
             isError: true
           });
           continue;
@@ -1101,17 +1297,30 @@ export async function* runAgentTurn(input) {
         // ledger the model asks about lives HERE, not behind an adapter, so
         // routing it through dispatch would only work on a device and would
         // record the undo as a fresh effect.
-        const result = action === SNAPSHOT_ACTION ? projectSnapshot(toolId, await requireSnapshot(readSnapshot, toolId), params) : toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await (prefetch.get(call.id) ?? dispatch(toolId, action, params));
+        const result = action === SNAPSHOT_ACTION ? projectSnapshot(toolId, await requireSnapshot(readSnapshot, toolId), params) : toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch, evidence, params, procedures) : await (prefetch.get(call.id) ?? dispatch(toolId, action, params));
         const cleaned = redact(stripSelfTraffic(result));
         const refused = reportsFailure(result);
-        const encodedResult = encodeResult(cleaned);
+
+        // Kept in full — after redaction, never before — so the model can go
+        // back to it. Not a retrieve's own result (a retrieve of a retrieve is
+        // a loop), and not a refusal (nothing to go back to).
+        const text = fullText(cleaned);
+        const ref = evidence && !refused && !(toolId === "ask-buoy" && action === "retrieve") ? evidence.stash({
+          toolId,
+          action,
+          params,
+          capturedAt: Date.now(),
+          text
+        }) : undefined;
+        const encodedResult = encodeResult(text, ref);
+        const traceResult = encodedResult.length > MAX_TRACE_RESULT_CHARS ? `${encodedResult.slice(0, MAX_TRACE_RESULT_CHARS)}…` : encodedResult;
         yield {
           type: "tool-end",
           id: call.id,
           ok: !refused,
           summary: summarise(result),
           durationMs: Date.now() - startedAt,
-          result: encodedResult.length > MAX_TRACE_RESULT_CHARS ? `${encodedResult.slice(0, MAX_TRACE_RESULT_CHARS)}…` : encodedResult
+          result: traceResult
         };
 
         // The receipt: what the user sees of this result, built from the
@@ -1135,7 +1344,12 @@ export async function* runAgentTurn(input) {
             before: stateBefore,
             after: stateAfter
           });
-          if (fx) ledger.record(toolId, action, fx, ledgerGeneration);
+          if (fx) {
+            const entry = ledger.record(toolId, action, fx, ledgerGeneration);
+            // Ties the change to its round, so the budget keeps that round
+            // while the change is live. See LedgerEntry.callId.
+            if (entry) entry.callId = call.id;
+          }
         }
         // No receipt for a call that changed nothing: a "what changed" card
         // under a refusal is the same lie as the ledger entry, drawn bigger.
@@ -1153,10 +1367,36 @@ export async function* runAgentTurn(input) {
           block: receipt,
           forToolCallId: call.id
         };
+        /**
+         * THE OUTCOME CHECK. A write's own `{ok:true}` says the adapter
+         * accepted it; this reads the app back and says whether the requested
+         * state is actually there. Only for actions that have a verifier, only
+         * for writes that were not refused, and never itself a write. Its
+         * verdict rides in the tool result as a trailer the model reads, and
+         * on a second tool-end so the row says "verified" / "unverified" /
+         * "check failed". See engine/verify.ts for the three meanings.
+         */
+        const verification = descriptor.effect !== "read" && !refused ? await verifyOutcome({
+          toolId,
+          action,
+          params,
+          result,
+          dispatch,
+          signal,
+          after: stateAfter
+        }) : undefined;
+        if (verification) yield {
+          type: "tool-verified",
+          id: call.id,
+          verification
+        };
         for (const url of encodedResult.match(URL_RE) ?? []) seenUrls.add(url);
         results.push({
           toolCallId: call.id,
-          content: encodedResult + ownedKeyNote(toolId, descriptor, params, storeKeyOwners) + aliasTrailer + (salvagedIds.has(call.id) ? SALVAGE_NOTE : "")
+          content: encodedResult + ownedKeyNote(toolId, descriptor, params, storeKeyOwners) + aliasTrailer + (verification ? verificationTrailer(verification) : "") + (salvagedIds.has(call.id) ? SALVAGE_NOTE : ""),
+          ...(ref ? {
+            ref
+          } : {})
         });
         if (toolId === "app" && (action === "reloadApp" || action === "reload")) {
           realmWillDie = true;
@@ -1201,7 +1441,8 @@ export async function* runAgentTurn(input) {
         blockId: awaiting
       };
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "awaiting-user"
       };
       return messages;
     }
@@ -1209,7 +1450,8 @@ export async function* runAgentTurn(input) {
       // Anything after this dies with the JS realm. Stop cleanly instead of
       // sending a request whose answer can never arrive.
       yield {
-        type: "done"
+        type: "done",
+        stopReason: "realm-died"
       };
       return messages;
     }
@@ -1229,7 +1471,8 @@ export async function* runAgentTurn(input) {
     }
   };
   yield {
-    type: "done"
+    type: "done",
+    stopReason: "step-cap"
   };
   return messages;
 }
@@ -1356,7 +1599,7 @@ export async function runGatedAction(input) {
     };
   }
   try {
-    const result = toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await dispatch(toolId, action, params);
+    const result = toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch, undefined, params) : await dispatch(toolId, action, params);
 
     // Same rule as the model's path: a resolved `{ok:false}` is a refusal, not
     // a change. Without this a block button (or an approval answered after a
@@ -1398,7 +1641,33 @@ export async function runGatedAction(input) {
  * adapter's same-named actions remain for desktop/MCP, where the ledger is
  * reached over the broker instead.
  */
-async function runAskBuoyAction(action, ledger, dispatch) {
+async function runAskBuoyAction(action, ledger, dispatch, evidence, params, procedures) {
+  if (action === "retrieve") {
+    return retrieveEvidence(evidence, params ?? {});
+  }
+  if (action === "openProcedure") {
+    const id = typeof params?.id === "string" ? params.id : "";
+    const found = procedures?.find(p => p.id === id);
+    if (!found) {
+      const ids = (procedures ?? []).map(p => p.id);
+      return {
+        ok: false,
+        error: ids.length ? `No procedure "${id}". This app's procedures: ${ids.join(", ")}.` : "This app has no procedures written for it."
+      };
+    }
+    return {
+      id: found.id,
+      title: found.title,
+      ...(found.version ? {
+        version: found.version
+      } : {}),
+      ...(found.requires?.length ? {
+        requires: found.requires
+      } : {}),
+      body: found.body,
+      note: "Follow these steps with the ordinary tools. Every write still goes through the same policy, approval and undo as any other call; a step that is refused stays refused."
+    };
+  }
   if (action === "listChanges") {
     const changes = ledger.list().filter(e => !e.undoneAt).map(e => ({
       toolId: e.toolId,