@buoy-gg/agent-core 7.0.35 → 7.0.38

package/lib/commonjs/engine/textToolCalls.js

@@ -0,0 +1,276 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SALVAGE_NOTE = void 0;
+exports.couldBeToolCallEnvelope = couldBeToolCallEnvelope;
+exports.parseTextToolCalls = parseTextToolCalls;
+var _toProviderTools = require("../catalog/toProviderTools");
+var _uiTool = require("../blocks/uiTool");
+var _runId = require("../blocks/runId");
+/**
+ * Recovering a tool call a model wrote as TEXT instead of calling.
+ *
+ * Every provider here is sent real tool definitions, and most models use them.
+ * Some don't — under a gateway, after a clarifying question, or just on the
+ * wrong roll, a model answers with the call spelled out as JSON:
+ *
+ *     ```json
+ *     {"calls":[{"tool":"buoy_zustand","action":"setState","params":{…}}],
+ *      "reply":"Done — I added one Jigglypuff to your bag."}
+ *     ```
+ *
+ * Left alone this is the worst outcome the product has: the user said "yes,
+ * go ahead", nothing happened, and what they got back was a wall of JSON
+ * claiming it did. The same class of problem as the parameter aliases in
+ * normalizeParams — models reach for a convention they know, and meeting them
+ * costs one parse.
+ *
+ * Two halves, and the first is why this file exists at all:
+ *
+ * 1. {@link couldBeToolCallEnvelope} runs on every delta, because the decision
+ *    has to be made BEFORE the text reaches the screen. Streamed text cannot
+ *    be taken back. It withholds only what could still be an envelope and
+ *    releases the moment it can't be.
+ * 2. {@link parseTextToolCalls} turns the finished blob into ordinary calls,
+ *    which then go through validation, the policy, and approval exactly like a
+ *    native one. Nothing here decides that a call is allowed to run — a
+ *    recovered destructive call still stops at the same approval sheet.
+ */
+
+const id = (0, _runId.idFactory)("txt");
+
+/** `{`, optionally inside a ```json fence. */
+const OPENER = /^(?:```[a-zA-Z]*[ \t]*\r?\n?)?\{/;
+/** A fence still arriving a backtick at a time: "`", "``", "```json\n". */
+const PARTIAL_OPENER = /^`{1,3}[a-zA-Z]*\s*$/;
+/**
+ * The keys an envelope names almost immediately.
+ *
+ * Deliberately excludes `name` and `action`: a response body the user asked to
+ * see routinely has a `name` field, and holding those back would make every
+ * JSON answer in the product stutter to catch a shape no model emits.
+ */
+const ENVELOPE_KEY = /"(calls|tool_calls|toolCalls|tool|function)"/;
+/**
+ * How far past the opening brace to keep withholding before an envelope has to
+ * have named itself. Long enough for `{\n  "calls": [` with any indentation,
+ * short enough that a JSON answer the user actually asked for barely stutters.
+ */
+const KEY_WINDOW = 80;
+
+/**
+ * Could the text so far still turn out to be a tool-call envelope?
+ *
+ * False the instant it can't be, so an ordinary answer streams exactly as it
+ * did before — the window this holds is one opening brace plus a key name.
+ */
+function couldBeToolCallEnvelope(text) {
+  const t = text.trimStart();
+  if (t.length === 0) return true;
+  if (PARTIAL_OPENER.test(t)) return true;
+  const opener = OPENER.exec(t);
+  if (!opener) return false;
+  const body = t.slice(opener[0].length);
+  return body.length <= KEY_WINDOW || ENVELOPE_KEY.test(body);
+}
+
+/**
+ * The JSON object inside the text, fence and trailing prose removed — as up
+ * to two readings, tried in order.
+ *
+ * The first version cut at the FIRST closing fence. Seen live: an envelope
+ * whose `reply` carried its own ```json block — the bag line the user had
+ * asked for — was cut off inside that string, failed to parse, and the raw
+ * blob became the answer. So: (1) cut at the LAST fence, which is the
+ * envelope's own closer when the text is fenced; (2) ignore fences entirely
+ * and take everything up to the last "}". Whichever parses wins.
+ */
+function jsonBodies(text) {
+  const t = text.trim();
+  const unfenced = t.startsWith("```") ? t.replace(/^```[a-zA-Z]*[ \t]*\r?\n?/, "") : t;
+  const close = unfenced.lastIndexOf("```");
+  const candidates = [close >= 0 ? unfenced.slice(0, close) : unfenced, unfenced];
+  const out = [];
+  for (const raw of candidates) {
+    const c = raw.trim();
+    if (!c.startsWith("{")) continue;
+    const end = c.lastIndexOf("}");
+    if (end === -1) continue;
+    const body = c.slice(0, end + 1);
+    if (!out.includes(body)) out.push(body);
+  }
+  return out;
+}
+
+/**
+ * A last-resort parse for JSON a model got slightly wrong.
+ *
+ * The envelope that produced this file was not valid JSON. The model wrote
+ * `…"unitPrice":999}}}}],"reply":…` — four closing braces where five were
+ * needed, so the call object was never closed and `]` arrived while still
+ * inside it. Strict parsing rejects the whole thing, and rejecting it hands
+ * the user the blob and no action: exactly the failure this file exists to
+ * stop, and it survived the first version of it. A model that writes its call
+ * as prose is already off the rails; expecting it to balance twelve nested
+ * braces by hand is expecting the wrong thing.
+ *
+ * The repair is mechanical and changes no values: a container is auto-closed
+ * when a mismatched closer arrives, a stray closer with nothing open is
+ * dropped, and anything still open at the end is closed. Whatever comes out
+ * still has to READ as an envelope naming a tool this app has, and every call
+ * it yields goes through validation, the policy and approval. A repaired call
+ * is not a trusted one — it is only a legible one.
+ */
+function repairJson(text) {
+  const out = [];
+  const stack = [];
+  let inString = false;
+  let escaped = false;
+  for (const ch of text) {
+    if (inString) {
+      out.push(ch);
+      if (escaped) escaped = false;else if (ch === "\\") escaped = true;else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out.push(ch);
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      stack.push(ch);
+      out.push(ch);
+      continue;
+    }
+    if (ch === "}" || ch === "]") {
+      const want = ch === "}" ? "{" : "[";
+      let i = stack.length - 1;
+      while (i >= 0 && stack[i] !== want) i--;
+      // Nothing this could be closing. Dropping it is the only repair that
+      // does not invent structure.
+      if (i < 0) continue;
+      while (stack.length - 1 > i) out.push(stack.pop() === "{" ? "}" : "]");
+      stack.pop();
+      out.push(ch);
+      continue;
+    }
+    out.push(ch);
+  }
+  if (inString) out.push('"');
+  while (stack.length) out.push(stack.pop() === "{" ? "}" : "]");
+  return out.join("");
+}
+const rec = v => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+const str = v => typeof v === "string" && v.length > 0 ? v : undefined;
+function tryParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/** `params` may arrive as an object or, in the OpenAI convention, as a string. */
+function asParams(v) {
+  const direct = rec(v);
+  if (direct) return direct;
+  const s = str(v);
+  if (!s) return undefined;
+  try {
+    return rec(JSON.parse(s));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Name it the way the provider would have, so the rest of the loop can't tell
+ * — or nothing, if it names no tool this app has.
+ *
+ * This is the guard that keeps ordinary JSON out. `{"name":"Bulbasaur", …}` is
+ * a Pokémon the user asked to see, not a call, and the only reliable way to
+ * tell is that no tool is called Bulbasaur.
+ */
+function providerName(name, catalog) {
+  if (name === _uiTool.UI_TOOL_NAME) return name;
+  if (catalog.some(t => t.toolId === name)) return (0, _toProviderTools.toProviderToolName)(name);
+  if (catalog.some(t => (0, _toProviderTools.toProviderToolName)(t.toolId) === name)) return name;
+  return undefined;
+}
+function toCall(entry, catalog) {
+  const e = rec(entry);
+  if (!e) return undefined;
+  // `function` is the OpenAI nesting; `input` is Anthropic's.
+  const fn = rec(e.function);
+  const inner = rec(e.input) ?? rec(e.arguments) ?? fn;
+  const named = str(e.tool) ?? str(e.name) ?? str(fn?.name) ?? str(e.toolName);
+  const name = named ? providerName(named, catalog) : undefined;
+  if (!name) return undefined;
+  const action = str(e.action) ?? str(inner?.action);
+  // Every real action is named. Requiring it keeps a JSON object that merely
+  // happens to share a word with a tool from being run as one.
+  if (!action && name !== _uiTool.UI_TOOL_NAME) return undefined;
+  const params = asParams(e.params) ?? asParams(inner?.params) ?? asParams(fn?.arguments) ?? asParams(e.arguments) ?? {};
+  return {
+    id: id(),
+    name,
+    input: {
+      ...(action ? {
+        action
+      } : {}),
+      params
+    }
+  };
+}
+/**
+ * Read a text envelope as tool calls, or nothing if that is not what it is.
+ *
+ * Deliberately strict about the SHAPE and loose about the spelling: it will
+ * not turn arbitrary JSON into calls (a model showing the user a response body
+ * must still be shown), but it accepts every naming convention a model might
+ * carry over — `tool`/`name`, `params`/`input`/`arguments`, one call or many.
+ */
+function parseTextToolCalls(text, catalog) {
+  const bodies = jsonBodies(text);
+  if (bodies.length === 0) return undefined;
+  // Strict first, on every reading; the repair only ever sees JSON that
+  // already failed every strict attempt.
+  let parsed;
+  for (const body of bodies) if ((parsed = tryParse(body)) !== undefined) break;
+  if (parsed === undefined) for (const body of bodies) if ((parsed = tryParse(repairJson(body))) !== undefined) break;
+  const env = rec(parsed);
+  if (!env) return undefined;
+  const list = env.calls ?? env.tool_calls ?? env.toolCalls;
+  const entries = Array.isArray(list) ? list : env.tool || env.name ? [env] : undefined;
+  if (!entries) return undefined;
+  const reply = str(env.reply) ?? str(env.text) ?? str(env.message) ?? "";
+
+  // An envelope with NO calls is the model wrapping a plain answer in the
+  // shape it uses for calls. Seen live: `{"calls":[],"reply":"Here is the
+  // full Poké Mart menu…"}` in a ```json fence, with a whole markdown table
+  // inside the string — and the screen showed the blob, because "nothing to
+  // salvage" used to mean "show the text as-is". There is nothing to run, but
+  // the reply is the answer and the wrapper is not. Show the words.
+  if (entries.length === 0) return reply ? {
+    calls: [],
+    reply
+  } : undefined;
+  const calls = entries.map(e => toCall(e, catalog)).filter(Boolean);
+  // Every entry has to read as a call. A partial parse would run half of what
+  // the model described and silently drop the rest, which is worse than
+  // running none of it.
+  if (calls.length === 0 || calls.length !== entries.length) return undefined;
+  return {
+    calls,
+    reply
+  };
+}
+
+/**
+ * Appended to a recovered call's result, so the model corrects itself for the
+ * rest of the conversation instead of writing the next one as text too.
+ */
+const SALVAGE_NOTE = exports.SALVAGE_NOTE = "\n\n[You wrote this call as JSON in your reply instead of calling the tool. It was recovered and run this time. Call tools through the tool interface — text is shown to the user as-is, and a call written there does not run.]";
+//# sourceMappingURL=textToolCalls.js.map

package/lib/commonjs/engine/textToolCalls.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_toProviderTools","require","_uiTool","_runId","id","idFactory","OPENER","PARTIAL_OPENER","ENVELOPE_KEY","KEY_WINDOW","couldBeToolCallEnvelope","text","t","trimStart","length","test","opener","exec","body","slice","jsonBodies","trim","unfenced","startsWith","replace","close","lastIndexOf","candidates","out","raw","c","end","includes","push","repairJson","stack","inString","escaped","ch","want","i","pop","join","rec","v","Array","isArray","undefined","str","tryParse","JSON","parse","asParams","direct","s","providerName","name","catalog","UI_TOOL_NAME","some","toolId","toProviderToolName","toCall","entry","e","fn","function","inner","input","arguments","named","tool","toolName","action","params","parseTextToolCalls","bodies","parsed","env","list","calls","tool_calls","toolCalls","entries","reply","message","map","filter","Boolean","SALVAGE_NOTE","exports"],"sourceRoot":"../../../src","sources":["engine/textToolCalls.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/engine/tokenCalibration.js

@@ -0,0 +1,81 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TokenCalibration = exports.DEFAULT_CHARS_PER_TOKEN = void 0;
+exports.promptTokensOf = promptTokensOf;
+/**
+ * How many characters make a token — measured, not assumed.
+ *
+ * Every budget in this engine is kept in characters because that is what a
+ * string has, but every LIMIT that matters is in tokens: the provider's
+ * context window, the reply room, the cost. The conversion was a constant
+ * (4) everywhere. English prose does run near 4; the tool results this agent
+ * actually sends are JSON, which tokenizes nearer 3 — so a request the budget
+ * called 100k tokens could be 130k, on a gateway whose window is 128k. The
+ * proactive budget was optimistic in exactly the sessions it exists for.
+ *
+ * The provider tells us the truth after every request: its usage report
+ * carries the prompt's token count, and the engine knows how many characters
+ * it sent. One division gives the ratio for THIS conversation on THIS
+ * tokenizer; an exponential average smooths a single odd request (a round
+ * that was all prose, or all ids). Strands' design 0008 does the same in
+ * reverse — a known token baseline plus an estimate of the delta — and its
+ * decision record says why: public limits should be in LLM-native units.
+ *
+ * Clamped, because a wrong sample must not be able to blow the budget wide
+ * open (a gateway that reports nonsense usage) or shrink it to nothing.
+ */
+
+const DEFAULT_CHARS_PER_TOKEN = exports.DEFAULT_CHARS_PER_TOKEN = 4;
+const MIN_CHARS_PER_TOKEN = 2.5;
+const MAX_CHARS_PER_TOKEN = 5;
+/** Weight of the newest sample once there is history. The first sample replaces the default outright. */
+const EMA_ALPHA = 0.3;
+/** Below this many prompt tokens a sample says more about rounding than about the tokenizer. */
+const MIN_SAMPLE_TOKENS = 500;
+class TokenCalibration {
+  ratio = DEFAULT_CHARS_PER_TOKEN;
+  samples = 0;
+
+  /** Characters per token, as currently believed. */
+  get charsPerToken() {
+    return this.ratio;
+  }
+  get sampleCount() {
+    return this.samples;
+  }
+
+  /** Fold in one request: what was sent, and what the provider counted. */
+  observe(requestChars, promptTokens) {
+    if (!(requestChars > 0) || !(promptTokens >= MIN_SAMPLE_TOKENS)) return;
+    const sample = Math.min(MAX_CHARS_PER_TOKEN, Math.max(MIN_CHARS_PER_TOKEN, requestChars / promptTokens));
+    this.ratio = this.samples === 0 ? sample : this.ratio + EMA_ALPHA * (sample - this.ratio);
+    this.samples += 1;
+  }
+
+  /** Characters a token budget allows, at the believed ratio. */
+  chars(tokens) {
+    return Math.floor(tokens * this.ratio);
+  }
+  reset() {
+    this.ratio = DEFAULT_CHARS_PER_TOKEN;
+    this.samples = 0;
+  }
+}
+
+/**
+ * The whole prompt's token count from a usage report.
+ *
+ * Anthropic reports the cached and freshly-written prefix SEPARATELY from
+ * `input`; OpenAI-shaped providers fold `cached_tokens` INTO `prompt_tokens`.
+ * See TokenUsage. Adding on the wrong protocol double-counts the cache and
+ * halves the believed ratio.
+ */
+exports.TokenCalibration = TokenCalibration;
+function promptTokensOf(usage, protocol) {
+  if (protocol === "anthropic") return usage.input + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+  return usage.input;
+}
+//# sourceMappingURL=tokenCalibration.js.map

package/lib/commonjs/engine/tokenCalibration.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_CHARS_PER_TOKEN","exports","MIN_CHARS_PER_TOKEN","MAX_CHARS_PER_TOKEN","EMA_ALPHA","MIN_SAMPLE_TOKENS","TokenCalibration","ratio","samples","charsPerToken","sampleCount","observe","requestChars","promptTokens","sample","Math","min","max","chars","tokens","floor","reset","promptTokensOf","usage","protocol","input","cacheRead","cacheWrite"],"sourceRoot":"../../../src","sources":["engine/tokenCalibration.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGO,MAAMA,uBAAuB,GAAAC,OAAA,CAAAD,uBAAA,GAAG,CAAC;AACxC,MAAME,mBAAmB,GAAG,GAAG;AAC/B,MAAMC,mBAAmB,GAAG,CAAC;AAC7B;AACA,MAAMC,SAAS,GAAG,GAAG;AACrB;AACA,MAAMC,iBAAiB,GAAG,GAAG;AAEtB,MAAMC,gBAAgB,CAAC;EACpBC,KAAK,GAAGP,uBAAuB;EAC/BQ,OAAO,GAAG,CAAC;;EAEnB;EACA,IAAIC,aAAaA,CAAA,EAAW;IAC1B,OAAO,IAAI,CAACF,KAAK;EACnB;EAEA,IAAIG,WAAWA,CAAA,EAAW;IACxB,OAAO,IAAI,CAACF,OAAO;EACrB;;EAEA;EACAG,OAAOA,CAACC,YAAoB,EAAEC,YAAoB,EAAQ;IACxD,IAAI,EAAED,YAAY,GAAG,CAAC,CAAC,IAAI,EAAEC,YAAY,IAAIR,iBAAiB,CAAC,EAAE;IACjE,MAAMS,MAAM,GAAGC,IAAI,CAACC,GAAG,CAACb,mBAAmB,EAAEY,IAAI,CAACE,GAAG,CAACf,mBAAmB,EAAEU,YAAY,GAAGC,YAAY,CAAC,CAAC;IACxG,IAAI,CAACN,KAAK,GAAG,IAAI,CAACC,OAAO,KAAK,CAAC,GAAGM,MAAM,GAAG,IAAI,CAACP,KAAK,GAAGH,SAAS,IAAIU,MAAM,GAAG,IAAI,CAACP,KAAK,CAAC;IACzF,IAAI,CAACC,OAAO,IAAI,CAAC;EACnB;;EAEA;EACAU,KAAKA,CAACC,MAAc,EAAU;IAC5B,OAAOJ,IAAI,CAACK,KAAK,CAACD,MAAM,GAAG,IAAI,CAACZ,KAAK,CAAC;EACxC;EAEAc,KAAKA,CAAA,EAAS;IACZ,IAAI,CAACd,KAAK,GAAGP,uBAAuB;IACpC,IAAI,CAACQ,OAAO,GAAG,CAAC;EAClB;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAPAP,OAAA,CAAAK,gBAAA,GAAAA,gBAAA;AAQO,SAASgB,cAAcA,CAACC,KAAiB,EAAEC,QAAgC,EAAU;EAC1F,IAAIA,QAAQ,KAAK,WAAW,EAAE,OAAOD,KAAK,CAACE,KAAK,IAAIF,KAAK,CAACG,SAAS,IAAI,CAAC,CAAC,IAAIH,KAAK,CAACI,UAAU,IAAI,CAAC,CAAC;EACnG,OAAOJ,KAAK,CAACE,KAAK;AACpB","ignoreList":[]}

package/lib/commonjs/engine/verify.js

@@ -0,0 +1,300 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.VERIFIERS = void 0;
+exports.atPath = atPath;
+exports.isSubset = isSubset;
+exports.verificationTrailer = verificationTrailer;
+exports.verifyOutcome = verifyOutcome;
+/**
+ * Outcome verification: after a write lands, check that what the user asked
+ * for actually happened — not just that the adapter said ok.
+ *
+ * "Install override → `{ok:true}`" was reported as done. But installed ≠ a
+ * request has used it ≠ the cart shows it, and each step can succeed while
+ * the outcome fails: the app had the old response cached, the screen kept
+ * saying In Stock, and the reply said "the item is now sold out". Strands'
+ * GoalLoop frames this as a completion criterion with bounded correction; the
+ * criterion borrowed here is DETERMINISTIC — a read-back the engine performs
+ * with the same tools the model has — not a second model judging the reply.
+ *
+ * Three outcomes, each honest about what it is:
+ *
+ * - `verified`   — the read-back shows the requested state.
+ * - `unverified` — the write landed but the read-back cannot yet show the
+ *                  outcome (an override is installed but no request has
+ *                  matched it). Reported as exactly that, never as proof.
+ * - `failed`     — the read-back contradicts the write. The model is told
+ *                  what was found and asked for ONE correction through the
+ *                  same policy and ledger path; never to repeat the write.
+ *
+ * Bounded by construction: each verifier makes a few reads, polls for at most
+ * `waitMs` (small, per action), and stops on the turn's abort signal. It never
+ * dispatches a write, and its reads are not stashed as evidence. Undefined
+ * means "no opinion" — nothing is appended, which is what every action
+ * without a verifier gets.
+ */
+
+const rec = v => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+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
+    });
+  });
+}
+
+/** Poll `read` every `everyMs` until `until` says so or `waitMs` is spent. Returns the last read. */
+async function poll(read, until, waitMs, everyMs, signal) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const value = await read();
+    if (until(value)) return {
+      value,
+      satisfied: true
+    };
+    if (signal?.aborted || Date.now() + everyMs > deadline) return {
+      value,
+      satisfied: false
+    };
+    await sleep(everyMs, signal);
+  }
+}
+
+/** Every key in `want` present in `have` with an equal (deep) value. Arrays compare whole. */
+function isSubset(want, have) {
+  if (want === null || typeof want !== "object" || Array.isArray(want)) return JSON.stringify(want) === JSON.stringify(have);
+  const h = rec(have);
+  if (!h) return false;
+  for (const [k, v] of Object.entries(want)) {
+    if (!(k in h)) return false;
+    if (!isSubset(v, h[k])) return false;
+  }
+  return true;
+}
+
+/**
+ * The adapters' path grammar — dotted keys, `[0]`, and the id-addressed
+ * `[field=value]` the prompt recommends for list edits ("lines[lineId=seed-1].qty").
+ * A mirror of shared/sync/valuePath.ts, kept here because agent-core imports
+ * nothing. The first live run wrote exactly that form and this resolver, then
+ * dotted-only, reported a landed edit as "did not take".
+ */
+function atPath(root, path) {
+  const segs = path.replace(/^\/+/, "").match(/\[[^\]]*\]|[^.[\]/]+/g) ?? [];
+  let cur = root;
+  for (const seg of segs) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    if (seg.startsWith("[")) {
+      const inner = seg.slice(1, -1).trim();
+      if (!Array.isArray(cur)) return undefined;
+      const eq = inner.indexOf("=");
+      if (eq < 0) {
+        cur = cur[Number(inner)];
+      } else {
+        const field = inner.slice(0, eq).trim();
+        const value = inner.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+        cur = cur.find(el => el && typeof el === "object" && String(el[field]) === value);
+      }
+    } else {
+      cur = cur[seg];
+    }
+  }
+  return cur;
+}
+const brief = v => {
+  const s = JSON.stringify(v);
+  return s === undefined ? "undefined" : s.length > 80 ? `${s.slice(0, 77)}…` : s;
+};
+
+// ── the verifiers ────────────────────────────────────────────────────────────
+
+const storageSetItem = async ({
+  params,
+  dispatch
+}) => {
+  if (typeof params.key !== "string") return undefined;
+  const back = await dispatch("storage", "async.getItem", {
+    key: params.key
+  });
+  const value = typeof back === "string" ? back : rec(back)?.value;
+  const wanted = typeof params.value === "string" ? params.value : JSON.stringify(params.value);
+  if (value === wanted) return {
+    status: "verified",
+    detail: `Read back: "${params.key}" now holds the written value.`
+  };
+  return {
+    status: "failed",
+    detail: `Read back after the write: "${params.key}" holds ${brief(value)}, not what was written. The write did not take.`
+  };
+};
+const zustandSetState = async ({
+  params,
+  dispatch,
+  after
+}) => {
+  if (typeof params.storeName !== "string") return undefined;
+  const back = rec(after !== undefined ? after : await dispatch("zustand", "getStoreState", {
+    storeName: params.storeName
+  }));
+  if (!back || back.found === false) return {
+    status: "failed",
+    detail: `Read back: store "${params.storeName}" could not be read after the write.`
+  };
+  const current = back.currentState;
+  if (typeof params.path === "string") {
+    const got = atPath(current, params.path);
+    if (JSON.stringify(got) === JSON.stringify(params.value)) return {
+      status: "verified",
+      detail: `Read back: ${params.storeName}.${params.path} is now ${brief(got)}.`
+    };
+    return {
+      status: "failed",
+      detail: `Read back: ${params.storeName}.${params.path} is ${brief(got)}, not ${brief(params.value)}. The store did not take the write.`
+    };
+  }
+  const want = rec(params.state);
+  if (!want) return undefined;
+  if (isSubset(want, current)) return {
+    status: "verified",
+    detail: `Read back: "${params.storeName}" now holds the written fields (${Object.keys(want).join(", ")}).`
+  };
+  const wrong = Object.keys(want).filter(k => !isSubset(want[k], rec(current)?.[k]));
+  return {
+    status: "failed",
+    detail: `Read back: "${params.storeName}" does not hold the written value for ${wrong.join(", ")}. The store did not take the write — read it before deciding what to do.`
+  };
+};
+const querySetQueryData = async ({
+  params,
+  dispatch,
+  after
+}) => {
+  const key = params.queryHash !== undefined ? {
+    queryHash: params.queryHash
+  } : params.queryKey !== undefined ? {
+    queryKey: params.queryKey
+  } : undefined;
+  if (!key) return undefined;
+  const back = rec(after !== undefined ? after : await dispatch("query", "getQueryData", key));
+  if (!back || back.found === false) return {
+    status: "failed",
+    detail: "Read back: the query could not be read after the write."
+  };
+  const data = back.data;
+  if (typeof params.path === "string") {
+    const got = atPath(data, params.path);
+    if (JSON.stringify(got) === JSON.stringify(params.value)) return {
+      status: "verified",
+      detail: `Read back: the cached ${params.path} is now ${brief(got)}.`
+    };
+    return {
+      status: "failed",
+      detail: `Read back: the cached ${params.path} is ${brief(got)}, not ${brief(params.value)}. The cache did not take the write — the app may have refetched over it.`
+    };
+  }
+  if (params.data === undefined) return undefined;
+  if (isSubset(params.data, data)) return {
+    status: "verified",
+    detail: "Read back: the cache now holds the written data."
+  };
+  return {
+    status: "failed",
+    detail: "Read back: the cache does not hold the written data — the app may have refetched over it, or the shape differed."
+  };
+};
+const navigate = async ({
+  params,
+  dispatch,
+  signal
+}) => {
+  if (typeof params.path !== "string") return undefined;
+  const wanted = params.path.split("?")[0];
+  const {
+    value,
+    satisfied
+  } = await poll(async () => rec(await dispatch("route-events", "getCurrentRoute", {})), r => typeof r?.path === "string" && (r.path === wanted || r.path.split("?")[0] === wanted), 2_000, 250, signal);
+  if (satisfied) return {
+    status: "verified",
+    detail: `The app is now on ${wanted}.`
+  };
+  const at = typeof value?.path === "string" ? value.path : "an unknown route";
+  return {
+    status: "failed",
+    detail: `Two seconds after navigating, the app is on ${at}, not ${wanted}. Do not navigate again blindly — check the route exists (the sitemap) and whether something redirected.`
+  };
+};
+const upsertOverrideRule = async ({
+  params,
+  result,
+  dispatch,
+  signal
+}) => {
+  const id = rec(rec(result)?.rule)?.id ?? rec(params.rule)?.id;
+  if (typeof id !== "string") return undefined;
+  const find = async () => {
+    const list = rec(await dispatch("network", "listOverrideRules", {}));
+    const rules = Array.isArray(list?.rules) ? list.rules : [];
+    return rules.map(rec).find(r => r?.id === id);
+  };
+  const {
+    value,
+    satisfied
+  } = await poll(find, r => typeof r?.hits === "number" && r.hits > 0, 3_000, 500, signal);
+  if (!value) return {
+    status: "failed",
+    detail: "The rule is not in the override list after the write. It did not install."
+  };
+  if (value.enabled === false) return {
+    status: "failed",
+    detail: "The rule is installed but disabled, so it will not fire."
+  };
+  if (satisfied) return {
+    status: "verified",
+    detail: `The rule has matched ${value.hits} request${value.hits === 1 ? "" : "s"} — the app has already received the overridden response.`
+  };
+  return {
+    status: "unverified",
+    detail: "The rule is installed, but no request has matched it yet — the app is still showing whatever it loaded before. A refetch or a visit to the screen that fetches this will exercise it; until then, do not say the screen shows the override."
+  };
+};
+const VERIFIERS = exports.VERIFIERS = {
+  "storage.async.setItem": storageSetItem,
+  "zustand.setState": zustandSetState,
+  "query.setQueryData": querySetQueryData,
+  "route-events.navigate": navigate,
+  "network.upsertOverrideRule": upsertOverrideRule
+};
+
+/** Run the verifier for this action, if there is one. Never throws: a read that blows up is "no opinion". */
+async function verifyOutcome(input) {
+  const verifier = VERIFIERS[`${input.toolId}.${input.action}`];
+  if (!verifier) return undefined;
+  try {
+    return await verifier(input);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The trailer the model reads. Kept in the `[Buoy] ` trailer form the bench's parser splits on. */
+function verificationTrailer(v) {
+  switch (v.status) {
+    case "verified":
+      return `\n\n[Buoy] Verified: ${v.detail}`;
+    case "unverified":
+      return `\n\n[Buoy] Unverified: ${v.detail}`;
+    case "failed":
+      return `\n\n[Buoy] Check FAILED: ${v.detail} You may correct this ONCE — read the current state first, then make a different, targeted change; never repeat the same write and never claim the outcome happened.`;
+  }
+}
+//# sourceMappingURL=verify.js.map