@agent-native/core 0.203.0 → 0.203.1-nightly-20261007183952

package/dist/agent/provider-model-selection.d.ts

@@ -105,10 +105,29 @@ export declare function resolveProviderModelSelectionAtScope(provider: ProviderM
 export declare function applyProviderModelSelection(catalog: readonly string[], selection: EffectiveProviderModelSelection | null): string[];
 /**
  * The model to run when nothing picked one and the engine's default is no
- * longer checked: the first checked model. `undefined` keeps the engine
- * default, which is also what happens when the selection can't be read.
+ * longer checked: the first checked model in the order it was saved, which is
+ * not a ranking of the models. `undefined` keeps the engine default, which is
+ * also what happens when the selection can't be read.
  */
 export declare function resolveUncheckedDefaultModelReplacement(engine: {
     name: string;
     defaultModel: string;
 }): Promise<string | undefined>;
+/**
+ * `selection` with the unchecked-default replacement applied. Only the engine
+ * default yields to the provider's checked models: a model the request or a
+ * stored default names still runs after it is unchecked, so chats already on
+ * it keep working. A replaced model is labelled `provider-selection-fallback`,
+ * never `default`, so logs and traces can tell a checkbox swap from the
+ * engine's own default.
+ */
+export declare function applyUncheckedDefaultModelReplacement<Source extends string>(engine: {
+    name: string;
+    defaultModel: string;
+}, selection: {
+    model: string;
+    source: Source;
+}): Promise<{
+    model: string;
+    source: Source | "provider-selection-fallback";
+}>;

package/dist/agent/provider-model-selection.js

@@ -381,8 +381,9 @@ export function applyProviderModelSelection(catalog, selection) {
 }
 /**
  * The model to run when nothing picked one and the engine's default is no
- * longer checked: the first checked model. `undefined` keeps the engine
- * default, which is also what happens when the selection can't be read.
+ * longer checked: the first checked model in the order it was saved, which is
+ * not a ranking of the models. `undefined` keeps the engine default, which is
+ * also what happens when the selection can't be read.
  */
 export async function resolveUncheckedDefaultModelReplacement(engine) {
     const provider = providerForEngineName(engine.name);
@@ -402,3 +403,19 @@ export async function resolveUncheckedDefaultModelReplacement(engine) {
         return undefined;
     return selection.models[0];
 }
+/**
+ * `selection` with the unchecked-default replacement applied. Only the engine
+ * default yields to the provider's checked models: a model the request or a
+ * stored default names still runs after it is unchecked, so chats already on
+ * it keep working. A replaced model is labelled `provider-selection-fallback`,
+ * never `default`, so logs and traces can tell a checkbox swap from the
+ * engine's own default.
+ */
+export async function applyUncheckedDefaultModelReplacement(engine, selection) {
+    if (selection.source !== "default")
+        return selection;
+    const replacement = await resolveUncheckedDefaultModelReplacement(engine);
+    return replacement
+        ? { model: replacement, source: "provider-selection-fallback" }
+        : selection;
+}

package/dist/agent/run-loop-with-resume.js

@@ -2,7 +2,7 @@ import { MAX_BACKGROUND_RUN_LOOP_CONTINUATIONS, MAX_RUN_LOOP_CONTINUATIONS, } fr
 import { SERVER_OWNED_ABORT_REASONS, clientAbortReason, } from "./abort-reasons.js";
 import { PROVIDER_RATE_LIMITED_ERROR_CODE } from "./engine/error-detail.js";
 import { EngineError } from "./engine/types.js";
-import { runAgentLoop, appendAgentLoopContinuation, isResumableEngineError, isTransientProviderRateLimitError, continuationReasonForResumableError, lastUnfinishedPreparingActionToolFromEvents, resolveFinalResponseGuardRequestText, SELF_CHAIN_MIN_CONTINUATION_BUDGET_MS, PROVIDER_RATE_LIMITED_TERMINAL_MESSAGE, } from "./production-agent.js";
+import { runAgentLoop, mergeAgentLoopUsage, appendAgentLoopContinuation, isResumableEngineError, isTransientProviderRateLimitError, continuationReasonForResumableError, lastUnfinishedPreparingActionToolFromEvents, resolveFinalResponseGuardRequestText, SELF_CHAIN_MIN_CONTINUATION_BUDGET_MS, PROVIDER_RATE_LIMITED_TERMINAL_MESSAGE, } from "./production-agent.js";
 import { resolveRunSoftTimeoutMs } from "./run-manager.js";
 import { getCurrentTurnEventsForThread } from "./run-store.js";
 import { classifyToolCallJournal, buildResumeJournalNote, } from "./tool-call-journal.js";
@@ -239,21 +239,7 @@ export async function runAgentLoopDirectWithSoftTimeout(opts, softTimeoutMs, tim
         engineName: opts.engine.name,
         model: opts.model,
     };
-    const addUsage = (next) => {
-        usage.inputTokens += next.inputTokens;
-        usage.outputTokens += next.outputTokens;
-        usage.cacheReadTokens += next.cacheReadTokens;
-        usage.cacheWriteTokens += next.cacheWriteTokens;
-        if (next.builderCreditsUsed !== undefined) {
-            usage.builderCreditsUsed =
-                (usage.builderCreditsUsed ?? 0) + next.builderCreditsUsed;
-        }
-        usage.engineName = next.engineName ?? usage.engineName;
-        usage.model = next.model;
-        if (next.usageReported)
-            usage.usageReported = true;
-        usage.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
-    };
+    const addUsage = (next) => mergeAgentLoopUsage(usage, next);
     const localTurnEvents = [];
     const continueFromChunkBoundary = async (reason, attemptEvents) => {
         if ((await completedSideEffectInCurrentTurn(opts.threadId, opts.turnId, localTurnEvents)) === "none") {

package/dist/agent/tool-search.d.ts

@@ -2,6 +2,8 @@ import type { ActionEntry } from "./production-agent.js";
 export declare const TOOL_SEARCH_ACTION_NAME = "tool-search";
 type ToolSearchArgs = {
     query?: unknown;
+    queries?: unknown;
+    names?: unknown;
     limit?: unknown;
     includeSchemas?: unknown;
     readOnlyOnly?: unknown;
@@ -30,7 +32,7 @@ type ToolSearchOptions = {
 export declare function createToolSearchEntry(getRegistry: () => Record<string, ActionEntry>, options?: ToolSearchOptions): ActionEntry;
 export declare function attachToolSearch(registry: Record<string, ActionEntry>, options?: ToolSearchOptions): Record<string, ActionEntry>;
 export declare function filterActionsForAgentDiscovery(registry: Record<string, ActionEntry>, context?: import("../action.js").ActionRunContext): Promise<Record<string, ActionEntry>>;
-export declare function searchToolRegistry(registry: Record<string, ActionEntry>, args?: ToolSearchArgs, options?: ToolSearchOptions): {
+type ToolSearchOutput = {
     query: string;
     totalTools: number;
     count: number;
@@ -38,5 +40,33 @@ export declare function searchToolRegistry(registry: Record<string, ActionEntry>
     message?: string;
     results: ToolSearchResult[];
 };
+/**
+ * One call may carry several capability queries and exact names; every match
+ * loads on the same next step. Each query keeps its own repeat guard.
+ */
+export declare function searchToolRegistry(registry: Record<string, ActionEntry>, args?: ToolSearchArgs, options?: ToolSearchOptions): ToolSearchOutput;
 export declare function searchToolRegistryForRequest(registry: Record<string, ActionEntry>, args?: ToolSearchArgs, options?: ToolSearchOptions, context?: import("../action.js").ActionRunContext): Promise<ReturnType<typeof searchToolRegistry>>;
+/**
+ * Whether a search names anything to look for. A menu search (no query,
+ * queries or names) only lists, so a caller that grants tools from a search
+ * result must not grant from it. Reads the lists exactly as the search does,
+ * so a form the search accepts is never read as a menu search.
+ */
+export declare function isTargetedToolSearch(args: object): boolean;
+/** Callable matches of a targeted search; empty for a menu or an error. */
+export declare function extractToolSearchResultNames(value: unknown): string[];
+/**
+ * The tools a search made callable lead its stored result. Replayed history
+ * clips a result mid-object, and the loaded list must outlive that clip, so it
+ * is read before the rest of the object is parsed.
+ */
+export declare function withLoadedToolNames<T extends object>(output: T, names: string[]): {
+    loadedForNextStep: string[];
+} & T;
+/**
+ * Tools a stored tool-search result made callable. `[]` means it loaded
+ * nothing, which includes a failed or interrupted search (not an object);
+ * `null` means it is a search result that cannot be read, clipped or corrupt.
+ */
+export declare function readLoadedToolNames(content: string): string[] | null;
 export {};

package/dist/agent/tool-search.js

@@ -2,9 +2,13 @@ import { isActionHiddenFromEveryAgentSurface } from "../action.js";
 import { parseMcpToolName } from "../mcp-client/manager.js";
 import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { getRequestRunContext } from "../server/request-context.js";
+import { clipHead } from "./clip-text.js";
 export const TOOL_SEARCH_ACTION_NAME = "tool-search";
 const DEFAULT_LIMIT = 8;
 const MAX_LIMIT = 10;
+const MAX_QUERIES = 5;
+const MAX_NAMES = 20;
+const EXACT_NAME_SCORE = 100;
 const MAX_MENU_DESCRIPTION_CHARS = 140;
 const MAX_DESCRIPTION_CHARS = 220;
 const MAX_PARAMETER_COUNT = 8;
@@ -16,7 +20,7 @@ export function createToolSearchEntry(getRegistry, options = {}) {
     const defaultLimit = Math.max(1, Math.min(options.defaultLimit ?? DEFAULT_LIMIT, maxLimit));
     return {
         tool: {
-            description: "Find actions and connected MCP tools named `mcp__<server>__<tool>` by capability or name. A targeted query returns concise details and adds matches allowed in the current mode, with their full schemas, to the next model step. Omit query for a bounded alphabetical menu; menu entries are informational until you search for a capability or name.",
+            description: "Find actions and connected MCP tools named `mcp__<server>__<tool>` by capability or name. A targeted search returns concise details and adds matches allowed in the current mode, with their full schemas, to the NEXT model step, not this one, so request every tool you need in one call (`queries` and/or `names`) and call them on the next step. If every match is already callable, call it directly instead of searching again. Omit query for a bounded alphabetical menu; menu entries are informational until you search for a capability or name.",
             parameters: {
                 type: "object",
                 properties: {
@@ -24,9 +28,21 @@ export function createToolSearchEntry(getRegistry, options = {}) {
                         type: "string",
                         description: "Capability or exact tool name to find. A targeted search adds matches allowed in the current mode, with their full schemas, to the next model step. Omit for a bounded alphabetical inventory.",
                     },
+                    queries: {
+                        type: "array",
+                        items: { type: "string" },
+                        maxItems: MAX_QUERIES,
+                        description: `Up to ${MAX_QUERIES} capability searches run together; all matches load on the next step.`,
+                    },
+                    names: {
+                        type: "array",
+                        items: { type: "string" },
+                        maxItems: MAX_NAMES,
+                        description: "Exact tool names to load on the next step, together with any queries.",
+                    },
                     limit: {
                         type: "number",
-                        description: `Maximum results to return, including menu mode. Defaults to ${defaultLimit}; capped at ${maxLimit}.`,
+                        description: `Maximum results to return per query, including menu mode. Defaults to ${defaultLimit}; capped at ${maxLimit}.`,
                     },
                     includeSchemas: {
                         type: "boolean",
@@ -75,8 +91,72 @@ export async function filterActionsForAgentDiscovery(registry, context) {
     }
     return filtered;
 }
+/**
+ * One call may carry several capability queries and exact names; every match
+ * loads on the same next step. Each query keeps its own repeat guard.
+ */
 export function searchToolRegistry(registry, args = {}, options = {}) {
-    const query = String(args.query ?? "").trim();
+    const { parsedQueries, parsedNames } = parseToolSearchLists(args);
+    const queries = parsedQueries.kept;
+    const names = parsedNames.kept;
+    // Providers rarely enforce `maxItems`; a silently dropped entry reads as a
+    // tool that loaded.
+    const truncationNote = [
+        droppedEntriesNote("queries", MAX_QUERIES, parsedQueries.dropped),
+        droppedEntriesNote("names", MAX_NAMES, parsedNames.dropped),
+    ]
+        .filter(Boolean)
+        .join(" ");
+    const withTruncationNote = (output) => truncationNote
+        ? {
+            ...output,
+            message: [output.message, truncationNote].filter(Boolean).join(" "),
+        }
+        : output;
+    const targets = [
+        ...queries.map((query) => ({ query })),
+        ...(names.length > 0 ? [{ names }] : []),
+    ];
+    if (targets.length <= 1) {
+        return withTruncationNote(searchOnce(registry, targets[0] ?? { query: "" }, args, options));
+    }
+    const parts = targets.map((target) => searchOnce(registry, target, args, options));
+    const byName = new Map();
+    for (const part of parts) {
+        for (const result of part.results) {
+            const existing = byName.get(result.name);
+            if (!existing || result.score > existing.score) {
+                byName.set(result.name, result);
+            }
+        }
+    }
+    const results = [...byName.values()].sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    const allRepeated = parts.every((part) => part.repeated);
+    const message = allRepeated
+        ? parts[0].message
+        : parts
+            .filter((part) => !part.repeated && part.message)
+            .map((part) => part.message)
+            .join(" ");
+    return withTruncationNote({
+        query: parts.map((part) => part.query).join(" | "),
+        totalTools: Math.max(...parts.map((part) => part.totalTools)),
+        count: results.length,
+        ...(allRepeated ? { repeated: true } : {}),
+        ...(message ? { message } : {}),
+        results,
+    });
+}
+function searchOnce(registry, target, args, options) {
+    const names = "names" in target ? target.names : undefined;
+    const exactNames = names
+        ? new Set(names.map((name) => name.toLowerCase()))
+        : undefined;
+    const query = names
+        ? `names: ${names.join(", ")}`
+        : "query" in target
+            ? target.query
+            : "";
     const listAll = query.length === 0;
     const readOnlyOnly = parseBoolean(args.readOnlyOnly);
     const limit = parseLimit(args.limit, options.defaultLimit ?? DEFAULT_LIMIT, Math.min(options.maxLimit ?? MAX_LIMIT, MAX_LIMIT));
@@ -144,15 +224,19 @@ export function searchToolRegistry(registry, args = {}, options = {}) {
             continue;
         }
         const parameters = summarizeParameters(entry.tool.parameters);
-        const score = scoreTool({
-            query,
-            queryTokens,
-            name,
-            source,
-            description,
-            parameters,
-            kind,
-        });
+        const score = exactNames
+            ? exactNames.has(name.toLowerCase())
+                ? EXACT_NAME_SCORE
+                : 0
+            : scoreTool({
+                query,
+                queryTokens,
+                name,
+                source,
+                description,
+                parameters,
+                kind,
+            });
         if (score <= 0)
             continue;
         candidates.push({
@@ -185,11 +269,19 @@ export function searchToolRegistry(registry, args = {}, options = {}) {
             return b.score - a.score;
         return a.name.localeCompare(b.name);
     });
+    const cap = exactNames ? MAX_NAMES : limit;
+    const found = new Set(candidates.map((candidate) => candidate.name.toLowerCase()));
+    const missing = names?.filter((name) => !found.has(name.toLowerCase()));
     const result = {
         query,
         totalTools,
-        count: Math.min(candidates.length, limit),
-        results: candidates.slice(0, limit),
+        count: Math.min(candidates.length, cap),
+        ...(missing && missing.length > 0
+            ? {
+                message: `No tool named ${missing.join(", ")} is available in the current mode.`,
+            }
+            : {}),
+        results: candidates.slice(0, cap),
     };
     rememberToolSearchResult(cacheKey, result);
     return result;
@@ -241,7 +333,96 @@ function rememberToolSearchResult(cacheKey, result) {
 function truncate(value, max) {
     if (value.length <= max)
         return value;
-    return `${value.slice(0, max - 1).trimEnd()}…`;
+    return `${clipHead(value, max - 1).trimEnd()}…`;
+}
+function parseToolSearchLists(args) {
+    return {
+        parsedQueries: parseStringList([String(args.query ?? ""), args.queries], MAX_QUERIES),
+        parsedNames: parseStringList([args.names], MAX_NAMES),
+    };
+}
+/**
+ * Whether a search names anything to look for. A menu search (no query,
+ * queries or names) only lists, so a caller that grants tools from a search
+ * result must not grant from it. Reads the lists exactly as the search does,
+ * so a form the search accepts is never read as a menu search.
+ */
+export function isTargetedToolSearch(args) {
+    const { parsedQueries, parsedNames } = parseToolSearchLists(args);
+    return parsedQueries.kept.length > 0 || parsedNames.kept.length > 0;
+}
+/** Callable matches of a targeted search; empty for a menu or an error. */
+export function extractToolSearchResultNames(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const result = value;
+    if (typeof result.query !== "string" || result.query.trim().length === 0) {
+        return [];
+    }
+    if (!Array.isArray(result.results))
+        return [];
+    const names = [];
+    for (const item of result.results) {
+        if (!item || typeof item !== "object")
+            continue;
+        const record = item;
+        if (record.callable === false)
+            continue;
+        const name = record.name;
+        if (typeof name === "string" && name.trim())
+            names.push(name);
+    }
+    return names;
+}
+/**
+ * The tools a search made callable lead its stored result. Replayed history
+ * clips a result mid-object, and the loaded list must outlive that clip, so it
+ * is read before the rest of the object is parsed.
+ */
+export function withLoadedToolNames(output, names) {
+    return { loadedForNextStep: names, ...output };
+}
+const LEADING_LOADED_TOOL_NAMES = /^\s*\{\s*"loadedForNextStep"\s*:\s*(\[\s*(?:"(?:[^"\\]|\\.)*"(?:\s*,\s*"(?:[^"\\]|\\.)*")*)?\s*\])/;
+/**
+ * Tools a stored tool-search result made callable. `[]` means it loaded
+ * nothing, which includes a failed or interrupted search (not an object);
+ * `null` means it is a search result that cannot be read, clipped or corrupt.
+ */
+export function readLoadedToolNames(content) {
+    try {
+        const leading = LEADING_LOADED_TOOL_NAMES.exec(content);
+        if (leading)
+            return JSON.parse(leading[1]);
+        if (!content.trimStart().startsWith("{"))
+            return [];
+        // Results stored before the loaded list existed carry every callable
+        // match. Pretty-printed JSON has no blank line, so notes appended after
+        // the object start at the first one.
+        const end = content.indexOf("\n\n");
+        return extractToolSearchResultNames(JSON.parse(end < 0 ? content : content.slice(0, end)));
+        // coercion-ok: unreadable returns null, which callers tell apart from [] (loaded nothing) and warn about
+    }
+    catch {
+        return null;
+    }
+}
+function parseStringList(values, max) {
+    const unique = new Map();
+    for (const item of values.flat()) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (trimmed && !unique.has(trimmed.toLowerCase())) {
+            unique.set(trimmed.toLowerCase(), trimmed);
+        }
+    }
+    const all = [...unique.values()];
+    return { kept: all.slice(0, max), dropped: all.slice(max) };
+}
+function droppedEntriesNote(kind, max, dropped) {
+    if (dropped.length === 0)
+        return "";
+    return `Only the first ${max} ${kind} were used; ${dropped.length} more were ignored (${truncate(dropped.join(", "), 200)}). Request them in another call.`;
 }
 function parseLimit(value, fallback, max) {
     const n = typeof value === "number"

package/dist/agent/write-receipts.d.ts

@@ -0,0 +1,27 @@
+import type { WriteReceipt } from "../action.js";
+import type { AgentLoopFinalResponseGuardResult } from "./production-agent.js";
+export type ToolWriteReceipt = WriteReceipt & {
+    tool: string;
+};
+export interface WriteReceiptGuard {
+    retryMessage: string;
+    fallbackMessage: string;
+    exhaustedDraftPrefix: string;
+    maxRetries: number;
+}
+/**
+ * Reads the reserved `_receipt` off an action's raw result. A receipt that is
+ * present but unreadable is `unverified`, never silently clean.
+ */
+export declare function readWriteReceipt(result: unknown): WriteReceipt | undefined;
+/**
+ * A receipt that says nothing was written, or that the effect did not hold,
+ * forces one retry per turn. `unverified` alone only annotates the answer.
+ */
+export declare function writeReceiptGuard(receipts: readonly ToolWriteReceipt[], alreadyRetried: boolean): WriteReceiptGuard | null;
+/**
+ * One guard result from the receipt guard and the app's guard. The retry
+ * counter is shared, so the larger budget wins and both messages are sent in
+ * the same retry.
+ */
+export declare function mergeFinalResponseGuards(receipt: WriteReceiptGuard, app: AgentLoopFinalResponseGuardResult): AgentLoopFinalResponseGuardResult;

package/dist/agent/write-receipts.js

@@ -0,0 +1,181 @@
+import { clipHead } from "./clip-text.js";
+const MAX_SUMMARY_CHARS = 200;
+const MAX_SUBJECT_CHARS = 200;
+const MAX_DETAIL_CHARS = 160;
+const MAX_CHECKS = 8;
+const MAX_WARNINGS = 5;
+// About 120 tokens per receipt in the retry block.
+const MAX_RECEIPT_LINE_CHARS = 480;
+const MAX_RECEIPT_LINES = 6;
+const clip = (text, max) => text.length > max ? `${clipHead(text, max - 1)}…` : text;
+// Bidi overrides and isolates reorder the line the user reads, and zero-width
+// space, word joiner, BOM and tag characters hide text. ZWJ, ZWNJ and the
+// directional marks stay: they change the meaning of Persian, Indic and emoji
+// text.
+const HIDING_CHARS = /[\u200b\u2060\ufeff\u202a-\u202e\u2066-\u2069\u{E0000}-\u{E007F}]/gu;
+/**
+ * Receipt text can carry strings an author of the written record controls
+ * (panel titles, column aliases). It reaches a user-role retry message and
+ * a user-visible block, so it is one line with no control characters and no
+ * angle brackets that could close the `<write-receipts>` tag.
+ */
+function sanitizeText(text, max) {
+    return clip(text
+        .replace(/[\p{Cc}\u2028\u2029]/gu, " ")
+        .replace(HIDING_CHARS, "")
+        .replace(/</g, "‹")
+        .replace(/>/g, "›")
+        .replace(/\s+/g, " ")
+        .trim(), max);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseReceipt(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { changed, verified, summary, subject, checks, warnings } = raw;
+    if (typeof changed !== "boolean" || typeof summary !== "string")
+        return null;
+    if (subject !== undefined && typeof subject !== "string")
+        return null;
+    if (verified !== true && verified !== false && verified !== "unverified") {
+        return null;
+    }
+    let parsedChecks;
+    if (checks !== undefined) {
+        if (!Array.isArray(checks))
+            return null;
+        parsedChecks = [];
+        for (const check of checks.slice(0, MAX_CHECKS)) {
+            if (!isRecord(check) ||
+                typeof check.id !== "string" ||
+                typeof check.ok !== "boolean" ||
+                (check.detail !== undefined && typeof check.detail !== "string")) {
+                return null;
+            }
+            parsedChecks.push({
+                id: check.id,
+                ok: check.ok,
+                ...(check.detail === undefined
+                    ? {}
+                    : { detail: clip(check.detail, MAX_DETAIL_CHARS) }),
+            });
+        }
+    }
+    if (warnings !== undefined &&
+        (!Array.isArray(warnings) ||
+            !warnings.every((warning) => typeof warning === "string"))) {
+        return null;
+    }
+    return {
+        changed,
+        verified,
+        summary: clip(summary, MAX_SUMMARY_CHARS),
+        ...(subject?.trim()
+            ? { subject: clip(subject.trim(), MAX_SUBJECT_CHARS) }
+            : {}),
+        ...(parsedChecks ? { checks: parsedChecks } : {}),
+        ...(warnings
+            ? {
+                warnings: warnings
+                    .slice(0, MAX_WARNINGS)
+                    .map((warning) => clip(warning, MAX_DETAIL_CHARS)),
+            }
+            : {}),
+    };
+}
+/**
+ * Reads the reserved `_receipt` off an action's raw result. A receipt that is
+ * present but unreadable is `unverified`, never silently clean.
+ */
+export function readWriteReceipt(result) {
+    if (!isRecord(result) || result._receipt === undefined)
+        return undefined;
+    return (parseReceipt(result._receipt) ?? {
+        changed: true,
+        verified: "unverified",
+        summary: "malformed receipt",
+    });
+}
+function receiptLine(receipt) {
+    const failed = (receipt.checks ?? [])
+        .filter((check) => !check.ok)
+        .map((check) => check.detail
+        ? `${sanitizeText(check.id, MAX_DETAIL_CHARS)} (${sanitizeText(check.detail, MAX_DETAIL_CHARS)})`
+        : sanitizeText(check.id, MAX_DETAIL_CHARS));
+    return clip(`- ${receipt.tool}: changed=${receipt.changed} verified=${receipt.verified}. ${sanitizeText(receipt.summary, MAX_SUMMARY_CHARS)}${failed.length > 0 ? ` Failed checks: ${failed.join("; ")}.` : ""}`, MAX_RECEIPT_LINE_CHARS);
+}
+/**
+ * A flagged receipt is dropped once later verified changes to the same subject
+ * re-checked everything it failed on. A verified receipt speaks only for the
+ * parts it checked, so one with no matching `ok` checks (an edit that touched
+ * nothing the failure was about) supersedes nothing that carried a failing
+ * check. A later receipt from another tool counts only against a failing
+ * check, because that check id is what ties the two tools' receipts to the
+ * same fault; a flagged receipt with no failing checks is dropped only by a
+ * later change from its own tool. A receipt with no subject is never
+ * superseded.
+ */
+function stillFlaggedReceipts(receipts) {
+    return receipts.filter((receipt, index) => {
+        if (receipt.verified === true && receipt.changed)
+            return false;
+        const { subject } = receipt;
+        if (!subject)
+            return true;
+        const failing = (receipt.checks ?? []).filter((check) => !check.ok);
+        const verifiedLater = receipts
+            .slice(index + 1)
+            .filter((later) => (later.tool === receipt.tool || failing.length > 0) &&
+            later.subject === subject &&
+            later.changed &&
+            later.verified === true);
+        if (verifiedLater.length === 0)
+            return true;
+        const rechecked = new Set(verifiedLater.flatMap((later) => (later.checks ?? []).filter((check) => check.ok).map(({ id }) => id)));
+        return failing.some((check) => !rechecked.has(check.id));
+    });
+}
+/**
+ * A receipt that says nothing was written, or that the effect did not hold,
+ * forces one retry per turn. `unverified` alone only annotates the answer.
+ */
+export function writeReceiptGuard(receipts, alreadyRetried) {
+    const flagged = stillFlaggedReceipts(receipts);
+    if (flagged.length === 0)
+        return null;
+    const lines = flagged.slice(0, MAX_RECEIPT_LINES).map(receiptLine);
+    if (flagged.length > MAX_RECEIPT_LINES) {
+        lines.push(`- (+${flagged.length - MAX_RECEIPT_LINES} more)`);
+    }
+    const block = lines.join("\n");
+    const needsRetry = flagged.some((receipt) => receipt.verified === false || !receipt.changed);
+    return {
+        retryMessage: `<write-receipts>\n${block}\n</write-receipts>\nState what these receipts show. Do not say a change is visible or working unless verified=true.`,
+        fallbackMessage: `Write check:\n${block}`,
+        exhaustedDraftPrefix: `Write check:\n${block}`,
+        maxRetries: needsRetry && !alreadyRetried ? 1 : 0,
+    };
+}
+/**
+ * One guard result from the receipt guard and the app's guard. The retry
+ * counter is shared, so the larger budget wins and both messages are sent in
+ * the same retry.
+ */
+export function mergeFinalResponseGuards(receipt, app) {
+    const appGuard = typeof app === "string" ? { retryMessage: app, fallbackMessage: app } : app;
+    return {
+        retryMessage: `${receipt.retryMessage}\n\n${appGuard.retryMessage}`,
+        maxRetries: Math.max(receipt.maxRetries, appGuard.maxRetries ?? 1),
+        ...(appGuard.expandToolSurface ? { expandToolSurface: true } : {}),
+        ...(appGuard.exhaustedDraftPrefix
+            ? {
+                exhaustedDraftPrefix: `${receipt.exhaustedDraftPrefix}\n\n${appGuard.exhaustedDraftPrefix}`,
+                fallbackMessage: appGuard.fallbackMessage ?? receipt.fallbackMessage,
+            }
+            : {
+                fallbackMessage: `${receipt.fallbackMessage}\n\n${appGuard.fallbackMessage ?? appGuard.retryMessage}`,
+            }),
+    };
+}

package/dist/automation/index.d.ts

@@ -139,8 +139,8 @@ export declare function createAutomationCallbackHandler(runtime: AutomationRunti
     duplicate?: undefined;
     eventId?: undefined;
 } | {
+    error?: undefined;
     accepted: boolean;
     duplicate: boolean;
     eventId: string;
-    error?: undefined;
 }>;

package/dist/collab/awareness.d.ts

@@ -38,19 +38,19 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/file-upload/actions/upload-image.d.ts

@@ -39,11 +39,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     provider?: undefined;
     configured?: undefined;
 } | {
+    error?: undefined;
     url: string;
     id: string;
     provider: string;
     configured?: undefined;
-    error?: undefined;
 } | {
     url?: undefined;
     id?: undefined;