@buoy-gg/agent-core 7.0.35 → 7.0.36

package/lib/typescript/catalog/normalizeParams.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Parameter aliases — accept what models actually send.
+ *
+ * The provider sees ONE tool per Buoy tool with `params` as an open object
+ * (see toProviderTools.ts), so the per-action parameter names live in prose
+ * and every model has to reproduce them from memory. A sweep of 18 models
+ * against the live app showed the same handful of misses over and over, on
+ * cheap models AND on gpt-5 and Gemini 2.5 Pro:
+ *
+ *   queryKey: [...]   where the action wants queryHash   (by far the #1 miss —
+ *                     the RIGHT NOW block shows keys as arrays, and
+ *                     setQueryData takes queryKey, so the model reuses it)
+ *   requestId         where network.getEventBody wants id
+ *   newState/patch    where zustand.setState wants state
+ *   name              where zustand wants storeName
+ *   bodyPatch/body/…  at the top level of upsertOverrideRule instead of inside `rule`
+ *
+ * A validation error names the right field, but a cheap model repeats the same
+ * wrong call or gives up, and the user sees "nothing happened". Every one of
+ * these is mechanically unambiguous, so it is fixed HERE, before validation,
+ * and the result carries a one-line note so the model learns the real name
+ * without failing the call. Nothing here guesses: an alias only fires when the
+ * canonical field is absent and the alias is present.
+ */
+export interface NormalizedParams {
+    params: Record<string, unknown>;
+    /** Human-readable notes about what was accepted, for the tool result. */
+    notes: string[];
+}
+/**
+ * TanStack's default `hashKey`: JSON.stringify with plain-object keys sorted,
+ * so `["todos", {page:1, sort:"a"}]` hashes the same whatever order the model
+ * wrote the object in.
+ */
+export declare function hashQueryKey(key: unknown[]): string;
+/**
+ * Fix the unambiguous parameter-name misses before validation. Returns the
+ * same object shape validation expects plus the notes to append to the result.
+ */
+export declare function normalizeParams(toolId: string, action: string, raw: Record<string, unknown>): NormalizedParams;
+/** The one-line trailer appended to a tool result when aliases fired. */
+export declare function aliasNote(notes: string[]): string;
+//# sourceMappingURL=normalizeParams.d.ts.map

package/lib/typescript/catalog/normalizeParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeParams.d.ts","sourceRoot":"","sources":["../../../src/catalog/normalizeParams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,CAWnD;AA4TD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,gBAAgB,CAoBlB;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEjD"}

package/lib/typescript/catalog/signature.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Rendering a JSON Schema as the one-line signature a model reads.
+ *
+ * Lifted out of `blocks/uiTool.ts`, where it was written for `buoy_ui` and
+ * where its own comment records the result that justifies using it everywhere:
+ *
+ *   > `uiProviderTool` used to send `params: { type: "object" }` and 26 lines
+ *   > of prose about what each kind is FOR — and not one field name. The model
+ *   > was being asked to guess `images` vs `items` and `chips` vs `options`,
+ *   > and it guessed wrong three rounds running.
+ *
+ * The other 24 tools still send exactly that: an open `params` object and a
+ * sentence promising the error will explain the shape. `normalizeParams.ts`
+ * exists to catch the five misses that produced most often. This renders the
+ * field names instead, from the SAME schema `validateParams` enforces, so what
+ * the model reads can never drift from what the validator accepts.
+ */
+import type { JsonSchema } from "../types";
+/** `{ url*, alt?, caption? }` — `*` marks required. */
+export declare function signature(schema: JsonSchema | undefined, depth?: number): string;
+/**
+ * The `params:` line under an action, or "" when the action takes none.
+ *
+ * Actions with no declared properties (71 of 192) get nothing rather than an
+ * empty `{}` — a line that says the action takes no arguments is already said
+ * by its absence, and 71 of them would be pure noise.
+ */
+export declare function paramsLine(schema: JsonSchema | undefined): string;
+//# sourceMappingURL=signature.d.ts.map

package/lib/typescript/catalog/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/catalog/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,MAAM,CA+B3E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAIjE"}

package/lib/typescript/catalog/snapshotReads.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshotReads.d.ts","sourceRoot":"","sources":["../../../src/catalog/snapshotReads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,gEAAgE;AAChE,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAyM7C;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAeT"}
+{"version":3,"file":"snapshotReads.d.ts","sourceRoot":"","sources":["../../../src/catalog/snapshotReads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,gEAAgE;AAChE,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAgN7C;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAeT"}

package/lib/typescript/catalog/toProviderTools.d.ts

@@ -1,24 +1,37 @@
+import type { ToolDescriptor } from "../types";
 /**
- * Catalog -> provider tool definitions.
- *
- * WHY ONE TOOL PER BUOY TOOL, NOT ONE PER ACTION: tool-selection accuracy
- * degrades past roughly 30-50 tools. Buoy has ~179 actions across 22 tools, so
- * a 1:1 mapping is far past the point where the model starts picking wrong.
- * Each Buoy tool therefore becomes ONE provider tool whose `action` property is
- * an enum, with the per-action summaries folded into that enum's description.
+ * Provider-agnostic tool definition; the adapters reshape it per protocol.
  *
- * `params` stays an open object at the provider boundary — a discriminated
- * union across 179 branches is unusable by any model and unreadable by a human.
- * The real per-action schema is enforced one layer in, by `validateParams`,
- * which returns a structured error the model can correct on the next turn.
- * That is strictly stronger than the MCP server's `z.record(z.unknown())`,
- * which validates nothing.
+ * The description comes in three forms because the two protocols cap it
+ * differently. Anthropic takes `description` whole. OpenAI (and Azure, and
+ * every OpenAI-compatible gateway) caps a function description at 1024
+ * chars, and the catalog renders the summary first and the `Actions:` list
+ * LAST — so trimming `description` to fit dropped every action line for 23
+ * of 24 tools (the 24th kept one line of sixteen), and a model on that
+ * protocol saw a summary cut mid-sentence plus a bare `action` enum. Hence
+ * the split: `summaryDescription` is the part that fits the cap,
+ * `actionsBlock` goes into the `action` property's description, which
+ * nothing caps. `description` stays their concatenation
+ * so the Anthropic request is byte-identical to what it was.
  */
-import type { ToolDescriptor } from "../types";
-/** Provider-agnostic tool definition; the adapters reshape it per protocol. */
 export interface ProviderTool {
     name: string;
+    /** `summaryDescription` + `actionsBlock` — the whole thing. */
     description: string;
+    /** The tool's summary alone — the part that fits OpenAI's 1024-char cap. */
+    summaryDescription: string;
+    /** `Unavailable when: …` (if any) then `Actions:` and one `- <action> — <summary> [tags]` line each. */
+    actionsBlock: string;
+    /**
+     * Worked example inputs, sent as Anthropic's `input_examples`.
+     *
+     * Anthropic report 72% -> 90% on complex parameter handling. Their own
+     * framing is that JSON Schema "can't express usage patterns: when to include
+     * optional parameters, which combinations make sense, or what conventions
+     * your API expects" — which is the gap between knowing a field's NAME and
+     * knowing its SHAPE, and the gap the params signatures did not close.
+     */
+    inputExamples?: Record<string, unknown>[];
     inputSchema: {
         type: "object";
         properties: Record<string, unknown>;

package/lib/typescript/catalog/toProviderTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toProviderTools.d.ts","sourceRoot":"","sources":["../../../src/catalog/toProviderTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,UAAU,CAAC;AAEjE,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,oBAAoB,EAAE,OAAO,CAAC;KAC/B,CAAC;CACH;AASD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EAAE,GACxB,MAAM,GAAG,SAAS,CAEpB;AAmBD,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EAAE,EACzB,IAAI,GAAE,sBAA2B,GAChC,YAAY,EAAE,CAiEhB"}
+{"version":3,"file":"toProviderTools.d.ts","sourceRoot":"","sources":["../../../src/catalog/toProviderTools.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,UAAU,CAAC;AAEjE;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC1C,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,oBAAoB,EAAE,OAAO,CAAC;KAC/B,CAAC;CACH;AASD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EAAE,GACxB,MAAM,GAAG,SAAS,CAEpB;AA0BD,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EAAE,EACzB,IAAI,GAAE,sBAA2B,GAChC,YAAY,EAAE,CA4EhB"}

package/lib/typescript/context/buildContextPack.d.ts

@@ -8,6 +8,21 @@
  * ~5.7KB (~1.5K tokens) covering routes, env, query keys, redux slices,
  * zustand stores, jotai atoms, storage keys and API hosts.
  *
+ * TWO HALVES, READ ON TWO SCHEDULES.
+ *
+ * The STABLE half (routes, slices, stores, atoms, storage keys, env names) is
+ * read once when the chat opens and rendered inside the cached system block.
+ * It changes rarely, and when it does the cache re-warms once.
+ *
+ * The LIVE half — the current route, which queries are MOUNTED right now, the
+ * last few requests — is read again before EVERY turn and rendered as a
+ * separate, uncached block. This exists because of one failure: asked to
+ * "rename the Pokémon I'm looking at", the model went to an empty zustand cart
+ * because the once-at-open digest had been built before any query was cached,
+ * so React Query never appeared in its prompt at all. A query with
+ * `observers > 0` IS what the screen is rendering; that fact has to be in
+ * front of the model at the moment it decides which tool to reach for.
+ *
  * What this does NOT do, and why:
  * - No `getSnapshot('query')`. It returns the full dehydrated cache — 8.3KB for
  *   ten queries in that same measurement, growing with every cached payload.
@@ -22,11 +37,18 @@
 import type { DispatchFn, SnapshotFn } from "../types";
 export interface BuildContextInput {
     dispatch: DispatchFn;
-    /** Needed by the snapshot-only probes (routes, env). */
+    /** Needed by the snapshot-only probes (routes, env, network). */
     readSnapshot?: SnapshotFn;
     /** Tool ids actually present, so we do not probe what cannot answer. */
     availableToolIds: string[];
     availableActions?: Record<string, string[]>;
 }
-export declare function buildContextDigest({ dispatch, readSnapshot, availableToolIds, availableActions, }: BuildContextInput): Promise<Record<string, unknown>>;
+/** The stable half: read once at open, rendered inside the cached prompt. */
+export declare function buildContextDigest(input: BuildContextInput): Promise<Record<string, unknown>>;
+/**
+ * The live half: read before every turn. Current route, mounted queries,
+ * recent requests, armed overrides. Rendered as the uncached "RIGHT NOW"
+ * block — see `buildLiveBlock` in systemPrompt.ts.
+ */
+export declare function buildLiveContext(input: BuildContextInput): Promise<Record<string, unknown>>;
 //# sourceMappingURL=buildContextPack.d.ts.map

package/lib/typescript/context/buildContextPack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildContextPack.d.ts","sourceRoot":"","sources":["../../../src/context/buildContextPack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAiHvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,CAAC;IACrB,wDAAwD;IACxD,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C;AAED,wBAAsB,kBAAkB,CAAC,EACvC,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAsCtD"}
+{"version":3,"file":"buildContextPack.d.ts","sourceRoot":"","sources":["../../../src/context/buildContextPack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAsVvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,CAAC;IACrB,iEAAiE;IACjE,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C;AA6CD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE7F;AAsFD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAIjG"}

package/lib/typescript/effects/digest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A short, stable fingerprint of any JSON-able value. Not cryptographic —
+ * it only has to answer "is this the same as what I saw?" — and deliberately
+ * lossy so the thing persisted beside an unanswered approval or a ledger
+ * entry is a hash of a store's state, never the state itself.
+ */
+export declare function digestOf(value: unknown): string | undefined;
+/** Byte-ish size of a value once serialised; Infinity when it cannot be. */
+export declare function jsonLength(value: unknown): number;
+//# sourceMappingURL=digest.d.ts.map

package/lib/typescript/effects/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../../src/effects/digest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAU3D;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMjD"}

package/lib/typescript/effects/ledger.d.ts

@@ -49,6 +49,26 @@ export type AppliedEffect = {
     /** The action that removes the key, for the did-not-exist case. */
     removeAction?: string;
     label: string;
+} | {
+    /**
+     * A React Query cache edit, reversible because the engine reads the
+     * query's data before `setQueryData` runs (see captureStoreState). This
+     * was the most common write in a real QA session — nine of eleven —
+     * and it was filed as a permanent `state-write`, so the changes bar
+     * promised undo and then said "can't be undone automatically" for the
+     * one thing the tester had actually changed.
+     */
+    kind: "query-write";
+    queryHash: string;
+    /** The cached data before this write; undefined when the query held none. */
+    before?: unknown;
+    /**
+     * Fingerprint of the data as this write left it. A refetch replaces the
+     * cache underneath us; restoring `before` over fresh server data would
+     * be a second unwanted edit, so undo compares first.
+     */
+    wroteDigest?: string;
+    label: string;
 } | {
     kind: "state-write";
     toolId: string;
@@ -89,8 +109,43 @@ export interface RevertOutcome {
 export declare class EffectLedger {
     private entries;
     private listeners;
+    private gen;
+    /**
+     * Which conversation this ledger is holding, bumped by `clear`.
+     *
+     * A turn captures it when it starts and hands it back on every `record`.
+     * Nothing about a dispatch can be pulled back once it is in flight, so a
+     * write that settles after the user has already tapped "New conversation"
+     * still lands in the app — but it must not land in the NEW conversation's
+     * undo bar, which is what happened: reset cleared the ledger, the old
+     * write finished a moment later, and an empty chat came up owning a change
+     * nobody in it had made. Recording it here would be worse than dropping it,
+     * because Undo would then offer to reverse something the user cannot see.
+     */
+    get generation(): number;
+    /**
+     * @param generation The value of `generation` when the turn began. Omit for
+     * a human-initiated action, which is by definition happening now — and which
+     * therefore always returns an entry.
+     */
     record(toolId: string, action: string, effect: AppliedEffect): LedgerEntry;
+    record(toolId: string, action: string, effect: AppliedEffect, generation: number): LedgerEntry | undefined;
     list(): LedgerEntry[];
+    /**
+     * Put back the entries of a conversation that outlived the app.
+     *
+     * The ledger is the ONLY undo surface, and it used to die with the JS
+     * context: after a reload the transcript came back — receipt cards, "saved"
+     * lines and all — while the changes bar quietly vanished and the changes
+     * themselves stayed applied. "New conversation" warns before losing that
+     * ("Clearing the conversation loses the only automatic undo for it"); a
+     * reload took the same thing without asking.
+     *
+     * Refuses once anything has been recorded, for the same reason `hydrate`
+     * refuses a live transcript: a late disk read must not shuffle old entries
+     * in among changes made since.
+     */
+    restore(entries: LedgerEntry[]): boolean;
     /** New array identity for the snapshot after entries were mutated in place. */
     private touch;
     /** Not-yet-undone entries that Undo can actually deliver on. Agrees with

package/lib/typescript/effects/ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../src/effects/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE3D;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAyB;IAE1C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW;IAiB1E,IAAI,IAAI,WAAW,EAAE;IAIrB,+EAA+E;IAC/E,OAAO,CAAC,KAAK;IAKb;;4EAEwE;IACxE,UAAU,IAAI,WAAW,EAAE;IAI3B,4EAA4E;IAC5E,UAAU,IAAI,WAAW,EAAE;IAI3B,OAAO,IAAI,OAAO;IAIlB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,KAAK,IAAI,IAAI;IAKb;;;;;;OAMG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAyBzF,OAAO,CAAC,IAAI;IAUZ,wEAAwE;IAClE,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAqEtF,uDAAuD;IACjD,SAAS,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;CAgB9D"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../src/effects/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE;;;;;;;OAOG;IACH,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE3D;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,GAAG,CAAK;IAEhB;;;;;;;;;;;OAWG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW;IAC1E,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,MAAM,GACjB,WAAW,GAAG,SAAS;IAwB1B,IAAI,IAAI,WAAW,EAAE;IAIrB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO;IAOxC,+EAA+E;IAC/E,OAAO,CAAC,KAAK;IAKb;;4EAEwE;IACxE,UAAU,IAAI,WAAW,EAAE;IAI3B,4EAA4E;IAC5E,UAAU,IAAI,WAAW,EAAE;IAI3B,OAAO,IAAI,OAAO;IAIlB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,KAAK,IAAI,IAAI;IAQb;;;;;;OAMG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAyBzF,OAAO,CAAC,IAAI;IAUZ,wEAAwE;IAClE,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAsGtF,uDAAuD;IACjD,SAAS,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;CAgB9D"}

package/lib/typescript/engine/askGate.d.ts

@@ -0,0 +1,29 @@
+import type { ActionsBlock, ChoiceBlock } from "../blocks/types";
+/**
+ * The block a turn should have ended with, or null to leave the prose alone.
+ *
+ * `text` is everything the model said this turn, rounds joined in order.
+ */
+export declare function synthesizeAskBlock(text: string): ChoiceBlock | null;
+/**
+ * `attempted` — did this turn call anything that GOES AND GETS data?
+ * Keyed on the actions the prompt's ladder names, so the two move together.
+ */
+export declare const ACQUISITION_CALLS: Set<string>;
+export interface ShortfallInput {
+    /** Everything the model said this turn, rounds joined in order. */
+    text: string;
+    /** Whether any ACQUISITION_CALLS ran this turn. */
+    attempted: boolean;
+}
+/**
+ * The block a turn should have ended with when it conceded a gap and never
+ * tried to close it, or null to leave the prose alone.
+ *
+ * An `actions` block, not a `choice`: nothing is being ASKED here. The turn is
+ * over and the answer stands; this is one button that says the gap is closable
+ * and closes it. So it must not end the turn or set `awaiting-user` — a
+ * synthesized card must never look like it is blocking on a reply.
+ */
+export declare function synthesizeShortfallBlock({ text, attempted }: ShortfallInput): ActionsBlock | null;
+//# sourceMappingURL=askGate.d.ts.map

package/lib/typescript/engine/askGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"askGate.d.ts","sourceRoot":"","sources":["../../../src/engine/askGate.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAgB,MAAM,iBAAiB,CAAC;AAuD/E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAwBnE;AA0FD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAS5B,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,cAAc,GAAG,YAAY,GAAG,IAAI,CAuBjG"}

package/lib/typescript/engine/effectFor.d.ts

@@ -17,5 +17,10 @@ import type { AppliedEffect } from "../effects/ledger";
 export declare function effectFor(toolId: string, descriptor: ActionDescriptor, params: Record<string, unknown>, result: unknown, before: {
     had: boolean;
     value?: string;
-} | undefined): AppliedEffect | undefined;
+} | undefined, 
+/** The query cache read before and after a `setQueryData` — see runAgentTurn. */
+cache?: {
+    before?: unknown;
+    after?: unknown;
+}): AppliedEffect | undefined;
 //# sourceMappingURL=effectFor.d.ts.map

package/lib/typescript/engine/effectFor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effectFor.d.ts","sourceRoot":"","sources":["../../../src/engine/effectFor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACnD,aAAa,GAAG,SAAS,CAwD3B"}
+{"version":3,"file":"effectFor.d.ts","sourceRoot":"","sources":["../../../src/engine/effectFor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAmCvD,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS;AACpD,iFAAiF;AACjF,KAAK,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C,aAAa,GAAG,SAAS,CA6G3B"}

package/lib/typescript/engine/historyBudget.d.ts

@@ -0,0 +1,92 @@
+/**
+ * How much conversation the model is allowed to be sent, and what gets cut.
+ *
+ * Lives here, not in `session.ts`, because it is needed in TWO places and used
+ * to run in only one. The session trims once per turn, before the loop starts
+ * — and a turn is not one request. A twelve-step investigation appends an
+ * assistant message and a tool-results message per step, each result capped at
+ * 24,000 characters, so a long read chain could add well over a hundred
+ * thousand characters AFTER the only check had already happened and walk
+ * straight into the provider's context limit. The engine now applies the same
+ * budget before every request; the session still applies it when a turn opens.
+ */
+import type { AgentMessage } from "../providers/types";
+/**
+ * A long QA session must not die on the provider's context limit with an
+ * opaque error, so the history is kept under a budget.
+ *
+ * TWO STAGES, AND THE ORDER IS THE POINT. Dropping the oldest rounds was the
+ * only stage, and in a QA session the oldest round is usually the SETUP — the
+ * override that was armed, the store that was written, the user someone is
+ * impersonating. Drop it and the model can no longer explain the screen it is
+ * looking at, or that a "wrong" response is its own mock. The reply gets worse
+ * in exactly the sessions long enough to need trimming.
+ *
+ * So: COMPRESS first, DROP only if that was not enough.
+ *
+ * A tool result is "consumed" once the model has produced an assistant message
+ * after seeing it — it has already been reasoned over, and what remains is
+ * bulk. Replacing it with a marker keeps the round, its decision and its
+ * ordering while giving back nearly all the bytes. Three exemptions carry
+ * their weight:
+ *
+ * - Errors are never compressed. A failure is the diagnostic value.
+ * - The newest tool-results message is never compressed. The model is about
+ *   to answer from it.
+ * - The last read before a WRITE is never compressed: that is the shape the
+ *   model matched its edit to, and it is the thing it re-reads when the write
+ *   is refused and it has to correct itself.
+ *
+ * Only if the history is still over budget do whole rounds get dropped, as
+ * before — a round starts at a user message, so the assistant/tool-result
+ * pairing every provider requires stays intact.
+ */
+export declare const MAX_HISTORY_CHARS = 150000;
+/**
+ * The ceiling on a WHOLE request: tools, system prompt, messages and the room
+ * reserved for the reply. ~100k tokens, which fits the smallest context Ask
+ * Buoy is pointed at in practice (a 128k-token gateway) with headroom, and
+ * leaves Anthropic's 200k far from the limit.
+ */
+export declare const MAX_REQUEST_CHARS = 400000;
+export declare function messageSize(m: AgentMessage): number;
+/**
+ * Replace consumed tool results with a marker. See the note above
+ * MAX_HISTORY_CHARS for what "consumed" means and why the exemptions exist.
+ */
+export declare function compressConsumed(messages: AgentMessage[]): AgentMessage[];
+/**
+ * Trim, and say how many whole rounds were dropped — the number the UI turns
+ * into "older messages were trimmed from the agent's memory".
+ *
+ * A round is a user message and everything up to the next one. Once a drop
+ * starts it ALWAYS runs to the next user boundary: the inner loop used to stop
+ * at `MIN_KEEP_MESSAGES` as well, so a history could come out starting with an
+ * assistant or tool-results message — which every provider rejects. The
+ * minimum-keep guard belongs on STARTING a drop, not on finishing one.
+ */
+export declare function trimHistoryReport(messages: AgentMessage[]): {
+    messages: AgentMessage[];
+    droppedRounds: number;
+};
+/** Exported for the history tests; not part of the package surface. */
+export declare function trimHistory(messages: AgentMessage[]): AgentMessage[];
+/**
+ * Trim the working history of a turn that is still running.
+ *
+ * Differs from `trimHistoryReport` in one way that matters: the CURRENT round
+ * is never touched. A turn's own user message and the reads it has taken since
+ * are the thing being answered, so compressing or dropping them would make the
+ * request cheaper and the answer wrong. Everything before the last user
+ * message is fair game, in the same order as always — compress, then drop.
+ *
+ * `reserve` is what the request costs BEFORE any messages: the tool
+ * definitions (~8k tokens for a typical install, ~23k with everything
+ * installed), the system prompt, and the reply the model is allowed to write.
+ * Budgeting messages alone would leave the biggest fixed cost out of the sum.
+ */
+export declare function budgetForRequest(messages: AgentMessage[], reserve: number): {
+    messages: AgentMessage[];
+    droppedRounds: number;
+};
+//# sourceMappingURL=historyBudget.d.ts.map

package/lib/typescript/engine/historyBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"historyBudget.d.ts","sourceRoot":"","sources":["../../../src/engine/historyBudget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAC;AACzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAC;AAKzC,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAMnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CA6CzE;AASD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG;IAC3D,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB,CAwBA;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAqDrD"}

package/lib/typescript/engine/runAgentTurn.d.ts

@@ -20,10 +20,22 @@ import type { DispatchFn, SnapshotFn, ToolDescriptor } from "../types";
 import type { AgentMessage, Provider } from "../providers/types";
 import { EffectLedger } from "../effects/ledger";
 import { type AskBuoyPolicy } from "../policy/policy";
+import { digestOf } from "../effects/digest";
 import { type Block } from "../blocks/types";
 export type TurnEvent = {
     type: "text";
     delta: string;
+    /**
+     * This delta opens a new round of the same answer.
+     *
+     * One assistant bubble spans every round of a multi-step run, so without
+     * a marker the last sentence of one round and the first of the next are
+     * concatenated — "…resets every launch.Here's the full picture…". The
+     * ENGINE is the only layer that knows where a round ends: the UI sees a
+     * flat stream of deltas, and the tool events it used to infer the
+     * boundary from are not always there (a declined approval runs no tool).
+     */
+    breakBefore?: boolean;
 }
 /**
  * The model's own reasoning for this turn, when the provider reports any.
@@ -36,6 +48,18 @@ export type TurnEvent = {
  | {
     type: "reasoning";
     text: string;
+}
+/**
+ * Whole rounds were dropped from the model's memory before this turn.
+ *
+ * Yielded by the SESSION (which owns trimming), never by the engine. The
+ * screen still shows those rounds, so without this the transcript and the
+ * model silently disagree — the user asks "turn off that override" and the
+ * model, having lost the round that armed it, asks which one.
+ */
+ | {
+    type: "history-trimmed";
+    droppedRounds: number;
 } | {
     type: "tool-start";
     id: string;
@@ -93,11 +117,20 @@ export type TurnEvent = {
     type: "error";
     message: string;
 }
-/** Token usage for one provider request, when the provider reports it. */
+/**
+ * Token usage for one provider request, when the provider reports it.
+ * `cacheRead`/`cacheWrite` are the prompt-cache counters (see TokenUsage —
+ * without them a cached Claude request looks nearly free) and `model` is
+ * the id the provider actually SERVED, which is what a cost table or a
+ * benchmark needs when a gateway alias drifts to a new snapshot.
+ */
  | {
     type: "usage";
     input: number;
     output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    model?: string;
 } | {
     type: "done";
 };
@@ -106,6 +139,8 @@ export interface RunTurnInput {
     catalog: ToolDescriptor[];
     messages: AgentMessage[];
     system: string;
+    /** Per-turn "right now" block. See ProviderRequest.systemVolatile. */
+    systemVolatile?: string;
     model: string;
     maxTokens: number;
     dispatch: DispatchFn;
@@ -131,10 +166,57 @@ export interface RunTurnInput {
         label: string;
         description: string;
         reason: string;
+        /**
+         * The exact call being asked about.
+         *
+         * The UI does not render it — an approval prompt shows the effect, not the
+         * payload. It travels so a card that OUTLIVES this turn can still run it:
+         * the sheet persists an unanswered approval, and after a reload the
+         * generator holding this promise no longer exists, so Allow has to
+         * re-dispatch the call itself.
+         */
+        params: Record<string, unknown>;
+        /**
+         * A fingerprint of the value this call is about to overwrite, read at the
+         * moment the question was asked — see `readTargetDigest`. A card that comes
+         * back after a restart re-reads and compares before it writes; a card
+         * answered live never needs it. Absent when the target cannot be read.
+         */
+        targetDigest?: string;
     }) => Promise<boolean>;
     signal?: AbortSignal;
+    /**
+     * Every http(s) URL this CONVERSATION has read out of a tool result. Owned
+     * by the session so it outlives one turn: "now show me those as pictures"
+     * is a normal second message, and a per-turn set answered it by silently
+     * stripping every image — the model then described artwork the user could
+     * not see. Provenance is still enforced, just over the whole conversation
+     * rather than one turn of it. Omitted (tests, one-shot callers) means a
+     * fresh per-turn set.
+     */
+    seenUrls?: Set<string>;
 }
 export declare function runAgentTurn(input: RunTurnInput): AsyncGenerator<TurnEvent, AgentMessage[], void>;
+export { digestOf };
+/**
+ * Fingerprint the value a write is about to replace.
+ *
+ * Built for the approval card that outlives its turn: the app crashed with
+ * "Set bag line L-01 qty to 14" still asking, relaunched, and the card came
+ * back — and Allow wrote qty 14 against whatever the bag was NOW, maybe a
+ * different account, maybe a line that no longer existed. A hash of the
+ * params alone would not catch that (same label, same params, different
+ * world). So the card carries a digest of the TARGET at ask time, and a
+ * restored Allow re-reads and compares before it writes. Undefined when the
+ * target cannot be read — then the card can only warn, not check.
+ */
+export declare function readTargetDigest(input: {
+    toolId: string;
+    action: string;
+    params: Record<string, unknown>;
+    dispatch: DispatchFn;
+    catalog?: ToolDescriptor[];
+}): Promise<string | undefined>;
 export interface GatedActionInput {
     toolId: string;
     action: string;

package/lib/typescript/engine/runAgentTurn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runAgentTurn.d.ts","sourceRoot":"","sources":["../../../src/engine/runAgentTurn.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runAgentTurn.d.ts","sourceRoot":"","sources":["../../../src/engine/runAgentTurn.ts"],"names":[],"mappings":"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"}