@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,282 @@
+import { isAbortError, TheoremError, toErrorEvent, withPublicLabels, } from '../../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../../guardrails/events.js';
+import { resolveTraceWriter } from '../../observability/policy.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 { endThrownSpan, optional, traceLinks } from '../engine/turn-trace.js';
+import { pickModel } from '../registry/resolve.js';
+import { turnDoneOf } from '../turn-events.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 {
+        profile: request.profile,
+        path: request.path,
+        sessionPermissions: request.sessionPermissions,
+        input: request.turnInput,
+        model: request.model,
+        host: request.host,
+    };
+}
+async function prepareInvokeSnapshot(registry, request, profile) {
+    const req = turnRequestFromInvoke(request);
+    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);
+}
+/**
+ * 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* 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 tree = startTrace(spanName, {
+        attributes: {
+            'gen_ai.agent.name': request.profile,
+            ...optional('gen_ai.conversation.id', request.conversationId),
+        },
+        links: traceLinks(request.links),
+        ...(request.traceparent ? { traceparent: request.traceparent } : {}),
+    });
+    // why: Agent tool calls run nested turns in this record; their canaries are scrubbed from it.
+    const canaries = [];
+    try {
+        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) {
+        run.failed(tree, err);
+        throw err;
+    }
+    finally {
+        await writeTrace(sink, buildRecord({
+            spans: tree.collect(),
+            policy,
+            canaries,
+            ...(request.metadata ? { metadata: request.metadata } : {}),
+        }), policy);
+    }
+}
+/** 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);
+    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 });
+    }
+    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 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);
+}
+/** 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, invokeToolStep, startInvoke, startInvokeStep };

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

@@ -0,0 +1,23 @@
+/**
+ * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
+ * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
+ */
+export type McpSession = {
+    id: string;
+    protocolVersion: string;
+};
+export interface McpSessionCache {
+    get(key: string): McpSession | undefined;
+    /** Parallel callers for one key share a single `open`. */
+    open(key: string, open: () => Promise<McpSession>): Promise<McpSession>;
+    /** Only drops the session if it's still `id`, so a late expiry can't evict a newer one. */
+    drop(key: string, id: string): void;
+    clear(): void;
+}
+export declare function createMcpSessionCache(now?: () => number): McpSessionCache;
+export declare function isMcpSessionId(value: string | null): value is string;
+/**
+ * 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

@@ -0,0 +1,69 @@
+/**
+ * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
+ * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
+ */
+const MAX_SESSIONS = 256;
+const IDLE_MS = 30 * 60 * 1000;
+// 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();
+    const pending = new Map();
+    return {
+        get(key) {
+            const entry = sessions.get(key);
+            if (!entry)
+                return undefined;
+            sessions.delete(key);
+            if (now() - entry.usedAt > IDLE_MS)
+                return undefined;
+            // 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 };
+        },
+        open(key, open) {
+            const inFlight = pending.get(key);
+            if (inFlight)
+                return inFlight;
+            const opening = open()
+                .then((session) => {
+                sessions.delete(key);
+                sessions.set(key, { ...session, usedAt: now() });
+                for (const oldest of sessions.keys()) {
+                    if (sessions.size <= MAX_SESSIONS)
+                        break;
+                    sessions.delete(oldest);
+                }
+                return session;
+            })
+                .finally(() => pending.delete(key));
+            pending.set(key, opening);
+            return opening;
+        },
+        drop(key, id) {
+            if (sessions.get(key)?.id === id)
+                sessions.delete(key);
+        },
+        clear() {
+            sessions.clear();
+            pending.clear();
+        },
+    };
+}
+export function isMcpSessionId(value) {
+    return value !== null && SESSION_ID.test(value);
+}
+/**
+ * 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([
+        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));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}

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

@@ -0,0 +1,10 @@
+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 { 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

@@ -0,0 +1,7 @@
+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, 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

@@ -0,0 +1,16 @@
+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) has no profile in hand, so every detector's
+ * matches are replaced.
+ */
+export declare function formatToolResult(result: ModelToolResult): string;
+/** 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

@@ -0,0 +1,31 @@
+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) has no profile in hand, so every detector's
+ * matches are replaced.
+ */
+export function formatToolResult(result) {
+    if (result.modelText !== undefined) {
+        return result.modelText;
+    }
+    return redactDetectors(composeToolText(result.finding, result.data), DETECTORS);
+}
+/** 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}): ${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;

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

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { publicError, TheoremError } from '../../guardrails/error.js';
+import { errorKindSchema, guardrailHit, provenance } from '../../guardrails/event-schemas.js';
+import { jsonObjectSchema, jsonValueSchema } from '../json.js';
+import { interactionPartSchema, TURN_EVENT_SCHEMAS, turnHistoryMessageSchema, } from '../turn-events.js';
+export const savedToolInvocationSchema = z.strictObject({
+    accepted: jsonObjectSchema,
+    preparedInput: jsonValueSchema,
+});
+export function operationUnavailable() {
+    const error = new TheoremError('unavailable', '');
+    error.message = publicError(error);
+    return error;
+}
+export async function toolInvocationHash(value) {
+    const ordered = (item) => {
+        if (Array.isArray(item))
+            return item.map(ordered);
+        if (item && typeof item === 'object') {
+            return Object.fromEntries(Object.entries(item)
+                .filter(([, entry]) => entry !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([key, entry]) => [key, ordered(entry)]));
+        }
+        return item;
+    };
+    const data = jsonValueSchema.parse(ordered(operationWireValue(value)));
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(data)));
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+const terminalSchema = TURN_EVENT_SCHEMAS.tool.transform((event, ctx) => {
+    if (event.tool.phase === 'complete' || event.tool.phase === 'error') {
+        return { ...event, tool: event.tool };
+    }
+    ctx.addIssue({ code: 'custom' });
+    return z.NEVER;
+});
+export const toolOperationOutcomeSchema = z.strictObject({
+    event: terminalSchema,
+    effects: z.enum(['not_started', 'completed', 'unknown']),
+    replay: z.strictObject({
+        modelResult: z
+            .strictObject({
+            finding: z.string(),
+            data: jsonValueSchema.optional(),
+            parts: z.array(interactionPartSchema).optional(),
+            modelText: z.string().optional(),
+            provenance: provenance.optional(),
+            suspicious: z.array(guardrailHit).optional(),
+        })
+            .optional(),
+        outputRaw: jsonValueSchema.optional(),
+        failure: z
+            .strictObject({
+            code: z.string(),
+            kind: errorKindSchema,
+            message: z.string(),
+            error: z.string().optional(),
+            details: jsonValueSchema.optional(),
+        })
+            .optional(),
+        awaiting: z.boolean().optional(),
+        denied: z.literal(true).optional(),
+        callNotStarted: z.boolean().optional(),
+        aborted: z.union([z.boolean(), z.strictObject({ reason: z.string().optional() })]).optional(),
+        pendingInject: z
+            .array(z.strictObject({ id: z.string().optional(), messages: z.array(turnHistoryMessageSchema) }))
+            .optional(),
+    }),
+});
+export function operationWireValue(value) {
+    const ancestors = new Set();
+    const normalize = (item) => {
+        if (!item || typeof item !== 'object')
+            return item;
+        if (ancestors.has(item))
+            throw operationUnavailable();
+        const prototype = Object.getPrototypeOf(item);
+        if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null) {
+            throw operationUnavailable();
+        }
+        if (Object.hasOwn(item, '__proto__'))
+            throw operationUnavailable();
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item))
+                return item.map(normalize);
+            const entries = Object.entries(Object.getOwnPropertyDescriptors(item));
+            if (entries.some(([, descriptor]) => descriptor.get || descriptor.set))
+                throw operationUnavailable();
+            return Object.fromEntries(entries
+                .filter(([, descriptor]) => descriptor.enumerable && descriptor.value !== undefined)
+                .map(([key, descriptor]) => [key, normalize(descriptor.value)]));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    return jsonValueSchema.parse(normalize(value));
+}

package/esm/src/kernel/tools/page-answer.d.ts

@@ -0,0 +1,8 @@
+import type { ToolHandler } from './types.js';
+/**
+ * The handler of a function tool the page answers (`answeredBy: 'page'`): it returns what the
+ * page sent for the call (`ctx.page.output`), which the tool's `output` schema then checks. A
+ * call the page never answered fails to the model. A call run with no answer at all never
+ * reaches here: it is held at a `page` gate.
+ */
+export declare function pageAnswerHandler(name: string): ToolHandler<unknown, unknown>;

package/esm/src/kernel/tools/page-answer.js

@@ -0,0 +1,19 @@
+import { labelText } from '../../guardrails/labels.js';
+import { uncheckedOutput } from './unchecked-output.js';
+/**
+ * The handler of a function tool the page answers (`answeredBy: 'page'`): it returns what the
+ * page sent for the call (`ctx.page.output`), which the tool's `output` schema then checks. A
+ * call the page never answered fails to the model. A call run with no answer at all never
+ * reaches here: it is held at a `page` gate.
+ */
+export function pageAnswerHandler(name) {
+    return (_input, ctx) => {
+        const { page } = ctx;
+        if (page && 'output' in page)
+            return uncheckedOutput(page.output);
+        const { labels } = ctx.profile;
+        if (page?.timedOut)
+            throw new Error(labelText('tool.page_timed_out', {}, labels));
+        throw new Error(labelText('tool.page_no_answer', { tool: name }, labels));
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { ToolAccess } from '../schema.js';
+import type { ToolGateBase } from '../turn-events.js';
+import type { InvokeToolResume, ToolGate, ToolLabels, ToolPermission } from './types.js';
+export declare function isResumeContinuation(resume?: InvokeToolResume): boolean;
+export declare function isGateResumeGranted(resume?: InvokeToolResume): boolean;
+export declare function isGateResumeDenied(resume?: InvokeToolResume): boolean;
+export declare function permissionGranted(toolName: string, sessionPermissions?: string[]): boolean;
+/** What a gate says about the call beyond its kind: the tool's access and its filled request. */
+export type GateDetails = Pick<ToolGateBase, 'access' | 'request'>;
+/** What an approval card says about a call: what it would do, and what the tool can change. */
+export declare function gateDetails(tool: {
+    access: ToolAccess;
+    labels?: ToolLabels;
+}, input: unknown): GateDetails;
+export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume, details?: GateDetails): ToolGate | null;