omk-agent-core 0.90.8 → 0.91.0

package/dist/tool-timeout.js

@@ -0,0 +1,173 @@
+/**
+ * Per-tool execution timeout and cancellation for the agent loop.
+ *
+ * The agent loop awaits each tool's `execute` promise at a single shared
+ * chokepoint. A tool that ignores its `AbortSignal` and never settles would
+ * otherwise stall the whole run. This module bounds that risk without process
+ * killing: the real execute promise is raced against two terminal causes — a
+ * per-call timeout timer and the parent run's abort — so an uncooperative tool
+ * still yields an immediate, immutable terminal result.
+ *
+ * The child `AbortSignal` handed to the tool is best-effort cooperative
+ * cancellation only; correctness comes from the race, not from the tool
+ * honoring the signal. `AbortSignal.any()` is intentionally not used: the
+ * parent-abort and timeout wiring is explicit so timer/listener disposal is
+ * idempotent and runs on every outcome.
+ *
+ * A late settlement of the real promise (after the terminal cause already won)
+ * is observed exactly once for audit only. It never emits a second tool result
+ * or lifecycle end, never mutates the committed result, and — because the real
+ * promise is wrapped so it never rejects — can never surface as an unhandled
+ * rejection.
+ */
+import { createAbortedToolResult, createTimeoutToolResult } from "./tool-execution-boundary.js";
+export { createAbortedToolResult, createTimeoutToolResult } from "./tool-execution-boundary.js";
+/**
+ * Resolve the effective {@link ToolExecutionPolicy} with the release default
+ * `lateSettlement: "audit"`: late settlements are observable audit events
+ * unless a caller explicitly opts out with `"ignore"`.
+ */
+export function resolveToolExecutionPolicy(policy) {
+    return {
+        ...(policy?.timeoutMs === undefined ? {} : { timeoutMs: policy.timeoutMs }),
+        ...(policy?.cancelSiblingsOnFatal === undefined ? {} : { cancelSiblingsOnFatal: policy.cancelSiblingsOnFatal }),
+        lateSettlement: policy?.lateSettlement === "ignore" ? "ignore" : "audit",
+    };
+}
+/**
+ * Resolve the effective per-call timeout with strict precedence:
+ * per-tool `AgentTool.timeoutMs` > per-name `config.toolTimeouts[name]` >
+ * global `config.toolTimeoutMs`.
+ *
+ * The first level that is *present* (not `undefined`) wins, so a per-tool `0`
+ * deliberately disables the timeout even when a global default is set. A
+ * resolved value that is absent, non-finite, or non-positive returns `0`, which
+ * disables only the timer. Parent cancellation is still raced so an
+ * uncooperative tool cannot keep an aborted run open.
+ */
+export function resolveToolTimeoutMs(tool, config, toolName) {
+    let chosen;
+    if (tool.timeoutMs !== undefined) {
+        chosen = tool.timeoutMs;
+    }
+    else if (config.toolTimeouts?.[toolName] !== undefined) {
+        chosen = config.toolTimeouts[toolName];
+    }
+    else {
+        chosen = config.toolTimeoutMs;
+    }
+    if (typeof chosen !== "number" || !Number.isFinite(chosen) || chosen <= 0) {
+        return 0;
+    }
+    return chosen;
+}
+/**
+ * Race a tool's `execute` promise against a per-call timeout and parent abort.
+ *
+ * Control flow (single path, no `AbortSignal.any()`):
+ * - A timer and a parent-abort listener each resolve one shared "terminal cause"
+ *   deferred. Whichever fires first wins; resolving is idempotent.
+ * - The timer callback resolves the timeout cause *before* aborting the child so
+ *   a tool that rejects promptly on abort cannot make "aborted" win a timeout.
+ * - `Promise.race` picks the real settlement or the terminal cause. Timer and
+ *   listener disposal is idempotent and runs on every outcome.
+ * - On a terminal-cause win, the real promise (wrapped so it never rejects) is
+ *   observed once for the audit event and the committed result is immutable.
+ */
+export async function runToolCallWithTimeout(options) {
+    const { toolCallId, toolName, timeoutMs, signal, start, emitUpdate, emitLateSettlement, toErrorResult } = options;
+    const lateSettlementPolicy = resolveToolExecutionPolicy({ lateSettlement: options.lateSettlement }).lateSettlement;
+    // Defensive: a parent already aborted before execution starts never runs the
+    // tool. prepareToolCall normally catches this earlier.
+    if (signal?.aborted) {
+        return {
+            result: createAbortedToolResult(false),
+            isError: true,
+            executionStarted: false,
+            terminalDisposition: "aborted",
+        };
+    }
+    const childController = new AbortController();
+    let raceSettled = false;
+    let disposed = false;
+    let timer;
+    let resolveCause;
+    const causePromise = new Promise((resolve) => {
+        resolveCause = resolve;
+    });
+    const abortChild = (reason) => {
+        if (!childController.signal.aborted) {
+            childController.abort(reason);
+        }
+    };
+    const onParentAbort = () => {
+        // Resolve the terminal cause before aborting the child so the committed
+        // disposition stays "aborted" even for a tool that rejects on its signal.
+        resolveCause({ kind: "aborted" });
+        abortChild(signal?.reason);
+    };
+    const dispose = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        signal?.removeEventListener("abort", onParentAbort);
+    };
+    if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+            // Reason ordering: settle the timeout cause first, then signal the child.
+            resolveCause({ kind: "timeout" });
+            abortChild(new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    }
+    signal?.addEventListener("abort", onParentAbort, { once: true });
+    // Updates are observation-only: deliver those seen before terminality, but
+    // never let listener settlement or failure delay the terminal race.
+    const gatedUpdate = (partialResult) => {
+        if (raceSettled)
+            return;
+        void Promise.resolve()
+            .then(() => emitUpdate(partialResult))
+            .catch(() => undefined);
+    };
+    // Wrap so a synchronous throw from `start` becomes a rejection and, crucially,
+    // so this promise never rejects — both settlements map to a value. That makes
+    // the late observer safe from unhandled rejections.
+    const realSettled = (async () => start(childController.signal, gatedUpdate))().then((result) => ({ kind: "resolved", result }), (error) => ({ kind: "rejected", error }));
+    const raced = await Promise.race([
+        realSettled.then((settlement) => ({ from: "real", settlement })),
+        causePromise.then((cause) => ({ from: "cause", cause })),
+    ]);
+    raceSettled = true;
+    dispose();
+    if (raced.from === "real") {
+        // The tool settled first: behave exactly like the no-timeout path.
+        const settlement = raced.settlement;
+        if (settlement.kind === "resolved") {
+            return { result: settlement.result, isError: false, executionStarted: true };
+        }
+        return { result: toErrorResult(settlement.error), isError: true, executionStarted: true };
+    }
+    // A terminal cause won. Observe the real promise's eventual settlement exactly
+    // once for audit only; realSettled never rejects and the chained catch guards
+    // against a throwing emit, so no unhandled rejection is possible. The
+    // `"ignore"` policy drops the audit event but never the immutable result.
+    const disposition = raced.cause.kind;
+    if (lateSettlementPolicy === "audit") {
+        realSettled
+            .then((settlement) => emitLateSettlement({
+            toolCallId,
+            toolName,
+            disposition,
+            outcome: settlement.kind === "resolved" ? "resolved" : "rejected",
+        }))
+            .catch(() => { });
+    }
+    const result = disposition === "timeout" ? createTimeoutToolResult(toolName, timeoutMs) : createAbortedToolResult(true);
+    return { result, isError: true, executionStarted: true, terminalDisposition: disposition };
+}
+//# sourceMappingURL=tool-timeout.js.map

package/dist/tool-timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-timeout.js","sourceRoot":"","sources":["../src/tool-timeout.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-tool execution timeout and cancellation for the agent loop.\n *\n * The agent loop awaits each tool's `execute` promise at a single shared\n * chokepoint. A tool that ignores its `AbortSignal` and never settles would\n * otherwise stall the whole run. This module bounds that risk without process\n * killing: the real execute promise is raced against two terminal causes — a\n * per-call timeout timer and the parent run's abort — so an uncooperative tool\n * still yields an immediate, immutable terminal result.\n *\n * The child `AbortSignal` handed to the tool is best-effort cooperative\n * cancellation only; correctness comes from the race, not from the tool\n * honoring the signal. `AbortSignal.any()` is intentionally not used: the\n * parent-abort and timeout wiring is explicit so timer/listener disposal is\n * idempotent and runs on every outcome.\n *\n * A late settlement of the real promise (after the terminal cause already won)\n * is observed exactly once for audit only. It never emits a second tool result\n * or lifecycle end, never mutates the committed result, and — because the real\n * promise is wrapped so it never rejects — can never surface as an unhandled\n * rejection.\n */\n\nimport { createAbortedToolResult, createTimeoutToolResult } from \"./tool-execution-boundary.ts\";\nimport type {\n\tAgentLoopConfig,\n\tAgentTool,\n\tAgentToolResult,\n\tAgentToolUpdateCallback,\n\tToolExecutionPolicy,\n\tToolLateSettlementOutcome,\n\tToolTimeoutDisposition,\n} from \"./types.ts\";\n\nexport type { ToolDispositionEnvelope } from \"./tool-execution-boundary.ts\";\nexport { createAbortedToolResult, createTimeoutToolResult } from \"./tool-execution-boundary.ts\";\n\n/**\n * Resolve the effective {@link ToolExecutionPolicy} with the release default\n * `lateSettlement: \"audit\"`: late settlements are observable audit events\n * unless a caller explicitly opts out with `\"ignore\"`.\n */\nexport function resolveToolExecutionPolicy(policy: Partial<ToolExecutionPolicy> | undefined): ToolExecutionPolicy {\n\treturn {\n\t\t...(policy?.timeoutMs === undefined ? {} : { timeoutMs: policy.timeoutMs }),\n\t\t...(policy?.cancelSiblingsOnFatal === undefined ? {} : { cancelSiblingsOnFatal: policy.cancelSiblingsOnFatal }),\n\t\tlateSettlement: policy?.lateSettlement === \"ignore\" ? \"ignore\" : \"audit\",\n\t};\n}\n\n/** Audit-only description of a real tool promise settling after its terminal cause won. */\nexport interface ToolLateSettlement {\n\ttoolCallId: string;\n\ttoolName: string;\n\t/** The terminal disposition that was already committed when the real promise settled. */\n\tdisposition: ToolTimeoutDisposition;\n\t/** How the real tool promise eventually settled. Disposition-safe metadata only. */\n\toutcome: ToolLateSettlementOutcome;\n}\n\n/**\n * Resolve the effective per-call timeout with strict precedence:\n * per-tool `AgentTool.timeoutMs` > per-name `config.toolTimeouts[name]` >\n * global `config.toolTimeoutMs`.\n *\n * The first level that is *present* (not `undefined`) wins, so a per-tool `0`\n * deliberately disables the timeout even when a global default is set. A\n * resolved value that is absent, non-finite, or non-positive returns `0`, which\n * disables only the timer. Parent cancellation is still raced so an\n * uncooperative tool cannot keep an aborted run open.\n */\nexport function resolveToolTimeoutMs(\n\ttool: Pick<AgentTool<any>, \"timeoutMs\">,\n\tconfig: Pick<AgentLoopConfig, \"toolTimeoutMs\" | \"toolTimeouts\">,\n\ttoolName: string,\n): number {\n\tlet chosen: number | undefined;\n\tif (tool.timeoutMs !== undefined) {\n\t\tchosen = tool.timeoutMs;\n\t} else if (config.toolTimeouts?.[toolName] !== undefined) {\n\t\tchosen = config.toolTimeouts[toolName];\n\t} else {\n\t\tchosen = config.toolTimeoutMs;\n\t}\n\tif (typeof chosen !== \"number\" || !Number.isFinite(chosen) || chosen <= 0) {\n\t\treturn 0;\n\t}\n\treturn chosen;\n}\n\ntype TerminalCause = { kind: ToolTimeoutDisposition };\n\ntype RealSettlement<TDetails> =\n\t| { kind: \"resolved\"; result: AgentToolResult<TDetails> }\n\t| { kind: \"rejected\"; error: unknown };\n\nexport interface RunToolCallWithTimeoutOptions<TDetails = any> {\n\ttoolCallId: string;\n\ttoolName: string;\n\t/** Effective timeout in ms. A non-positive value disables the timer, not parent cancellation. */\n\ttimeoutMs: number;\n\t/** Parent run abort signal, if any. */\n\tsignal: AbortSignal | undefined;\n\t/** Start the real tool, passing the child (best-effort) signal and update sink. */\n\tstart: (childSignal: AbortSignal, onUpdate: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;\n\t/** Emit a `tool_execution_update` for a partial result observed before terminality. */\n\temitUpdate: (partialResult: AgentToolResult<TDetails>) => Promise<void> | void;\n\t/** Emit the audit-only late-settlement event exactly once, after the terminal cause won. */\n\temitLateSettlement: (settlement: ToolLateSettlement) => Promise<void> | void;\n\t/** Map a thrown/rejected tool error to a normal error result (real completion path). */\n\ttoErrorResult: (error: unknown) => AgentToolResult<any>;\n\t/**\n\t * Late-settlement policy (default `\"audit\"`). `\"ignore\"` drops the audit\n\t * event; the committed terminal result is immutable under both policies.\n\t */\n\tlateSettlement?: ToolExecutionPolicy[\"lateSettlement\"];\n}\n\nexport interface RunToolCallWithTimeoutResult {\n\tresult: AgentToolResult<any>;\n\tisError: boolean;\n\t/** True when the tool's `execute` actually began before the result was committed. */\n\texecutionStarted: boolean;\n\t/** Terminal cause when the runtime (not the tool) committed the result. */\n\tterminalDisposition?: ToolTimeoutDisposition;\n}\n\n/**\n * Race a tool's `execute` promise against a per-call timeout and parent abort.\n *\n * Control flow (single path, no `AbortSignal.any()`):\n * - A timer and a parent-abort listener each resolve one shared \"terminal cause\"\n *   deferred. Whichever fires first wins; resolving is idempotent.\n * - The timer callback resolves the timeout cause *before* aborting the child so\n *   a tool that rejects promptly on abort cannot make \"aborted\" win a timeout.\n * - `Promise.race` picks the real settlement or the terminal cause. Timer and\n *   listener disposal is idempotent and runs on every outcome.\n * - On a terminal-cause win, the real promise (wrapped so it never rejects) is\n *   observed once for the audit event and the committed result is immutable.\n */\nexport async function runToolCallWithTimeout<TDetails = any>(\n\toptions: RunToolCallWithTimeoutOptions<TDetails>,\n): Promise<RunToolCallWithTimeoutResult> {\n\tconst { toolCallId, toolName, timeoutMs, signal, start, emitUpdate, emitLateSettlement, toErrorResult } = options;\n\tconst lateSettlementPolicy = resolveToolExecutionPolicy({ lateSettlement: options.lateSettlement }).lateSettlement;\n\n\t// Defensive: a parent already aborted before execution starts never runs the\n\t// tool. prepareToolCall normally catches this earlier.\n\tif (signal?.aborted) {\n\t\treturn {\n\t\t\tresult: createAbortedToolResult(false),\n\t\t\tisError: true,\n\t\t\texecutionStarted: false,\n\t\t\tterminalDisposition: \"aborted\",\n\t\t};\n\t}\n\n\tconst childController = new AbortController();\n\tlet raceSettled = false;\n\tlet disposed = false;\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\n\tlet resolveCause!: (cause: TerminalCause) => void;\n\tconst causePromise = new Promise<TerminalCause>((resolve) => {\n\t\tresolveCause = resolve;\n\t});\n\n\tconst abortChild = (reason: unknown): void => {\n\t\tif (!childController.signal.aborted) {\n\t\t\tchildController.abort(reason);\n\t\t}\n\t};\n\n\tconst onParentAbort = (): void => {\n\t\t// Resolve the terminal cause before aborting the child so the committed\n\t\t// disposition stays \"aborted\" even for a tool that rejects on its signal.\n\t\tresolveCause({ kind: \"aborted\" });\n\t\tabortChild(signal?.reason);\n\t};\n\n\tconst dispose = (): void => {\n\t\tif (disposed) {\n\t\t\treturn;\n\t\t}\n\t\tdisposed = true;\n\t\tif (timer !== undefined) {\n\t\t\tclearTimeout(timer);\n\t\t\ttimer = undefined;\n\t\t}\n\t\tsignal?.removeEventListener(\"abort\", onParentAbort);\n\t};\n\n\tif (timeoutMs > 0) {\n\t\ttimer = setTimeout(() => {\n\t\t\t// Reason ordering: settle the timeout cause first, then signal the child.\n\t\t\tresolveCause({ kind: \"timeout\" });\n\t\t\tabortChild(new Error(`Tool \"${toolName}\" timed out after ${timeoutMs}ms`));\n\t\t}, timeoutMs);\n\t}\n\n\tsignal?.addEventListener(\"abort\", onParentAbort, { once: true });\n\n\t// Updates are observation-only: deliver those seen before terminality, but\n\t// never let listener settlement or failure delay the terminal race.\n\tconst gatedUpdate: AgentToolUpdateCallback<TDetails> = (partialResult) => {\n\t\tif (raceSettled) return;\n\t\tvoid Promise.resolve()\n\t\t\t.then(() => emitUpdate(partialResult))\n\t\t\t.catch(() => undefined);\n\t};\n\n\t// Wrap so a synchronous throw from `start` becomes a rejection and, crucially,\n\t// so this promise never rejects — both settlements map to a value. That makes\n\t// the late observer safe from unhandled rejections.\n\tconst realSettled: Promise<RealSettlement<TDetails>> = (async () =>\n\t\tstart(childController.signal, gatedUpdate))().then(\n\t\t(result) => ({ kind: \"resolved\" as const, result }),\n\t\t(error) => ({ kind: \"rejected\" as const, error }),\n\t);\n\n\tconst raced = await Promise.race<\n\t\t{ from: \"real\"; settlement: RealSettlement<TDetails> } | { from: \"cause\"; cause: TerminalCause }\n\t>([\n\t\trealSettled.then((settlement) => ({ from: \"real\" as const, settlement })),\n\t\tcausePromise.then((cause) => ({ from: \"cause\" as const, cause })),\n\t]);\n\n\traceSettled = true;\n\tdispose();\n\n\tif (raced.from === \"real\") {\n\t\t// The tool settled first: behave exactly like the no-timeout path.\n\t\tconst settlement = raced.settlement;\n\t\tif (settlement.kind === \"resolved\") {\n\t\t\treturn { result: settlement.result, isError: false, executionStarted: true };\n\t\t}\n\t\treturn { result: toErrorResult(settlement.error), isError: true, executionStarted: true };\n\t}\n\n\t// A terminal cause won. Observe the real promise's eventual settlement exactly\n\t// once for audit only; realSettled never rejects and the chained catch guards\n\t// against a throwing emit, so no unhandled rejection is possible. The\n\t// `\"ignore\"` policy drops the audit event but never the immutable result.\n\tconst disposition = raced.cause.kind;\n\tif (lateSettlementPolicy === \"audit\") {\n\t\trealSettled\n\t\t\t.then((settlement) =>\n\t\t\t\temitLateSettlement({\n\t\t\t\t\ttoolCallId,\n\t\t\t\t\ttoolName,\n\t\t\t\t\tdisposition,\n\t\t\t\t\toutcome: settlement.kind === \"resolved\" ? \"resolved\" : \"rejected\",\n\t\t\t\t}),\n\t\t\t)\n\t\t\t.catch(() => {});\n\t}\n\n\tconst result =\n\t\tdisposition === \"timeout\" ? createTimeoutToolResult(toolName, timeoutMs) : createAbortedToolResult(true);\n\treturn { result, isError: true, executionStarted: true, terminalDisposition: disposition };\n}\n"]}

package/dist/tool-transcript-integrity.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure, browser-safe transcript integrity inspector and repair for the tool-call
+ * transcripts produced by the agent loop.
+ *
+ * The inspector detects five classes of structural corruption:
+ * - `missing_result`: a tool call with no matching tool result
+ * - `duplicate_result`: two or more tool results for the same call id
+ * - `orphan_result`: a tool result whose call id was never emitted
+ * - `duplicate_call_id`: two or more tool calls sharing an id
+ * - `interleaved_non_result`: a non-result message breaks the contiguous run of
+ *   results that must follow an assistant message's tool calls (including a
+ *   result that arrives before its call, after a user/custom boundary, or at the
+ *   start of the transcript)
+ *
+ * IDs are accounted globally, so an orphan or duplicate is caught regardless of
+ * where it appears. Repair is intentionally conservative: it only appends
+ * synthetic results for unambiguous missing tail calls. Any duplicate, orphan,
+ * interleaving, or mid-transcript gap fails closed.
+ *
+ * This module uses no platform APIs (no `process`, fs, or timers) so it is safe
+ * to run in a browser.
+ */
+import type { ToolResultMessage } from "omk-ai";
+import { type AgentMessage } from "./types.ts";
+export type TranscriptIntegrityIssueKind = "missing_result" | "duplicate_result" | "orphan_result" | "duplicate_call_id" | "interleaved_non_result";
+export interface TranscriptIntegrityIssue {
+    readonly kind: TranscriptIntegrityIssueKind;
+    readonly toolCallId: string;
+    readonly toolName?: string;
+}
+export interface TranscriptIntegrityReport {
+    readonly ok: boolean;
+    readonly issues: readonly TranscriptIntegrityIssue[];
+}
+/** Thrown by {@link repairTranscriptIntegrity} when a transcript cannot be safely repaired. */
+export declare class TranscriptIntegrityError extends Error {
+    readonly report: TranscriptIntegrityReport;
+    constructor(message: string, report: TranscriptIntegrityReport);
+}
+/**
+ * Inspect a transcript and report every detected integrity issue. Pure: does not
+ * mutate the input and uses no platform APIs.
+ *
+ * IDs are accounted globally first (catching duplicates, orphans, and missing
+ * results anywhere in the transcript), then a single left-to-right pass checks
+ * the ordering invariant that an assistant message's tool calls must be followed
+ * by a contiguous run of their results with no intervening non-result message.
+ */
+export declare function inspectTranscriptIntegrity(messages: readonly AgentMessage[]): TranscriptIntegrityReport;
+/**
+ * Create a synthetic terminal tool result. Shared by transcript repair and the
+ * agent-loop abort closure so the disposition of an unresolved call is encoded
+ * identically everywhere. The `details.omk` envelope marks the artifact as
+ * synthetic (`executionStarted: false`): it closes the provider transcript and
+ * never claims the tool actually ran.
+ */
+export declare function createSyntheticToolResult(toolCallId: string, toolName: string, reason: string, timestamp?: number, disposition?: "aborted" | "skipped"): ToolResultMessage;
+/**
+ * Repair a transcript by appending synthetic results for unambiguous missing
+ * tail calls. Fails closed (throws {@link TranscriptIntegrityError}) for any
+ * duplicate, orphan, interleaving, or mid-transcript gap. Idempotent: a second
+ * call on already-repaired input returns an equal copy with no new messages.
+ */
+export declare function repairTranscriptIntegrity(messages: readonly AgentMessage[], reason?: string): AgentMessage[];
+//# sourceMappingURL=tool-transcript-integrity.d.ts.map

package/dist/tool-transcript-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-transcript-integrity.d.ts","sourceRoot":"","sources":["../src/tool-transcript-integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAA8B,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAE5E,OAAO,EAAE,KAAK,YAAY,EAA4B,MAAM,YAAY,CAAC;AAEzE,MAAM,MAAM,4BAA4B,GACrC,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,mBAAmB,GACnB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACrD;AAED,+FAA+F;AAC/F,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAI7D;CACD;AAcD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,yBAAyB,CA8FvG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAmB,EAC9B,WAAW,GAAE,SAAS,GAAG,SAAqB,GAC5C,iBAAiB,CAgBnB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAgE5G","sourcesContent":["/**\n * Pure, browser-safe transcript integrity inspector and repair for the tool-call\n * transcripts produced by the agent loop.\n *\n * The inspector detects five classes of structural corruption:\n * - `missing_result`: a tool call with no matching tool result\n * - `duplicate_result`: two or more tool results for the same call id\n * - `orphan_result`: a tool result whose call id was never emitted\n * - `duplicate_call_id`: two or more tool calls sharing an id\n * - `interleaved_non_result`: a non-result message breaks the contiguous run of\n *   results that must follow an assistant message's tool calls (including a\n *   result that arrives before its call, after a user/custom boundary, or at the\n *   start of the transcript)\n *\n * IDs are accounted globally, so an orphan or duplicate is caught regardless of\n * where it appears. Repair is intentionally conservative: it only appends\n * synthetic results for unambiguous missing tail calls. Any duplicate, orphan,\n * interleaving, or mid-transcript gap fails closed.\n *\n * This module uses no platform APIs (no `process`, fs, or timers) so it is safe\n * to run in a browser.\n */\n\nimport type { AssistantMessage, ToolCall, ToolResultMessage } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"./plain-data.ts\";\nimport { type AgentMessage, createToolResultEnvelope } from \"./types.ts\";\n\nexport type TranscriptIntegrityIssueKind =\n\t| \"missing_result\"\n\t| \"duplicate_result\"\n\t| \"orphan_result\"\n\t| \"duplicate_call_id\"\n\t| \"interleaved_non_result\";\n\nexport interface TranscriptIntegrityIssue {\n\treadonly kind: TranscriptIntegrityIssueKind;\n\treadonly toolCallId: string;\n\treadonly toolName?: string;\n}\n\nexport interface TranscriptIntegrityReport {\n\treadonly ok: boolean;\n\treadonly issues: readonly TranscriptIntegrityIssue[];\n}\n\n/** Thrown by {@link repairTranscriptIntegrity} when a transcript cannot be safely repaired. */\nexport class TranscriptIntegrityError extends Error {\n\treadonly report: TranscriptIntegrityReport;\n\tconstructor(message: string, report: TranscriptIntegrityReport) {\n\t\tsuper(message);\n\t\tthis.name = \"TranscriptIntegrityError\";\n\t\tthis.report = report;\n\t}\n}\n\nfunction isAssistantMessage(message: AgentMessage): message is AssistantMessage {\n\treturn message.role === \"assistant\";\n}\n\nfunction isToolResultMessage(message: AgentMessage): message is ToolResultMessage {\n\treturn message.role === \"toolResult\";\n}\n\nfunction isToolCallBlock(block: unknown): block is ToolCall {\n\treturn (block as { type?: string } | null)?.type === \"toolCall\";\n}\n\n/**\n * Inspect a transcript and report every detected integrity issue. Pure: does not\n * mutate the input and uses no platform APIs.\n *\n * IDs are accounted globally first (catching duplicates, orphans, and missing\n * results anywhere in the transcript), then a single left-to-right pass checks\n * the ordering invariant that an assistant message's tool calls must be followed\n * by a contiguous run of their results with no intervening non-result message.\n */\nexport function inspectTranscriptIntegrity(messages: readonly AgentMessage[]): TranscriptIntegrityReport {\n\tconst issues: TranscriptIntegrityIssue[] = [];\n\n\tconst callIdCount = new Map<string, number>();\n\tconst resultIdCount = new Map<string, number>();\n\tconst callToolName = new Map<string, string>();\n\n\tfor (const message of messages) {\n\t\tif (isAssistantMessage(message)) {\n\t\t\tfor (const block of message.content) {\n\t\t\t\tif (isToolCallBlock(block)) {\n\t\t\t\t\tcallIdCount.set(block.id, (callIdCount.get(block.id) ?? 0) + 1);\n\t\t\t\t\tif (!callToolName.has(block.id)) {\n\t\t\t\t\t\tcallToolName.set(block.id, block.name);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (isToolResultMessage(message)) {\n\t\t\tresultIdCount.set(message.toolCallId, (resultIdCount.get(message.toolCallId) ?? 0) + 1);\n\t\t}\n\t}\n\n\tfor (const [id, count] of callIdCount) {\n\t\tif (count > 1) {\n\t\t\tissues.push({ kind: \"duplicate_call_id\", toolCallId: id, toolName: callToolName.get(id) });\n\t\t}\n\t}\n\tfor (const [id, count] of resultIdCount) {\n\t\tif (count > 1) {\n\t\t\tissues.push({ kind: \"duplicate_result\", toolCallId: id });\n\t\t}\n\t}\n\tfor (const [id] of resultIdCount) {\n\t\tif (!callIdCount.has(id)) {\n\t\t\tissues.push({ kind: \"orphan_result\", toolCallId: id });\n\t\t}\n\t}\n\tfor (const [id] of callIdCount) {\n\t\tif (!resultIdCount.has(id)) {\n\t\t\tissues.push({ kind: \"missing_result\", toolCallId: id, toolName: callToolName.get(id) });\n\t\t}\n\t}\n\n\tconst pending = new Map<string, string>();\n\tlet resultsRegion = false;\n\n\tfor (const message of messages) {\n\t\tif (isAssistantMessage(message)) {\n\t\t\tconst calls = message.content.filter(isToolCallBlock);\n\t\t\tif (calls.length > 0) {\n\t\t\t\t// A new assistant message with tool calls while previous calls are\n\t\t\t\t// still unresolved means a non-result interrupted the prior region.\n\t\t\t\tif (pending.size > 0) {\n\t\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tfor (const call of calls) {\n\t\t\t\t\tpending.set(call.id, call.name);\n\t\t\t\t}\n\t\t\t\tresultsRegion = true;\n\t\t\t} else if (resultsRegion && pending.size > 0) {\n\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} else if (isToolResultMessage(message)) {\n\t\t\tif (resultsRegion && pending.has(message.toolCallId)) {\n\t\t\t\tpending.delete(message.toolCallId);\n\t\t\t\tif (pending.size === 0) {\n\t\t\t\t\tresultsRegion = false;\n\t\t\t\t}\n\t\t\t} else if (callIdCount.has(message.toolCallId)) {\n\t\t\t\t// Known call id arriving outside its contiguous results region:\n\t\t\t\t// orphan-at-start, after-user, or assistant -> non-result -> result.\n\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: message.toolCallId });\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\t// Unknown-id orphans are already reported above; do not double report.\n\t\t} else {\n\t\t\t// user or custom non-result message: breaks an open results region.\n\t\t\tif (resultsRegion && pending.size > 0) {\n\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\tconst frozenIssues = Object.freeze(issues.map((issue) => Object.freeze({ ...issue })));\n\treturn Object.freeze({ ok: frozenIssues.length === 0, issues: frozenIssues });\n}\n\n/**\n * Create a synthetic terminal tool result. Shared by transcript repair and the\n * agent-loop abort closure so the disposition of an unresolved call is encoded\n * identically everywhere. The `details.omk` envelope marks the artifact as\n * synthetic (`executionStarted: false`): it closes the provider transcript and\n * never claims the tool actually ran.\n */\nexport function createSyntheticToolResult(\n\ttoolCallId: string,\n\ttoolName: string,\n\treason: string,\n\ttimestamp: number = Date.now(),\n\tdisposition: \"aborted\" | \"skipped\" = \"aborted\",\n): ToolResultMessage {\n\tconst envelope = createToolResultEnvelope({\n\t\tsynthetic: true,\n\t\tdisposition,\n\t\treason,\n\t\texecutionStarted: false,\n\t});\n\treturn createImmutableSnapshot({\n\t\trole: \"toolResult\",\n\t\ttoolCallId,\n\t\ttoolName,\n\t\tcontent: [{ type: \"text\", text: reason }],\n\t\tdetails: { omk: envelope },\n\t\tisError: true,\n\t\ttimestamp,\n\t});\n}\n\n/**\n * Repair a transcript by appending synthetic results for unambiguous missing\n * tail calls. Fails closed (throws {@link TranscriptIntegrityError}) for any\n * duplicate, orphan, interleaving, or mid-transcript gap. Idempotent: a second\n * call on already-repaired input returns an equal copy with no new messages.\n */\nexport function repairTranscriptIntegrity(messages: readonly AgentMessage[], reason?: string): AgentMessage[] {\n\tconst report = inspectTranscriptIntegrity(messages);\n\n\tfor (const issue of report.issues) {\n\t\tif (issue.kind !== \"missing_result\") {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t`Cannot repair transcript: detected ${issue.kind} for tool call ${issue.toolCallId}`,\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst missingIds = new Set(report.issues.map((issue) => issue.toolCallId));\n\tif (missingIds.size === 0) {\n\t\treturn messages.slice();\n\t}\n\n\tlet lastAssistantIndex = -1;\n\tfor (let i = messages.length - 1; i >= 0; i--) {\n\t\tif (isAssistantMessage(messages[i])) {\n\t\t\tlastAssistantIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (lastAssistantIndex === -1) {\n\t\tthrow new TranscriptIntegrityError(\n\t\t\t\"Cannot repair transcript: missing results without an assistant message\",\n\t\t\treport,\n\t\t);\n\t}\n\n\tconst lastAssistant = messages[lastAssistantIndex];\n\tif (!isAssistantMessage(lastAssistant)) {\n\t\tthrow new TranscriptIntegrityError(\"Cannot repair transcript: trailing message is not assistant\", report);\n\t}\n\tconst tailCalls = lastAssistant.content.filter(isToolCallBlock);\n\tconst tailCallIds = new Set(tailCalls.map((call) => call.id));\n\tfor (const id of missingIds) {\n\t\tif (!tailCallIds.has(id)) {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t`Cannot repair transcript: missing result for ${id} is not in the trailing assistant message`,\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tfor (let i = lastAssistantIndex + 1; i < messages.length; i++) {\n\t\tconst message = messages[i];\n\t\tif (!isToolResultMessage(message) || !tailCallIds.has(message.toolCallId)) {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t\"Cannot repair transcript: non-result message after the trailing assistant message\",\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst text = reason ?? \"Tool result missing; synthesized by transcript repair\";\n\tconst repaired = messages.slice();\n\tfor (const call of tailCalls) {\n\t\tif (missingIds.has(call.id)) {\n\t\t\trepaired.push(createSyntheticToolResult(call.id, call.name, text));\n\t\t}\n\t}\n\treturn repaired;\n}\n"]}

package/dist/tool-transcript-integrity.js

@@ -0,0 +1,223 @@
+/**
+ * Pure, browser-safe transcript integrity inspector and repair for the tool-call
+ * transcripts produced by the agent loop.
+ *
+ * The inspector detects five classes of structural corruption:
+ * - `missing_result`: a tool call with no matching tool result
+ * - `duplicate_result`: two or more tool results for the same call id
+ * - `orphan_result`: a tool result whose call id was never emitted
+ * - `duplicate_call_id`: two or more tool calls sharing an id
+ * - `interleaved_non_result`: a non-result message breaks the contiguous run of
+ *   results that must follow an assistant message's tool calls (including a
+ *   result that arrives before its call, after a user/custom boundary, or at the
+ *   start of the transcript)
+ *
+ * IDs are accounted globally, so an orphan or duplicate is caught regardless of
+ * where it appears. Repair is intentionally conservative: it only appends
+ * synthetic results for unambiguous missing tail calls. Any duplicate, orphan,
+ * interleaving, or mid-transcript gap fails closed.
+ *
+ * This module uses no platform APIs (no `process`, fs, or timers) so it is safe
+ * to run in a browser.
+ */
+import { createImmutableSnapshot } from "./plain-data.js";
+import { createToolResultEnvelope } from "./types.js";
+/** Thrown by {@link repairTranscriptIntegrity} when a transcript cannot be safely repaired. */
+export class TranscriptIntegrityError extends Error {
+    report;
+    constructor(message, report) {
+        super(message);
+        this.name = "TranscriptIntegrityError";
+        this.report = report;
+    }
+}
+function isAssistantMessage(message) {
+    return message.role === "assistant";
+}
+function isToolResultMessage(message) {
+    return message.role === "toolResult";
+}
+function isToolCallBlock(block) {
+    return block?.type === "toolCall";
+}
+/**
+ * Inspect a transcript and report every detected integrity issue. Pure: does not
+ * mutate the input and uses no platform APIs.
+ *
+ * IDs are accounted globally first (catching duplicates, orphans, and missing
+ * results anywhere in the transcript), then a single left-to-right pass checks
+ * the ordering invariant that an assistant message's tool calls must be followed
+ * by a contiguous run of their results with no intervening non-result message.
+ */
+export function inspectTranscriptIntegrity(messages) {
+    const issues = [];
+    const callIdCount = new Map();
+    const resultIdCount = new Map();
+    const callToolName = new Map();
+    for (const message of messages) {
+        if (isAssistantMessage(message)) {
+            for (const block of message.content) {
+                if (isToolCallBlock(block)) {
+                    callIdCount.set(block.id, (callIdCount.get(block.id) ?? 0) + 1);
+                    if (!callToolName.has(block.id)) {
+                        callToolName.set(block.id, block.name);
+                    }
+                }
+            }
+        }
+        else if (isToolResultMessage(message)) {
+            resultIdCount.set(message.toolCallId, (resultIdCount.get(message.toolCallId) ?? 0) + 1);
+        }
+    }
+    for (const [id, count] of callIdCount) {
+        if (count > 1) {
+            issues.push({ kind: "duplicate_call_id", toolCallId: id, toolName: callToolName.get(id) });
+        }
+    }
+    for (const [id, count] of resultIdCount) {
+        if (count > 1) {
+            issues.push({ kind: "duplicate_result", toolCallId: id });
+        }
+    }
+    for (const [id] of resultIdCount) {
+        if (!callIdCount.has(id)) {
+            issues.push({ kind: "orphan_result", toolCallId: id });
+        }
+    }
+    for (const [id] of callIdCount) {
+        if (!resultIdCount.has(id)) {
+            issues.push({ kind: "missing_result", toolCallId: id, toolName: callToolName.get(id) });
+        }
+    }
+    const pending = new Map();
+    let resultsRegion = false;
+    for (const message of messages) {
+        if (isAssistantMessage(message)) {
+            const calls = message.content.filter(isToolCallBlock);
+            if (calls.length > 0) {
+                // A new assistant message with tool calls while previous calls are
+                // still unresolved means a non-result interrupted the prior region.
+                if (pending.size > 0) {
+                    for (const [id, name] of pending) {
+                        issues.push({ kind: "interleaved_non_result", toolCallId: id, toolName: name });
+                    }
+                    break;
+                }
+                for (const call of calls) {
+                    pending.set(call.id, call.name);
+                }
+                resultsRegion = true;
+            }
+            else if (resultsRegion && pending.size > 0) {
+                for (const [id, name] of pending) {
+                    issues.push({ kind: "interleaved_non_result", toolCallId: id, toolName: name });
+                }
+                break;
+            }
+        }
+        else if (isToolResultMessage(message)) {
+            if (resultsRegion && pending.has(message.toolCallId)) {
+                pending.delete(message.toolCallId);
+                if (pending.size === 0) {
+                    resultsRegion = false;
+                }
+            }
+            else if (callIdCount.has(message.toolCallId)) {
+                // Known call id arriving outside its contiguous results region:
+                // orphan-at-start, after-user, or assistant -> non-result -> result.
+                issues.push({ kind: "interleaved_non_result", toolCallId: message.toolCallId });
+                break;
+            }
+            // Unknown-id orphans are already reported above; do not double report.
+        }
+        else {
+            // user or custom non-result message: breaks an open results region.
+            if (resultsRegion && pending.size > 0) {
+                for (const [id, name] of pending) {
+                    issues.push({ kind: "interleaved_non_result", toolCallId: id, toolName: name });
+                }
+                break;
+            }
+        }
+    }
+    const frozenIssues = Object.freeze(issues.map((issue) => Object.freeze({ ...issue })));
+    return Object.freeze({ ok: frozenIssues.length === 0, issues: frozenIssues });
+}
+/**
+ * Create a synthetic terminal tool result. Shared by transcript repair and the
+ * agent-loop abort closure so the disposition of an unresolved call is encoded
+ * identically everywhere. The `details.omk` envelope marks the artifact as
+ * synthetic (`executionStarted: false`): it closes the provider transcript and
+ * never claims the tool actually ran.
+ */
+export function createSyntheticToolResult(toolCallId, toolName, reason, timestamp = Date.now(), disposition = "aborted") {
+    const envelope = createToolResultEnvelope({
+        synthetic: true,
+        disposition,
+        reason,
+        executionStarted: false,
+    });
+    return createImmutableSnapshot({
+        role: "toolResult",
+        toolCallId,
+        toolName,
+        content: [{ type: "text", text: reason }],
+        details: { omk: envelope },
+        isError: true,
+        timestamp,
+    });
+}
+/**
+ * Repair a transcript by appending synthetic results for unambiguous missing
+ * tail calls. Fails closed (throws {@link TranscriptIntegrityError}) for any
+ * duplicate, orphan, interleaving, or mid-transcript gap. Idempotent: a second
+ * call on already-repaired input returns an equal copy with no new messages.
+ */
+export function repairTranscriptIntegrity(messages, reason) {
+    const report = inspectTranscriptIntegrity(messages);
+    for (const issue of report.issues) {
+        if (issue.kind !== "missing_result") {
+            throw new TranscriptIntegrityError(`Cannot repair transcript: detected ${issue.kind} for tool call ${issue.toolCallId}`, report);
+        }
+    }
+    const missingIds = new Set(report.issues.map((issue) => issue.toolCallId));
+    if (missingIds.size === 0) {
+        return messages.slice();
+    }
+    let lastAssistantIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (isAssistantMessage(messages[i])) {
+            lastAssistantIndex = i;
+            break;
+        }
+    }
+    if (lastAssistantIndex === -1) {
+        throw new TranscriptIntegrityError("Cannot repair transcript: missing results without an assistant message", report);
+    }
+    const lastAssistant = messages[lastAssistantIndex];
+    if (!isAssistantMessage(lastAssistant)) {
+        throw new TranscriptIntegrityError("Cannot repair transcript: trailing message is not assistant", report);
+    }
+    const tailCalls = lastAssistant.content.filter(isToolCallBlock);
+    const tailCallIds = new Set(tailCalls.map((call) => call.id));
+    for (const id of missingIds) {
+        if (!tailCallIds.has(id)) {
+            throw new TranscriptIntegrityError(`Cannot repair transcript: missing result for ${id} is not in the trailing assistant message`, report);
+        }
+    }
+    for (let i = lastAssistantIndex + 1; i < messages.length; i++) {
+        const message = messages[i];
+        if (!isToolResultMessage(message) || !tailCallIds.has(message.toolCallId)) {
+            throw new TranscriptIntegrityError("Cannot repair transcript: non-result message after the trailing assistant message", report);
+        }
+    }
+    const text = reason ?? "Tool result missing; synthesized by transcript repair";
+    const repaired = messages.slice();
+    for (const call of tailCalls) {
+        if (missingIds.has(call.id)) {
+            repaired.push(createSyntheticToolResult(call.id, call.name, text));
+        }
+    }
+    return repaired;
+}
+//# sourceMappingURL=tool-transcript-integrity.js.map

package/dist/tool-transcript-integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-transcript-integrity.js","sourceRoot":"","sources":["../src/tool-transcript-integrity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure, browser-safe transcript integrity inspector and repair for the tool-call\n * transcripts produced by the agent loop.\n *\n * The inspector detects five classes of structural corruption:\n * - `missing_result`: a tool call with no matching tool result\n * - `duplicate_result`: two or more tool results for the same call id\n * - `orphan_result`: a tool result whose call id was never emitted\n * - `duplicate_call_id`: two or more tool calls sharing an id\n * - `interleaved_non_result`: a non-result message breaks the contiguous run of\n *   results that must follow an assistant message's tool calls (including a\n *   result that arrives before its call, after a user/custom boundary, or at the\n *   start of the transcript)\n *\n * IDs are accounted globally, so an orphan or duplicate is caught regardless of\n * where it appears. Repair is intentionally conservative: it only appends\n * synthetic results for unambiguous missing tail calls. Any duplicate, orphan,\n * interleaving, or mid-transcript gap fails closed.\n *\n * This module uses no platform APIs (no `process`, fs, or timers) so it is safe\n * to run in a browser.\n */\n\nimport type { AssistantMessage, ToolCall, ToolResultMessage } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"./plain-data.ts\";\nimport { type AgentMessage, createToolResultEnvelope } from \"./types.ts\";\n\nexport type TranscriptIntegrityIssueKind =\n\t| \"missing_result\"\n\t| \"duplicate_result\"\n\t| \"orphan_result\"\n\t| \"duplicate_call_id\"\n\t| \"interleaved_non_result\";\n\nexport interface TranscriptIntegrityIssue {\n\treadonly kind: TranscriptIntegrityIssueKind;\n\treadonly toolCallId: string;\n\treadonly toolName?: string;\n}\n\nexport interface TranscriptIntegrityReport {\n\treadonly ok: boolean;\n\treadonly issues: readonly TranscriptIntegrityIssue[];\n}\n\n/** Thrown by {@link repairTranscriptIntegrity} when a transcript cannot be safely repaired. */\nexport class TranscriptIntegrityError extends Error {\n\treadonly report: TranscriptIntegrityReport;\n\tconstructor(message: string, report: TranscriptIntegrityReport) {\n\t\tsuper(message);\n\t\tthis.name = \"TranscriptIntegrityError\";\n\t\tthis.report = report;\n\t}\n}\n\nfunction isAssistantMessage(message: AgentMessage): message is AssistantMessage {\n\treturn message.role === \"assistant\";\n}\n\nfunction isToolResultMessage(message: AgentMessage): message is ToolResultMessage {\n\treturn message.role === \"toolResult\";\n}\n\nfunction isToolCallBlock(block: unknown): block is ToolCall {\n\treturn (block as { type?: string } | null)?.type === \"toolCall\";\n}\n\n/**\n * Inspect a transcript and report every detected integrity issue. Pure: does not\n * mutate the input and uses no platform APIs.\n *\n * IDs are accounted globally first (catching duplicates, orphans, and missing\n * results anywhere in the transcript), then a single left-to-right pass checks\n * the ordering invariant that an assistant message's tool calls must be followed\n * by a contiguous run of their results with no intervening non-result message.\n */\nexport function inspectTranscriptIntegrity(messages: readonly AgentMessage[]): TranscriptIntegrityReport {\n\tconst issues: TranscriptIntegrityIssue[] = [];\n\n\tconst callIdCount = new Map<string, number>();\n\tconst resultIdCount = new Map<string, number>();\n\tconst callToolName = new Map<string, string>();\n\n\tfor (const message of messages) {\n\t\tif (isAssistantMessage(message)) {\n\t\t\tfor (const block of message.content) {\n\t\t\t\tif (isToolCallBlock(block)) {\n\t\t\t\t\tcallIdCount.set(block.id, (callIdCount.get(block.id) ?? 0) + 1);\n\t\t\t\t\tif (!callToolName.has(block.id)) {\n\t\t\t\t\t\tcallToolName.set(block.id, block.name);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (isToolResultMessage(message)) {\n\t\t\tresultIdCount.set(message.toolCallId, (resultIdCount.get(message.toolCallId) ?? 0) + 1);\n\t\t}\n\t}\n\n\tfor (const [id, count] of callIdCount) {\n\t\tif (count > 1) {\n\t\t\tissues.push({ kind: \"duplicate_call_id\", toolCallId: id, toolName: callToolName.get(id) });\n\t\t}\n\t}\n\tfor (const [id, count] of resultIdCount) {\n\t\tif (count > 1) {\n\t\t\tissues.push({ kind: \"duplicate_result\", toolCallId: id });\n\t\t}\n\t}\n\tfor (const [id] of resultIdCount) {\n\t\tif (!callIdCount.has(id)) {\n\t\t\tissues.push({ kind: \"orphan_result\", toolCallId: id });\n\t\t}\n\t}\n\tfor (const [id] of callIdCount) {\n\t\tif (!resultIdCount.has(id)) {\n\t\t\tissues.push({ kind: \"missing_result\", toolCallId: id, toolName: callToolName.get(id) });\n\t\t}\n\t}\n\n\tconst pending = new Map<string, string>();\n\tlet resultsRegion = false;\n\n\tfor (const message of messages) {\n\t\tif (isAssistantMessage(message)) {\n\t\t\tconst calls = message.content.filter(isToolCallBlock);\n\t\t\tif (calls.length > 0) {\n\t\t\t\t// A new assistant message with tool calls while previous calls are\n\t\t\t\t// still unresolved means a non-result interrupted the prior region.\n\t\t\t\tif (pending.size > 0) {\n\t\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t\t}\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tfor (const call of calls) {\n\t\t\t\t\tpending.set(call.id, call.name);\n\t\t\t\t}\n\t\t\t\tresultsRegion = true;\n\t\t\t} else if (resultsRegion && pending.size > 0) {\n\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t} else if (isToolResultMessage(message)) {\n\t\t\tif (resultsRegion && pending.has(message.toolCallId)) {\n\t\t\t\tpending.delete(message.toolCallId);\n\t\t\t\tif (pending.size === 0) {\n\t\t\t\t\tresultsRegion = false;\n\t\t\t\t}\n\t\t\t} else if (callIdCount.has(message.toolCallId)) {\n\t\t\t\t// Known call id arriving outside its contiguous results region:\n\t\t\t\t// orphan-at-start, after-user, or assistant -> non-result -> result.\n\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: message.toolCallId });\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\t// Unknown-id orphans are already reported above; do not double report.\n\t\t} else {\n\t\t\t// user or custom non-result message: breaks an open results region.\n\t\t\tif (resultsRegion && pending.size > 0) {\n\t\t\t\tfor (const [id, name] of pending) {\n\t\t\t\t\tissues.push({ kind: \"interleaved_non_result\", toolCallId: id, toolName: name });\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\tconst frozenIssues = Object.freeze(issues.map((issue) => Object.freeze({ ...issue })));\n\treturn Object.freeze({ ok: frozenIssues.length === 0, issues: frozenIssues });\n}\n\n/**\n * Create a synthetic terminal tool result. Shared by transcript repair and the\n * agent-loop abort closure so the disposition of an unresolved call is encoded\n * identically everywhere. The `details.omk` envelope marks the artifact as\n * synthetic (`executionStarted: false`): it closes the provider transcript and\n * never claims the tool actually ran.\n */\nexport function createSyntheticToolResult(\n\ttoolCallId: string,\n\ttoolName: string,\n\treason: string,\n\ttimestamp: number = Date.now(),\n\tdisposition: \"aborted\" | \"skipped\" = \"aborted\",\n): ToolResultMessage {\n\tconst envelope = createToolResultEnvelope({\n\t\tsynthetic: true,\n\t\tdisposition,\n\t\treason,\n\t\texecutionStarted: false,\n\t});\n\treturn createImmutableSnapshot({\n\t\trole: \"toolResult\",\n\t\ttoolCallId,\n\t\ttoolName,\n\t\tcontent: [{ type: \"text\", text: reason }],\n\t\tdetails: { omk: envelope },\n\t\tisError: true,\n\t\ttimestamp,\n\t});\n}\n\n/**\n * Repair a transcript by appending synthetic results for unambiguous missing\n * tail calls. Fails closed (throws {@link TranscriptIntegrityError}) for any\n * duplicate, orphan, interleaving, or mid-transcript gap. Idempotent: a second\n * call on already-repaired input returns an equal copy with no new messages.\n */\nexport function repairTranscriptIntegrity(messages: readonly AgentMessage[], reason?: string): AgentMessage[] {\n\tconst report = inspectTranscriptIntegrity(messages);\n\n\tfor (const issue of report.issues) {\n\t\tif (issue.kind !== \"missing_result\") {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t`Cannot repair transcript: detected ${issue.kind} for tool call ${issue.toolCallId}`,\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst missingIds = new Set(report.issues.map((issue) => issue.toolCallId));\n\tif (missingIds.size === 0) {\n\t\treturn messages.slice();\n\t}\n\n\tlet lastAssistantIndex = -1;\n\tfor (let i = messages.length - 1; i >= 0; i--) {\n\t\tif (isAssistantMessage(messages[i])) {\n\t\t\tlastAssistantIndex = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (lastAssistantIndex === -1) {\n\t\tthrow new TranscriptIntegrityError(\n\t\t\t\"Cannot repair transcript: missing results without an assistant message\",\n\t\t\treport,\n\t\t);\n\t}\n\n\tconst lastAssistant = messages[lastAssistantIndex];\n\tif (!isAssistantMessage(lastAssistant)) {\n\t\tthrow new TranscriptIntegrityError(\"Cannot repair transcript: trailing message is not assistant\", report);\n\t}\n\tconst tailCalls = lastAssistant.content.filter(isToolCallBlock);\n\tconst tailCallIds = new Set(tailCalls.map((call) => call.id));\n\tfor (const id of missingIds) {\n\t\tif (!tailCallIds.has(id)) {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t`Cannot repair transcript: missing result for ${id} is not in the trailing assistant message`,\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tfor (let i = lastAssistantIndex + 1; i < messages.length; i++) {\n\t\tconst message = messages[i];\n\t\tif (!isToolResultMessage(message) || !tailCallIds.has(message.toolCallId)) {\n\t\t\tthrow new TranscriptIntegrityError(\n\t\t\t\t\"Cannot repair transcript: non-result message after the trailing assistant message\",\n\t\t\t\treport,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst text = reason ?? \"Tool result missing; synthesized by transcript repair\";\n\tconst repaired = messages.slice();\n\tfor (const call of tailCalls) {\n\t\tif (missingIds.has(call.id)) {\n\t\t\trepaired.push(createSyntheticToolResult(call.id, call.name, text));\n\t\t}\n\t}\n\treturn repaired;\n}\n"]}