@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/tools/invoke.js

@@ -1,14 +1,19 @@
-import { isAbortError, TheoremError, toErrorEvent, withPublicWording, } from '../../guardrails/error.js';
+import { isAbortError, TheoremError, toErrorEvent, withPublicLabels, } from '../../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../../guardrails/events.js';
 import { resolveTraceWriter } from '../../observability/policy.js';
-import { writeSpans } from '../../observability/trace.js';
+import { writeTrace } from '../../observability/trace.js';
+import { buildRecord } from '../../observability/trace-record.js';
 import { startTrace, } from '../../observability/trace-span.js';
+import { invokeAgentCaller } from '../engine/runner/mod.js';
+import { inStep, runSideBySide, stepOrder } from '../engine/runner/step-order.js';
 import { startToolTrace, toolSpanName } from '../engine/tool-trace.js';
-import { optional, traceLinks } from '../engine/turn-trace.js';
+import { endThrownSpan, optional, traceLinks } from '../engine/turn-trace.js';
 import { pickModel } from '../registry/resolve.js';
 import { turnDoneOf } from '../turn-events.js';
-import { failureEvent, newCallId, toolCallArguments, toolCallRequestEvent } from './events.js';
-import { executeRegisteredTool } from './execute.js';
-import { cloneTurnToolSnapshot, prepareTurnToolSnapshot, promoteLoadedTools } from './resolve.js';
+import { coordinateTool } from './coordinate.js';
+import { failedActivity, failureEvent, newCallId, toolCallArguments, toolCallRequestEvent, } from './events.js';
+import { authorizeToolReplay, executeRegisteredTool, } from './execute.js';
+import { cloneTurnToolSnapshot, prepareTurnToolSnapshot, profileToolsParallel, promoteLoadedTools, } from './resolve.js';
 import { plainToolInput } from './schema.js';
 function turnRequestFromInvoke(request) {
     return {
@@ -22,24 +27,25 @@ function turnRequestFromInvoke(request) {
 }
 async function prepareInvokeSnapshot(registry, request, profile) {
     const req = turnRequestFromInvoke(request);
-    if (profile.type === 'decision') {
-        throw new TheoremError('request', `Profile ${profile.id}: type 'decision' cannot invoke tools`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (profile.type === 'decision' || profile.type === 'embedding') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'decision' cannot invoke tools`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const model = profile.type === 'host' ? undefined : pickModel(profile, request.model);
     return await prepareTurnToolSnapshot(registry.tools, profile, req, model);
 }
 /**
- * The trace record is written however the call ends, including an early stop or a failure before
- * the tool. An unknown profile is recorded under the standard observability policy: there is none to read.
+ * One trace record around an invoke, written however it ends, including an early stop or a
+ * failure before the tool. The profile's labels and guardrail policy shape every event. An unknown
+ * profile is recorded under the standard observability policy: there is none to read.
  */
-async function* invokeTool(registry, request, sinkOverride) {
+async function* invokeInTrace(registry, request, spanName, sinkOverride, run) {
     const known = registry.profiles.find(request.profile);
     const { sink, policy } = resolveTraceWriter({
         override: sinkOverride,
         observability: known?.observability,
+        guardrails: known?.guardrails,
     });
-    const callId = request.callId ?? newCallId(request.name);
-    const tree = startTrace(toolSpanName(request.name), {
+    const tree = startTrace(spanName, {
         attributes: {
             'gen_ai.agent.name': request.profile,
             ...optional('gen_ai.conversation.id', request.conversationId),
@@ -47,83 +53,230 @@ async function* invokeTool(registry, request, sinkOverride) {
         links: traceLinks(request.links),
         ...(request.traceparent ? { traceparent: request.traceparent } : {}),
     });
-    const openSpan = (_name, attributes) => {
-        tree.root.set(attributes);
-        return tree.root;
-    };
-    const failBeforeTool = (end) => startToolTrace(openSpan, {
-        name: request.name,
-        callId,
-        call: { arguments: toolCallArguments(plainToolInput(request.input)) },
-    }).end(end);
+    // why: Agent tool calls run nested turns in this record; their canaries are scrubbed from it.
+    const canaries = [];
     try {
-        const lexicon = known?.lexicon;
-        const traceparent = tree.root.traceparent();
-        for await (const event of invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent)) {
-            yield withPublicWording(event, lexicon);
+        const labels = known?.labels;
+        for await (const event of run.events(tree, canaries)) {
+            // invariant: A match is the caught text itself; it leaves only when the profile asks for it.
+            yield projectGuardrailTurnEvent(withPublicLabels(event, labels), policy.include.guardrailMatchPreview);
         }
+        run.ended?.(tree);
     }
     catch (err) {
-        failBeforeTool(isAbortError(err) ? { outcome: 'cancelled' } : { outcome: 'error', thrown: err });
+        run.failed(tree, err);
         throw err;
     }
     finally {
-        await writeSpans(sink, tree.collect(), policy, request.metadata);
+        await writeTrace(sink, buildRecord({
+            spans: tree.collect(),
+            policy,
+            canaries,
+            ...(request.metadata ? { metadata: request.metadata } : {}),
+        }), policy);
     }
 }
-async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent) {
+/** Close the call's span for a failure before its tool ran. */
+function failCallBeforeTool(openSpan, invoke, callId) {
+    return (end) => startToolTrace(openSpan, {
+        name: invoke.name,
+        callId,
+        call: { arguments: toolCallArguments(plainToolInput(invoke.input)) },
+    }).end(end);
+}
+/** The profile an invoke runs under, and its own copy of the tool snapshot. */
+async function invokeSnapshot(registry, request) {
     const profile = registry.profiles.get(request.profile);
     const snapshot = request.snapshot
         ? cloneTurnToolSnapshot(request.snapshot)
         : await prepareInvokeSnapshot(registry, request, profile);
-    // A model's call was already announced by its turn.
-    if (request.callId === undefined) {
-        yield toolCallRequestEvent({ name: request.name, callId }, toolCallArguments(request.input));
+    return { profile, snapshot };
+}
+function invokeTool(registry, request, sinkOverride) {
+    return startInvoke(registry, request, sinkOverride).events;
+}
+function startInvoke(registry, request, sinkOverride) {
+    const callId = request.callId ?? newCallId(request.name);
+    const invoke = {
+        ...request,
+        operationId: request.operationId ?? crypto.randomUUID(),
+    };
+    const openSpan = (tree) => (_name, attributes) => {
+        tree.root.set(attributes);
+        return tree.root;
+    };
+    const events = invokeInTrace(registry, invoke, toolSpanName(invoke.name), sinkOverride, {
+        events: (tree, canaries) => invokeTraced(registry, invoke, callId, openSpan(tree), failCallBeforeTool(openSpan(tree), invoke, callId), tree.root.traceparent(), canaries),
+        failed: (tree, err) => failCallBeforeTool(openSpan(tree), invoke, callId)(isAbortError(err) ? { outcome: 'cancelled' } : { outcome: 'error', thrown: err }),
+    });
+    return { name: invoke.name, callId, events };
+}
+/**
+ * Runs the host's calls as one step, the way a turn runs the model's. Every call the step names
+ * itself is announced with the step's id before any runs. With `tools.parallel` they run side by
+ * side, otherwise one at a time in the order given; a call whose `pre_tool` answers `waitFor`
+ * starts once those calls in the step settle. Each call's events arrive as it gives them, and its
+ * terminal `tool` event says it settled. The calls share one snapshot. A call that gates waits for
+ * its own approval while the others run; the step then ends `gate`. One trace record holds a span
+ * per call under the step's root, rooted under the host span when one is given.
+ */
+function invokeToolStep(registry, request, sinkOverride) {
+    return startInvokeStep(registry, request, sinkOverride).events;
+}
+function startInvokeStep(registry, request, sinkOverride) {
+    const { calls: given, ...shared } = request;
+    const calls = given.map((call) => {
+        const callId = call.callId ?? newCallId(call.name);
+        return {
+            callId,
+            invoke: {
+                ...shared,
+                name: call.name,
+                input: call.input,
+                callId,
+                operationId: call.operationId ?? crypto.randomUUID(),
+            },
+            // why: A model's call was already announced by its turn; only a call the step names itself is announced here.
+            announce: call.callId === undefined,
+        };
+    });
+    const events = invokeInTrace(registry, request, `tool_step ${request.profile}`, sinkOverride, {
+        events: (tree, canaries) => invokeStepTraced(registry, request, calls, (name, attributes) => tree.root.child(name, { attributes }), tree.root.traceparent(), canaries),
+        ended: (tree) => tree.root.end({ code: 'OK' }),
+        failed: (tree, err) => {
+            if (isAbortError(err))
+                tree.root.end();
+            else
+                endThrownSpan(tree.root, err);
+        },
+    });
+    return {
+        calls: calls.map(({ callId, invoke }) => ({ name: invoke.name, callId })),
+        events,
+    };
+}
+async function* invokeStepTraced(registry, request, calls, openSpan, traceparent, canaries) {
+    const { profile, snapshot } = await invokeSnapshot(registry, request);
+    const stepId = crypto.randomUUID();
+    for (const { callId, invoke, announce } of calls) {
+        if (!announce)
+            continue;
+        yield toolCallRequestEvent({ name: invoke.name, callId, operationId: invoke.operationId }, toolCallArguments(invoke.input), { stepId, stepCallCount: calls.length });
     }
-    if (request.promoted?.length) {
-        const { failure } = promoteLoadedTools(registry.tools, snapshot, request.promoted, profile);
-        if (failure) {
-            failBeforeTool({ outcome: 'error', failure });
-            yield failureEvent({ name: request.name, callId }, failure);
-            yield { type: 'done', stop: { kind: 'completed' }, traceparent };
-            return;
-        }
+    const order = stepOrder(calls.map(({ callId }) => callId), profileToolsParallel(profile) === true, request.signal);
+    const step = {
+        stepCalls: calls.map(({ callId, invoke }) => ({
+            callId,
+            tool: invoke.name,
+            input: toolCallArguments(invoke.input),
+        })),
+        wait: order.wait,
+    };
+    let gated = false;
+    try {
+        // why: As in a turn's step, one call that throws ends the step; the others are closed.
+        const settlements = yield* runSideBySide(calls.map(({ callId, invoke }) => inStep(order, callId, () => runCall(registry, invoke, profile, snapshot, callId, openSpan, failCallBeforeTool(openSpan, invoke, callId), canaries, step))));
+        gated = settlements.some((settlement) => settlement?.gated !== undefined);
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+    }
+    yield turnDoneOf({
+        stop: { kind: gated ? 'gate' : 'completed' },
+        traceparent,
+    }, snapshot);
+}
+async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent, canaries) {
+    const { profile, snapshot } = await invokeSnapshot(registry, request);
+    // why: A model's call was already announced by its turn.
+    if (request.callId === undefined) {
+        yield toolCallRequestEvent({ name: request.name, callId, operationId: request.operationId }, toolCallArguments(request.input));
     }
     let gated = false;
     try {
-        const handlers = request.onStage ? [request.onStage] : [];
-        const settlement = yield* executeRegisteredTool({
-            tools: registry.tools,
-            profile,
-            name: request.name,
-            input: request.input,
-            callId,
-            ctx: {
-                sessionPermissions: request.sessionPermissions,
-                credentials: request.credentials,
-                resolveHost: request.resolveHost,
-                path: request.path,
-                signal: request.signal,
-                resume: request.resume,
-                host: request.host,
-            },
-            snapshot,
-            openSpan,
-            stages: {
-                handlers,
-                profile,
-                step: 1,
-                history: () => [],
-                injectAllowed: false,
-                host: request.host,
-                signal: request.signal,
-            },
-        });
+        const settlement = yield* runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries);
         gated = settlement.gated !== undefined;
     }
     catch (err) {
         yield toErrorEvent(err);
     }
-    yield turnDoneOf({ stop: { kind: gated ? 'gate' : 'completed' }, traceparent }, snapshot);
+    yield turnDoneOf({
+        stop: { kind: gated ? 'gate' : 'completed' },
+        traceparent,
+    }, snapshot);
+}
+/** One call, coordinated: replayed when its operation already ran, else executed. */
+function runCall(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, step) {
+    return coordinateTool(request.execution, {
+        operationId: request.operationId ?? crypto.randomUUID(),
+        callId,
+        profileId: profile.id,
+        toolId: request.name,
+    }, {
+        input: request.input,
+        resume: request.resume,
+        snapshot,
+        context: {
+            model: request.model,
+            turnInput: request.turnInput,
+            promoted: request.promoted,
+        },
+    }, request.signal, (beginBody) => invokePrepared(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, beginBody, step), (outcome) => authorizeToolReplay({
+        outcome,
+        tools: registry.tools,
+        profile,
+        name: request.name,
+        resume: request.resume,
+        snapshot,
+    }));
+}
+async function* invokePrepared(registry, request, profile, snapshot, callId, openSpan, failBeforeTool, canaries, beginBody, step) {
+    if (request.promoted?.length) {
+        const { failure } = promoteLoadedTools(registry.tools, snapshot, request.promoted, profile);
+        if (failure) {
+            failBeforeTool({ outcome: 'error', failure });
+            yield failureEvent({
+                name: request.name,
+                callId,
+                operationId: request.operationId,
+                activityFailed: failedActivity(request.name, profile.labels),
+            }, failure);
+            return { failure, callNotStarted: true };
+        }
+    }
+    const handlers = request.onStage ? [request.onStage] : [];
+    return yield* executeRegisteredTool({
+        tools: registry.tools,
+        beginBody,
+        agents: invokeAgentCaller(registry, request, canaries),
+        profile,
+        name: request.name,
+        input: request.input,
+        callId,
+        ctx: {
+            operationId: request.operationId,
+            sessionPermissions: request.sessionPermissions,
+            credentials: request.credentials,
+            resolveHost: request.resolveHost,
+            path: request.path,
+            signal: request.signal,
+            resume: request.resume,
+            page: request.page,
+            pageExecution: request.pageExecution,
+            host: request.host,
+        },
+        snapshot,
+        openSpan,
+        stages: {
+            handlers,
+            profile,
+            step: 1,
+            history: () => [],
+            injectAllowed: false,
+            host: request.host,
+            signal: request.signal,
+            ...step,
+        },
+    });
 }
-export { invokeTool };
+export { invokeTool, invokeToolStep, startInvoke, startInvokeStep };

package/esm/src/kernel/tools/mcp-sessions.d.ts

@@ -16,5 +16,8 @@ export interface McpSessionCache {
 }
 export declare function createMcpSessionCache(now?: () => number): McpSessionCache;
 export declare function isMcpSessionId(value: string | null): value is string;
-/** One session per server and credential; the credential is hashed, never kept. */
+/**
+ * One session per server and credential. The URL is hashed with the headers, since a key can sit
+ * in either; the credential is never kept.
+ */
 export declare function mcpSessionKey(url: string, headers: Record<string, string>): Promise<string>;

package/esm/src/kernel/tools/mcp-sessions.js

@@ -4,7 +4,7 @@
  */
 const MAX_SESSIONS = 256;
 const IDLE_MS = 30 * 60 * 1000;
-// The spec allows visible ASCII only; the cap keeps a server from bloating every later request.
+// why: The spec allows visible ASCII only; the cap keeps a server from bloating every later request.
 const SESSION_ID = /^[\x21-\x7E]{1,256}$/;
 export function createMcpSessionCache(now = Date.now) {
     const sessions = new Map();
@@ -17,7 +17,7 @@ export function createMcpSessionCache(now = Date.now) {
             sessions.delete(key);
             if (now() - entry.usedAt > IDLE_MS)
                 return undefined;
-            // Re-inserting keeps the map in least-recently-used order for eviction.
+            // why: Re-inserting keeps the map in least-recently-used order for eviction.
             sessions.set(key, { ...entry, usedAt: now() });
             return { id: entry.id, protocolVersion: entry.protocolVersion };
         },
@@ -53,12 +53,17 @@ export function createMcpSessionCache(now = Date.now) {
 export function isMcpSessionId(value) {
     return value !== null && SESSION_ID.test(value);
 }
-/** One session per server and credential; the credential is hashed, never kept. */
+/**
+ * One session per server and credential. The URL is hashed with the headers, since a key can sit
+ * in either; the credential is never kept.
+ */
 export async function mcpSessionKey(url, headers) {
-    const canonical = JSON.stringify(Object.entries(headers)
-        .map(([name, value]) => [name.toLowerCase(), value])
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const canonical = JSON.stringify([
+        url,
+        Object.entries(headers)
+            .map(([name, value]) => [name.toLowerCase(), value])
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    ]);
     const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
-    const hex = [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0'));
-    return `${url}\n${hex.join('')}`;
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }

package/esm/src/kernel/tools/mod.d.ts

@@ -1,9 +1,10 @@
-export { coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
+export { authorizeToolReplay, coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
 export { askUserTool, registerHarnessTools } from './harness.js';
 export { formatToolResult } from './model-text.js';
 export type { ToolRegistry } from './registry.js';
 export { createToolRegistry } from './registry.js';
-export type { McpProtocolVersion, McpRpcResponse } from './remote.js';
-export { buildHttpToolTarget, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, } from './remote.js';
+export type { CredentialQuery, McpProtocolVersion, McpRpcResponse } from './remote.js';
+export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
 export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
 export type * from './types.js';
+export { UncheckedOutput, uncheckedOutput } from './unchecked-output.js';

package/esm/src/kernel/tools/mod.js

@@ -1,6 +1,7 @@
-export { coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
+export { authorizeToolReplay, coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
 export { askUserTool, registerHarnessTools } from './harness.js';
 export { formatToolResult } from './model-text.js';
 export { createToolRegistry } from './registry.js';
-export { buildHttpToolTarget, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, } from './remote.js';
+export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
 export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
+export { UncheckedOutput, uncheckedOutput } from './unchecked-output.js';

package/esm/src/kernel/tools/model-text.d.ts

@@ -1,11 +1,16 @@
-import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
-import type { Provenance } from '../../guardrails/types.js';
 import type { ModelToolResult, ToolFailure } from './types.js';
 /**
  * Every transport and replay formats through here, so the model's view of a call cannot drift.
  * Never embeds `parts[].data`: media travels on `TurnHistoryMessage.parts`. A result without
- * `modelText` (a host replaying a transcript) is guarded here under full detection.
+ * `modelText` (a host replaying a transcript) has no profile in hand, so every detector's
+ * matches are replaced.
  */
 export declare function formatToolResult(result: ModelToolResult): string;
-/** The message is remote-authored on HTTP and MCP tools, so it is redacted before the kernel frames it. */
-export declare function formatToolFailureForModel(failure: Pick<ToolFailure, 'code' | 'message' | 'details'>, provenance?: Provenance, policy?: ReturnType<typeof resolveGuardrailPolicy>): ModelToolResult;
+/** A failure as the kernel reports it to the model. The message is used as given. */
+export declare function frameToolFailure(failure: Pick<ToolFailure, 'code' | 'message' | 'details'>): ModelToolResult;
+/**
+ * A failure framed with no profile in hand: the message is remote-authored on HTTP and MCP
+ * tools, so every detector's matches are replaced first. A call that settles through the
+ * executor reads the message at its own boundary instead.
+ */
+export declare function formatToolFailureForModel(failure: Pick<ToolFailure, 'code' | 'message' | 'details'>): ModelToolResult;

package/esm/src/kernel/tools/model-text.js

@@ -1,25 +1,31 @@
-import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
-import { sanitizeText } from '../../guardrails/sanitize.js';
-import { composeToolText, guardToolFailureText } from '../../guardrails/tool-result.js';
+import { redactDetectors } from '../../guardrails/detect-at.js';
+import { DETECTORS } from '../../guardrails/detectors.js';
+import { composeToolText } from '../../guardrails/tool-result.js';
 /**
  * Every transport and replay formats through here, so the model's view of a call cannot drift.
  * Never embeds `parts[].data`: media travels on `TurnHistoryMessage.parts`. A result without
- * `modelText` (a host replaying a transcript) is guarded here under full detection.
+ * `modelText` (a host replaying a transcript) has no profile in hand, so every detector's
+ * matches are replaced.
  */
 export function formatToolResult(result) {
     if (result.modelText !== undefined) {
         return result.modelText;
     }
-    return sanitizeText(composeToolText(result.finding, result.data));
+    return redactDetectors(composeToolText(result.finding, result.data), DETECTORS);
 }
-/** The message is remote-authored on HTTP and MCP tools, so it is redacted before the kernel frames it. */
-export function formatToolFailureForModel(failure, provenance, policy = resolveGuardrailPolicy(undefined)) {
-    const safe = provenance
-        ? guardToolFailureText(failure.message, provenance, policy).text
-        : sanitizeText(failure.message);
+/** A failure as the kernel reports it to the model. The message is used as given. */
+export function frameToolFailure(failure) {
     return {
-        finding: `Tool error (${failure.code}): ${safe}`,
-        // The finding already says the code and message; only details are new.
+        finding: `Tool error (${failure.code}): ${failure.message}`,
+        // why: The finding already says the code and message; only details are new.
         ...(failure.details !== undefined ? { data: { details: failure.details } } : {}),
     };
 }
+/**
+ * A failure framed with no profile in hand: the message is remote-authored on HTTP and MCP
+ * tools, so every detector's matches are replaced first. A call that settles through the
+ * executor reads the message at its own boundary instead.
+ */
+export function formatToolFailureForModel(failure) {
+    return frameToolFailure({ ...failure, message: redactDetectors(failure.message, DETECTORS) });
+}

package/esm/src/kernel/tools/operation.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { type JsonObject, type JsonValue } from '../json.js';
+import type { GateReference, TurnEventOf } from '../turn-events.js';
+import type { TurnHistoryMessage } from '../types.js';
+import type { ModelToolResult, PageAnswer, ToolFailure } from './types.js';
+export type TerminalToolEvent = TurnEventOf<'tool'> & {
+    tool: Extract<TurnEventOf<'tool'>['tool'], {
+        phase: 'complete' | 'error';
+    }>;
+};
+export interface SavedToolInvocation {
+    accepted: JsonObject;
+    preparedInput: JsonValue;
+}
+export declare const savedToolInvocationSchema: z.ZodType<SavedToolInvocation>;
+export interface ToolOperationIdentity extends GateReference {
+    profileId: string;
+    toolId: string;
+    invocationHash: string;
+    invocation?: SavedToolInvocation;
+}
+export interface ToolOperationClaim extends ToolOperationIdentity {
+    claimToken: string;
+}
+export interface PageToolDispatch {
+    grantId: string;
+    result: Promise<PageAnswer>;
+}
+export interface PageToolExecution {
+    dispatch(claim: ToolOperationClaim, signal?: AbortSignal): Promise<PageToolDispatch>;
+}
+export interface ToolOperationOutcome {
+    event: TerminalToolEvent;
+    effects: 'not_started' | 'completed' | 'unknown';
+    replay: {
+        modelResult?: ModelToolResult;
+        outputRaw?: unknown;
+        failure?: ToolFailure;
+        awaiting?: boolean;
+        denied?: true;
+        callNotStarted?: boolean;
+        aborted?: boolean | {
+            reason?: string;
+        };
+        pendingInject?: {
+            id?: string;
+            messages: TurnHistoryMessage[];
+        }[];
+    };
+}
+export type ToolOperationUncertainty = 'execution_interrupted' | 'settlement_write_failed' | 'worker_lost';
+export type BeginToolOperationResult = {
+    kind: 'acquired';
+    claimToken: string;
+} | {
+    kind: 'settled';
+    outcome: ToolOperationOutcome;
+} | {
+    kind: 'running';
+} | {
+    kind: 'uncertain';
+};
+export interface ToolExecutionCoordinator {
+    lookup(operation: ToolOperationIdentity): Promise<Exclude<BeginToolOperationResult, {
+        kind: 'acquired';
+    }> | undefined>;
+    begin(operation: ToolOperationIdentity): Promise<BeginToolOperationResult>;
+    settle(claim: ToolOperationClaim, outcome: ToolOperationOutcome): Promise<void>;
+    settleNotStarted(operation: ToolOperationIdentity, outcome: ToolOperationOutcome): Promise<void>;
+    markUncertain(claim: ToolOperationClaim, reason: ToolOperationUncertainty): Promise<void>;
+}
+export declare function operationUnavailable(): TheoremError;
+export declare function toolInvocationHash(value: unknown): Promise<string>;
+export declare const toolOperationOutcomeSchema: z.ZodType<ToolOperationOutcome>;
+export declare function operationWireValue(value: unknown): JsonValue;