theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,614 @@
+/**
+ * Shared tool execution core for model-initiated and host-initiated calls.
+ *
+ * @module
+ */
+import { throwIfAborted } from '../../guardrails/error.js';
+import { lexiconText } from '../../guardrails/lexicon.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeText } from '../../guardrails/sanitize.js';
+import { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
+import { isAwaitingUserInput } from '../stages.js';
+import { failureEvent, messageOf, startToolExecution, toolEvent } from './events.js';
+import { checkPermission, isGateResumeDenied, isResumeContinuation } from './permission.js';
+import { getTool } from './registry.js';
+import { executeHttpTool, executeMcpTool, modelResultFromOutput, parseToolOutput, } from './remote.js';
+import { promoteLoadedTools } from './resolve.js';
+import { plainToolInput } from './schema.js';
+import { emitGateSettlement, runPostToolStages, runPreToolPipeline, } from './stage-run.js';
+export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
+/** Map a registered tool's type onto the origin its bytes carry. */
+function originOfTool(type) {
+    if (type === 'http')
+        return 'http';
+    if (type === 'mcp')
+        return 'mcp';
+    if (type === 'builtin')
+        return 'builtin';
+    return 'local';
+}
+function provenanceFor(tool, depth = 1) {
+    return { origin: originOfTool(tool.type), tool: tool.name, depth };
+}
+function isStreamHandler(handler) {
+    return (typeof handler === 'function' &&
+        Object.prototype.toString.call(handler) === '[object AsyncGeneratorFunction]');
+}
+const MEDIA_PART_TYPES = new Set(['image', 'audio', 'video', 'document']);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+/** Validate host-emitted InteractionPart shapes; drop invalid entries. */
+export function coerceToolResultParts(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const parts = [];
+    for (const item of raw) {
+        if (!isRecord(item) || typeof item.type !== 'string')
+            continue;
+        if (item.type === 'text' && typeof item.text === 'string') {
+            parts.push({ type: 'text', text: item.text });
+            continue;
+        }
+        if (MEDIA_PART_TYPES.has(item.type) &&
+            typeof item.mimeType === 'string' &&
+            item.mimeType.trim() &&
+            typeof item.data === 'string' &&
+            item.data.length > 0) {
+            parts.push({
+                type: item.type,
+                mimeType: item.mimeType,
+                data: item.data,
+            });
+        }
+    }
+    return parts.length > 0 ? parts : undefined;
+}
+/** Copy tool output for model `data`, omitting media `parts`. */
+export function leanToolResultData(output) {
+    if (!isRecord(output))
+        return output;
+    const { parts: _parts, ...rest } = output;
+    return rest;
+}
+/** @deprecated Gates use `ToolGate` / `phase: 'gate'`. Kept for type narrowing during migration. */
+export function isToolPause(value) {
+    return ('kind' in value &&
+        (value.kind === 'interactive' ||
+            value.kind === 'confirmation' ||
+            value.kind === 'permission' ||
+            value.kind === 'auth'));
+}
+export function* yieldHandlerSideEvent(base, event) {
+    if (event.kind === 'progress') {
+        yield toolEvent(base, { phase: 'progress', data: event.data });
+    }
+    else if (event.kind === 'trace') {
+        yield toolEvent(base, { phase: 'trace', step: event.step });
+    }
+    else if (event.kind === 'artifact') {
+        yield toolEvent(base, { phase: 'artifact', artifact: event.artifact });
+    }
+    else if (event.kind === 'warning') {
+        yield toolEvent(base, { phase: 'warning', warning: event.warning });
+    }
+}
+/** Run the handler, yielding stream side-events live; returns terminal output. */
+async function* runHandler(handler, input, ctx, base) {
+    if (isStreamHandler(handler)) {
+        let output;
+        const gen = handler(input, ctx);
+        for await (const event of gen) {
+            throwIfAborted(ctx.signal);
+            if (event.kind === 'complete') {
+                output = event.output;
+                continue;
+            }
+            yield* yieldHandlerSideEvent(base, event);
+        }
+        return output;
+    }
+    const output = await handler(input, ctx);
+    return output;
+}
+export function projectForModel(tool, output) {
+    if (tool.exposeToModel === false) {
+        return { finding: 'Completed.' };
+    }
+    if (isAwaitingUserInput(output)) {
+        return {
+            finding: lexiconText('tool.awaiting_user', { kind: output.kind, prompt: output.prompt }),
+            data: leanToolResultData(output),
+        };
+    }
+    const finding = typeof output === 'object' && output !== null && 'finding' in output
+        ? String(output.finding)
+        : JSON.stringify(output);
+    const parts = isRecord(output) && 'parts' in output ? coerceToolResultParts(output.parts) : undefined;
+    return {
+        finding: sanitizeText(finding),
+        data: leanToolResultData(output),
+        ...(parts ? { parts } : {}),
+    };
+}
+/**
+ * Format model-facing tool output for provider history continuation.
+ *
+ * Text projection only — never embeds `parts[].data`; media travels on
+ * `TurnHistoryMessage.parts` and adapters wire it from there.
+ *
+ * `executeRegisteredTool` guards at the boundary and leaves `modelText` behind, so
+ * the common path returns already-fenced text. A result recorded elsewhere — a
+ * host replaying a transcript — is guarded here instead, under full detection.
+ */
+export function formatToolResult(result) {
+    if (result.modelText !== undefined) {
+        return result.modelText;
+    }
+    return sanitizeText(composeToolText(result.finding, result.data));
+}
+/**
+ * Format a tool failure for provider history — structured so the model (or host)
+ * sees the code.
+ *
+ * The message is remote-authored on HTTP and MCP tools, so it is redacted before
+ * the kernel frames it as a system report.
+ */
+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}`,
+        data: {
+            ok: false,
+            code: failure.code,
+            message: safe,
+            ...(failure.details !== undefined ? { details: failure.details } : {}),
+        },
+    };
+}
+/** True when this tool is the profile's T2 loader: its output drives the snapshot. */
+function loadsT2(tool, ctx) {
+    if (ctx.profile.type === 'speech' || ctx.profile.type === 'live' || ctx.profile.type === 'host') {
+        return false;
+    }
+    return ctx.profile.tools.t2Loader === tool.name;
+}
+function applyT2LoaderPromotion(tool, checkedData, ctx, snapshot) {
+    if (!loadsT2(tool, ctx)) {
+        return { ok: true, output: checkedData };
+    }
+    if (!snapshot) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: lexiconText('tool.t2_loader_needs_snapshot', { tool: tool.name }),
+            },
+        };
+    }
+    const loaded = extractLoadedIds(checkedData);
+    if (!loaded) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: lexiconText('tool.t2_loader_shape', { tool: tool.name }),
+            },
+        };
+    }
+    const { promoted, failure: promoteFailure } = promoteLoadedTools(snapshot, loaded, ctx.profile);
+    if (promoteFailure) {
+        return { ok: false, failure: promoteFailure };
+    }
+    const finalOutput = { ...checkedData, loaded: promoted };
+    const rechecked = tool.output.safeParse(finalOutput);
+    if (!rechecked.success) {
+        return {
+            ok: false,
+            failure: {
+                code: 'invalid_output',
+                message: lexiconText('tool.t2_loader_output_invalid'),
+                details: rechecked.error.flatten(),
+            },
+        };
+    }
+    return { ok: true, output: rechecked.data };
+}
+/**
+ * Settle a tool call, once, for every transport: guard the provisional result,
+ * run `post_tool`, apply a host `deny` or `mutate` (re-projected and re-guarded),
+ * then emit the single terminal `tool` event with what the model actually gets.
+ * `reproject` is absent when the kernel owns the output (the T2 loader), which
+ * makes `mutate` a warning instead of a replacement.
+ */
+async function* settleToolCall(args) {
+    const { base, toolName, callId, input, stages, provisional, guard, reproject } = args;
+    let modelResult = yield* guard(provisional.modelResult);
+    let failure = 'failure' in provisional ? provisional.failure : undefined;
+    let outputRaw = 'outputRaw' in provisional ? provisional.outputRaw : undefined;
+    const callNotStarted = 'callNotStarted' in provisional ? provisional.callNotStarted : undefined;
+    let awaiting = !failure && isAwaitingUserInput(outputRaw);
+    let post;
+    if (stages) {
+        // Do not applyInject here — the text runner records the tool result first.
+        const { applyInject: _apply, ...rest } = stages;
+        post = yield* runPostToolStages({
+            stages: rest,
+            toolName,
+            callId,
+            input,
+            callNotStarted,
+            outputRaw,
+            outputModel: modelResult,
+            failure,
+            awaiting: awaiting || undefined,
+            mutable: !failure && reproject !== undefined,
+        });
+        if (post.deny) {
+            failure = { code: post.deny.code, message: post.deny.message };
+            modelResult = yield* guard(formatToolFailureForModel(failure));
+            outputRaw = undefined;
+            awaiting = false;
+        }
+        else if (post.mutate && reproject) {
+            const next = reproject(plainToolInput(post.mutate.output));
+            if (next.ok) {
+                failure = undefined;
+                outputRaw = next.outputRaw;
+                modelResult = yield* guard(next.modelResult);
+                awaiting = isAwaitingUserInput(outputRaw);
+            }
+            else {
+                failure = next.failure;
+                modelResult = yield* guard(formatToolFailureForModel(next.failure));
+                outputRaw = undefined;
+                awaiting = false;
+            }
+        }
+    }
+    yield failure
+        ? failureEvent(base, failure)
+        : toolEvent(base, { phase: 'complete', output: outputRaw });
+    return {
+        modelResult,
+        ...(failure ? { failure } : { outputRaw }),
+        ...(callNotStarted ? { callNotStarted: true } : {}),
+        ...(awaiting ? { awaiting: true } : {}),
+        ...(post?.abort !== undefined ? { aborted: post.abort } : {}),
+        ...(post?.inject?.length ? { pendingInject: post.inject } : {}),
+    };
+}
+/** Settle a call that failed before or during its body. */
+function settleToolFailure(guard, base, failure, stages, args) {
+    return settleToolCall({
+        base,
+        toolName: args.toolName,
+        callId: args.callId,
+        input: args.input,
+        stages,
+        guard,
+        provisional: {
+            failure,
+            modelResult: formatToolFailureForModel(failure),
+            ...(args.callNotStarted ? { callNotStarted: true } : {}),
+        },
+    });
+}
+/** The one guard every model-facing tool result passes through, bound to this call. */
+function resultGuard(tool, ctx, snapshot) {
+    const provenance = provenanceFor(tool);
+    const policy = resolveGuardrailPolicy(ctx.profile.guardrails);
+    const callableTools = snapshot?.executable ?? [];
+    return (result) => guardResult(result, provenance, policy, callableTools);
+}
+/** Tool `preTool` + host `pre_tool` + mutate re-parse, mapped onto a function-tool settlement. */
+async function* runFunctionPreBodyStages(args) {
+    const { tool, base, stages, guard } = args;
+    const pre = yield* runPreToolPipeline(args);
+    if (pre.ok)
+        return pre;
+    if (pre.kind === 'aborted') {
+        return { aborted: pre.aborted, callNotStarted: true };
+    }
+    if (pre.kind === 'gated') {
+        return { gated: pre.gate, callNotStarted: true };
+    }
+    return yield* settleToolFailure(guard, base, pre.failure, stages, {
+        toolName: tool.name,
+        callId: base.callId ?? '',
+        input: args.input,
+        callNotStarted: true,
+    });
+}
+function makeReproject(parse, project) {
+    return (output) => {
+        const checked = parse(output);
+        if (!checked.success) {
+            return {
+                ok: false,
+                failure: {
+                    code: 'invalid_output',
+                    message: lexiconText('tool.output_invalid_after_mutate'),
+                    details: checked.error.flatten(),
+                },
+            };
+        }
+        return { ok: true, outputRaw: checked.data, modelResult: project(checked.data) };
+    };
+}
+export async function* executeFunction(tool, rawInput, ctx, base, snapshot, stages) {
+    const guard = resultGuard(tool, ctx, snapshot);
+    const callId = base.callId ?? '';
+    const parsed = yield* startToolExecution(tool, rawInput, ctx, base);
+    if (!parsed.ok) {
+        return yield* settleToolFailure(guard, base, { code: 'invalid_input', message: lexiconText('tool.input_invalid') }, stages, { toolName: tool.name, callId, callNotStarted: true });
+    }
+    let input = parsed.data;
+    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    if (permissionGate) {
+        yield* emitGateSettlement({ base, gate: permissionGate, callId, toolName: tool.name });
+        return { gated: permissionGate, callNotStarted: true };
+    }
+    throwIfAborted(ctx.signal);
+    const preBody = yield* runFunctionPreBodyStages({ tool, input, ctx, base, stages, guard });
+    if (!('ok' in preBody)) {
+        return preBody;
+    }
+    input = preBody.input;
+    throwIfAborted(ctx.signal);
+    const fail = (failure) => settleToolFailure(guard, base, failure, stages, { toolName: tool.name, callId, input });
+    let output;
+    try {
+        output = yield* runHandler(tool.handler, input, ctx, base);
+    }
+    catch (err) {
+        return yield* fail({ code: 'handler_error', message: messageOf(err) });
+    }
+    if (output === undefined) {
+        return yield* fail({ code: 'invalid_output', message: lexiconText('tool.handler_no_output') });
+    }
+    const checked = tool.output.safeParse(output);
+    if (!checked.success) {
+        return yield* fail({
+            code: 'invalid_output',
+            message: lexiconText('tool.output_invalid'),
+            details: checked.error.flatten(),
+        });
+    }
+    const promoted = applyT2LoaderPromotion(tool, checked.data, ctx, snapshot);
+    if (!promoted.ok) {
+        return yield* fail(promoted.failure);
+    }
+    // The T2 loader's output drives the snapshot; the kernel owns it, so no mutate.
+    const ownsOutput = loadsT2(tool, ctx);
+    return yield* settleToolCall({
+        base,
+        toolName: tool.name,
+        callId,
+        input,
+        stages,
+        guard,
+        provisional: {
+            outputRaw: promoted.output,
+            modelResult: projectForModel(tool, promoted.output),
+        },
+        ...(ownsOutput
+            ? {}
+            : {
+                reproject: makeReproject((v) => tool.output.safeParse(v), (data) => projectForModel(tool, data)),
+            }),
+    });
+}
+export function notLoadedMessage(tool) {
+    if (tool.loadTier === 'T1') {
+        return lexiconText('tool.not_wired_t1', { tool: tool.name });
+    }
+    if (tool.loadTier === 'T2') {
+        return lexiconText('tool.not_loaded_t2', { tool: tool.name });
+    }
+    return lexiconText('tool.not_visible', { tool: tool.name });
+}
+export function extractLoadedIds(output) {
+    if (!output || typeof output !== 'object' || Array.isArray(output)) {
+        return undefined;
+    }
+    const loaded = output.loaded;
+    if (!Array.isArray(loaded) || !loaded.every((id) => typeof id === 'string')) {
+        return undefined;
+    }
+    return loaded;
+}
+function earlyFailure(failure) {
+    return { failure, callNotStarted: true, modelResult: formatToolFailureForModel(failure) };
+}
+export async function* executeBuiltin(tool, ctx, base, snapshot) {
+    yield toolEvent(base, { phase: 'running' });
+    throwIfAborted(ctx.signal);
+    if (!snapshot.builtins.includes(tool.name)) {
+        const failure = {
+            code: 'not_loaded',
+            message: lexiconText('tool.builtin_not_enabled', { tool: tool.name }),
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
+    }
+    const failure = {
+        code: 'provider_native',
+        message: lexiconText('tool.provider_native', { tool: tool.name }),
+    };
+    yield failureEvent(base, failure);
+    return earlyFailure(failure);
+}
+/** Snapshot / allowlist / load-tier checks before body execution. */
+function registeredEligibilityFailure(args) {
+    const { tool, profile, name, resume, snapshot } = args;
+    if (profile.type === 'speech' || !profile.tools.allow.includes(name)) {
+        return {
+            code: 'not_allowed',
+            message: lexiconText('tool.not_allowed', { tool: name, profile: profile.id }),
+        };
+    }
+    if (!snapshot)
+        return undefined;
+    const continuing = isResumeContinuation(resume);
+    if (!continuing && !snapshot.gated.includes(name)) {
+        return { code: 'not_gated', message: lexiconText('tool.not_eligible', { tool: name }) };
+    }
+    if (!snapshot.visible.includes(name)) {
+        const skipLoadCheck = continuing && tool.loadTier === 'T0';
+        if (!skipLoadCheck) {
+            return { code: 'not_loaded', message: notLoadedMessage(tool) };
+        }
+    }
+    return undefined;
+}
+async function* settleRemoteOutcome(args) {
+    const { outcome, tool, base, callId, safeInput, stages, guard } = args;
+    const name = tool.name;
+    if (outcome.kind === 'gated') {
+        if (outcome.gate.kind === 'confirmation') {
+            return { gated: outcome.gate, callNotStarted: true };
+        }
+        yield* emitGateSettlement({ base, gate: outcome.gate, callId, toolName: name });
+        return { gated: outcome.gate, callNotStarted: true };
+    }
+    if (outcome.kind === 'aborted') {
+        return { aborted: outcome.aborted, callNotStarted: true };
+    }
+    if (outcome.kind === 'failed') {
+        return yield* settleToolFailure(guard, base, outcome.failure, stages, {
+            toolName: name,
+            callId,
+            input: safeInput,
+            callNotStarted: outcome.callNotStarted,
+        });
+    }
+    return yield* settleToolCall({
+        base,
+        toolName: name,
+        callId,
+        input: safeInput,
+        stages,
+        guard,
+        provisional: { outputRaw: outcome.outputRaw, modelResult: outcome.modelResult },
+        reproject: makeReproject((v) => parseToolOutput(tool.output, v), modelResultFromOutput),
+    });
+}
+export async function* executeRegisteredTool(args) {
+    const { profile, name, input, callId, ctx, snapshot, stages } = args;
+    const tool = getTool(name);
+    const safeInput = plainToolInput(input);
+    const base = {
+        name,
+        callId,
+        arguments: typeof safeInput === 'object' && safeInput !== null && !Array.isArray(safeInput)
+            ? safeInput
+            : { value: safeInput },
+    };
+    if (!tool) {
+        const failure = {
+            code: 'unknown_tool',
+            message: lexiconText('tool.not_registered', { tool: name }),
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
+    }
+    if (tool.type === 'builtin') {
+        if (!snapshot) {
+            const failure = {
+                code: 'provider_native',
+                message: lexiconText('tool.builtin_needs_snapshot', { tool: name }),
+            };
+            yield failureEvent(base, failure);
+            return earlyFailure(failure);
+        }
+        const fullCtx = { ...ctx, callId, profile };
+        return yield* executeBuiltin(tool, fullCtx, base, snapshot);
+    }
+    const eligibility = registeredEligibilityFailure({
+        tool,
+        profile,
+        name,
+        resume: ctx.resume,
+        snapshot,
+    });
+    if (eligibility) {
+        yield failureEvent(base, eligibility);
+        return earlyFailure(eligibility);
+    }
+    // Host denied after a gate — synthetic failure + post_tool, no body.
+    if (isGateResumeDenied(ctx.resume)) {
+        return yield* settleToolFailure(resultGuard(tool, { ...ctx, callId, profile }, snapshot), base, { code: 'denied', message: lexiconText('session.tool_denied', { tool: name }) }, stages, { toolName: name, callId, input: safeInput, callNotStarted: true });
+    }
+    const fullCtx = { ...ctx, callId, profile };
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const provenance = provenanceFor(tool);
+    const argEvent = toolCallEvent(inspectToolArguments(safeInput, policy), provenance);
+    if (argEvent) {
+        yield { type: 'guardrail', guardrail: argEvent };
+    }
+    const taintVerdict = checkTaintGate(ctx.turn?.taint, tool.access, policy);
+    const taintEvent = toolCallEvent(taintVerdict, provenance);
+    if (taintEvent) {
+        yield { type: 'guardrail', guardrail: taintEvent };
+    }
+    if (taintVerdict.action === 'block') {
+        const failure = {
+            code: 'tainted_turn',
+            message: taintVerdict.rejection,
+        };
+        yield failureEvent(base, failure);
+        return earlyFailure(failure);
+    }
+    return yield* settleByType(tool, safeInput, fullCtx, base, snapshot, stages);
+}
+/** Run the body for the tool's transport and settle it through `settleToolCall`. */
+async function* settleByType(tool, safeInput, fullCtx, base, snapshot, stages) {
+    const { name } = tool;
+    if (tool.type === 'function') {
+        return yield* executeFunction(tool, safeInput, fullCtx, base, snapshot, stages);
+    }
+    if (tool.type !== 'http' && tool.type !== 'mcp') {
+        return earlyFailure({
+            code: 'unknown_tool',
+            message: lexiconText('tool.unsupported_type', { tool: name }),
+        });
+    }
+    // HTTP / MCP: schema → permission → auth → preTool → body (inside remote).
+    const remoteOutcome = tool.type === 'http'
+        ? yield* executeHttpTool(tool, safeInput, fullCtx, base, stages)
+        : yield* executeMcpTool(tool, safeInput, fullCtx, base, stages);
+    return yield* settleRemoteOutcome({
+        outcome: remoteOutcome,
+        tool,
+        base,
+        callId: base.callId ?? '',
+        safeInput,
+        stages,
+        guard: resultGuard(tool, fullCtx, snapshot),
+    });
+}
+/**
+ * Guard a tool result before it becomes model context.
+ *
+ * Every tool returns through here, so the fence, the redaction, and the
+ * provenance label are applied once and cannot be skipped by adding a tool type.
+ */
+function* guardResult(result, provenance, policy, callableTools) {
+    const guarded = guardToolResult(result.finding, result.data, provenance, policy, callableTools);
+    if (guarded.event) {
+        yield { type: 'guardrail', guardrail: guarded.event };
+    }
+    return {
+        ...result,
+        modelText: guarded.text,
+        provenance,
+        ...(guarded.suspicious ? { suspicious: guarded.suspicious } : {}),
+    };
+}
+export { startToolExecution };
+export function newCallId(name) {
+    return `call_${name}_${Date.now()}`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Built-in harness tools registered with THEORUM.
+ *
+ * @module
+ */
+/** Register harness tools shipped with THEORUM. */
+declare function registerHarnessTools(): void;
+export { registerHarnessTools };

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

@@ -0,0 +1,46 @@
+/**
+ * Built-in harness tools registered with THEORUM.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { AWAITING_USER_INPUT_STATUS } from '../schema.js';
+import { registerTool } from './registry.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(),
+});
+/** Register harness tools shipped with THEORUM. */
+function registerHarnessTools() {
+    registerTool({
+        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;
+        },
+    });
+}
+export { registerHarnessTools };

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

@@ -0,0 +1,10 @@
+/**
+ * Host-initiated tool execution entrypoint.
+ *
+ * @module
+ */
+import type { TurnEvent } from '../types.js';
+import type { InvokeToolRequest } from './types.js';
+/** Execute a registered tool without calling a model provider. */
+declare function invokeTool(request: InvokeToolRequest): AsyncGenerator<TurnEvent>;
+export { invokeTool };