@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,50 @@
+import type { ApiKeyCredential, BearerCredential } from '../auth/types.js';
+import type { ToolPermission } from '../schema.js';
+import type { ToolAuthChallenge } from '../turn-events.js';
+import type { InvokeToolResume } from './types.js';
+/** What a sign-in gate asks for, minus the challenge's OAuth details. */
+export type ToolGateAuth = Pick<ToolAuthChallenge, 'slot' | 'authType' | 'service'>;
+/** A bad value is refused when `owner` is built, not when a gate expires. */
+export declare function resolveGateTtlMs(owner: string, gateTtlMs: number | undefined): number;
+export declare function gateExpired(createdAt: number, now: number, ttlMs: number): boolean;
+export declare const GATE_DECISIONS: readonly ["approve", "deny", "abandon"];
+export type GateDecision = (typeof GATE_DECISIONS)[number];
+/** `edited.from` is the input the model proposed. */
+export type GateAnswer = {
+    decision: 'approve';
+    edited?: {
+        from: Record<string, unknown>;
+    };
+} | {
+    decision: 'deny' | 'abandon';
+};
+/** `signIn` when the gate answered is a sign-in, so a refusal tells the model so. */
+export declare function resumeForAnswer(answer: GateAnswer, signIn?: boolean): InvokeToolResume;
+/** Only a `session_consent` approval lasts the session; any other gate is approved for this call only. */
+export declare function sessionPermissionsAfterApproval(sessionPermissions: readonly string[], toolName: string, permission?: ToolPermission): string[];
+export type GateAnswerRequest = {
+    callId: string;
+    decision: GateDecision;
+    /** The user's edit; approvals only. */
+    input?: unknown;
+    /** The key typed at a sign-in gate; approvals only. */
+    secret?: string;
+};
+export type HeldGatedCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+    permission?: ToolPermission;
+    /** Absent on any gate other than sign-in. */
+    auth?: ToolGateAuth;
+};
+export type AnsweredGate = {
+    resume: InvokeToolResume;
+    input: unknown;
+    sessionPermissions: string[];
+    typed?: {
+        slot: string;
+        credential: BearerCredential | ApiKeyCredential;
+    };
+};
+/** Shared by `createTheoremHandler` and `runSession`. A refused key throws, so the gate keeps waiting for another. */
+export declare function answerGatedCall(request: GateAnswerRequest, call: HeldGatedCall, sessionPermissions: readonly string[]): AnsweredGate;

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

@@ -0,0 +1,54 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { credentialForSignInGate } from '../auth/typed-secret.js';
+const DEFAULT_GATE_TTL_MS = 30 * 60 * 1000;
+/** A bad value is refused when `owner` is built, not when a gate expires. */
+export function resolveGateTtlMs(owner, gateTtlMs) {
+    const ttl = gateTtlMs ?? DEFAULT_GATE_TTL_MS;
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+        throw new TheoremError('config', `${owner} gateTtlMs must be a positive number of milliseconds; got ${ttl}.`);
+    }
+    return ttl;
+}
+export function gateExpired(createdAt, now, ttlMs) {
+    return now - createdAt >= ttlMs;
+}
+export const GATE_DECISIONS = ['approve', 'deny', 'abandon'];
+/** `signIn` when the gate answered is a sign-in, so a refusal tells the model so. */
+export function resumeForAnswer(answer, signIn = false) {
+    if (answer.decision === 'approve') {
+        return answer.edited ? { granted: true, edited: answer.edited } : { granted: true };
+    }
+    return {
+        granted: false,
+        cause: answer.decision === 'deny' ? 'declined' : 'abandoned',
+        ...(signIn ? { signIn } : {}),
+    };
+}
+/** Only a `session_consent` approval lasts the session; any other gate is approved for this call only. */
+export function sessionPermissionsAfterApproval(sessionPermissions, toolName, permission) {
+    if (permission !== 'session_consent' || sessionPermissions.includes(toolName)) {
+        return [...sessionPermissions];
+    }
+    return [...sessionPermissions, toolName];
+}
+/** Shared by `createTheoremHandler` and `runSession`. A refused key throws, so the gate keeps waiting for another. */
+export function answerGatedCall(request, call, sessionPermissions) {
+    const { callId, decision, input, secret } = request;
+    if ((input !== undefined || secret !== undefined) && decision !== 'approve') {
+        throw new TheoremError('request', `only an approval takes edited input or a secret (call ${callId})`);
+    }
+    if (decision !== 'approve') {
+        return {
+            resume: resumeForAnswer({ decision }, call.auth !== undefined),
+            input: call.arguments,
+            sessionPermissions: [...sessionPermissions],
+        };
+    }
+    const typed = secret === undefined ? undefined : credentialForSignInGate(call.auth, secret);
+    return {
+        resume: resumeForAnswer(input === undefined ? { decision } : { decision, edited: { from: call.arguments } }),
+        input: input ?? call.arguments,
+        sessionPermissions: sessionPermissionsAfterApproval(sessionPermissions, call.name, call.permission),
+        ...(typed ? { typed } : {}),
+    };
+}

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

@@ -0,0 +1,16 @@
+import { AWAITING_USER_INPUT_STATUS } from '../schema.js';
+import type { ToolDefinitionInput } from './types.js';
+type AskKind = 'confirm' | 'choice' | 'text';
+type AskInput = {
+    kind: AskKind;
+    prompt: string;
+    options?: string[];
+};
+type AskOutput = AskInput & {
+    status: typeof AWAITING_USER_INPUT_STATUS;
+};
+/** A scope of its own registers it with `tools.register`. */
+declare const askUserTool: ToolDefinitionInput<AskInput, AskOutput>;
+declare function registerHarnessTools(): void;
+export type { AskInput, AskKind, AskOutput };
+export { askUserTool, registerHarnessTools };

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { registerTool } from '../default-scope.js';
+import { AWAITING_USER_INPUT_STATUS } from '../schema.js';
+const AskInputSchema = z.object({
+    kind: z.enum(['confirm', 'choice', 'text']),
+    prompt: z.string().trim().min(1),
+    options: z.array(z.string()).optional(),
+});
+const AskOutputSchema = z.object({
+    status: z.literal(AWAITING_USER_INPUT_STATUS),
+    kind: z.enum(['confirm', 'choice', 'text']),
+    prompt: z.string().trim().min(1),
+    options: z.array(z.string()).optional(),
+});
+/** A scope of its own registers it with `tools.register`. */
+const askUserTool = {
+    type: 'function',
+    name: 'ask_user',
+    description: 'Ask the user a question (completes with awaiting_user_input)', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    category: 'conversation',
+    access: 'read-only',
+    paths: ['*'],
+    loadTier: 'T0',
+    permission: 'auto',
+    input: AskInputSchema,
+    output: AskOutputSchema,
+    handler: (input) => {
+        const out = {
+            status: AWAITING_USER_INPUT_STATUS,
+            kind: input.kind,
+            prompt: input.prompt,
+        };
+        if (input.kind === 'choice' && input.options?.length) {
+            out.options = input.options;
+        }
+        return out;
+    },
+};
+function registerHarnessTools() {
+    registerTool(askUserTool);
+}
+export { askUserTool, registerHarnessTools };

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

@@ -0,0 +1,10 @@
+import type { TraceSink } from '../../observability/trace-sink.js';
+import type { KernelRegistry } from '../registry/kernel-registry.js';
+import type { TurnEvent } from '../types.js';
+import type { InvokeToolRequest } from './types.js';
+/**
+ * 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.
+ */
+declare function invokeTool(registry: KernelRegistry, request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+export { invokeTool };

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

@@ -0,0 +1,129 @@
+import { isAbortError, TheoremError, toErrorEvent, withPublicWording, } from '../../guardrails/error.js';
+import { resolveTraceWriter } from '../../observability/policy.js';
+import { writeSpans } from '../../observability/trace.js';
+import { startTrace, } from '../../observability/trace-span.js';
+import { startToolTrace, toolSpanName } from '../engine/tool-trace.js';
+import { 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 { 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') {
+        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)
+    }
+    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.
+ */
+async function* invokeTool(registry, request, sinkOverride) {
+    const known = registry.profiles.find(request.profile);
+    const { sink, policy } = resolveTraceWriter({
+        override: sinkOverride,
+        observability: known?.observability,
+    });
+    const callId = request.callId ?? newCallId(request.name);
+    const tree = startTrace(toolSpanName(request.name), {
+        attributes: {
+            'gen_ai.agent.name': request.profile,
+            ...optional('gen_ai.conversation.id', request.conversationId),
+        },
+        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);
+    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);
+        }
+    }
+    catch (err) {
+        failBeforeTool(isAbortError(err) ? { outcome: 'cancelled' } : { outcome: 'error', thrown: err });
+        throw err;
+    }
+    finally {
+        await writeSpans(sink, tree.collect(), policy, request.metadata);
+    }
+}
+async function* invokeTraced(registry, request, callId, openSpan, failBeforeTool, traceparent) {
+    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));
+    }
+    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;
+        }
+    }
+    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,
+            },
+        });
+        gated = settlement.gated !== undefined;
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+    }
+    yield turnDoneOf({ stop: { kind: gated ? 'gate' : 'completed' }, traceparent }, snapshot);
+}
+export { invokeTool };

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

@@ -0,0 +1,20 @@
+/**
+ * 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 credential is hashed, 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,64 @@
+/**
+ * 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;
+// 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;
+            // 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 credential is hashed, 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 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('')}`;
+}

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

@@ -0,0 +1,9 @@
+export { 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 { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
+export type * from './types.js';

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

@@ -0,0 +1,6 @@
+export { 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 { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';

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

@@ -0,0 +1,11 @@
+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.
+ */
+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;

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

@@ -0,0 +1,25 @@
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeText } from '../../guardrails/sanitize.js';
+import { composeToolText, guardToolFailureText } 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.
+ */
+export function formatToolResult(result) {
+    if (result.modelText !== undefined) {
+        return result.modelText;
+    }
+    return sanitizeText(composeToolText(result.finding, result.data));
+}
+/** 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);
+    return {
+        finding: `Tool error (${failure.code}): ${safe}`,
+        // The finding already says the code and message; only details are new.
+        ...(failure.details !== undefined ? { data: { details: failure.details } } : {}),
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { InvokeToolResume, ToolGate, 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;
+export declare function checkPermission(toolName: string, permission: ToolPermission, sessionPermissions?: string[], resume?: InvokeToolResume): ToolGate | null;

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

@@ -0,0 +1,38 @@
+export function isResumeContinuation(resume) {
+    return typeof resume?.granted === 'boolean';
+}
+export function isGateResumeGranted(resume) {
+    return resume?.granted === true;
+}
+export function isGateResumeDenied(resume) {
+    return resume?.granted === false;
+}
+export function permissionGranted(toolName, sessionPermissions) {
+    if (!sessionPermissions) {
+        return false;
+    }
+    return sessionPermissions.includes('*') || sessionPermissions.includes(toolName);
+}
+export function checkPermission(toolName, permission, sessionPermissions, resume) {
+    if (permission === 'auto') {
+        return null;
+    }
+    if (permission === 'always_confirm') {
+        if (resume?.granted === true) {
+            return null;
+        }
+        return {
+            kind: 'permission',
+            tool: toolName,
+            permission,
+        };
+    }
+    if (permissionGranted(toolName, sessionPermissions)) {
+        return null;
+    }
+    return {
+        kind: 'permission',
+        tool: toolName,
+        permission,
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { Profile, ToolId } from '../types.js';
+import type { ToolRegistry } from './registry.js';
+import type { RegisteredTool } from './types.js';
+declare function projectTools(tools: ToolRegistry, profile: Profile): Array<RegisteredTool | {
+    name: ToolId;
+    missing: true;
+}>;
+export { projectTools };

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

@@ -0,0 +1,25 @@
+import { profileToolAllow } from './resolve.js';
+function projectTool(tools, name) {
+    const tool = tools.get(name);
+    if (!tool) {
+        return { name, missing: true };
+    }
+    return tool;
+}
+function builtInToolIds(profile) {
+    const seen = new Set();
+    if (profile.type === 'host' || profile.type === 'decision') {
+        return [];
+    }
+    for (const binding of Object.values(profile.models)) {
+        for (const id of binding.builtInTools ?? []) {
+            seen.add(id);
+        }
+    }
+    return [...seen];
+}
+function projectTools(tools, profile) {
+    const ids = [...profileToolAllow(profile), ...builtInToolIds(profile)];
+    return ids.map((name) => projectTool(tools, name));
+}
+export { projectTools };

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

@@ -0,0 +1,20 @@
+import { type McpSessionCache } from './mcp-sessions.js';
+import type { RegisteredTool, ToolDefinitionInput } from './types.js';
+interface ToolRegistry {
+    /** Replaces a tool of the same name. */
+    register<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
+    registerMany(defs: ToolDefinitionInput[]): RegisteredTool[];
+    get(name: string): RegisteredTool | undefined;
+    /** Throws when there is none. */
+    require(name: string): RegisteredTool;
+    has(name: string): boolean;
+    list(): RegisteredTool[];
+    /** Also forgets the MCP sessions. */
+    reset(): void;
+    /** Sessions for this scope's MCP servers that require one; never shared across scopes. */
+    readonly mcpSessions: McpSessionCache;
+}
+/** Registration is not synchronized: register a scope's tools before its turns or invokes run. */
+declare function createToolRegistry(): ToolRegistry;
+export type { ToolRegistry };
+export { createToolRegistry };

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

@@ -0,0 +1,84 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { activityLabelProblem } from './activity-label.js';
+import { createMcpSessionCache } from './mcp-sessions.js';
+import { assertFixedEndpointOrigin, jsonSchemaFromZod, validateToolInputSchema, validateToolOutputSchema, } from './schema.js';
+function schemasFromZod(def) {
+    const inputSchema = jsonSchemaFromZod(def.input, 'input');
+    validateToolInputSchema(inputSchema);
+    const outputSchema = jsonSchemaFromZod(def.output, 'output');
+    validateToolOutputSchema(outputSchema);
+    const labels = {
+        activity: { input: inputSchema },
+        activityPast: { input: inputSchema, output: outputSchema },
+    };
+    for (const field of ['activity', 'activityPast']) {
+        const template = def.labels?.[field];
+        const problem = template ? activityLabelProblem(template, labels[field]) : undefined;
+        if (problem) {
+            throw new TheoremError('config', `Tool "${def.name}" ${field} label: ${problem}`);
+        }
+    }
+    return { inputSchema, outputSchema };
+}
+/** The person is told which service they sign in to; the tool's builder names it, never the model or the server. */
+function assertAuthService(name, auth) {
+    if (auth && (typeof auth.service !== 'string' || !auth.service.trim())) {
+        throw new TheoremError('config', `Tool "${name}" signs in with slot "${auth.slot}" but names no service`);
+    }
+}
+function normalizeHttp(def) {
+    assertFixedEndpointOrigin(def.endpoint);
+    assertAuthService(def.name, def.auth);
+    return { ...def, type: 'http', ...schemasFromZod(def) };
+}
+function normalizeMcp(def) {
+    assertAuthService(def.name, def.auth);
+    return { ...def, type: 'mcp', ...schemasFromZod(def) };
+}
+function normalizeFunction(def) {
+    assertAuthService(def.name, def.auth);
+    return { ...def, type: 'function', ...schemasFromZod(def) };
+}
+function normalizeToolDefinition(def) {
+    if (def.type === 'builtin') {
+        return def;
+    }
+    if (def.type === 'http') {
+        return normalizeHttp(def);
+    }
+    if (def.type === 'mcp') {
+        return normalizeMcp(def);
+    }
+    return normalizeFunction(def);
+}
+/** Registration is not synchronized: register a scope's tools before its turns or invokes run. */
+function createToolRegistry() {
+    const tools = new Map();
+    const mcpSessions = createMcpSessionCache();
+    const get = (name) => tools.get(name);
+    const register = (def) => {
+        const normalized = normalizeToolDefinition(def);
+        tools.set(normalized.name, normalized);
+        return normalized;
+    };
+    return {
+        register,
+        registerMany: (defs) => defs.map((def) => register(def)),
+        get,
+        require(name) {
+            const tool = get(name);
+            if (!tool) {
+                throw new TheoremError('config', `Tool '${name}' is not registered`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            return tool;
+        },
+        has: (name) => tools.has(name),
+        list: () => [...tools.values()],
+        reset: () => {
+            tools.clear();
+            mcpSessions.clear();
+        },
+        mcpSessions,
+    };
+}
+export { createToolRegistry };