@buoy-gg/agent-core 7.0.35 → 7.0.38

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

@@ -0,0 +1,67 @@
+/**
+ * The evidence store: every tool result this conversation produced, kept in
+ * full so the model can go back to it.
+ *
+ * Two markers used to point nowhere. A result over 24 000 characters was cut
+ * with "ask for a narrower slice" — and no tool offers one, so the bank has
+ * cases tagged `capability` (Pokémon `stats` sit at offset ~180 000 of a
+ * 400 000-character detail; unreadable by design). And a result compressed
+ * out of memory said "ask again" — a re-dispatch returns the CURRENT value,
+ * not what the model saw before it wrote, which is the one it needs when a
+ * write is refused and it has to say what it changed FROM.
+ *
+ * So the full text is kept here, keyed by a short ref the markers carry, and
+ * `ask-buoy.retrieve` reads any part of it back: a path, a substring, a
+ * window. Borrowed from Strands' ContextOffloader (`retrieve_offloaded_content`
+ * with pattern / line_range), minus the storage layer — this is in-memory and
+ * per session on purpose: persisted transcripts deliberately carry no tool
+ * result payloads (see ask-buoy transcriptPersistence.ts), and this must not
+ * quietly change that.
+ *
+ * What goes in is what the MODEL was given: after `redact` (credential names
+ * and value shapes) and `stripSelfTraffic`. Never the raw adapter value.
+ *
+ * Bounded by bytes and entries, oldest out first; an evicted ref is remembered
+ * so the answer is "evicted" rather than "never existed" — the marker still
+ * names a real thing, and the honest reply is to call the tool again.
+ */
+export interface EvidenceEntry {
+    ref: string;
+    toolId: string;
+    action: string;
+    params: Record<string, unknown>;
+    /** Epoch ms when the result came back. */
+    capturedAt: number;
+    /** The redacted JSON text the model was shown (before any truncation). */
+    text: string;
+}
+export interface EvidenceStoreOptions {
+    /** Total characters kept across entries. Default 4 000 000 (~4 MB). */
+    maxChars?: number;
+    /** Entries kept. Default 200. */
+    maxEntries?: number;
+}
+export declare class EvidenceStore {
+    private readonly entries;
+    private readonly evictedRefs;
+    private readonly maxChars;
+    private readonly maxEntries;
+    private chars;
+    private seq;
+    constructor(opts?: EvidenceStoreOptions);
+    /** Keep a result. Returns its ref — `ev_<n>`, counting up for the life of the store. */
+    stash(input: Omit<EvidenceEntry, "ref">): string;
+    get(ref: string): EvidenceEntry | undefined;
+    /** True when the ref was real and has since been dropped for space. */
+    wasEvicted(ref: string): boolean;
+    get size(): number;
+    get totalChars(): number;
+    /** New conversation: nothing from the old one is retrievable. */
+    clear(): void;
+    private evict;
+}
+/** The tail of a result cut at the engine's cap. */
+export declare function truncationMarker(totalChars: number, ref: string | undefined): string;
+/** What a consumed result is replaced with when history is compressed. Keep the `[earlier result` prefix — historyBudget skips on it. */
+export declare function compressedMarker(totalChars: number, ref: string | undefined): string;
+//# sourceMappingURL=evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../src/engine/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAK;gBAEJ,IAAI,GAAE,oBAAyB;IAK3C,wFAAwF;IACxF,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,MAAM;IAWhD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI3C,uEAAuE;IACvE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,iEAAiE;IACjE,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,KAAK;CAUd;AAMD,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIpF;AAED,yIAAyI;AACzI,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIpF"}

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

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+/**
+ * The limits are in TOKENS — the unit the provider enforces — and turned into
+ * characters at the ratio the session has measured (engine/tokenCalibration.ts).
+ * The `_CHARS` constants below are those limits at the default 4 chars/token,
+ * kept for callers that have no calibration in hand (tests, one-shot use).
+ */
+export declare const MAX_HISTORY_TOKENS = 37500;
+/**
+ * The ceiling on a WHOLE request: tools, system prompt, messages and the room
+ * reserved for the reply. 100k tokens 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_TOKENS = 100000;
+export declare const MAX_HISTORY_CHARS: number;
+export declare const MAX_REQUEST_CHARS: number;
+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[], exemptNewest?: boolean): 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[], charsPerToken?: number, 
+/** Tool-call ids whose change is still applied — their rounds are dropped last. See dropRounds. */
+pinnedCallIds?: ReadonlySet<string>): {
+    messages: AgentMessage[];
+    droppedRounds: number;
+    /** Of `droppedRounds`, how many still held an applied change. */
+    droppedPinned: 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, 
+/**
+ * A tighter ceiling on the messages than MAX_HISTORY_CHARS — set by the
+ * engine after the provider refused a request as too big. The proactive
+ * budget is an estimate; the provider's refusal is the truth.
+ */
+cap?: number, 
+/** The session's measured ratio; scales the whole-request ceiling. */
+charsPerToken?: number, 
+/** Tool-call ids whose change is still applied — their rounds are dropped last. See dropRounds. */
+pinnedCallIds?: ReadonlySet<string>): {
+    messages: AgentMessage[];
+    droppedRounds: number;
+    droppedPinned: 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;AAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAC1C,eAAO,MAAM,iBAAiB,QAA+C,CAAC;AAC9E,eAAO,MAAM,iBAAiB,QAA+C,CAAC;AAK9E,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAMnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,YAAY,UAAO,GAAG,YAAY,EAAE,CAiD9F;AA2ED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EAAE,EACxB,aAAa,GAAE,MAAgC;AAC/C,mGAAmG;AACnG,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC;IACD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;CACvB,CAcA;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;AACf;;;;GAIG;AACH,GAAG,GAAE,MAA0B;AAC/B,sEAAsE;AACtE,aAAa,GAAE,MAAgC;AAC/C,mGAAmG;AACnG,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CA4D5E"}

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

@@ -0,0 +1,32 @@
+/**
+ * `ask-buoy.retrieve` — read part of a kept result back. See evidence.ts.
+ *
+ * Four ways in, chosen so the model never needs the whole thing again:
+ *
+ * - nothing but `ref`   → the SHAPE: top-level keys with type and size, so the
+ *                          next call can name a path. Handing back the full
+ *                          text would only hit the same cap that cut it.
+ * - `path`              → the value at a dotted / slash path ("stats.0.base_stat",
+ *                          "/moves/3/move/name"). Arrays index by number.
+ * - `slice: [a, b]`     → a window: items of an array, characters of a string.
+ *                          Combines with `path`.
+ * - `pattern`           → a literal, case-insensitive substring search over the
+ *                          pretty-printed text; matching lines with
+ *                          `contextLines` (default 2) around each. Not a regex:
+ *                          a model that means "height" should not have to
+ *                          escape anything, and an executable pattern over a
+ *                          store of app data is a surface nobody asked for.
+ *
+ * Every result is capped at the same size as any other tool result, and the
+ * engine never stashes a retrieve result — a retrieve of a retrieve is a loop.
+ */
+import type { EvidenceStore } from "./evidence";
+export interface RetrieveParams {
+    ref: string;
+    path?: string;
+    slice?: [number, number];
+    pattern?: string;
+    contextLines?: number;
+}
+export declare function retrieveEvidence(store: EvidenceStore | undefined, params: RetrieveParams): unknown;
+//# sourceMappingURL=retrieve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/engine/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAqDlG"}

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

@@ -20,10 +20,26 @@ 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";
+import { TokenCalibration } from "./tokenCalibration";
+import { type EvidenceStore } from "./evidence";
+import { type Verification } from "./verify";
+import type { Procedure } from "./systemPrompt";
 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 +52,25 @@ 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;
+    /**
+     * Of those, rounds that had made a change still applied — dropped only
+     * because nothing else was left. The caption should say so: the change
+     * is still in the app and still in the changes bar, but the model no
+     * longer remembers making it.
+     */
+    droppedPinned?: number;
 } | {
     type: "tool-start";
     id: string;
@@ -71,6 +106,17 @@ export type TurnEvent = {
      */
     result?: string;
 }
+/**
+ * The outcome check for a write that has one (engine/verify.ts), after its
+ * receipt: the row updates in place to "Verified" / "Done · not yet
+ * visible" / "Done · check failed". Its own event, not a second tool-end,
+ * so a consumer counting ends per call is not fooled.
+ */
+ | {
+    type: "tool-verified";
+    id: string;
+    verification: Verification;
+}
 /** A block to render — a receipt from a tool result, or a model-authored block. */
  | {
     type: "block";
@@ -93,19 +139,72 @@ export type TurnEvent = {
     type: "error";
     message: string;
 }
-/** Token usage for one provider request, when the provider reports it. */
+/**
+ * The model request failed before producing anything and is being sent
+ * again after a wait — see THROTTLE_RETRIES. Yielded so the thinking strip
+ * can say "endpoint busy, retrying in 2 s" rather than sit still.
+ */
+ | {
+    type: "retrying";
+    reason: "throttled" | "overflow";
+    attempt: number;
+    maxAttempts: number;
+    inMs: number;
+}
+/**
+ * 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";
+    stopReason: StopReason;
+};
+/**
+ * Why the turn ended — the machine-readable half of the notices. The text in
+ * the notice blocks is unchanged (the eval classifier pins it); this is for a
+ * host, the bank and the desktop, which used to have to grep the prose.
+ */
+export type StopReason = 
+/** The model wrote its answer and stopped calling tools. */
+"answered"
+/** An Ask block (the model's or the gate's) ended the turn; the answer comes as the next user message. */
+ | "awaiting-user"
+/** The model→tools→model cap (policy.maxSteps, default 12). */
+ | "step-cap"
+/** The wall-clock cap, approval time excluded. */
+ | "time-cap"
+/** The user pressed Stop. */
+ | "stopped"
+/** `app.reloadApp` ran; the JS realm is about to die and nothing after it can be answered. */
+ | "realm-died"
+/** The stream ended without the provider saying it finished, or the model ran out of room — recoverable with Continue. */
+ | "incomplete"
+/** A provider error, after any retries. */
+ | "error"
+/** The conversation was reset while this turn was getting ready; nothing was sent. */
+ | "superseded";
+export type ApprovalAnswer = boolean | {
+    approved: boolean;
+    reason?: string;
+    trust?: boolean;
 };
 export interface RunTurnInput {
     provider: Provider;
     catalog: ToolDescriptor[];
     messages: AgentMessage[];
     system: string;
+    /** Per-turn "right now" block. See ProviderRequest.systemVolatile. */
+    systemVolatile?: string;
     model: string;
     maxTokens: number;
     dispatch: DispatchFn;
@@ -123,7 +222,12 @@ export interface RunTurnInput {
     /** Live tool ids from `listToolActions()`, so absent tools are never offered. */
     availableToolIds?: string[];
     availableActions?: Record<string, string[]>;
-    /** Resolves once the user taps Approve/Reject on a pending call. */
+    /**
+     * Resolves once the user answers the pending call — a bare boolean, or the
+     * richer shape: a note with a decline goes to the model verbatim (one round
+     * trip saved), and `trust` on an approval waives the card for that
+     * tool.action for the rest of the conversation. See `trusted`.
+     */
     requestApproval?: (input: {
         id: string;
         toolId: string;
@@ -131,10 +235,82 @@ export interface RunTurnInput {
         label: string;
         description: string;
         reason: string;
-    }) => Promise<boolean>;
+        /**
+         * 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<ApprovalAnswer>;
+    /**
+     * `toolId.action` keys the user has waived the approval card for in THIS
+     * conversation ("Allow for this chat"). Session-owned and mutated here when
+     * an answer carries `trust`. It suppresses `needs-approval` only — `deny`,
+     * `allow`, `readOnly` and release refusals are the app saying no, not the
+     * app asking, and a waiver never widens what the agent can reach. The
+     * Strands HITL handler calls the same thing `enableTrust`, and keeps the
+     * same rule: a negated tool cannot be trusted.
+     */
+    trusted?: Set<string>;
+    /** The app's procedures this device can follow — served by `ask-buoy.openProcedure`. See systemPrompt.ts `Procedure`. */
+    procedures?: Procedure[];
     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>;
+    /**
+     * Where every result's full text is kept for `ask-buoy.retrieve` — see
+     * engine/evidence.ts. Session-owned, like `seenUrls`; absent (tests,
+     * one-shot callers) means results are not retrievable and the markers say
+     * so.
+     */
+    evidence?: EvidenceStore;
+    /**
+     * The session's measured chars-per-token (engine/tokenCalibration.ts). Read
+     * for every budget and fed after every usage report. Absent means the
+     * default ratio, uncorrected.
+     */
+    calibration?: TokenCalibration;
 }
 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":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAoB,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAKzF,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAgB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK5E,OAAO,EAAc,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAazD,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACjC;;;;;;;GAOG;GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oDAAoD;IACpD,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;CAC1C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACH,mFAAmF;GACjF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE;AACzD,oFAAoF;GAClF;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACpC,0EAA0E;GACxE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,UAAU,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAwDD,wBAAuB,YAAY,CACjC,KAAK,EAAE,YAAY,GAClB,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,CAmXjD;AA8BD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuCzF"}
+{"version":3,"file":"runAgentTurn.d.ts","sourceRoot":"","sources":["../../../src/engine/runAgentTurn.ts"],"names":[],"mappings":"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"}

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

@@ -35,15 +35,95 @@ export interface ContextPack {
     digest?: Record<string, unknown>;
     /** Anything else the app wants to say to the model. */
     extra?: string;
+    /**
+     * App-author procedures the model can open ON DEMAND — see `Procedure`.
+     * Only `id — summary` goes in every prompt; the body is loaded by
+     * `ask-buoy.openProcedure` when the task matches, so a long playbook costs
+     * nothing until it is needed.
+     */
+    procedures?: Procedure[];
+}
+/**
+ * A playbook for this app: how to put it into a state, reproduce a ticket,
+ * or read something that is not obvious. Written by the app's developers,
+ * loaded when the model decides it applies. Borrowed from Strands' AgentSkills
+ * (SKILL.md name + description in the prompt, body on activation) — in-memory
+ * objects, no filesystem.
+ *
+ * A procedure GUIDES tool use; it grants nothing. Every step it names still
+ * goes through the same catalog, policy, approval card and ledger as any other
+ * call, and the outcome checks (engine/verify.ts) still run.
+ */
+export interface Procedure {
+    /** Stable, short, what the model calls it by: "expire-subscription". */
+    id: string;
+    title: string;
+    /** One line, shown in every prompt. Make it say WHEN to open this. */
+    summary: string;
+    /** The steps, preconditions, data conventions and what "done" looks like. Plain text or markdown. */
+    body: string;
+    /**
+     * Tool ids this procedure needs (`"zustand"`, `"network"`). It is only
+     * listed when every one is installed on this device — a procedure that
+     * names a tool the app does not have is one the model cannot follow.
+     */
+    requires?: string[];
+    /** The app/build it was written against, so a stale one can say so. */
+    version?: string;
 }
 export interface SystemPromptInput {
     catalog: ToolDescriptor[];
     context?: ContextPack;
+    /** Live tool ids, so a procedure that needs a tool this device lacks is not offered. */
+    availableToolIds?: string[];
     isRelease: boolean;
     readOnly: boolean;
+    /**
+     * Who turned read-only on. The APP configuring it is a rule the user cannot
+     * change; the DEVICE toggle is the person in front of the phone choosing to
+     * look without touching — and the model should tell them where to turn it
+     * off rather than send them to a developer.
+     */
+    readOnlySource?: "app" | "device";
     requireApproval: string[];
+    /**
+     * The user turned approval cards off on this device. Distinct from an empty
+     * `requireApproval`, which is the APP choosing full auto-run: here a gate
+     * exists and the person in front of the phone waived it, so the model is
+     * told plainly that nothing will stop a destructive call.
+     */
+    approvalsBypassed?: boolean;
     appName?: string;
     platform?: string;
 }
 export declare function buildSystemPrompt(input: SystemPromptInput): string;
+/** The procedures this device can follow: every `requires` tool installed (or no `requires` at all). */
+export declare function listableProcedures(procedures: Procedure[] | undefined, availableToolIds: string[] | undefined): Procedure[];
+/**
+ * The per-turn block: what the app is showing at the moment the user typed.
+ * Rendered AFTER the cached prompt (see ProviderRequest.systemVolatile), so it
+ * can change on every message without invalidating anything.
+ *
+ * Returns undefined when nothing was readable — the prompt then says so, so the
+ * model knows to read for itself rather than assume the block was empty
+ * because the app is.
+ */
+export declare function buildLiveBlock(live: Record<string, unknown> | undefined, 
+/**
+ * What this conversation has already changed, newest last.
+ *
+ * The ledger existed from the start and the model could never see it. Two
+ * failures came out of that. Asked "what have you changed?" it answered from
+ * memory of its own sentences, which drifts and cannot survive a reload. And
+ * reading a value it had itself overwritten three turns earlier, it reported
+ * the number as the app's own — the same "never fake the answer" problem as
+ * a network override, with the model as the one deceived.
+ *
+ * Short by construction: tool, action and a label per entry, capped. It is a
+ * reminder of what happened, not a replay of it.
+ */
+changes?: {
+    label: string;
+    undone: boolean;
+}[]): string;
 //# sourceMappingURL=systemPrompt.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"systemPrompt.d.ts","sourceRoot":"","sources":["../../../src/engine/systemPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CA2FlE"}
+{"version":3,"file":"systemPrompt.d.ts","sourceRoot":"","sources":["../../../src/engine/systemPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAClC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAsIlE;AAED,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,EAAE,CAK3H;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;AACzC;;;;;;;;;;;;GAYG;AACH,OAAO,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,GAC7C,MAAM,CAgBR"}

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

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+import type { ToolCall } from "../providers/types";
+import type { ToolDescriptor } from "../types";
+/**
+ * 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.
+ */
+export declare function couldBeToolCallEnvelope(text: string): boolean;
+export interface SalvagedCalls {
+    calls: ToolCall[];
+    /** The prose the envelope carried, if any. The JSON itself is never shown. */
+    reply: string;
+}
+/**
+ * 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.
+ */
+export declare function parseTextToolCalls(text: string, catalog: ToolDescriptor[]): SalvagedCalls | undefined;
+/**
+ * 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.
+ */
+export declare const 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 \u2014 text is shown to the user as-is, and a call written there does not run.]";
+//# sourceMappingURL=textToolCalls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"textToolCalls.d.ts","sourceRoot":"","sources":["../../../src/engine/textToolCalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA0B/C;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ7D;AA+JD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EAAE,GACxB,aAAa,GAAG,SAAS,CA+B3B;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,0OAC2M,CAAC"}