omk-agent-core 0.90.7 → 0.90.9

package/dist/tool-resource-claims.js

@@ -0,0 +1,128 @@
+/** Browser-safe resource claims for the opt-in dag-v2 scheduler. */
+import { findRegisteredToolClaimDefinition, isBuiltinPathClaimTool, isPlainArguments, pathClaimsOverlap, resolveBuiltinPathClaimWithIdentity, resolvePathClaimWithIdentity, resolveToolClaims, resolveToolPolicy, } from "./builtin-tool-resource-claims.js";
+import { NEVER_PARALLEL_TOOLS } from "./parallel-tool-batch.js";
+export { resolvePathClaimKey, resolveToolClaims } from "./builtin-tool-resource-claims.js";
+function isNonPathKind(value) {
+    return value === "session" || value === "terminal" || value === "network" || value === "global";
+}
+async function normalizeCustomClaims(value, options) {
+    if (value === "exclusive")
+        return { kind: "exclusive" };
+    if (!Array.isArray(value) || value.length === 0)
+        return { kind: "exclusive" };
+    const claims = [];
+    let hasExclusiveAccess = false;
+    for (const candidate of value) {
+        if (!isPlainArguments(candidate) || typeof candidate.key !== "string" || candidate.key.trim().length === 0) {
+            return { kind: "exclusive" };
+        }
+        if (candidate.kind === "path") {
+            if (candidate.access !== "read" && candidate.access !== "write")
+                return { kind: "exclusive" };
+            const pathResolution = await resolvePathClaimWithIdentity(candidate.key, candidate.access, options);
+            if (pathResolution.kind === "exclusive")
+                return pathResolution;
+            claims.push(...pathResolution.claims);
+            continue;
+        }
+        if (!isNonPathKind(candidate.kind))
+            return { kind: "exclusive" };
+        if (candidate.access !== "read" && candidate.access !== "write" && candidate.access !== "exclusive") {
+            return { kind: "exclusive" };
+        }
+        const access = candidate.access;
+        claims.push({ kind: candidate.kind, key: candidate.key, access });
+        if (access === "exclusive")
+            hasExclusiveAccess = true;
+    }
+    return hasExclusiveAccess ? { kind: "exclusive" } : { kind: "claims", claims };
+}
+/** Resolve one call, failing malformed or rejected extension claims closed. */
+export async function resolveToolClaimsForCall(toolCall, options) {
+    const registeredTool = findRegisteredToolClaimDefinition(toolCall.name, options.registeredTools);
+    if (!registeredTool?.resourceClaims) {
+        if (options.resourceKeyResolver &&
+            isBuiltinPathClaimTool(toolCall.name) &&
+            isPlainArguments(toolCall.arguments) &&
+            !NEVER_PARALLEL_TOOLS.has(toolCall.name) &&
+            resolveToolPolicy(toolCall.name, options) !== "sequential") {
+            return resolveBuiltinPathClaimWithIdentity(toolCall, options);
+        }
+        return resolveToolClaims(toolCall, options);
+    }
+    if (!isPlainArguments(toolCall.arguments))
+        return { kind: "exclusive" };
+    let resolution;
+    try {
+        const claims = await registeredTool.resourceClaims(toolCall.arguments, {
+            cwd: options.cwd,
+            toolCallId: toolCall.id ?? "",
+        });
+        resolution = await normalizeCustomClaims(claims, options);
+    }
+    catch {
+        return { kind: "exclusive" };
+    }
+    if (NEVER_PARALLEL_TOOLS.has(toolCall.name) ||
+        toolCall.name === "bash" ||
+        resolveToolPolicy(toolCall.name, options) === "sequential") {
+        return { kind: "exclusive" };
+    }
+    return resolution;
+}
+export function compareClaims(left, right) {
+    if (left.kind !== right.kind)
+        return left.kind < right.kind ? -1 : 1;
+    if (left.key !== right.key)
+        return left.key < right.key ? -1 : 1;
+    if (left.access !== right.access)
+        return left.access < right.access ? -1 : 1;
+    const leftReal = left.kind === "path" ? (left.realKey ?? "") : "";
+    const rightReal = right.kind === "path" ? (right.realKey ?? "") : "";
+    if (leftReal !== rightReal)
+        return leftReal < rightReal ? -1 : 1;
+    const leftInode = left.kind === "path" ? (left.inodeKey ?? "") : "";
+    const rightInode = right.kind === "path" ? (right.inodeKey ?? "") : "";
+    if (leftInode !== rightInode)
+        return leftInode < rightInode ? -1 : 1;
+    return 0;
+}
+export function canonicalizeClaims(claims) {
+    return claims
+        .map((claim) => claim.kind === "path"
+        ? {
+            kind: "path",
+            key: claim.key,
+            access: claim.access,
+            ...(claim.realKey === undefined ? {} : { realKey: claim.realKey }),
+            ...(claim.inodeKey === undefined ? {} : { inodeKey: claim.inodeKey }),
+        }
+        : { kind: claim.kind, key: claim.key, access: claim.access })
+        .sort(compareClaims);
+}
+export function claimsConflict(left, right) {
+    if (left.access === "exclusive" || right.access === "exclusive")
+        return true;
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === "path" && right.kind === "path") {
+        if (!pathClaimsOverlap(left, right))
+            return false;
+    }
+    else if (left.key !== right.key) {
+        return false;
+    }
+    return !(left.access === "read" && right.access === "read");
+}
+export function resolutionsConflict(left, right) {
+    if (left.kind === "exclusive" || right.kind === "exclusive")
+        return true;
+    for (const leftClaim of left.claims) {
+        for (const rightClaim of right.claims) {
+            if (claimsConflict(leftClaim, rightClaim))
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=tool-resource-claims.js.map

package/dist/tool-resource-claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-resource-claims.js","sourceRoot":"","sources":["../src/tool-resource-claims.ts"],"names":[],"mappings":"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","sourcesContent":["/** Browser-safe resource claims for the opt-in dag-v2 scheduler. */\n\nimport {\n\tfindRegisteredToolClaimDefinition,\n\tisBuiltinPathClaimTool,\n\tisPlainArguments,\n\tpathClaimsOverlap,\n\tresolveBuiltinPathClaimWithIdentity,\n\tresolvePathClaimWithIdentity,\n\tresolveToolClaims,\n\tresolveToolPolicy,\n} from \"./builtin-tool-resource-claims.ts\";\nimport type { ToolParallelPolicy } from \"./parallel-tool-batch.ts\";\nimport { NEVER_PARALLEL_TOOLS } from \"./parallel-tool-batch.ts\";\nimport type { AgentTool, ResourceAccess, ResourceKeyResolver, ToolResourceClaim } from \"./types.ts\";\n\nexport { resolvePathClaimKey, resolveToolClaims } from \"./builtin-tool-resource-claims.ts\";\nexport type {\n\tResourceAccess,\n\tToolResourceAccess,\n\tToolResourceClaim,\n\tToolResourceClaims,\n\tToolResourceClaimsContext,\n} from \"./types.ts\";\n\nexport type ToolClaimResolution = { kind: \"exclusive\" } | { kind: \"claims\"; claims: ToolResourceClaim[] };\n\nexport interface ClaimableToolCall {\n\tid?: string;\n\tname: string;\n\targuments: unknown;\n}\n\nexport type RegisteredToolClaimDefinition = Pick<AgentTool, \"name\" | \"executionMode\" | \"resourceClaims\">;\n\nexport interface ResolveToolClaimsOptions {\n\tcwd: string;\n\ttoolPolicies?: ReadonlyMap<string, ToolParallelPolicy>;\n\tregisteredTools?: readonly RegisteredToolClaimDefinition[];\n\tstrictExtensionClaims?: boolean;\n\tresourceKeyResolver?: ResourceKeyResolver;\n}\n\nfunction isNonPathKind(value: unknown): value is Exclude<ToolResourceClaim[\"kind\"], \"path\"> {\n\treturn value === \"session\" || value === \"terminal\" || value === \"network\" || value === \"global\";\n}\n\nasync function normalizeCustomClaims(value: unknown, options: ResolveToolClaimsOptions): Promise<ToolClaimResolution> {\n\tif (value === \"exclusive\") return { kind: \"exclusive\" };\n\tif (!Array.isArray(value) || value.length === 0) return { kind: \"exclusive\" };\n\n\tconst claims: ToolResourceClaim[] = [];\n\tlet hasExclusiveAccess = false;\n\tfor (const candidate of value) {\n\t\tif (!isPlainArguments(candidate) || typeof candidate.key !== \"string\" || candidate.key.trim().length === 0) {\n\t\t\treturn { kind: \"exclusive\" };\n\t\t}\n\t\tif (candidate.kind === \"path\") {\n\t\t\tif (candidate.access !== \"read\" && candidate.access !== \"write\") return { kind: \"exclusive\" };\n\t\t\tconst pathResolution = await resolvePathClaimWithIdentity(candidate.key, candidate.access, options);\n\t\t\tif (pathResolution.kind === \"exclusive\") return pathResolution;\n\t\t\tclaims.push(...pathResolution.claims);\n\t\t\tcontinue;\n\t\t}\n\t\tif (!isNonPathKind(candidate.kind)) return { kind: \"exclusive\" };\n\t\tif (candidate.access !== \"read\" && candidate.access !== \"write\" && candidate.access !== \"exclusive\") {\n\t\t\treturn { kind: \"exclusive\" };\n\t\t}\n\t\tconst access: ResourceAccess = candidate.access;\n\t\tclaims.push({ kind: candidate.kind, key: candidate.key, access });\n\t\tif (access === \"exclusive\") hasExclusiveAccess = true;\n\t}\n\treturn hasExclusiveAccess ? { kind: \"exclusive\" } : { kind: \"claims\", claims };\n}\n\n/** Resolve one call, failing malformed or rejected extension claims closed. */\nexport async function resolveToolClaimsForCall(\n\ttoolCall: ClaimableToolCall,\n\toptions: ResolveToolClaimsOptions,\n): Promise<ToolClaimResolution> {\n\tconst registeredTool = findRegisteredToolClaimDefinition(toolCall.name, options.registeredTools);\n\tif (!registeredTool?.resourceClaims) {\n\t\tif (\n\t\t\toptions.resourceKeyResolver &&\n\t\t\tisBuiltinPathClaimTool(toolCall.name) &&\n\t\t\tisPlainArguments(toolCall.arguments) &&\n\t\t\t!NEVER_PARALLEL_TOOLS.has(toolCall.name) &&\n\t\t\tresolveToolPolicy(toolCall.name, options) !== \"sequential\"\n\t\t) {\n\t\t\treturn resolveBuiltinPathClaimWithIdentity(toolCall, options);\n\t\t}\n\t\treturn resolveToolClaims(toolCall, options);\n\t}\n\tif (!isPlainArguments(toolCall.arguments)) return { kind: \"exclusive\" };\n\n\tlet resolution: ToolClaimResolution;\n\ttry {\n\t\tconst claims = await registeredTool.resourceClaims(toolCall.arguments, {\n\t\t\tcwd: options.cwd,\n\t\t\ttoolCallId: toolCall.id ?? \"\",\n\t\t});\n\t\tresolution = await normalizeCustomClaims(claims, options);\n\t} catch {\n\t\treturn { kind: \"exclusive\" };\n\t}\n\tif (\n\t\tNEVER_PARALLEL_TOOLS.has(toolCall.name) ||\n\t\ttoolCall.name === \"bash\" ||\n\t\tresolveToolPolicy(toolCall.name, options) === \"sequential\"\n\t) {\n\t\treturn { kind: \"exclusive\" };\n\t}\n\treturn resolution;\n}\n\nexport function compareClaims(left: ToolResourceClaim, right: ToolResourceClaim): number {\n\tif (left.kind !== right.kind) return left.kind < right.kind ? -1 : 1;\n\tif (left.key !== right.key) return left.key < right.key ? -1 : 1;\n\tif (left.access !== right.access) return left.access < right.access ? -1 : 1;\n\tconst leftReal = left.kind === \"path\" ? (left.realKey ?? \"\") : \"\";\n\tconst rightReal = right.kind === \"path\" ? (right.realKey ?? \"\") : \"\";\n\tif (leftReal !== rightReal) return leftReal < rightReal ? -1 : 1;\n\tconst leftInode = left.kind === \"path\" ? (left.inodeKey ?? \"\") : \"\";\n\tconst rightInode = right.kind === \"path\" ? (right.inodeKey ?? \"\") : \"\";\n\tif (leftInode !== rightInode) return leftInode < rightInode ? -1 : 1;\n\treturn 0;\n}\n\nexport function canonicalizeClaims(claims: readonly ToolResourceClaim[]): ToolResourceClaim[] {\n\treturn claims\n\t\t.map(\n\t\t\t(claim): ToolResourceClaim =>\n\t\t\t\tclaim.kind === \"path\"\n\t\t\t\t\t? {\n\t\t\t\t\t\t\tkind: \"path\",\n\t\t\t\t\t\t\tkey: claim.key,\n\t\t\t\t\t\t\taccess: claim.access,\n\t\t\t\t\t\t\t...(claim.realKey === undefined ? {} : { realKey: claim.realKey }),\n\t\t\t\t\t\t\t...(claim.inodeKey === undefined ? {} : { inodeKey: claim.inodeKey }),\n\t\t\t\t\t\t}\n\t\t\t\t\t: { kind: claim.kind, key: claim.key, access: claim.access },\n\t\t)\n\t\t.sort(compareClaims);\n}\n\nexport function claimsConflict(left: ToolResourceClaim, right: ToolResourceClaim): boolean {\n\tif (left.access === \"exclusive\" || right.access === \"exclusive\") return true;\n\tif (left.kind !== right.kind) return false;\n\tif (left.kind === \"path\" && right.kind === \"path\") {\n\t\tif (!pathClaimsOverlap(left, right)) return false;\n\t} else if (left.key !== right.key) {\n\t\treturn false;\n\t}\n\treturn !(left.access === \"read\" && right.access === \"read\");\n}\n\nexport function resolutionsConflict(left: ToolClaimResolution, right: ToolClaimResolution): boolean {\n\tif (left.kind === \"exclusive\" || right.kind === \"exclusive\") return true;\n\tfor (const leftClaim of left.claims) {\n\t\tfor (const rightClaim of right.claims) {\n\t\t\tif (claimsConflict(leftClaim, rightClaim)) return true;\n\t\t}\n\t}\n\treturn false;\n}\n"]}

package/dist/tool-timeout.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 type { AgentLoopConfig, AgentTool, AgentToolResult, AgentToolUpdateCallback, ToolExecutionPolicy, ToolLateSettlementOutcome, ToolTimeoutDisposition } from "./types.ts";
+export type { ToolDispositionEnvelope } from "./tool-execution-boundary.ts";
+export { createAbortedToolResult, createTimeoutToolResult } from "./tool-execution-boundary.ts";
+/**
+ * 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 declare function resolveToolExecutionPolicy(policy: Partial<ToolExecutionPolicy> | undefined): ToolExecutionPolicy;
+/** Audit-only description of a real tool promise settling after its terminal cause won. */
+export interface ToolLateSettlement {
+    toolCallId: string;
+    toolName: string;
+    /** The terminal disposition that was already committed when the real promise settled. */
+    disposition: ToolTimeoutDisposition;
+    /** How the real tool promise eventually settled. Disposition-safe metadata only. */
+    outcome: ToolLateSettlementOutcome;
+}
+/**
+ * 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 declare function resolveToolTimeoutMs(tool: Pick<AgentTool<any>, "timeoutMs">, config: Pick<AgentLoopConfig, "toolTimeoutMs" | "toolTimeouts">, toolName: string): number;
+export interface RunToolCallWithTimeoutOptions<TDetails = any> {
+    toolCallId: string;
+    toolName: string;
+    /** Effective timeout in ms. A non-positive value disables the timer, not parent cancellation. */
+    timeoutMs: number;
+    /** Parent run abort signal, if any. */
+    signal: AbortSignal | undefined;
+    /** Start the real tool, passing the child (best-effort) signal and update sink. */
+    start: (childSignal: AbortSignal, onUpdate: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+    /** Emit a `tool_execution_update` for a partial result observed before terminality. */
+    emitUpdate: (partialResult: AgentToolResult<TDetails>) => Promise<void> | void;
+    /** Emit the audit-only late-settlement event exactly once, after the terminal cause won. */
+    emitLateSettlement: (settlement: ToolLateSettlement) => Promise<void> | void;
+    /** Map a thrown/rejected tool error to a normal error result (real completion path). */
+    toErrorResult: (error: unknown) => AgentToolResult<any>;
+    /**
+     * Late-settlement policy (default `"audit"`). `"ignore"` drops the audit
+     * event; the committed terminal result is immutable under both policies.
+     */
+    lateSettlement?: ToolExecutionPolicy["lateSettlement"];
+}
+export interface RunToolCallWithTimeoutResult {
+    result: AgentToolResult<any>;
+    isError: boolean;
+    /** True when the tool's `execute` actually began before the result was committed. */
+    executionStarted: boolean;
+    /** Terminal cause when the runtime (not the tool) committed the result. */
+    terminalDisposition?: ToolTimeoutDisposition;
+}
+/**
+ * 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 declare function runToolCallWithTimeout<TDetails = any>(options: RunToolCallWithTimeoutOptions<TDetails>): Promise<RunToolCallWithTimeoutResult>;
+//# sourceMappingURL=tool-timeout.d.ts.map

package/dist/tool-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-timeout.d.ts","sourceRoot":"","sources":["../src/tool-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EACX,eAAe,EACf,SAAS,EACT,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEhG;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,SAAS,GAAG,mBAAmB,CAMhH;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,WAAW,EAAE,sBAAsB,CAAC;IACpC,oFAAoF;IACpF,OAAO,EAAE,yBAAyB,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,EACvC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,GAAG,cAAc,CAAC,EAC/D,QAAQ,EAAE,MAAM,GACd,MAAM,CAaR;AAQD,MAAM,WAAW,6BAA6B,CAAC,QAAQ,GAAG,GAAG;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,mFAAmF;IACnF,KAAK,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,uBAAuB,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrH,uFAAuF;IACvF,UAAU,EAAE,CAAC,aAAa,EAAE,eAAe,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/E,4FAA4F;IAC5F,kBAAkB,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,wFAAwF;IACxF,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC,GAAG,CAAC,CAAC;IACxD;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,4BAA4B;IAC5C,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,GAAG,GAAG,EAC1D,OAAO,EAAE,6BAA6B,CAAC,QAAQ,CAAC,GAC9C,OAAO,CAAC,4BAA4B,CAAC,CAsHvC","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-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"]}