omk-agent-core 0.90.7 → 0.90.9

package/dist/tool-transcript-integrity.js

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

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

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

package/dist/types.d.ts

@@ -19,6 +19,20 @@ export type StreamFn = (...args: Parameters<typeof streamSimple>) => ReturnType<
  *   while tool-result message artifacts are emitted later in assistant source order.
  */
 export type ToolExecutionMode = "sequential" | "parallel";
+/**
+ * Tool-call scheduler selection for a single assistant turn's tool batch.
+ *
+ * - `"waves-v1"` (default): the original contiguous-wave scheduler
+ *   (`partitionToolBatchWaves`). Established behavior and the rollback target.
+ * - `"dag-v2"`: the deterministic resource-claim DAG scheduler
+ *   (`scheduleDagLevels`). Active only when explicitly selected. It resolves
+ *   per-call resource claims and groups conflict-free calls into source-index
+ *   DAG levels so a conflicting call no longer head-of-line-blocks independent
+ *   later calls (e.g. `write x, write x, write y` schedules as `[[0, 2], [1]]`).
+ *   Final tool results are buffered globally and emitted in original source
+ *   order.
+ */
+export type ToolSchedulerKind = "waves-v1" | "dag-v2";
 /**
  * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
  *
@@ -220,17 +234,69 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Default: "parallel"
      */
     toolExecution?: ToolExecutionMode;
+    /**
+     * Default per-tool execution timeout in milliseconds applied to every tool
+     * call that does not resolve a more specific timeout.
+     *
+     * This is deliberately named to avoid colliding with the inherited
+     * {@link SimpleStreamOptions.timeoutMs} (the provider request timeout).
+     * Absent, non-finite, or non-positive values disable the tool timeout and
+     * preserve the current unbounded execution behavior.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Per-tool-name execution timeouts in milliseconds. An entry here overrides
+     * {@link toolTimeoutMs} for that tool name, and is itself overridden by a
+     * per-tool {@link AgentTool.timeoutMs}. Absent, non-finite, or non-positive
+     * entries disable the timeout for that name.
+     */
+    toolTimeouts?: Record<string, number>;
+    /**
+     * Tool-call scheduler. Defaults to `"waves-v1"` (the established
+     * contiguous-wave scheduler). Set to `"dag-v2"` to opt into the
+     * deterministic resource-claim DAG scheduler. The v1 path and its exports
+     * are unchanged when this is unset or `"waves-v1"`.
+     */
+    toolScheduler?: ToolSchedulerKind;
+    /**
+     * dag-v2 only. Optional positive width cap. When set, each DAG level is
+     * split into deterministic contiguous chunks of at most this many calls
+     * (preserving source order) so a wide conflict-free level does not fan out
+     * unbounded. Absent, non-finite, or non-positive values leave each level
+     * whole. No effect on the default `"waves-v1"` scheduler.
+     */
+    maxToolConcurrency?: number;
+    /**
+     * dag-v2 only. When `false` (default), an extension/custom tool with
+     * `executionMode: "parallel"` and no resource claims is treated as freely
+     * parallel (compatibility). When `true`, such tools are treated as
+     * exclusive (run alone). Unknown tools and bash are always exclusive
+     * regardless of this flag. No effect on the default `"waves-v1"` scheduler.
+     */
+    strictExtensionClaims?: boolean;
     /** Working directory for path-scoped parallel tool batch checks (read/write/edit). */
     cwd?: string;
+    /**
+     * dag-v2 only. Optional platform identity resolver used to detect
+     * symlink/hardlink/drive/UNC path aliases when scheduling resource claims.
+     * Absent, the scheduler uses lexical canonicalization only (browser-safe).
+     * Resolver failure isolates the call as exclusive (fail closed).
+     */
+    resourceKeyResolver?: ResourceKeyResolver;
+    /**
+     * Execution policy defaults for every tool call in this run. Only
+     * `lateSettlement` is consumed today; it defaults to `"audit"`.
+     */
+    toolExecutionPolicy?: Partial<ToolExecutionPolicy>;
     /**
      * Called before a tool is executed, after arguments have been validated.
      *
      * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.
-     * The hook receives the agent abort signal and is responsible for honoring it.
+     * The runtime bounds the hook by the parent abort signal and ignores a late settlement.
      */
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
     /**
-     * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
+     * Called after execution but skipped for an immutable committed timeout/abort terminal.
      *
      * Return an `AfterToolCallResult` to override parts of the executed tool result:
      * - `content` replaces the full content array
@@ -239,7 +305,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * - `terminate` replaces the early-termination hint
      *
      * Any omitted fields keep their original values. No deep merge is performed.
-     * The hook receives the agent abort signal and is responsible for honoring it.
+     * The runtime bounds the hook by the parent abort signal and ignores a late settlement.
      */
     afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
 }
@@ -317,6 +383,45 @@ export interface AgentToolResult<T> {
 }
 /** Callback used by tools to stream partial execution updates. */
 export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+/** Access mode used by a tool resource claim. */
+export type ResourceAccess = "read" | "write" | "exclusive";
+/** Access modes valid for path claims and built-in read/write resources. */
+export type ToolResourceAccess = Extract<ResourceAccess, "read" | "write">;
+/**
+ * A resource touched by one tool call.
+ *
+ * Path claims conflict on lexical parent/child overlap. Other claim kinds
+ * conflict when their keys are equal. `exclusive` access conflicts with every
+ * call, regardless of resource kind or key.
+ */
+export type ToolResourceClaim = {
+    kind: "path";
+    key: string;
+    access: ToolResourceAccess;
+    /** Canonical real-path identity (symlink-resolved), when a resolver is injected. */
+    realKey?: string;
+    /** `dev:ino` identity for an existing file, when a resolver is injected. */
+    inodeKey?: string;
+} | {
+    kind: "session" | "terminal" | "network" | "global";
+    key: string;
+    access: ResourceAccess;
+};
+/**
+ * Resource contract returned by {@link AgentTool.resourceClaims}.
+ *
+ * Return `"exclusive"` when the call must run alone, or a non-empty claim
+ * list. The dag-v2 scheduler fails closed to exclusive when a resolver throws,
+ * rejects, or returns an empty or malformed claim list.
+ */
+export type ToolResourceClaims = readonly ToolResourceClaim[] | "exclusive";
+/** Context passed to {@link AgentTool.resourceClaims}. */
+export interface ToolResourceClaimsContext {
+    /** Working directory used by the scheduler for this call batch. */
+    cwd: string;
+    /** Provider-supplied id of the tool call being scheduled. */
+    toolCallId: string;
+}
 /** Tool definition used by the agent runtime. */
 export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
     /** Human-readable label for UI display. */
@@ -336,7 +441,105 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * If omitted, the default execution mode applies.
      */
     executionMode?: ToolExecutionMode;
+    /**
+     * dag-v2 resource contract for this tool call.
+     *
+     * The resolver receives the raw call arguments and scheduler context before
+     * execution starts. It may return synchronously or asynchronously. Throwing,
+     * rejecting, returning malformed data, or returning no usable claim fails
+     * closed to exclusive scheduling. This field has no effect on waves-v1.
+     */
+    resourceClaims?: (args: unknown, context: ToolResourceClaimsContext) => ToolResourceClaims | Promise<ToolResourceClaims>;
+    /**
+     * Optional per-call execution timeout in milliseconds.
+     *
+     * When positive, the tool's `execute` promise is raced against this timeout at
+     * the shared execution chokepoint. If the timeout elapses first, the loop
+     * commits an immediate terminal timeout result and aborts the tool's child
+     * `AbortSignal`, so a tool that ignores the signal cannot stall the run.
+     *
+     * Precedence: this value overrides `AgentLoopConfig.toolTimeouts[name]`, which
+     * overrides `AgentLoopConfig.toolTimeoutMs`. Absent, non-finite, or
+     * non-positive values disable the timeout and preserve current behavior.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Terminal disposition of one tool call in a transcript (six-state model).
+ *
+ * - `completed`: the tool ran and returned a result.
+ * - `failed`: the tool ran and threw/rejected, or could not be prepared.
+ * - `blocked`: a policy hook prevented execution.
+ * - `aborted`: the run's abort terminated the call (started or unstarted).
+ * - `timeout`: the per-call timeout terminated the call.
+ * - `skipped`: the scheduler closed the call without ever starting it.
+ */
+export type ToolCallDisposition = "completed" | "failed" | "blocked" | "aborted" | "timeout" | "skipped";
+/** Schema tag for the {@link ToolResultEnvelope} attached to terminal tool results. */
+export declare const TOOL_RESULT_ENVELOPE_SCHEMA: "tool-result/v2";
+/**
+ * Model-invisible disposition envelope stamped at `details.omk` on every
+ * terminal tool result. `synthetic` means the result artifact was fabricated
+ * by the runtime and does not represent the tool's returned details;
+ * `executionStarted` records whether `AgentTool.execute` actually began.
+ */
+export interface ToolResultEnvelope {
+    schema: typeof TOOL_RESULT_ENVELOPE_SCHEMA;
+    synthetic: boolean;
+    disposition: ToolCallDisposition;
+    reason?: string;
+    timeoutMs?: number;
+    executionStarted: boolean;
+}
+/** Input accepted by the executor-owned {@link createToolResultEnvelope} boundary. */
+export type ToolResultEnvelopeInput = Omit<ToolResultEnvelope, "schema">;
+/** Compatibility wrapper used when original tool details are not a plain object. */
+export interface WrappedToolResultDetails {
+    readonly originalDetails: unknown;
+    readonly omk: ToolResultEnvelope;
 }
+/** Validate both the v2 shape and disposition-specific executor invariants. */
+export declare function isToolResultEnvelope(value: unknown): value is ToolResultEnvelope;
+/**
+ * Construct and freeze a validated executor envelope. Invalid combinations
+ * throw at the executor boundary instead of being persisted into a transcript.
+ */
+export declare function createToolResultEnvelope(input: ToolResultEnvelopeInput): ToolResultEnvelope;
+/**
+ * Per-call execution policy (ALG-004 §6.2). `lateSettlement` controls whether
+ * a real tool promise settling after its terminal cause is surfaced as an
+ * audit-only event (`"audit"`, default) or silently dropped (`"ignore"`).
+ * Terminal results are immutable either way.
+ */
+export interface ToolExecutionPolicy {
+    timeoutMs?: number;
+    cancelSiblingsOnFatal?: boolean;
+    lateSettlement: "audit" | "ignore";
+}
+/** Committed disposition for a tool call terminated by timeout or parent abort. */
+export type ToolTimeoutDisposition = "timeout" | "aborted";
+/** Identity keys resolved for one raw path by a {@link ResourceKeyResolver}. */
+export interface ResolvedResourceKeys {
+    /** Canonical lexical key (slash-normalized, dot-collapsed, drive/UNC normalized). */
+    lexicalKey: string;
+    /** Canonical real path: nearest existing ancestor realpath + non-existing suffix. */
+    realKey?: string;
+    /** `dev:ino` identity for an existing file (symlink target/hardlink aware). */
+    inodeKey?: string;
+}
+/**
+ * Optional platform identity resolver injected into the dag-v2 scheduler
+ * (§5.5 stage 2). The shared agent package stays browser-safe; a Node
+ * implementation lives in `omk-agent-core/node`. The raw path reaches the
+ * resolver before cwd-relative lexical canonicalization so Node-only tilde and
+ * platform aliases remain visible. Returning `null`, throwing, rejecting, or
+ * returning malformed keys isolates the call as exclusive.
+ */
+export interface ResourceKeyResolver {
+    resolvePath(rawPath: string, cwd: string): Promise<ResolvedResourceKeys | null> | ResolvedResourceKeys | null;
+}
+/** How a tool's real promise eventually settled after its terminal cause won. */
+export type ToolLateSettlementOutcome = "resolved" | "rejected";
 /** Context snapshot passed into the low-level agent loop. */
 export interface AgentContext {
     /** System prompt included with the request. */
@@ -349,9 +552,9 @@ export interface AgentContext {
 /**
  * Events emitted by the Agent for UI updates.
  *
- * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
- * listeners for that event are still part of run settlement. The agent becomes
- * idle only after those listeners finish.
+ * `agent_end` is the last event emitted for a run, and its subscribers remain
+ * part of run settlement. `tool_execution_update` delivery is observation-only:
+ * subscriber promises are detached and cannot delay timeout/abort terminality.
  */
 export type AgentEvent = {
     type: "agent_start";
@@ -378,18 +581,24 @@ export type AgentEvent = {
     type: "tool_execution_start";
     toolCallId: string;
     toolName: string;
-    args: any;
+    args: unknown;
 } | {
     type: "tool_execution_update";
     toolCallId: string;
     toolName: string;
-    args: any;
-    partialResult: any;
+    args: unknown;
+    partialResult: unknown;
 } | {
     type: "tool_execution_end";
     toolCallId: string;
     toolName: string;
-    result: any;
+    result: unknown;
     isError: boolean;
+} | {
+    type: "tool_execution_late_settlement";
+    toolCallId: string;
+    toolName: string;
+    disposition: ToolTimeoutDisposition;
+    outcome: ToolLateSettlementOutcome;
 };
 //# sourceMappingURL=types.d.ts.map