omk-agent-core 0.90.7 → 0.90.9

package/dist/tool-dag-scheduler.js

@@ -0,0 +1,171 @@
+/**
+ * Pure, browser-safe deterministic resource-claim DAG scheduler.
+ *
+ * Given a source-ordered batch of tool calls and their resolved resource
+ * claims, this module assigns each call after every earlier call it conflicts
+ * with. Levels run in source order; calls inside one level are mutually
+ * conflict-free and may execute concurrently. A positive `maxConcurrency`
+ * width cap splits each level into deterministic contiguous source-ordered
+ * chunks.
+ *
+ * Determinism contract:
+ * - The level assignment is a pure function of the source-ordered input
+ *   claims. The canonical example is the head-of-line example
+ *   `write x, write x, write y`, which schedules as `[[0, 2], [1]]`: the second
+ *   write to `x` is pushed to level 1, but the independent write to `y` is not
+ *   blocked and joins level 0.
+ * - Reordering claims *within* a single call does not change the plan: claims
+ *   are canonicalized (sorted, fixed property order) before comparison.
+ * - {@link DagSchedulePlan.planKey} is a canonical serialization of the
+ *   resolved claim sequence (canonical claim data only — never execution
+ *   timing or outcomes). It is collision-free for distinct canonical claim
+ *   sequences.
+ *
+ * This module uses no platform APIs (no `process`, fs, `node:path`, or timers).
+ */
+import { canonicalizeClaims, claimsConflict, resolveToolClaimsForCall, } from "./tool-resource-claims.js";
+/**
+ * Resolve and canonicalize claims for a whole batch, preserving source order.
+ * Registered custom resolvers are awaited one call at a time in source order,
+ * and every resolution completes before a schedule is constructed.
+ */
+export async function resolveBatchClaims(toolCalls, options) {
+    const entries = [];
+    for (let index = 0; index < toolCalls.length; index++) {
+        const resolution = await resolveToolClaimsForCall(toolCalls[index], options);
+        const canonicalClaims = resolution.kind === "claims" ? canonicalizeClaims(resolution.claims) : [];
+        entries.push({ sourceIndex: index, resolution, canonicalClaims });
+    }
+    return entries;
+}
+function claimConflictsAny(claim, candidates) {
+    for (const candidate of candidates) {
+        if (claimsConflict(claim, candidate)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when `resolution` cannot join `level`. Equivalent to the full pairwise
+ * `resolutionsConflict` check, optimized so read/read never triggers a scan:
+ * a read claim only needs to scan the level's writes, and a write claim scans
+ * both writes and reads. An exclusive resolution, or a level that already holds
+ * an exclusive call, conflicts unconditionally.
+ */
+function resolutionConflictsLevel(resolution, level) {
+    if (level.hasExclusive) {
+        return true;
+    }
+    if (resolution.kind === "exclusive") {
+        return true;
+    }
+    for (const claim of resolution.claims) {
+        if (claim.access === "exclusive") {
+            return true;
+        }
+        if (claim.access === "write") {
+            if (claimConflictsAny(claim, level.writeClaims)) {
+                return true;
+            }
+            if (claimConflictsAny(claim, level.readClaims)) {
+                return true;
+            }
+        }
+        else if (claimConflictsAny(claim, level.writeClaims)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Assign each source-ordered claim entry one level after its latest earlier
+ * conflict. Deterministic and stable: equal inputs (including claim reordering
+ * within a call, which is canonicalized away) always produce equal levels, and
+ * every directed conflict edge advances at least one level.
+ */
+export function assignDagLevels(entries) {
+    const levels = [];
+    for (const entry of entries) {
+        const resolution = entry.resolution;
+        let targetIndex = 0;
+        for (let levelIndex = 0; levelIndex < levels.length; levelIndex++) {
+            if (resolutionConflictsLevel(resolution, levels[levelIndex])) {
+                targetIndex = levelIndex + 1;
+            }
+        }
+        let target = levels[targetIndex];
+        if (!target) {
+            target = { indices: [], writeClaims: [], readClaims: [], hasExclusive: false };
+            levels.push(target);
+        }
+        target.indices.push(entry.sourceIndex);
+        if (resolution.kind === "exclusive" || entry.canonicalClaims.some((claim) => claim.access === "exclusive")) {
+            target.hasExclusive = true;
+        }
+        else {
+            for (const claim of entry.canonicalClaims) {
+                if (claim.access === "write") {
+                    target.writeClaims.push(claim);
+                }
+                else {
+                    target.readClaims.push(claim);
+                }
+            }
+        }
+    }
+    return levels.map((level) => level.indices);
+}
+/**
+ * Split each level into contiguous source-ordered chunks of at most `cap` calls.
+ * Absent/non-finite/non-positive `cap` returns the levels unchanged.
+ */
+export function applyConcurrencyCap(levels, cap) {
+    if (typeof cap !== "number" || !Number.isFinite(cap) || cap <= 0) {
+        return levels.map((level) => level.slice());
+    }
+    const integerCap = Math.max(1, Math.floor(cap));
+    const chunked = [];
+    for (const level of levels) {
+        if (level.length <= integerCap) {
+            chunked.push(level.slice());
+            continue;
+        }
+        for (let start = 0; start < level.length; start += integerCap) {
+            chunked.push(level.slice(start, start + integerCap));
+        }
+    }
+    return chunked;
+}
+/**
+ * Canonical deterministic key over the resolved claim sequence. Uses
+ * `JSON.stringify` of each call's canonicalized claims (fixed property order,
+ * sorted) with an `"E"`/`"C"` discriminator, so it is collision-free for
+ * distinct canonical claim sequences and stable under claim reordering within a
+ * call. Contains no execution timing or outcomes.
+ */
+export function computePlanKey(entries) {
+    let key = "";
+    for (const entry of entries) {
+        if (entry.resolution.kind === "exclusive") {
+            key += "E,";
+        }
+        else {
+            key += `C${JSON.stringify(entry.canonicalClaims)},`;
+        }
+    }
+    return key;
+}
+/**
+ * Schedule a source-ordered tool-call batch into deterministic DAG levels.
+ * Resolves default claims, computes source-directed dependency levels, applies
+ * the optional width cap, and computes the canonical plan key. Pure and
+ * deterministic.
+ */
+export async function scheduleDagLevels(toolCalls, options) {
+    const entries = await resolveBatchClaims(toolCalls, options);
+    const baseLevels = assignDagLevels(entries);
+    const levels = applyConcurrencyCap(baseLevels, options.maxConcurrency);
+    return { levels, planKey: computePlanKey(entries) };
+}
+//# sourceMappingURL=tool-dag-scheduler.js.map

package/dist/tool-dag-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dag-scheduler.js","sourceRoot":"","sources":["../src/tool-dag-scheduler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure, browser-safe deterministic resource-claim DAG scheduler.\n *\n * Given a source-ordered batch of tool calls and their resolved resource\n * claims, this module assigns each call after every earlier call it conflicts\n * with. Levels run in source order; calls inside one level are mutually\n * conflict-free and may execute concurrently. A positive `maxConcurrency`\n * width cap splits each level into deterministic contiguous source-ordered\n * chunks.\n *\n * Determinism contract:\n * - The level assignment is a pure function of the source-ordered input\n *   claims. The canonical example is the head-of-line example\n *   `write x, write x, write y`, which schedules as `[[0, 2], [1]]`: the second\n *   write to `x` is pushed to level 1, but the independent write to `y` is not\n *   blocked and joins level 0.\n * - Reordering claims *within* a single call does not change the plan: claims\n *   are canonicalized (sorted, fixed property order) before comparison.\n * - {@link DagSchedulePlan.planKey} is a canonical serialization of the\n *   resolved claim sequence (canonical claim data only — never execution\n *   timing or outcomes). It is collision-free for distinct canonical claim\n *   sequences.\n *\n * This module uses no platform APIs (no `process`, fs, `node:path`, or timers).\n */\n\nimport {\n\ttype ClaimableToolCall,\n\tcanonicalizeClaims,\n\tclaimsConflict,\n\ttype ResolveToolClaimsOptions,\n\tresolveToolClaimsForCall,\n\ttype ToolClaimResolution,\n\ttype ToolResourceClaim,\n} from \"./tool-resource-claims.ts\";\n\n/** Options for scheduling a batch into DAG levels. */\nexport interface ScheduleDagLevelsOptions extends ResolveToolClaimsOptions {\n\t/**\n\t * Optional positive width cap. When set, each level is split into contiguous\n\t * source-ordered chunks of at most this many calls so a wide conflict-free\n\t * level does not fan out unbounded. Absent, non-finite, or non-positive\n\t * values leave each level whole. Does not affect `planKey`.\n\t */\n\tmaxConcurrency?: number;\n}\n\n/** A scheduled plan: ordered levels of source indices plus a canonical key. */\nexport interface DagSchedulePlan {\n\t/** Levels in execution order; each level holds source indices that may run concurrently. */\n\tlevels: number[][];\n\t/**\n\t * Canonical deterministic key over the resolved claim sequence only (never\n\t * execution timing/outcomes). Stable under claim reordering within a call.\n\t */\n\tplanKey: string;\n}\n\n/** One tool call's resolved claim data, canonicalized for stable planning. */\nexport interface ResolvedClaimEntry {\n\tsourceIndex: number;\n\tresolution: ToolClaimResolution;\n\tcanonicalClaims: ToolResourceClaim[];\n}\n\n/**\n * Resolve and canonicalize claims for a whole batch, preserving source order.\n * Registered custom resolvers are awaited one call at a time in source order,\n * and every resolution completes before a schedule is constructed.\n */\nexport async function resolveBatchClaims(\n\ttoolCalls: readonly ClaimableToolCall[],\n\toptions: ResolveToolClaimsOptions,\n): Promise<ResolvedClaimEntry[]> {\n\tconst entries: ResolvedClaimEntry[] = [];\n\tfor (let index = 0; index < toolCalls.length; index++) {\n\t\tconst resolution = await resolveToolClaimsForCall(toolCalls[index], options);\n\t\tconst canonicalClaims = resolution.kind === \"claims\" ? canonicalizeClaims(resolution.claims) : [];\n\t\tentries.push({ sourceIndex: index, resolution, canonicalClaims });\n\t}\n\treturn entries;\n}\n\ninterface DagLevel {\n\tindices: number[];\n\t/** Write claims currently placed in this level (for fast read-vs-write checks). */\n\twriteClaims: ToolResourceClaim[];\n\t/** Read claims currently placed in this level (for fast write-vs-read checks). */\n\treadClaims: ToolResourceClaim[];\n\t/** True once an exclusive call is placed here; such a level accepts no more. */\n\thasExclusive: boolean;\n}\n\nfunction claimConflictsAny(claim: ToolResourceClaim, candidates: readonly ToolResourceClaim[]): boolean {\n\tfor (const candidate of candidates) {\n\t\tif (claimsConflict(claim, candidate)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * True when `resolution` cannot join `level`. Equivalent to the full pairwise\n * `resolutionsConflict` check, optimized so read/read never triggers a scan:\n * a read claim only needs to scan the level's writes, and a write claim scans\n * both writes and reads. An exclusive resolution, or a level that already holds\n * an exclusive call, conflicts unconditionally.\n */\nfunction resolutionConflictsLevel(resolution: ToolClaimResolution, level: DagLevel): boolean {\n\tif (level.hasExclusive) {\n\t\treturn true;\n\t}\n\tif (resolution.kind === \"exclusive\") {\n\t\treturn true;\n\t}\n\tfor (const claim of resolution.claims) {\n\t\tif (claim.access === \"exclusive\") {\n\t\t\treturn true;\n\t\t}\n\t\tif (claim.access === \"write\") {\n\t\t\tif (claimConflictsAny(claim, level.writeClaims)) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t\tif (claimConflictsAny(claim, level.readClaims)) {\n\t\t\t\treturn true;\n\t\t\t}\n\t\t} else if (claimConflictsAny(claim, level.writeClaims)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * Assign each source-ordered claim entry one level after its latest earlier\n * conflict. Deterministic and stable: equal inputs (including claim reordering\n * within a call, which is canonicalized away) always produce equal levels, and\n * every directed conflict edge advances at least one level.\n */\nexport function assignDagLevels(entries: readonly ResolvedClaimEntry[]): number[][] {\n\tconst levels: DagLevel[] = [];\n\tfor (const entry of entries) {\n\t\tconst resolution = entry.resolution;\n\t\tlet targetIndex = 0;\n\t\tfor (let levelIndex = 0; levelIndex < levels.length; levelIndex++) {\n\t\t\tif (resolutionConflictsLevel(resolution, levels[levelIndex])) {\n\t\t\t\ttargetIndex = levelIndex + 1;\n\t\t\t}\n\t\t}\n\t\tlet target = levels[targetIndex];\n\t\tif (!target) {\n\t\t\ttarget = { indices: [], writeClaims: [], readClaims: [], hasExclusive: false };\n\t\t\tlevels.push(target);\n\t\t}\n\t\ttarget.indices.push(entry.sourceIndex);\n\t\tif (resolution.kind === \"exclusive\" || entry.canonicalClaims.some((claim) => claim.access === \"exclusive\")) {\n\t\t\ttarget.hasExclusive = true;\n\t\t} else {\n\t\t\tfor (const claim of entry.canonicalClaims) {\n\t\t\t\tif (claim.access === \"write\") {\n\t\t\t\t\ttarget.writeClaims.push(claim);\n\t\t\t\t} else {\n\t\t\t\t\ttarget.readClaims.push(claim);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\treturn levels.map((level) => level.indices);\n}\n\n/**\n * Split each level into contiguous source-ordered chunks of at most `cap` calls.\n * Absent/non-finite/non-positive `cap` returns the levels unchanged.\n */\nexport function applyConcurrencyCap(levels: readonly number[][], cap: number | undefined): number[][] {\n\tif (typeof cap !== \"number\" || !Number.isFinite(cap) || cap <= 0) {\n\t\treturn levels.map((level) => level.slice());\n\t}\n\tconst integerCap = Math.max(1, Math.floor(cap));\n\tconst chunked: number[][] = [];\n\tfor (const level of levels) {\n\t\tif (level.length <= integerCap) {\n\t\t\tchunked.push(level.slice());\n\t\t\tcontinue;\n\t\t}\n\t\tfor (let start = 0; start < level.length; start += integerCap) {\n\t\t\tchunked.push(level.slice(start, start + integerCap));\n\t\t}\n\t}\n\treturn chunked;\n}\n\n/**\n * Canonical deterministic key over the resolved claim sequence. Uses\n * `JSON.stringify` of each call's canonicalized claims (fixed property order,\n * sorted) with an `\"E\"`/`\"C\"` discriminator, so it is collision-free for\n * distinct canonical claim sequences and stable under claim reordering within a\n * call. Contains no execution timing or outcomes.\n */\nexport function computePlanKey(entries: readonly ResolvedClaimEntry[]): string {\n\tlet key = \"\";\n\tfor (const entry of entries) {\n\t\tif (entry.resolution.kind === \"exclusive\") {\n\t\t\tkey += \"E,\";\n\t\t} else {\n\t\t\tkey += `C${JSON.stringify(entry.canonicalClaims)},`;\n\t\t}\n\t}\n\treturn key;\n}\n\n/**\n * Schedule a source-ordered tool-call batch into deterministic DAG levels.\n * Resolves default claims, computes source-directed dependency levels, applies\n * the optional width cap, and computes the canonical plan key. Pure and\n * deterministic.\n */\nexport async function scheduleDagLevels(\n\ttoolCalls: readonly ClaimableToolCall[],\n\toptions: ScheduleDagLevelsOptions,\n): Promise<DagSchedulePlan> {\n\tconst entries = await resolveBatchClaims(toolCalls, options);\n\tconst baseLevels = assignDagLevels(entries);\n\tconst levels = applyConcurrencyCap(baseLevels, options.maxConcurrency);\n\treturn { levels, planKey: computePlanKey(entries) };\n}\n"]}

package/dist/tool-execution-boundary.d.ts

@@ -0,0 +1,52 @@
+import type { AssistantMessage } from "omk-ai";
+import type { AgentContext, AgentLoopConfig, AgentToolCall, AgentToolResult, ToolResultEnvelope, ToolTimeoutDisposition } from "./types.ts";
+export { createImmutableJsonSnapshot, createImmutableSnapshot, parseJsonValue } from "./plain-data.ts";
+export type AbortBoundResult<T> = {
+    kind: "completed";
+    value: T;
+} | {
+    kind: "aborted";
+};
+/** Race one async extension boundary against the parent run's abort signal. */
+export declare function awaitWithAbort<T>(start: () => Promise<T> | T, signal: AbortSignal | undefined): Promise<AbortBoundResult<T>>;
+export interface ToolDispositionEnvelope {
+    omk: ToolResultEnvelope;
+}
+/** Build the immutable terminal committed when a tool timeout wins. */
+export declare function createTimeoutToolResult(toolName: string, timeoutMs: number): AgentToolResult<ToolDispositionEnvelope>;
+/** Build the immutable terminal committed when parent abort wins. */
+export declare function createAbortedToolResult(executionStarted: boolean): AgentToolResult<ToolDispositionEnvelope>;
+export interface ExecutedToolCallOutcome {
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+    executionStarted: boolean;
+    terminalDisposition?: ToolTimeoutDisposition;
+    isRealPromiseSettled: () => boolean;
+    commitTerminal: () => void;
+}
+export interface FinalizedToolCallOutcome {
+    toolCall: AgentToolCall;
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+    envelope: ToolResultEnvelope;
+    isRealPromiseSettled?: () => boolean;
+    commitTerminal?: () => void;
+}
+interface FinalizeToolCallOptions {
+    currentContext: AgentContext;
+    assistantMessage: AssistantMessage;
+    prepared: {
+        toolCall: AgentToolCall;
+        args: unknown;
+        timeoutMs: number;
+    };
+    executed: ExecutedToolCallOutcome;
+    afterToolCall: AgentLoopConfig["afterToolCall"];
+    signal: AbortSignal | undefined;
+}
+export declare function createErrorToolResult(message: string): AgentToolResult<unknown>;
+/** Commit a real result or immutable timeout/abort result across the after hook boundary. */
+export declare function finalizeExecutedToolCall(options: FinalizeToolCallOptions): Promise<FinalizedToolCallOutcome>;
+/** Preserve compatibility details while replacing any untrusted `omk` field. */
+export declare function stampToolResultEnvelope(details: unknown, envelope: ToolResultEnvelope): unknown;
+//# sourceMappingURL=tool-execution-boundary.d.ts.map

package/dist/tool-execution-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution-boundary.d.ts","sourceRoot":"","sources":["../src/tool-execution-boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,KAAK,EACX,YAAY,EACZ,eAAe,EACf,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvG,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExF,+EAA+E;AAC/E,wBAAsB,cAAc,CAAC,CAAC,EACrC,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAiB9B;AAED,MAAM,WAAW,uBAAuB;IACvC,GAAG,EAAE,kBAAkB,CAAC;CACxB;AAwBD,uEAAuE;AACvE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,uBAAuB,CAAC,CAarH;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,gBAAgB,EAAE,OAAO,GAAG,eAAe,CAAC,uBAAuB,CAAC,CAY3G;AAED,MAAM,WAAW,uBAAuB;IACvC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;IAC7C,oBAAoB,EAAE,MAAM,OAAO,CAAC;IACpC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,UAAU,uBAAuB;IAChC,cAAc,EAAE,YAAY,CAAC;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,QAAQ,EAAE;QAAE,QAAQ,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,QAAQ,EAAE,uBAAuB,CAAC;IAClC,aAAa,EAAE,eAAe,CAAC,eAAe,CAAC,CAAC;IAChD,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CAChC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAE/E;AAED,6FAA6F;AAC7F,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA8FlH;AAQD,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAO/F","sourcesContent":["import type { AssistantMessage } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"./plain-data.ts\";\nimport type {\n\tAgentContext,\n\tAgentLoopConfig,\n\tAgentToolCall,\n\tAgentToolResult,\n\tToolResultEnvelope,\n\tToolTimeoutDisposition,\n} from \"./types.ts\";\nimport { createToolResultEnvelope, isToolResultEnvelope } from \"./types.ts\";\n\nexport { createImmutableJsonSnapshot, createImmutableSnapshot, parseJsonValue } from \"./plain-data.ts\";\n\nexport type AbortBoundResult<T> = { kind: \"completed\"; value: T } | { kind: \"aborted\" };\n\n/** Race one async extension boundary against the parent run's abort signal. */\nexport async function awaitWithAbort<T>(\n\tstart: () => Promise<T> | T,\n\tsignal: AbortSignal | undefined,\n): Promise<AbortBoundResult<T>> {\n\tif (signal?.aborted) return { kind: \"aborted\" };\n\tif (signal === undefined) return { kind: \"completed\", value: await start() };\n\n\tlet notifyAbort: (() => void) | undefined;\n\tconst aborted = new Promise<AbortBoundResult<T>>((resolve) => {\n\t\tnotifyAbort = () => resolve({ kind: \"aborted\" });\n\t\tsignal.addEventListener(\"abort\", notifyAbort, { once: true });\n\t});\n\tif (signal.aborted) notifyAbort?.();\n\n\ttry {\n\t\tconst operation = Promise.resolve(start()).then((value): AbortBoundResult<T> => ({ kind: \"completed\", value }));\n\t\treturn await Promise.race([operation, aborted]);\n\t} finally {\n\t\tif (notifyAbort !== undefined) signal.removeEventListener(\"abort\", notifyAbort);\n\t}\n}\n\nexport interface ToolDispositionEnvelope {\n\tomk: ToolResultEnvelope;\n}\n\nfunction createValidatedToolResultSnapshot(result: AgentToolResult<unknown>): AgentToolResult<unknown> {\n\tconst snapshot = createImmutableSnapshot(result);\n\tif (!Array.isArray(snapshot.content)) throw new TypeError(\"Tool result content must be an array\");\n\tfor (const block of snapshot.content) {\n\t\tif (typeof block !== \"object\" || block === null) throw new TypeError(\"Invalid tool result content block\");\n\t\tconst type = Reflect.get(block, \"type\");\n\t\tif (type === \"text\" && typeof Reflect.get(block, \"text\") === \"string\") continue;\n\t\tif (\n\t\t\ttype === \"image\" &&\n\t\t\ttypeof Reflect.get(block, \"data\") === \"string\" &&\n\t\t\ttypeof Reflect.get(block, \"mimeType\") === \"string\"\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tthrow new TypeError(\"Invalid tool result content block\");\n\t}\n\tif (snapshot.terminate !== undefined && typeof snapshot.terminate !== \"boolean\") {\n\t\tthrow new TypeError(\"Tool result terminate must be a boolean\");\n\t}\n\treturn snapshot;\n}\n\n/** Build the immutable terminal committed when a tool timeout wins. */\nexport function createTimeoutToolResult(toolName: string, timeoutMs: number): AgentToolResult<ToolDispositionEnvelope> {\n\treturn createImmutableSnapshot({\n\t\tcontent: [{ type: \"text\", text: `Tool \"${toolName}\" timed out after ${timeoutMs}ms and was terminated.` }],\n\t\tdetails: {\n\t\t\tomk: createToolResultEnvelope({\n\t\t\t\tsynthetic: true,\n\t\t\t\tdisposition: \"timeout\",\n\t\t\t\treason: `Tool \"${toolName}\" timed out after ${timeoutMs}ms`,\n\t\t\t\ttimeoutMs,\n\t\t\t\texecutionStarted: true,\n\t\t\t}),\n\t\t},\n\t});\n}\n\n/** Build the immutable terminal committed when parent abort wins. */\nexport function createAbortedToolResult(executionStarted: boolean): AgentToolResult<ToolDispositionEnvelope> {\n\treturn createImmutableSnapshot({\n\t\tcontent: [{ type: \"text\", text: \"Operation aborted\" }],\n\t\tdetails: {\n\t\t\tomk: createToolResultEnvelope({\n\t\t\t\tsynthetic: true,\n\t\t\t\tdisposition: \"aborted\",\n\t\t\t\treason: \"Operation aborted\",\n\t\t\t\texecutionStarted,\n\t\t\t}),\n\t\t},\n\t});\n}\n\nexport interface ExecutedToolCallOutcome {\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n\texecutionStarted: boolean;\n\tterminalDisposition?: ToolTimeoutDisposition;\n\tisRealPromiseSettled: () => boolean;\n\tcommitTerminal: () => void;\n}\n\nexport interface FinalizedToolCallOutcome {\n\ttoolCall: AgentToolCall;\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n\tenvelope: ToolResultEnvelope;\n\tisRealPromiseSettled?: () => boolean;\n\tcommitTerminal?: () => void;\n}\n\ninterface FinalizeToolCallOptions {\n\tcurrentContext: AgentContext;\n\tassistantMessage: AssistantMessage;\n\tprepared: { toolCall: AgentToolCall; args: unknown; timeoutMs: number };\n\texecuted: ExecutedToolCallOutcome;\n\tafterToolCall: AgentLoopConfig[\"afterToolCall\"];\n\tsignal: AbortSignal | undefined;\n}\n\nexport function createErrorToolResult(message: string): AgentToolResult<unknown> {\n\treturn createImmutableSnapshot({ content: [{ type: \"text\", text: message }], details: {} });\n}\n\n/** Commit a real result or immutable timeout/abort result across the after hook boundary. */\nexport async function finalizeExecutedToolCall(options: FinalizeToolCallOptions): Promise<FinalizedToolCallOutcome> {\n\tconst { currentContext, assistantMessage, prepared, executed, afterToolCall, signal } = options;\n\tlet result = executed.result;\n\tlet isError = executed.isError;\n\tlet syntheticFailure = false;\n\tlet terminalDisposition = executed.terminalDisposition;\n\n\ttry {\n\t\tresult = createValidatedToolResultSnapshot(result);\n\t} catch (error) {\n\t\tresult = createErrorToolResult(`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`);\n\t\tisError = true;\n\t\tsyntheticFailure = true;\n\t}\n\n\tif (terminalDisposition === undefined && signal?.aborted) {\n\t\tterminalDisposition = \"aborted\";\n\t\tresult = createAbortedToolResult(executed.executionStarted);\n\t\tisError = true;\n\t}\n\tif (terminalDisposition === undefined && afterToolCall && !syntheticFailure) {\n\t\ttry {\n\t\t\tconst bounded = await awaitWithAbort(\n\t\t\t\t() =>\n\t\t\t\t\tafterToolCall(\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tassistantMessage,\n\t\t\t\t\t\t\ttoolCall: prepared.toolCall,\n\t\t\t\t\t\t\targs: prepared.args,\n\t\t\t\t\t\t\tresult,\n\t\t\t\t\t\t\tisError,\n\t\t\t\t\t\t\tcontext: currentContext,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t),\n\t\t\t\tsignal,\n\t\t\t);\n\t\t\tif (bounded.kind === \"aborted\" || signal?.aborted) {\n\t\t\t\tterminalDisposition = \"aborted\";\n\t\t\t\tresult = createAbortedToolResult(executed.executionStarted);\n\t\t\t\tisError = true;\n\t\t\t} else if (bounded.value) {\n\t\t\t\tresult = {\n\t\t\t\t\tcontent: bounded.value.content ?? result.content,\n\t\t\t\t\tdetails: Object.hasOwn(bounded.value, \"details\") ? bounded.value.details : result.details,\n\t\t\t\t\tterminate: bounded.value.terminate ?? result.terminate,\n\t\t\t\t};\n\t\t\t\tisError = bounded.value.isError ?? isError;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tresult = createErrorToolResult(error instanceof Error ? error.message : String(error));\n\t\t\tisError = true;\n\t\t\tsyntheticFailure = true;\n\t\t}\n\t}\n\n\tif (terminalDisposition === undefined) {\n\t\ttry {\n\t\t\tresult = createValidatedToolResultSnapshot(result);\n\t\t} catch (error) {\n\t\t\tresult = createErrorToolResult(\n\t\t\t\t`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t\tisError = true;\n\t\t\tsyntheticFailure = true;\n\t\t}\n\t} else {\n\t\tisError = true;\n\t}\n\tconst envelope =\n\t\tterminalDisposition !== undefined\n\t\t\t? createToolResultEnvelope({\n\t\t\t\t\tdisposition: terminalDisposition,\n\t\t\t\t\tsynthetic: true,\n\t\t\t\t\texecutionStarted: executed.executionStarted,\n\t\t\t\t\treason:\n\t\t\t\t\t\tterminalDisposition === \"timeout\"\n\t\t\t\t\t\t\t? `Tool \"${prepared.toolCall.name}\" timed out after ${prepared.timeoutMs}ms`\n\t\t\t\t\t\t\t: \"Operation aborted\",\n\t\t\t\t\t...(terminalDisposition === \"timeout\" ? { timeoutMs: prepared.timeoutMs } : {}),\n\t\t\t\t})\n\t\t\t: createToolResultEnvelope({\n\t\t\t\t\tdisposition: isError ? \"failed\" : \"completed\",\n\t\t\t\t\tsynthetic: syntheticFailure,\n\t\t\t\t\texecutionStarted: executed.executionStarted,\n\t\t\t\t});\n\treturn {\n\t\ttoolCall: prepared.toolCall,\n\t\tresult,\n\t\tisError,\n\t\tenvelope,\n\t\tisRealPromiseSettled: executed.isRealPromiseSettled,\n\t\tcommitTerminal: executed.commitTerminal,\n\t};\n}\n\nfunction isPlainDetails(details: unknown): details is Record<string, unknown> {\n\tif (typeof details !== \"object\" || details === null || Array.isArray(details)) return false;\n\tconst prototype = Object.getPrototypeOf(details);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\n/** Preserve compatibility details while replacing any untrusted `omk` field. */\nexport function stampToolResultEnvelope(details: unknown, envelope: ToolResultEnvelope): unknown {\n\tif (!isToolResultEnvelope(envelope)) throw new TypeError(\"Refusing to persist an invalid tool-result/v2 envelope\");\n\tif (details === undefined) return { omk: envelope };\n\tif (!isPlainDetails(details)) return { originalDetails: details, omk: envelope };\n\tconst preserved = { ...details };\n\tdelete preserved.omk;\n\treturn { ...preserved, omk: envelope };\n}\n"]}

package/dist/tool-execution-boundary.js

@@ -0,0 +1,185 @@
+import { createImmutableSnapshot } from "./plain-data.js";
+import { createToolResultEnvelope, isToolResultEnvelope } from "./types.js";
+export { createImmutableJsonSnapshot, createImmutableSnapshot, parseJsonValue } from "./plain-data.js";
+/** Race one async extension boundary against the parent run's abort signal. */
+export async function awaitWithAbort(start, signal) {
+    if (signal?.aborted)
+        return { kind: "aborted" };
+    if (signal === undefined)
+        return { kind: "completed", value: await start() };
+    let notifyAbort;
+    const aborted = new Promise((resolve) => {
+        notifyAbort = () => resolve({ kind: "aborted" });
+        signal.addEventListener("abort", notifyAbort, { once: true });
+    });
+    if (signal.aborted)
+        notifyAbort?.();
+    try {
+        const operation = Promise.resolve(start()).then((value) => ({ kind: "completed", value }));
+        return await Promise.race([operation, aborted]);
+    }
+    finally {
+        if (notifyAbort !== undefined)
+            signal.removeEventListener("abort", notifyAbort);
+    }
+}
+function createValidatedToolResultSnapshot(result) {
+    const snapshot = createImmutableSnapshot(result);
+    if (!Array.isArray(snapshot.content))
+        throw new TypeError("Tool result content must be an array");
+    for (const block of snapshot.content) {
+        if (typeof block !== "object" || block === null)
+            throw new TypeError("Invalid tool result content block");
+        const type = Reflect.get(block, "type");
+        if (type === "text" && typeof Reflect.get(block, "text") === "string")
+            continue;
+        if (type === "image" &&
+            typeof Reflect.get(block, "data") === "string" &&
+            typeof Reflect.get(block, "mimeType") === "string") {
+            continue;
+        }
+        throw new TypeError("Invalid tool result content block");
+    }
+    if (snapshot.terminate !== undefined && typeof snapshot.terminate !== "boolean") {
+        throw new TypeError("Tool result terminate must be a boolean");
+    }
+    return snapshot;
+}
+/** Build the immutable terminal committed when a tool timeout wins. */
+export function createTimeoutToolResult(toolName, timeoutMs) {
+    return createImmutableSnapshot({
+        content: [{ type: "text", text: `Tool "${toolName}" timed out after ${timeoutMs}ms and was terminated.` }],
+        details: {
+            omk: createToolResultEnvelope({
+                synthetic: true,
+                disposition: "timeout",
+                reason: `Tool "${toolName}" timed out after ${timeoutMs}ms`,
+                timeoutMs,
+                executionStarted: true,
+            }),
+        },
+    });
+}
+/** Build the immutable terminal committed when parent abort wins. */
+export function createAbortedToolResult(executionStarted) {
+    return createImmutableSnapshot({
+        content: [{ type: "text", text: "Operation aborted" }],
+        details: {
+            omk: createToolResultEnvelope({
+                synthetic: true,
+                disposition: "aborted",
+                reason: "Operation aborted",
+                executionStarted,
+            }),
+        },
+    });
+}
+export function createErrorToolResult(message) {
+    return createImmutableSnapshot({ content: [{ type: "text", text: message }], details: {} });
+}
+/** Commit a real result or immutable timeout/abort result across the after hook boundary. */
+export async function finalizeExecutedToolCall(options) {
+    const { currentContext, assistantMessage, prepared, executed, afterToolCall, signal } = options;
+    let result = executed.result;
+    let isError = executed.isError;
+    let syntheticFailure = false;
+    let terminalDisposition = executed.terminalDisposition;
+    try {
+        result = createValidatedToolResultSnapshot(result);
+    }
+    catch (error) {
+        result = createErrorToolResult(`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`);
+        isError = true;
+        syntheticFailure = true;
+    }
+    if (terminalDisposition === undefined && signal?.aborted) {
+        terminalDisposition = "aborted";
+        result = createAbortedToolResult(executed.executionStarted);
+        isError = true;
+    }
+    if (terminalDisposition === undefined && afterToolCall && !syntheticFailure) {
+        try {
+            const bounded = await awaitWithAbort(() => afterToolCall({
+                assistantMessage,
+                toolCall: prepared.toolCall,
+                args: prepared.args,
+                result,
+                isError,
+                context: currentContext,
+            }, signal), signal);
+            if (bounded.kind === "aborted" || signal?.aborted) {
+                terminalDisposition = "aborted";
+                result = createAbortedToolResult(executed.executionStarted);
+                isError = true;
+            }
+            else if (bounded.value) {
+                result = {
+                    content: bounded.value.content ?? result.content,
+                    details: Object.hasOwn(bounded.value, "details") ? bounded.value.details : result.details,
+                    terminate: bounded.value.terminate ?? result.terminate,
+                };
+                isError = bounded.value.isError ?? isError;
+            }
+        }
+        catch (error) {
+            result = createErrorToolResult(error instanceof Error ? error.message : String(error));
+            isError = true;
+            syntheticFailure = true;
+        }
+    }
+    if (terminalDisposition === undefined) {
+        try {
+            result = createValidatedToolResultSnapshot(result);
+        }
+        catch (error) {
+            result = createErrorToolResult(`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`);
+            isError = true;
+            syntheticFailure = true;
+        }
+    }
+    else {
+        isError = true;
+    }
+    const envelope = terminalDisposition !== undefined
+        ? createToolResultEnvelope({
+            disposition: terminalDisposition,
+            synthetic: true,
+            executionStarted: executed.executionStarted,
+            reason: terminalDisposition === "timeout"
+                ? `Tool "${prepared.toolCall.name}" timed out after ${prepared.timeoutMs}ms`
+                : "Operation aborted",
+            ...(terminalDisposition === "timeout" ? { timeoutMs: prepared.timeoutMs } : {}),
+        })
+        : createToolResultEnvelope({
+            disposition: isError ? "failed" : "completed",
+            synthetic: syntheticFailure,
+            executionStarted: executed.executionStarted,
+        });
+    return {
+        toolCall: prepared.toolCall,
+        result,
+        isError,
+        envelope,
+        isRealPromiseSettled: executed.isRealPromiseSettled,
+        commitTerminal: executed.commitTerminal,
+    };
+}
+function isPlainDetails(details) {
+    if (typeof details !== "object" || details === null || Array.isArray(details))
+        return false;
+    const prototype = Object.getPrototypeOf(details);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Preserve compatibility details while replacing any untrusted `omk` field. */
+export function stampToolResultEnvelope(details, envelope) {
+    if (!isToolResultEnvelope(envelope))
+        throw new TypeError("Refusing to persist an invalid tool-result/v2 envelope");
+    if (details === undefined)
+        return { omk: envelope };
+    if (!isPlainDetails(details))
+        return { originalDetails: details, omk: envelope };
+    const preserved = { ...details };
+    delete preserved.omk;
+    return { ...preserved, omk: envelope };
+}
+//# sourceMappingURL=tool-execution-boundary.js.map

package/dist/tool-execution-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution-boundary.js","sourceRoot":"","sources":["../src/tool-execution-boundary.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"./plain-data.ts\";\nimport type {\n\tAgentContext,\n\tAgentLoopConfig,\n\tAgentToolCall,\n\tAgentToolResult,\n\tToolResultEnvelope,\n\tToolTimeoutDisposition,\n} from \"./types.ts\";\nimport { createToolResultEnvelope, isToolResultEnvelope } from \"./types.ts\";\n\nexport { createImmutableJsonSnapshot, createImmutableSnapshot, parseJsonValue } from \"./plain-data.ts\";\n\nexport type AbortBoundResult<T> = { kind: \"completed\"; value: T } | { kind: \"aborted\" };\n\n/** Race one async extension boundary against the parent run's abort signal. */\nexport async function awaitWithAbort<T>(\n\tstart: () => Promise<T> | T,\n\tsignal: AbortSignal | undefined,\n): Promise<AbortBoundResult<T>> {\n\tif (signal?.aborted) return { kind: \"aborted\" };\n\tif (signal === undefined) return { kind: \"completed\", value: await start() };\n\n\tlet notifyAbort: (() => void) | undefined;\n\tconst aborted = new Promise<AbortBoundResult<T>>((resolve) => {\n\t\tnotifyAbort = () => resolve({ kind: \"aborted\" });\n\t\tsignal.addEventListener(\"abort\", notifyAbort, { once: true });\n\t});\n\tif (signal.aborted) notifyAbort?.();\n\n\ttry {\n\t\tconst operation = Promise.resolve(start()).then((value): AbortBoundResult<T> => ({ kind: \"completed\", value }));\n\t\treturn await Promise.race([operation, aborted]);\n\t} finally {\n\t\tif (notifyAbort !== undefined) signal.removeEventListener(\"abort\", notifyAbort);\n\t}\n}\n\nexport interface ToolDispositionEnvelope {\n\tomk: ToolResultEnvelope;\n}\n\nfunction createValidatedToolResultSnapshot(result: AgentToolResult<unknown>): AgentToolResult<unknown> {\n\tconst snapshot = createImmutableSnapshot(result);\n\tif (!Array.isArray(snapshot.content)) throw new TypeError(\"Tool result content must be an array\");\n\tfor (const block of snapshot.content) {\n\t\tif (typeof block !== \"object\" || block === null) throw new TypeError(\"Invalid tool result content block\");\n\t\tconst type = Reflect.get(block, \"type\");\n\t\tif (type === \"text\" && typeof Reflect.get(block, \"text\") === \"string\") continue;\n\t\tif (\n\t\t\ttype === \"image\" &&\n\t\t\ttypeof Reflect.get(block, \"data\") === \"string\" &&\n\t\t\ttypeof Reflect.get(block, \"mimeType\") === \"string\"\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tthrow new TypeError(\"Invalid tool result content block\");\n\t}\n\tif (snapshot.terminate !== undefined && typeof snapshot.terminate !== \"boolean\") {\n\t\tthrow new TypeError(\"Tool result terminate must be a boolean\");\n\t}\n\treturn snapshot;\n}\n\n/** Build the immutable terminal committed when a tool timeout wins. */\nexport function createTimeoutToolResult(toolName: string, timeoutMs: number): AgentToolResult<ToolDispositionEnvelope> {\n\treturn createImmutableSnapshot({\n\t\tcontent: [{ type: \"text\", text: `Tool \"${toolName}\" timed out after ${timeoutMs}ms and was terminated.` }],\n\t\tdetails: {\n\t\t\tomk: createToolResultEnvelope({\n\t\t\t\tsynthetic: true,\n\t\t\t\tdisposition: \"timeout\",\n\t\t\t\treason: `Tool \"${toolName}\" timed out after ${timeoutMs}ms`,\n\t\t\t\ttimeoutMs,\n\t\t\t\texecutionStarted: true,\n\t\t\t}),\n\t\t},\n\t});\n}\n\n/** Build the immutable terminal committed when parent abort wins. */\nexport function createAbortedToolResult(executionStarted: boolean): AgentToolResult<ToolDispositionEnvelope> {\n\treturn createImmutableSnapshot({\n\t\tcontent: [{ type: \"text\", text: \"Operation aborted\" }],\n\t\tdetails: {\n\t\t\tomk: createToolResultEnvelope({\n\t\t\t\tsynthetic: true,\n\t\t\t\tdisposition: \"aborted\",\n\t\t\t\treason: \"Operation aborted\",\n\t\t\t\texecutionStarted,\n\t\t\t}),\n\t\t},\n\t});\n}\n\nexport interface ExecutedToolCallOutcome {\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n\texecutionStarted: boolean;\n\tterminalDisposition?: ToolTimeoutDisposition;\n\tisRealPromiseSettled: () => boolean;\n\tcommitTerminal: () => void;\n}\n\nexport interface FinalizedToolCallOutcome {\n\ttoolCall: AgentToolCall;\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n\tenvelope: ToolResultEnvelope;\n\tisRealPromiseSettled?: () => boolean;\n\tcommitTerminal?: () => void;\n}\n\ninterface FinalizeToolCallOptions {\n\tcurrentContext: AgentContext;\n\tassistantMessage: AssistantMessage;\n\tprepared: { toolCall: AgentToolCall; args: unknown; timeoutMs: number };\n\texecuted: ExecutedToolCallOutcome;\n\tafterToolCall: AgentLoopConfig[\"afterToolCall\"];\n\tsignal: AbortSignal | undefined;\n}\n\nexport function createErrorToolResult(message: string): AgentToolResult<unknown> {\n\treturn createImmutableSnapshot({ content: [{ type: \"text\", text: message }], details: {} });\n}\n\n/** Commit a real result or immutable timeout/abort result across the after hook boundary. */\nexport async function finalizeExecutedToolCall(options: FinalizeToolCallOptions): Promise<FinalizedToolCallOutcome> {\n\tconst { currentContext, assistantMessage, prepared, executed, afterToolCall, signal } = options;\n\tlet result = executed.result;\n\tlet isError = executed.isError;\n\tlet syntheticFailure = false;\n\tlet terminalDisposition = executed.terminalDisposition;\n\n\ttry {\n\t\tresult = createValidatedToolResultSnapshot(result);\n\t} catch (error) {\n\t\tresult = createErrorToolResult(`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`);\n\t\tisError = true;\n\t\tsyntheticFailure = true;\n\t}\n\n\tif (terminalDisposition === undefined && signal?.aborted) {\n\t\tterminalDisposition = \"aborted\";\n\t\tresult = createAbortedToolResult(executed.executionStarted);\n\t\tisError = true;\n\t}\n\tif (terminalDisposition === undefined && afterToolCall && !syntheticFailure) {\n\t\ttry {\n\t\t\tconst bounded = await awaitWithAbort(\n\t\t\t\t() =>\n\t\t\t\t\tafterToolCall(\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tassistantMessage,\n\t\t\t\t\t\t\ttoolCall: prepared.toolCall,\n\t\t\t\t\t\t\targs: prepared.args,\n\t\t\t\t\t\t\tresult,\n\t\t\t\t\t\t\tisError,\n\t\t\t\t\t\t\tcontext: currentContext,\n\t\t\t\t\t\t},\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t),\n\t\t\t\tsignal,\n\t\t\t);\n\t\t\tif (bounded.kind === \"aborted\" || signal?.aborted) {\n\t\t\t\tterminalDisposition = \"aborted\";\n\t\t\t\tresult = createAbortedToolResult(executed.executionStarted);\n\t\t\t\tisError = true;\n\t\t\t} else if (bounded.value) {\n\t\t\t\tresult = {\n\t\t\t\t\tcontent: bounded.value.content ?? result.content,\n\t\t\t\t\tdetails: Object.hasOwn(bounded.value, \"details\") ? bounded.value.details : result.details,\n\t\t\t\t\tterminate: bounded.value.terminate ?? result.terminate,\n\t\t\t\t};\n\t\t\t\tisError = bounded.value.isError ?? isError;\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tresult = createErrorToolResult(error instanceof Error ? error.message : String(error));\n\t\t\tisError = true;\n\t\t\tsyntheticFailure = true;\n\t\t}\n\t}\n\n\tif (terminalDisposition === undefined) {\n\t\ttry {\n\t\t\tresult = createValidatedToolResultSnapshot(result);\n\t\t} catch (error) {\n\t\t\tresult = createErrorToolResult(\n\t\t\t\t`Invalid tool result: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t);\n\t\t\tisError = true;\n\t\t\tsyntheticFailure = true;\n\t\t}\n\t} else {\n\t\tisError = true;\n\t}\n\tconst envelope =\n\t\tterminalDisposition !== undefined\n\t\t\t? createToolResultEnvelope({\n\t\t\t\t\tdisposition: terminalDisposition,\n\t\t\t\t\tsynthetic: true,\n\t\t\t\t\texecutionStarted: executed.executionStarted,\n\t\t\t\t\treason:\n\t\t\t\t\t\tterminalDisposition === \"timeout\"\n\t\t\t\t\t\t\t? `Tool \"${prepared.toolCall.name}\" timed out after ${prepared.timeoutMs}ms`\n\t\t\t\t\t\t\t: \"Operation aborted\",\n\t\t\t\t\t...(terminalDisposition === \"timeout\" ? { timeoutMs: prepared.timeoutMs } : {}),\n\t\t\t\t})\n\t\t\t: createToolResultEnvelope({\n\t\t\t\t\tdisposition: isError ? \"failed\" : \"completed\",\n\t\t\t\t\tsynthetic: syntheticFailure,\n\t\t\t\t\texecutionStarted: executed.executionStarted,\n\t\t\t\t});\n\treturn {\n\t\ttoolCall: prepared.toolCall,\n\t\tresult,\n\t\tisError,\n\t\tenvelope,\n\t\tisRealPromiseSettled: executed.isRealPromiseSettled,\n\t\tcommitTerminal: executed.commitTerminal,\n\t};\n}\n\nfunction isPlainDetails(details: unknown): details is Record<string, unknown> {\n\tif (typeof details !== \"object\" || details === null || Array.isArray(details)) return false;\n\tconst prototype = Object.getPrototypeOf(details);\n\treturn prototype === Object.prototype || prototype === null;\n}\n\n/** Preserve compatibility details while replacing any untrusted `omk` field. */\nexport function stampToolResultEnvelope(details: unknown, envelope: ToolResultEnvelope): unknown {\n\tif (!isToolResultEnvelope(envelope)) throw new TypeError(\"Refusing to persist an invalid tool-result/v2 envelope\");\n\tif (details === undefined) return { omk: envelope };\n\tif (!isPlainDetails(details)) return { originalDetails: details, omk: envelope };\n\tconst preserved = { ...details };\n\tdelete preserved.omk;\n\treturn { ...preserved, omk: envelope };\n}\n"]}

package/dist/tool-resource-claims.d.ts

@@ -0,0 +1,31 @@
+/** Browser-safe resource claims for the opt-in dag-v2 scheduler. */
+import type { ToolParallelPolicy } from "./parallel-tool-batch.ts";
+import type { AgentTool, ResourceKeyResolver, ToolResourceClaim } from "./types.ts";
+export { resolvePathClaimKey, resolveToolClaims } from "./builtin-tool-resource-claims.ts";
+export type { ResourceAccess, ToolResourceAccess, ToolResourceClaim, ToolResourceClaims, ToolResourceClaimsContext, } from "./types.ts";
+export type ToolClaimResolution = {
+    kind: "exclusive";
+} | {
+    kind: "claims";
+    claims: ToolResourceClaim[];
+};
+export interface ClaimableToolCall {
+    id?: string;
+    name: string;
+    arguments: unknown;
+}
+export type RegisteredToolClaimDefinition = Pick<AgentTool, "name" | "executionMode" | "resourceClaims">;
+export interface ResolveToolClaimsOptions {
+    cwd: string;
+    toolPolicies?: ReadonlyMap<string, ToolParallelPolicy>;
+    registeredTools?: readonly RegisteredToolClaimDefinition[];
+    strictExtensionClaims?: boolean;
+    resourceKeyResolver?: ResourceKeyResolver;
+}
+/** Resolve one call, failing malformed or rejected extension claims closed. */
+export declare function resolveToolClaimsForCall(toolCall: ClaimableToolCall, options: ResolveToolClaimsOptions): Promise<ToolClaimResolution>;
+export declare function compareClaims(left: ToolResourceClaim, right: ToolResourceClaim): number;
+export declare function canonicalizeClaims(claims: readonly ToolResourceClaim[]): ToolResourceClaim[];
+export declare function claimsConflict(left: ToolResourceClaim, right: ToolResourceClaim): boolean;
+export declare function resolutionsConflict(left: ToolClaimResolution, right: ToolClaimResolution): boolean;
+//# sourceMappingURL=tool-resource-claims.d.ts.map

package/dist/tool-resource-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-resource-claims.d.ts","sourceRoot":"","sources":["../src/tool-resource-claims.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAYpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAkB,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpG,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,YAAY,EACX,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAAC;AAE1G,MAAM,WAAW,iBAAiB;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,gBAAgB,CAAC,CAAC;AAEzG,MAAM,WAAW,wBAAwB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACvD,eAAe,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IAC3D,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAkCD,+EAA+E;AAC/E,wBAAsB,wBAAwB,CAC7C,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,wBAAwB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAkC9B;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAWvF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAe5F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CASzF;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAQlG","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"]}