@buoy-gg/agent-core 7.0.33

package/lib/module/engine/runAgentTurn.js

@@ -0,0 +1,663 @@
+"use strict";
+
+/**
+ * One turn: user sentence in, tool calls and an answer out.
+ *
+ * The loop is deliberately explicit rather than clever, because every step of
+ * it encodes something that bites otherwise:
+ *
+ * - Validation happens BEFORE dispatch and a failure comes back as a readable
+ *   tool_result, not an exception. Buoy's adapters validate nothing, so a
+ *   wrong shape becomes an undefined read deep inside a tool — and an LLM
+ *   omitting `replace` on `zustand.setState` replaces the entire store.
+ * - `app.reloadApp` is TERMINAL. It returns before the reload fires and then
+ *   kills the JS realm; anything queued behind it dies with the conversation.
+ * - Results are truncated before they are sent. `dispatchToolAction` bypasses
+ *   the 8MB wire cap that protects the broker path, so an in-app agent can
+ *   receive a 50MB object and then try to feed it to a token-metered model.
+ * - Steps and wall-clock are capped, because a model that misreads a result
+ *   will otherwise retry the same call until the user closes the sheet.
+ */
+
+import { CATALOG } from "../catalog/catalog.g";
+import { applyDefaults, validateParams } from "../catalog/validateParams";
+import { fromProviderToolName, toProviderTools } from "../catalog/toProviderTools";
+import { projectSnapshot, SNAPSHOT_ACTION } from "../catalog/snapshotReads";
+import { isReversible } from "../effects/ledger";
+import { describeCall, decide } from "../policy/policy";
+import { redact, stripSelfTraffic } from "../policy/redact";
+import { effectFor } from "./effectFor";
+import { buildUiBlock, UI_TOOL_NAME, uiProviderTool } from "../blocks/uiTool";
+import { projectReceipt } from "../blocks/receipts";
+import { isAskBlock } from "../blocks/types";
+
+/** Beyond this a tool result costs more in tokens than it can possibly be worth. */
+const MAX_RESULT_CHARS = 24_000;
+const DEFAULT_MAX_STEPS = 12;
+const DEFAULT_TURN_MS = 180_000;
+function findDescriptor(catalog, toolId, action) {
+  return catalog.find(t => t.toolId === toolId)?.actions.find(a => a.action === action);
+}
+function encodeResult(value) {
+  let text;
+  try {
+    text = JSON.stringify(value ?? null);
+  } catch {
+    text = String(value);
+  }
+  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.]`;
+}
+
+/** A short line for the transcript row, so the UI never renders raw payloads. */
+/**
+ * The trailing status word on a transcript row — "12 items", "Not found",
+ * "Done". Written for the person watching, not the model (which gets the full
+ * result): a list of JSON key names ("found, storeName, …") told a QA tester
+ * nothing, so this reads the few result shapes that carry meaning and says
+ * "Done" for the rest.
+ */
+function summarise(value) {
+  if (value === null || value === undefined) return "Done";
+  if (Array.isArray(value)) return countOf(value.length);
+  if (typeof value === "boolean") return value ? "Done" : "Failed";
+  if (typeof value === "object") {
+    const rec = value;
+    if (rec.ok === false) return typeof rec.error === "string" ? rec.error : "Failed";
+    if (rec.found === false) return "Not found";
+    if (rec.tapped === false) return "Nothing to tap";
+    if (rec.active === false) return "Saved, but inactive in this build";
+    for (const key of ["returned", "count", "total"]) {
+      const n = rec[key];
+      if (typeof n === "number") return countOf(n);
+    }
+    // `{requests:[…]}` → "12 items", but a snapshot with several lists
+    // (`{stack, routes, recentNavigations}`) has no single honest count.
+    const lists = Object.values(rec).filter(Array.isArray);
+    if (lists.length === 1) return countOf(lists[0].length);
+    return "Done";
+  }
+  return String(value).slice(0, 80);
+}
+function countOf(n) {
+  return n === 1 ? "1 item" : `${n} items`;
+}
+export async function* runAgentTurn(input) {
+  const {
+    provider,
+    catalog,
+    system,
+    model,
+    maxTokens,
+    dispatch,
+    readSnapshot,
+    storeKeyOwners,
+    ledger,
+    policy,
+    isRelease,
+    requestApproval,
+    signal
+  } = input;
+  const messages = [...input.messages];
+  const tools = toProviderTools(catalog, {
+    availableToolIds: input.availableToolIds,
+    availableActions: input.availableActions,
+    isRelease
+  });
+  tools.push(uiProviderTool());
+  const maxSteps = policy.maxSteps ?? DEFAULT_MAX_STEPS;
+  const deadline = Date.now() + DEFAULT_TURN_MS;
+
+  // Every http(s) URL that appeared in a tool result THIS turn. The prompt
+  // tells the model image URLs must come from here; this Set is the
+  // enforcement — a model-remembered or injected URL in an image block is
+  // both a fabrication vector and a data-exfil beacon (the GET carries
+  // whatever is encoded into the URL).
+  const seenUrls = new Set();
+  const URL_RE = /https?:\/\/[^\s"'\\)\]}>]+/g;
+  for (let step = 0; step < maxSteps; step++) {
+    if (signal?.aborted) {
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    if (Date.now() > deadline) {
+      yield {
+        type: "error",
+        message: "This is taking too long — stopping here."
+      };
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    let text = "";
+    const calls = [];
+    let failed = false;
+    for await (const ev of provider.send({
+      messages,
+      system,
+      tools,
+      model,
+      maxTokens,
+      signal
+    })) {
+      if (ev.type === "text") {
+        text += ev.delta;
+        yield {
+          type: "text",
+          delta: ev.delta
+        };
+      } else if (ev.type === "tool-call") {
+        calls.push(ev.call);
+      } else if (ev.type === "error") {
+        // A mid-stream error can arrive on an already-committed 200.
+        yield {
+          type: "error",
+          message: ev.message
+        };
+        failed = true;
+      } else if (ev.type === "done" && ev.usage) {
+        // Surfaced so a host can meter cost per seat. Parsed for a long time;
+        // went nowhere anyone could see.
+        yield {
+          type: "usage",
+          input: ev.usage.input,
+          output: ev.usage.output
+        };
+      }
+    }
+    if (failed) {
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    messages.push({
+      role: "assistant",
+      text,
+      toolCalls: calls.length ? calls : undefined
+    });
+    if (calls.length === 0) {
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    const results = [];
+    let realmWillDie = false;
+    let awaiting = null;
+    for (const call of calls) {
+      // `buoy_ui`: show or ask. Validated like any action; an Ask block ends
+      // the turn after this batch — the answer comes back as a user message.
+      if (call.name === UI_TOOL_NAME) {
+        const built = buildUiBlock(call.input);
+        if (!built.ok || !built.block) {
+          results.push({
+            toolCallId: call.id,
+            content: `Invalid ${UI_TOOL_NAME} block:\n${built.errors.join("\n")}`,
+            isError: true
+          });
+          continue;
+        }
+        // Provenance for pictures, ENFORCED: an image URL the model did not
+        // read from a tool result this turn does not render. Live or nothing.
+        if (built.block.kind === "imageGrid") {
+          const kept = built.block.images.filter(img => seenUrls.has(img.url));
+          if (kept.length === 0) {
+            results.push({
+              toolCallId: call.id,
+              content: "Rejected: every image URL must be one you read from a tool result THIS turn (images.list, a storage value, a response body). Never invent or remember URLs — read them first.",
+              isError: true
+            });
+            continue;
+          }
+          built.block = {
+            ...built.block,
+            images: kept
+          };
+        }
+        if (built.block.kind === "list") {
+          built.block = {
+            ...built.block,
+            items: built.block.items.map(item => item.image && !seenUrls.has(item.image) ? {
+              ...item,
+              image: undefined
+            } : item)
+          };
+        }
+        yield {
+          type: "block",
+          block: built.block,
+          forToolCallId: call.id
+        };
+        if (isAskBlock(built.block)) {
+          awaiting = built.block.id;
+          results.push({
+            toolCallId: call.id,
+            content: "Shown. Waiting for the user's answer — it will arrive as their next message. Do not guess it."
+          });
+        } else {
+          results.push({
+            toolCallId: call.id,
+            content: "Shown to the user. Don't repeat its contents in text."
+          });
+        }
+        continue;
+      }
+      const toolId = fromProviderToolName(call.name, catalog);
+      const action = call.input.action;
+
+      // Two different mistakes, kept apart on purpose. Merging them tells a
+      // model that forgot `action` that the TOOL does not exist, and it stops
+      // reaching for a tool that was fine — the same distinction
+      // `dispatchToolAction` draws between an unknown tool and an unknown
+      // action, for the same reason.
+      if (!toolId) {
+        results.push({
+          toolCallId: call.id,
+          content: `There is no tool called "${call.name}". Use one of the tools you were given.`,
+          isError: true
+        });
+        continue;
+      }
+      if (!action) {
+        results.push({
+          toolCallId: call.id,
+          content: `"${call.name}" needs an "action" — it is required, and it names which of this tool's actions to run. See the action list in the tool's description.`,
+          isError: true
+        });
+        continue;
+      }
+      const descriptor = findDescriptor(catalog, toolId, action);
+      if (!descriptor) {
+        // Name the alternatives. Without them a model that guessed an action
+        // has nowhere to go but guess again, and the next guess is no better
+        // informed than the last.
+        const known = catalog.find(t => t.toolId === toolId)?.actions.map(a => a.action).join(", ");
+        results.push({
+          toolCallId: call.id,
+          content: `"${action}" is not an action on ${toolId}.${known ? ` Valid actions: ${known}.` : ""}`,
+          isError: true
+        });
+        continue;
+      }
+      const raw = call.input.params ?? {};
+      const params = applyDefaults(raw, descriptor.params);
+      const check = validateParams(params, descriptor.params);
+      if (!check.ok) {
+        results.push({
+          toolCallId: call.id,
+          content: `Invalid parameters for ${toolId}.${action}:\n${check.errors.join("\n")}\n\nExpected schema:\n${JSON.stringify(descriptor.params)}`,
+          isError: true
+        });
+        continue;
+      }
+      const label = describeCall(toolId, descriptor, params);
+      const verdict = decide({
+        descriptor,
+        toolId,
+        policy,
+        isRelease
+      });
+      if (verdict.verdict === "refuse") {
+        yield {
+          type: "tool-end",
+          id: call.id,
+          ok: false,
+          summary: "refused"
+        };
+        results.push({
+          toolCallId: call.id,
+          content: verdict.reason,
+          isError: true
+        });
+        continue;
+      }
+      if (verdict.verdict === "needs-approval") {
+        yield {
+          type: "approval-required",
+          id: call.id,
+          toolId,
+          action,
+          label,
+          description: descriptor.summary,
+          reason: verdict.reason
+        };
+        const approved = requestApproval ? await requestApproval({
+          id: call.id,
+          toolId,
+          action,
+          label,
+          description: descriptor.summary,
+          reason: verdict.reason
+        }) : false;
+        if (!approved) {
+          results.push({
+            toolCallId: call.id,
+            content: "The user declined this change. Do not retry it; ask what they would prefer.",
+            isError: true
+          });
+          continue;
+        }
+      }
+      yield {
+        type: "tool-start",
+        id: call.id,
+        toolId,
+        action,
+        label,
+        description: descriptor.summary
+      };
+
+      // Capture the prior value BEFORE a storage write, so undo can restore it
+      // exactly. This is the one thing that makes storage reversible here when
+      // the Scenarios engine has to treat it as permanent.
+      const before = await captureBefore(descriptor, toolId, params, dispatch);
+      const stateBefore = await captureStateBefore(descriptor, toolId, params, dispatch);
+      try {
+        // `getSnapshot` is reserved: it is not an adapter action, so it goes to
+        // the snapshot reader and is trimmed to the fields worth sending. See
+        // catalog/snapshotReads.ts. `ask-buoy.*` is the session itself — the
+        // 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 dispatch(toolId, action, params);
+        const cleaned = redact(stripSelfTraffic(result));
+        if (descriptor.effect !== "read" && toolId !== "ask-buoy") {
+          // A delete of something we created IS the undo, whoever asked for
+          // it — mark the matching entry undone instead of leaving the bar
+          // promising an undo against a rule that no longer exists.
+          ledger.noteExternalRevert(toolId, action, params);
+          const fx = effectFor(toolId, descriptor, params, result, before);
+          if (fx) ledger.record(toolId, action, fx);
+        }
+        yield {
+          type: "tool-end",
+          id: call.id,
+          ok: true,
+          summary: summarise(result)
+        };
+
+        // The receipt: what the user sees of this result, built from the
+        // same redacted data the model gets. See blocks/receipts.ts.
+        const receipt = projectReceipt({
+          toolId,
+          action,
+          params,
+          result: cleaned,
+          before: stateBefore ?? before,
+          effect: descriptor.effect
+        });
+        if (receipt) yield {
+          type: "block",
+          block: receipt,
+          forToolCallId: call.id
+        };
+        const encoded = encodeResult(cleaned);
+        for (const url of encoded.match(URL_RE) ?? []) seenUrls.add(url);
+        results.push({
+          toolCallId: call.id,
+          content: encoded + ownedKeyNote(toolId, descriptor, params, storeKeyOwners)
+        });
+        if (toolId === "app" && (action === "reloadApp" || action === "reload")) {
+          realmWillDie = true;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        yield {
+          type: "tool-end",
+          id: call.id,
+          ok: false,
+          summary: message
+        };
+        results.push({
+          toolCallId: call.id,
+          content: `Failed: ${message}`,
+          isError: true
+        });
+      }
+    }
+    messages.push({
+      role: "tool-results",
+      results
+    });
+    if (awaiting) {
+      yield {
+        type: "awaiting-user",
+        blockId: awaiting
+      };
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+    if (realmWillDie) {
+      // Anything after this dies with the JS realm. Stop cleanly instead of
+      // sending a request whose answer can never arrive.
+      yield {
+        type: "done"
+      };
+      return messages;
+    }
+  }
+  yield {
+    type: "block",
+    block: {
+      id: `cap${Date.now()}`,
+      kind: "notice",
+      tone: "warning",
+      text: `Stopped after ${maxSteps} steps to avoid looping.`,
+      actions: [{
+        label: "Continue",
+        primary: true,
+        send: "Continue where you left off."
+      }]
+    }
+  };
+  yield {
+    type: "done"
+  };
+  return messages;
+}
+
+/**
+ * A factual postscript for a storage write that landed on a store's saved copy.
+ *
+ * This is a STATEMENT ABOUT WHAT HAPPENED, not a policy reminder — the same
+ * kind of thing the release refusals say, and the reason it belongs in the
+ * result rather than the system prompt. The write really did succeed and the
+ * app really did not change, and only the engine is in a position to know
+ * both at once.
+ *
+ * Deliberately not a refusal. Writing the on-disk value on purpose — "make it
+ * this on next launch" — is legitimate, and a hard block would make that
+ * impossible. Saying so leaves the model free to continue, correct itself with
+ * `zustand.rehydrate`, or explain the distinction to the user.
+ */
+function ownedKeyNote(toolId, descriptor, params, storeKeyOwners) {
+  if (toolId !== "storage" || descriptor.effect === "read") return "";
+  if (!storeKeyOwners || typeof params.key !== "string") return "";
+  const storeName = storeKeyOwners[params.key];
+  if (!storeName) return "";
+  return `\n\n[Buoy] This wrote to disk, but "${params.key}" is the saved copy of the live "${storeName}" store, so nothing on screen has changed — the app read that key once at startup and has held the state in memory since. Call zustand.rehydrate({"storeName":"${storeName}"}) to make the app pick this up, or use zustand.setState next time to change the store directly. If you meant to set the value for the app's next launch, this is already done and no further action is needed.`;
+}
+/**
+ * One human-initiated action through EVERY gate the model's calls go through:
+ * catalog lookup, param validation, policy, pre-read, effect ledger.
+ *
+ * This exists for block buttons. The `buoy_ui` schema promises the model that
+ * a dispatch button runs "with the same policy and undo as if you called it",
+ * and the first implementation called `dispatchToolAction` raw — no deny list,
+ * no release refusal, no ledger entry. One tap on a model-authored button was
+ * an invisible, ungoverned, unundoable mutation. Route every button through
+ * here so the promise is true.
+ *
+ * `needs-approval` is treated as approved: the human's tap on the button IS
+ * the approval. Deny lists, read-only mode and release refusals still stand —
+ * a button must never reach further than the model could.
+ */
+export async function runGatedAction(input) {
+  const {
+    toolId,
+    action,
+    dispatch,
+    ledger,
+    policy,
+    isRelease
+  } = input;
+  const catalog = input.catalog ?? CATALOG;
+  const descriptor = findDescriptor(catalog, toolId, action);
+  if (!descriptor) {
+    return {
+      ok: false,
+      error: `${toolId}.${action} is not in Buoy's catalog.`
+    };
+  }
+  const params = applyDefaults(input.params ?? {}, descriptor.params);
+  const check = validateParams(params, descriptor.params);
+  if (!check.ok) {
+    return {
+      ok: false,
+      error: check.errors.join("\n")
+    };
+  }
+  const verdict = decide({
+    descriptor,
+    toolId,
+    policy,
+    isRelease
+  });
+  if (verdict.verdict === "refuse") {
+    return {
+      ok: false,
+      error: verdict.reason
+    };
+  }
+  const before = await captureBefore(descriptor, toolId, params, dispatch);
+  try {
+    const result = toolId === "ask-buoy" ? await runAskBuoyAction(action, ledger, dispatch) : await dispatch(toolId, action, params);
+    if (descriptor.effect !== "read" && toolId !== "ask-buoy") {
+      ledger.noteExternalRevert(toolId, action, params);
+      const fx = effectFor(toolId, descriptor, params, result, before);
+      if (fx) ledger.record(toolId, action, fx);
+    }
+    return {
+      ok: true,
+      result
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+
+/**
+ * The `ask-buoy` catalog tool, served by the engine itself. `listChanges` and
+ * `undoAll` operate on THIS session's ledger — the same one the changes bar
+ * renders — so the model's undo and the human's undo are one mechanism. The
+ * adapter's same-named actions remain for desktop/MCP, where the ledger is
+ * reached over the broker instead.
+ */
+async function runAskBuoyAction(action, ledger, dispatch) {
+  if (action === "listChanges") {
+    const changes = ledger.list().filter(e => !e.undoneAt).map(e => ({
+      toolId: e.toolId,
+      action: e.action,
+      kind: e.effect.kind,
+      label: e.effect.label,
+      reversible: isReversible(e.effect)
+    }));
+    return {
+      changes,
+      returned: changes.length
+    };
+  }
+  if (action === "undoAll") {
+    const outcome = await ledger.revertAll(dispatch);
+    return {
+      ok: outcome.failed.length === 0,
+      ...outcome
+    };
+  }
+  throw new Error(`Unknown ask-buoy action "${action}"`);
+}
+
+/** Fail loudly rather than hand the model an empty object it will believe. */
+async function requireSnapshot(readSnapshot, toolId) {
+  if (!readSnapshot) {
+    throw new Error(`This app cannot read ${toolId}'s snapshot — Buoy's tool registry is not published here.`);
+  }
+  return await readSnapshot(toolId);
+}
+
+/**
+ * Read a storage key's current value so the write can be reversed.
+ *
+ * This pre-read is the ONLY reason storage is reversible here. The adapter's
+ * `async.*` / `mmkv.*` proxies all return void, so neither the prior value nor
+ * the store event id that `timeTravel.undo` needs ever reaches a caller — and
+ * that event only exists while something holds capture open. Reading first is
+ * what turns "we don't know what was there" into a real undo.
+ *
+ * Deliberately NOT gated on `descriptor.undo`: the catalog's undo claims were
+ * audited down to almost nothing precisely because they were unsound. The
+ * ledger's reversibility comes from this read, not from a catalog promise.
+ */
+/**
+ * The prior state for a store write, so the receipt can show a real diff.
+ * Zustand only for now: `getStoreState` is cheap and the write params carry
+ * the after-state, so the diff is exact without the store's cooperation.
+ */
+async function captureStateBefore(descriptor, toolId, params, dispatch) {
+  if (toolId !== "zustand" || descriptor.action !== "setState") return undefined;
+  if (typeof params.storeName !== "string") return undefined;
+  try {
+    return await dispatch(toolId, "getStoreState", {
+      storeName: params.storeName
+    });
+  } catch {
+    return undefined;
+  }
+}
+async function captureBefore(descriptor, toolId, params, dispatch) {
+  if (descriptor.effect === "read") return undefined;
+  if (toolId !== "storage" || typeof params.key !== "string") return undefined;
+  const readAction = descriptor.action.startsWith("async.") ? "async.getItem" : descriptor.action.startsWith("mmkv.") ? "mmkv.get" : undefined;
+  // secure.* is excluded on purpose: a key registered with
+  // `requireAuthentication` cannot be read without a biometric prompt, so a
+  // pre-read would either fail or pop a Face ID sheet mid-conversation.
+  if (!readAction) return undefined;
+
+  // MMKV IS PER-INSTANCE, and `mmkv.get` does not throw when the id is missing
+  // — it returns `{found:false, reason:"missing instanceId/key"}`. Reading with
+  // the key alone therefore produced a `before` that LOOKED captured and was
+  // empty, which the ledger then read as "the key did not exist" and undid by
+  // deleting it. Without an instance there is nothing to capture, so say so.
+  const readParams = {
+    key: params.key
+  };
+  if (readAction === "mmkv.get") {
+    if (typeof params.instanceId !== "string") return undefined;
+    readParams.instanceId = params.instanceId;
+  }
+  try {
+    const current = await dispatch(toolId, readAction, readParams);
+    const rec = current && typeof current === "object" ? current : undefined;
+    // An explicit "I could not read that" is not a captured empty value.
+    if (rec?.found === false) return undefined;
+    const value = rec ? rec.value : current;
+    return {
+      had: value !== undefined && value !== null,
+      value: value ?? undefined
+    };
+  } catch {
+    // A failed pre-read must not block the write the user asked for; it just
+    // means this one is not reversible, which the ledger will say.
+    return undefined;
+  }
+}
+//# sourceMappingURL=runAgentTurn.js.map