theorum 1.0.0 → 1.1.3

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

@@ -0,0 +1,577 @@
+/**
+ * Execution runners for Declarative HTTP and Remote MCP tools.
+ *
+ * Implements:
+ * - URL parameter substitution and query/body mapping
+ * - Network SSRF guardrail enforcement via `assertSafeUrl`
+ * - Credential resolution (bearer, api_key, oauth2)
+ * - Proactive OAuth token refresh with progress event emission
+ * - ToolGate { kind: 'auth' } emission or model error reporting
+ * - Streamable HTTP MCP JSON-RPC protocol (`tools/call`) per 2026-07-28 spec
+ *
+ * @module
+ */
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { refreshOAuthToken } from '../auth/oauth.js';
+import { guardToolTarget, messageOf, startToolExecution, toolEvent, } from './events.js';
+import { checkPermission } from './permission.js';
+import { runPreToolPipeline } from './stage-run.js';
+function authHeaderPair(authConfig, value, defaults) {
+    const headerName = authConfig.headerName ?? defaults.headerName;
+    const headerPrefix = authConfig.headerPrefix ?? defaults.headerPrefix;
+    return { [headerName]: `${headerPrefix}${value}` };
+}
+function buildAuthGate(toolName, authConfig, message, extras) {
+    return {
+        kind: 'auth',
+        tool: toolName,
+        authChallenge: {
+            slot: authConfig.slot,
+            authType: authConfig.type,
+            message,
+            issuer: extras?.issuer ?? authConfig.preResolved?.issuer,
+            resource: extras?.resource ?? authConfig.preResolved?.resource,
+            requiredScopes: authConfig.scopes,
+        },
+    };
+}
+function unauthenticatedResult(toolName, authConfig, message, policy, extras) {
+    if (policy === 'pause') {
+        // Policy name remains `pause` in schema; wire is honest `gate`.
+        // Do not emit gate here — caller uses emitGateSettlement (pre_tool + gate).
+        const gate = buildAuthGate(toolName, authConfig, message, extras);
+        return { headers: {}, unauthenticated: true, gate };
+    }
+    return { headers: {}, unauthenticated: true, modelMessage: message };
+}
+function resolveStaticCredential(credential, authConfig) {
+    if (credential.type === 'bearer') {
+        return {
+            headers: authHeaderPair(authConfig, credential.token, {
+                headerName: 'Authorization',
+                headerPrefix: 'Bearer ',
+            }),
+        };
+    }
+    if (credential.type === 'api_key') {
+        const headerName = credential.headerName ?? authConfig.headerName ?? 'Authorization';
+        const headerPrefix = credential.headerPrefix ?? authConfig.headerPrefix ?? '';
+        return { headers: { [headerName]: `${headerPrefix}${credential.key}` } };
+    }
+    return undefined;
+}
+async function* resolveOAuth2Credential(toolName, authConfig, credential, ctx, base, policy) {
+    const slot = authConfig.slot;
+    let activeToken = credential.accessToken;
+    const now = Date.now();
+    const isExpired = credential.expiresAt !== undefined && credential.expiresAt <= now + 30000;
+    if (isExpired && credential.refreshToken) {
+        try {
+            const refreshResult = await refreshOAuthToken({
+                refreshToken: credential.refreshToken,
+                tokenEndpoint: credential.tokenEndpoint,
+                clientId: credential.clientId,
+                resource: credential.resource,
+                scope: credential.scope,
+                issuer: credential.issuer,
+            });
+            activeToken = refreshResult.credential.accessToken;
+            yield toolEvent(base, {
+                phase: 'progress',
+                data: {
+                    kind: 'auth_token_refreshed',
+                    slot,
+                    credential: refreshResult.credential,
+                },
+            });
+            if (ctx.credentials) {
+                ctx.credentials[slot] = refreshResult.credential;
+            }
+        }
+        catch (err) {
+            const message = `Failed to refresh OAuth token for '${toolName}' (slot: '${slot}'): ${err instanceof Error ? err.message : String(err)}`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return unauthenticatedResult(toolName, authConfig, message, policy, {
+                issuer: credential.issuer,
+                resource: credential.resource,
+            });
+        }
+    }
+    else if (isExpired && !credential.refreshToken) {
+        const message = `OAuth token expired for '${toolName}' (slot: '${slot}') and no refresh token is available.`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return unauthenticatedResult(toolName, authConfig, message, policy, {
+            issuer: credential.issuer,
+            resource: credential.resource,
+        });
+    }
+    return {
+        headers: authHeaderPair(authConfig, activeToken, {
+            headerName: 'Authorization',
+            headerPrefix: 'Bearer ',
+        }),
+    };
+}
+/**
+ * Resolves credentials and handles missing/expired tokens.
+ * Yields TurnEvents for auth pauses or progress (e.g. refreshed tokens).
+ */
+export async function* resolveToolAuth(toolName, authConfig, ctx, base) {
+    if (!authConfig) {
+        return { headers: {} };
+    }
+    const credential = ctx.credentials?.[authConfig.slot];
+    const policy = authConfig.onUnauthenticated ?? 'pause';
+    if (!credential) {
+        const message = `Authentication required for '${toolName}' (auth slot: '${authConfig.slot}').`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return unauthenticatedResult(toolName, authConfig, message, policy);
+    }
+    const staticResolved = resolveStaticCredential(credential, authConfig);
+    if (staticResolved) {
+        return staticResolved;
+    }
+    if (credential.type === 'oauth2') {
+        return yield* resolveOAuth2Credential(toolName, authConfig, credential, ctx, base, policy);
+    }
+    return { headers: {} };
+}
+/**
+ * Build the request URL (and optional JSON body) for a declarative HTTP tool
+ * from endpoint template, mapping, and validated input.
+ */
+export function buildHttpToolTarget(endpoint, method, input, mapping) {
+    let urlStr = endpoint;
+    const pathParams = mapping?.pathParams ?? [];
+    for (const param of pathParams) {
+        const val = input[param];
+        if (val !== undefined) {
+            urlStr = urlStr.replaceAll(`{${param}}`, encodeURIComponent(String(val)));
+        }
+    }
+    const unreplacedMatch = urlStr.match(/\{([a-zA-Z0-9_-]+)\}/);
+    if (unreplacedMatch) {
+        throw new Error(`Missing required path parameter "${unreplacedMatch[1]}" for endpoint "${endpoint}"`);
+    }
+    const targetUrl = new URL(urlStr);
+    const queryParams = mapping?.queryParams ?? [];
+    for (const param of queryParams) {
+        const val = input[param];
+        if (val !== undefined) {
+            targetUrl.searchParams.set(param, String(val));
+        }
+    }
+    if (method === 'GET') {
+        return { url: targetUrl.toString() };
+    }
+    if (mapping?.bodyParam) {
+        return { url: targetUrl.toString(), body: JSON.stringify(input[mapping.bodyParam]) };
+    }
+    const bodyObj = {};
+    const excluded = new Set([...pathParams, ...queryParams]);
+    for (const [k, v] of Object.entries(input)) {
+        if (!excluded.has(k)) {
+            bodyObj[k] = v;
+        }
+    }
+    return { url: targetUrl.toString(), body: JSON.stringify(bodyObj) };
+}
+function parseHttpResponseData(contentType, text, status) {
+    if (contentType.includes('application/json') && text.trim().length > 0) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    if (text.trim().length === 0 && status === 204) {
+        return null;
+    }
+    return text;
+}
+export function parseToolOutput(schema, responseData) {
+    let checked = schema.safeParse(responseData);
+    if (!checked.success && typeof responseData === 'string' && responseData.trim().length > 0) {
+        try {
+            const jsonParsed = JSON.parse(responseData);
+            const retryChecked = schema.safeParse(jsonParsed);
+            if (retryChecked.success) {
+                checked = retryChecked;
+            }
+        }
+        catch {
+            // Not JSON
+        }
+    }
+    return checked;
+}
+export function modelResultFromOutput(data) {
+    return {
+        finding: typeof data === 'string' ? data : JSON.stringify(data),
+        data,
+    };
+}
+function failureOutcome(failure, callNotStarted) {
+    return { kind: 'failed', failure, callNotStarted };
+}
+/** Tool `preTool` + host `pre_tool` + mutate re-parse, mapped onto a remote outcome. */
+async function* runRemotePreBodyStages(args) {
+    const pre = yield* runPreToolPipeline(args);
+    if (pre.ok)
+        return pre;
+    if (pre.kind === 'aborted') {
+        return { kind: 'aborted', aborted: pre.aborted };
+    }
+    if (pre.kind === 'gated') {
+        return { kind: 'gated', gate: pre.gate };
+    }
+    return failureOutcome(pre.failure, true);
+}
+async function* remoteParseAndPermit(tool, rawInput, ctx, base) {
+    const started = yield* startToolExecution(tool, rawInput, ctx, base);
+    if (!started.ok) {
+        return {
+            ok: false,
+            outcome: failureOutcome({ code: 'invalid_input', message: lexiconText('tool.input_invalid') }, true),
+        };
+    }
+    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    if (permissionGate) {
+        return { ok: false, outcome: { kind: 'gated', gate: permissionGate } };
+    }
+    return { ok: true, input: started.data };
+}
+function outcomeFromUnauth(authRes) {
+    if (!authRes.unauthenticated)
+        return undefined;
+    if (authRes.gate)
+        return { kind: 'gated', gate: authRes.gate };
+    if (authRes.modelMessage) {
+        return {
+            kind: 'ok',
+            modelResult: { finding: authRes.modelMessage },
+            outputRaw: { unauthenticated: true, message: authRes.modelMessage },
+        };
+    }
+    return failureOutcome({ code: 'not_authorized', message: 'Tool authentication required' }, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    true);
+}
+async function* remoteAuthAndPreBody(args) {
+    const authRes = yield* resolveToolAuth(args.tool.name, args.tool.auth, args.ctx, args.base);
+    const unauth = outcomeFromUnauth(authRes);
+    if (unauth)
+        return unauth;
+    const preBody = yield* runRemotePreBodyStages({
+        tool: args.tool,
+        input: args.input,
+        ctx: args.ctx,
+        base: args.base,
+        stages: args.stages,
+    });
+    if (!('ok' in preBody))
+        return preBody;
+    return { ok: true, input: preBody.input, authHeaders: authRes.headers ?? {} };
+}
+function networkFailureOutcome(err) {
+    return failureOutcome({ code: 'network_error', message: messageOf(err) }, false);
+}
+/**
+ * Executes a Declarative HTTP tool.
+ * Order: schema → permission → auth → preTool/host stages → body.
+ */
+export async function* executeHttpTool(tool, rawInput, ctx, base, stages) {
+    const parsed = yield* remoteParseAndPermit(tool, rawInput, ctx, base);
+    if (!parsed.ok)
+        return parsed.outcome;
+    let input = parsed.input;
+    const prepared = yield* remoteAuthAndPreBody({ tool, input, ctx, base, stages });
+    if (!('ok' in prepared))
+        return prepared;
+    input = prepared.input;
+    let target;
+    try {
+        target = buildHttpToolTarget(tool.endpoint, tool.method, input, tool.mapping);
+    }
+    catch (err) {
+        const failure = { code: 'invalid_input', message: messageOf(err) };
+        return failureOutcome(failure, true);
+    }
+    const targetUrl = yield* guardToolTarget(target.url, ctx, base);
+    if (!targetUrl) {
+        const failure = {
+            code: 'network_blocked',
+            message: 'HTTP target blocked by network policy', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+        return failureOutcome(failure, true);
+    }
+    const headers = {
+        Accept: 'application/json',
+        ...tool.headers,
+        ...prepared.authHeaders,
+    };
+    if (tool.method !== 'GET') {
+        headers['Content-Type'] = 'application/json';
+    }
+    try {
+        const response = await fetch(targetUrl.toString(), {
+            method: tool.method,
+            headers,
+            body: target.body,
+            signal: ctx.signal,
+        });
+        if (!response.ok) {
+            const errText = await response.text();
+            const failure = {
+                code: `http_${response.status}`,
+                message: `HTTP ${response.status} from ${targetUrl.hostname}: ${errText}`,
+            };
+            return failureOutcome(failure, false);
+        }
+        const text = await response.text();
+        const responseData = parseHttpResponseData(response.headers.get('content-type') ?? '', text, response.status);
+        const checked = parseToolOutput(tool.output, responseData);
+        if (!checked.success) {
+            const failure = {
+                code: 'invalid_output',
+                message: 'HTTP response did not match tool output schema', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                details: checked.error.flatten(),
+            };
+            return failureOutcome(failure, false);
+        }
+        return {
+            kind: 'ok',
+            modelResult: modelResultFromOutput(checked.data),
+            outputRaw: checked.data,
+        };
+    }
+    catch (err) {
+        return networkFailureOutcome(err);
+    }
+}
+/** Preferred-first Streamable HTTP protocol revisions the kernel will negotiate. */
+export const MCP_PROTOCOL_VERSIONS = [
+    '2026-07-28',
+    '2025-11-25',
+    '2025-06-18',
+    '2025-03-26',
+];
+/** Parse MCP JSON or SSE (`event: message` / `data:`) bodies into a JSON-RPC object. */
+export function parseMcpRpcResponse(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        return JSON.parse(trimmed);
+    }
+    const messages = [];
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('data: '))
+            continue;
+        const payload = line.slice(6).trim();
+        if (!payload || payload === '[DONE]')
+            continue;
+        try {
+            messages.push(JSON.parse(payload));
+        }
+        catch {
+            // Ignore non-JSON SSE payloads (e.g. pings).
+        }
+    }
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.result !== undefined && msg.method === undefined)
+            return msg;
+    }
+    const last = messages.at(-1);
+    if (!last) {
+        throw new Error(`MCP server returned non-JSON response: ${text.slice(0, 200)}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return last;
+}
+/** True when a JSON-RPC error indicates the server rejected our protocol revision. */
+export function isUnsupportedMcpProtocolError(error) {
+    if (!error)
+        return false;
+    const message = error.message.toLowerCase();
+    return (message.includes('unsupported protocol version') || // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message.includes('inconsistent mcp protocol version') // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    );
+}
+function unsupportedProtocolFromHttpBody(text) {
+    try {
+        const rpcResponse = parseMcpRpcResponse(text);
+        if (rpcResponse.error && isUnsupportedMcpProtocolError(rpcResponse.error)) {
+            return rpcResponse.error;
+        }
+    }
+    catch {
+        // Fall through to raw-text heuristic for non-JSON error pages.
+    }
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (text.toLowerCase().includes('unsupported protocol version')) {
+        return { code: -32600, message: text.slice(0, 300) };
+    }
+    return undefined;
+}
+async function fetchMcpProtocolAttempt(targetUrl, baseHeaders, rpcId, mcpToolName, input, protocolVersion, signal) {
+    const jsonRpcPayload = {
+        jsonrpc: '2.0',
+        id: rpcId,
+        method: 'tools/call',
+        params: {
+            name: mcpToolName,
+            arguments: input,
+            _meta: {
+                'io.modelcontextprotocol/protocolVersion': protocolVersion,
+            },
+        },
+    };
+    const response = await fetch(targetUrl, {
+        method: 'POST',
+        headers: {
+            ...baseHeaders,
+            'MCP-Protocol-Version': protocolVersion,
+        },
+        body: JSON.stringify(jsonRpcPayload),
+        signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        const acceptRejected = response.status === 406 &&
+            text.toLowerCase().includes('accept') &&
+            protocolVersion !== MCP_PROTOCOL_VERSIONS.at(-1);
+        if (acceptRejected)
+            return { kind: 'retry' };
+        const protocolError = unsupportedProtocolFromHttpBody(text);
+        if (protocolError)
+            return { kind: 'protocol_retry', error: protocolError };
+        return {
+            kind: 'failure',
+            failure: {
+                code: `mcp_http_${response.status}`,
+                message: `MCP server error HTTP ${response.status}: ${text.slice(0, 300)}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            },
+        };
+    }
+    try {
+        const rpcResponse = parseMcpRpcResponse(text);
+        if (rpcResponse.error && isUnsupportedMcpProtocolError(rpcResponse.error)) {
+            return { kind: 'protocol_retry', error: rpcResponse.error };
+        }
+        return { kind: 'rpc', response: rpcResponse };
+    }
+    catch {
+        return {
+            kind: 'failure',
+            failure: {
+                code: 'invalid_response',
+                message: `MCP server returned non-JSON response: ${text.slice(0, 200)}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            },
+        };
+    }
+}
+async function negotiateMcpRpc(targetUrl, baseHeaders, rpcId, mcpToolName, input, signal) {
+    let lastProtocolError;
+    for (const protocolVersion of MCP_PROTOCOL_VERSIONS) {
+        const outcome = await fetchMcpProtocolAttempt(targetUrl, baseHeaders, rpcId, mcpToolName, input, protocolVersion, signal);
+        if (outcome.kind === 'retry' || outcome.kind === 'protocol_retry') {
+            if (outcome.kind === 'protocol_retry')
+                lastProtocolError = outcome.error;
+            continue;
+        }
+        if (outcome.kind === 'failure') {
+            return { failure: outcome.failure };
+        }
+        return { rpc: outcome.response };
+    }
+    return { lastProtocolError };
+}
+function extractMcpOutput(result) {
+    if (result?.content && Array.isArray(result.content)) {
+        return result.content.map((c) => c.text ?? '').join('\n');
+    }
+    return result;
+}
+function mcpResultFailure(rpcResponse) {
+    if (rpcResponse.error) {
+        return {
+            code: `mcp_rpc_error_${rpcResponse.error.code}`,
+            message: rpcResponse.error.message,
+            details: rpcResponse.error.data,
+        };
+    }
+    const result = rpcResponse.result;
+    if (result?.isError) {
+        return {
+            code: 'mcp_tool_execution_failed',
+            message: result.content?.map((c) => c.text ?? '').join('\n') ?? 'MCP Tool execution error', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        };
+    }
+    return undefined;
+}
+function interpretMcpRpc(tool, negotiated) {
+    if (negotiated.failure) {
+        return { ok: false, failure: negotiated.failure };
+    }
+    const rpcResponse = negotiated.rpc;
+    if (!rpcResponse) {
+        return {
+            ok: false,
+            failure: {
+                code: 'mcp_protocol_error',
+                message: negotiated.lastProtocolError?.message ?? 'MCP protocol negotiation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                details: negotiated.lastProtocolError?.data,
+            },
+        };
+    }
+    const resultFailure = mcpResultFailure(rpcResponse);
+    if (resultFailure) {
+        return { ok: false, failure: resultFailure };
+    }
+    const checked = parseToolOutput(tool.output, extractMcpOutput(rpcResponse.result));
+    if (!checked.success) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: 'MCP output schema validation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                details: checked.error.flatten(),
+            },
+        };
+    }
+    return { ok: true, data: checked.data };
+}
+/**
+ * Executes a Remote MCP tool over Streamable HTTP (spec revision 2026-07-28).
+ * Order: schema → permission → auth → preTool/host stages → body.
+ */
+export async function* executeMcpTool(tool, rawInput, ctx, base, stages) {
+    const permitted = yield* remoteParseAndPermit(tool, rawInput, ctx, base);
+    if (!permitted.ok)
+        return permitted.outcome;
+    const targetUrl = yield* guardToolTarget(tool.serverUrl, ctx, base);
+    if (!targetUrl) {
+        return failureOutcome({ code: 'network_blocked', message: 'MCP target blocked by network policy' }, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        true);
+    }
+    let input = permitted.input;
+    const prepared = yield* remoteAuthAndPreBody({ tool, input, ctx, base, stages });
+    if (!('ok' in prepared))
+        return prepared;
+    input = prepared.input;
+    try {
+        const interpreted = interpretMcpRpc(tool, await negotiateMcpRpc(targetUrl.toString(), {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            ...tool.headers,
+            ...prepared.authHeaders,
+        }, base.callId ?? Date.now(), tool.mcpToolName, input, ctx.signal));
+        if (!interpreted.ok) {
+            return failureOutcome(interpreted.failure, false);
+        }
+        return {
+            kind: 'ok',
+            modelResult: modelResultFromOutput(interpreted.data),
+            outputRaw: interpreted.data,
+        };
+    }
+    catch (err) {
+        return networkFailureOutcome(err);
+    }
+}

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

@@ -3,23 +3,33 @@
  *
  * @module
  */
-import type { ModelId, Profile, ToolId, TurnRequest } from '../types.js';
+import type { ModelId, ModelProfile, Profile, ToolId, TurnRequest } from '../types.js';
 import type { PromoteLoadedResult, ToolFailure, TurnToolSnapshot, WireFunctionTool } from './types.js';
 export declare function pathMatches(catalogPaths?: string[], turnPath?: string): boolean;
 export declare function applyBuiltinMutualExclusions(requested: string[]): string[];
 export declare function resolveAllowedCustomToolIds(profile: Profile, req: TurnRequest): ToolId[];
 /** Provider builtins listed on the selected model — on for the turn (path-filtered). */
-export declare function resolveModelBuiltinIds(profile: Profile, req: TurnRequest, modelId: ModelId): ToolId[];
+export declare function resolveModelBuiltinIds(profile: ModelProfile, req: TurnRequest, modelId: ModelId): ToolId[];
 export declare function wireForTool(name: string): WireFunctionTool | undefined;
 export declare function buildWire(visible: ToolId[]): WireFunctionTool[];
 export declare function promoteTool(state: TurnToolSnapshot, id: ToolId): void;
 export declare function promoteBuiltin(state: TurnToolSnapshot, id: ToolId): void;
-export declare function initialVisible(gated: ToolId[]): ToolId[];
-export declare function initialBuiltins(gated: ToolId[]): ToolId[];
-/** Build the initial tool snapshot for a turn (T0 wired; T1/T2 pending). */
-export declare function resolveTurnTools(profile: Profile, req: TurnRequest, modelId: ModelId): TurnToolSnapshot;
+/**
+ * Custom tools wired at turn start. Text/image: T0 only (T1/T2 pending).
+ * Live: every gated tool — declarations are fixed at session setup, so every
+ * allowed tool is effectively T0. Host: every gated tool — no tiers at all.
+ */
+export declare function initialVisible(profile: Profile, gated: ToolId[]): ToolId[];
+/** Builtins on at turn start — every gated builtin on live, T0 elsewhere (mutual exclusions applied). */
+export declare function initialBuiltins(profile: Profile, gated: ToolId[]): ToolId[];
+/**
+ * Build the initial tool snapshot for a turn.
+ * Text/image: T0 wired, T1/T2 pending. Live: the whole allow list and every
+ * model builtin. Host: the whole allow list, no builtins, no path gating.
+ */
+export declare function resolveTurnTools(profile: Profile, req: TurnRequest, modelId: ModelId | undefined): TurnToolSnapshot;
 /** Resolve T0 snapshot and expand T1 selections from `profile.tools.t1Policy`. */
-export declare function prepareTurnToolSnapshot(profile: Profile, req: TurnRequest, modelId: ModelId): Promise<TurnToolSnapshot>;
+export declare function prepareTurnToolSnapshot(profile: Profile, req: TurnRequest, modelId: ModelId | undefined): Promise<TurnToolSnapshot>;
 /** Deep-clone a turn snapshot so host-side concurrent invokes do not share mutable state. */
 export declare function cloneTurnToolSnapshot(state: TurnToolSnapshot): TurnToolSnapshot;
 /** Wire T1 tools selected by `profile.tools.t1Policy`. */