theorum 0.1.15 → 1.1.3

package/esm/src/kernel/engine/session/mod.js

@@ -0,0 +1,557 @@
+/**
+ * `runSession` — long-lived live profile execution.
+ *
+ * Shares resolve / tools / canary / system / outbound gate with `runTurn`.
+ * Does not use `ModelProvider.complete()` — live is a session, not one turn.
+ *
+ * Stages: `docs/contracts/stages.md` (cycle map + `executeTool`).
+ *
+ * @module
+ */
+import { bindCanary } from '../../../guardrails/canary.js';
+import { publicError, TheorumError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../../../guardrails/events.js';
+import { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from '../../../guardrails/live-outbound-gate.js';
+import { resolveGuardrailPolicy } from '../../../guardrails/policy.js';
+import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
+import { resolveObservabilityPolicy } from '../../../observability/resolve-policy.js';
+import { buildGeminiLiveRealtimeInput, buildGeminiLiveRealtimeText, buildGeminiLiveToolResponse, buildGeminiLiveToolResponses, } from '../../../providers/google/live/framing.js';
+import { openGoogleLiveSession } from '../../../providers/google/live/session.js';
+import { providerCompleteRequest } from '../../registry/provider-request.js';
+import { resolveTurn } from '../../registry/resolve.js';
+import { runStage } from '../../stages.js';
+import { profileAllowsInject } from '../../stop.js';
+import { executeRegisteredTool, formatToolFailureForModel, formatToolResult, } from '../../tools/execute.js';
+import { cloneTurnToolSnapshot } from '../../tools/resolve.js';
+import { prepareLiveInboundText } from '../live-inbound.js';
+import { assertLiveIngress } from '../live-ingress.js';
+/** Inject on live is realtime text ingress only: no tool role, no media parts. */
+function liveInjectTexts(messages) {
+    const out = [];
+    for (const msg of messages) {
+        if (msg.role === 'tool')
+            continue;
+        if (msg.parts?.length)
+            continue;
+        const text = msg.content?.trim();
+        if (text)
+            out.push(text);
+    }
+    return out;
+}
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheorumError(`runSession requires profile.type 'live' (got '${profile.type}' for ${profile.id})`);
+    }
+}
+/**
+ * Accept a registry-resolved snapshot from the process that owns the tool
+ * registry. The profile's `tools.allow` stays the ceiling: a custom tool id
+ * outside it is refused rather than declared.
+ */
+function sessionSnapshotWithinAllow(profile, snapshot) {
+    const allow = new Set(profile.tools.allow);
+    const builtins = new Set(snapshot.builtins);
+    const outside = new Set();
+    for (const id of [...snapshot.gated, ...snapshot.visible, ...snapshot.executable]) {
+        if (!allow.has(id) && !builtins.has(id)) {
+            outside.add(id);
+        }
+    }
+    if (outside.size > 0) {
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const detail = `session snapshot declares tools outside tools.allow: ${[...outside].join(', ')}`;
+        throw new TheorumError(`Profile ${profile.id}: ${detail}`);
+    }
+    return cloneTurnToolSnapshot(snapshot);
+}
+function toTurnRequest(req) {
+    return {
+        profile: req.profile,
+        system: req.system,
+        path: req.path,
+        sessionPermissions: req.sessionPermissions,
+        sessionResumptionHandle: req.sessionResumptionHandle,
+        signal: req.signal,
+        metadata: req.metadata,
+        host: req.host,
+        input: {
+            text: '',
+            history: req.history,
+            sessionResumptionHandle: req.sessionResumptionHandle,
+        },
+    };
+}
+function applyVoiceOverride(generation, voice) {
+    if (!voice || !generation.live) {
+        return generation;
+    }
+    return {
+        ...generation,
+        live: {
+            ...generation.live,
+            voice,
+        },
+    };
+}
+function applyInitialInput(generation, input) {
+    if (!input || input.length === 0) {
+        return generation;
+    }
+    return { ...generation, input };
+}
+async function applyOutbound(gate, events, turnPhase, onWithhold) {
+    if (turnPhase === 'abort') {
+        abortLiveOutboundTurn(gate);
+        // Keep tool calls + interrupted marker; drop buffered speech via abortLiveOutboundTurn.
+        return events.filter((ev) => ev.type === 'tool' ||
+            ev.type === 'session' ||
+            (ev.type === 'done' && ev.interrupted === true));
+    }
+    const batch = await processLiveOutboundBatch(gate, events);
+    const out = [];
+    if (batch.action === 'withhold') {
+        onWithhold(batch.error);
+        return [...(batch.events ?? []), { type: 'error', error: batch.error }];
+    }
+    if (batch.action === 'emit') {
+        out.push(...batch.events);
+    }
+    if (turnPhase === 'complete') {
+        const finalized = await finalizeLiveOutboundTurn(gate);
+        if (finalized.action === 'withhold') {
+            onWithhold(finalized.error);
+            return [...out, { type: 'error', error: finalized.error }];
+        }
+        if (finalized.action === 'emit') {
+            out.push(...finalized.events);
+        }
+        // Conversational turn boundary — session stays open.
+        out.push({ type: 'done', stop: { kind: 'completed' } });
+    }
+    return out;
+}
+function* drainPendingHostEvents(pendingHostEvents) {
+    while (pendingHostEvents.length > 0) {
+        const pending = pendingHostEvents.shift();
+        if (pending)
+            yield pending;
+    }
+}
+function boundaryDoneEvents(doneBatch, turnPhase, interrupted) {
+    if (doneBatch.length > 0)
+        return doneBatch;
+    if (turnPhase === 'abort' || interrupted) {
+        return [{ type: 'done', stop: { kind: 'interrupted' }, interrupted: true }];
+    }
+    return [{ type: 'done', stop: { kind: 'completed' } }];
+}
+/** Yield non-done batch events; return the done subset for boundary handling. */
+function* yieldLiveNonDoneEvents(gated, includeMatch, withholdClose, recordAssistantText) {
+    const doneBatch = gated.filter((ev) => ev.type === 'done');
+    for (const ev of gated) {
+        if (ev.type === 'done')
+            continue;
+        if (ev.type === 'error') {
+            yield {
+                ...ev,
+                error: publicError(ev.error ?? withholdClose ?? 'guardrail withheld'),
+            };
+            continue;
+        }
+        if (ev.type === 'text' && typeof ev.text === 'string') {
+            recordAssistantText(ev.text);
+        }
+        yield projectGuardrailTurnEvent(ev, includeMatch ?? false);
+    }
+    return doneBatch;
+}
+function buildLiveSession(args) {
+    const { profile, canary, connection, gate, signal, onStage, host: sessionHost, credentials: sessionCredentials, sessionPermissions, path, snapshot, } = args;
+    let closed = false;
+    let withholdClose;
+    const pendingHostEvents = [];
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    let cycle = 'idle';
+    let cycleStep = 0;
+    const history = args.historySeed?.length
+        ? structuredClone(args.historySeed)
+        : [];
+    /** Serialize stage + ingress so concurrent send* cannot interleave cycles. */
+    let ingressChain = Promise.resolve();
+    const recordUserText = (text) => {
+        const trimmed = text.trim();
+        if (trimmed)
+            history.push({ role: 'user', content: trimmed });
+    };
+    const recordAssistantText = (text) => {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        const last = history.at(-1);
+        if (last?.role === 'assistant' && typeof last.content === 'string' && !last.tool_calls) {
+            last.content = `${last.content}${trimmed}`;
+            return;
+        }
+        history.push({ role: 'assistant', content: trimmed });
+    };
+    const recordToolSettle = (tool) => {
+        const args = tool.input && typeof tool.input === 'object' && !Array.isArray(tool.input)
+            ? tool.input
+            : {};
+        const modelResult = tool.failure
+            ? formatToolFailureForModel(tool.failure)
+            : tool.output !== undefined
+                ? {
+                    finding: typeof tool.output === 'string' ? tool.output : JSON.stringify(tool.output),
+                    data: tool.output,
+                }
+                : formatToolFailureForModel({
+                    code: 'error',
+                    message: 'Tool settled without output', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                });
+        history.push({
+            role: 'assistant',
+            tool_calls: [
+                {
+                    id: tool.callId,
+                    type: 'function',
+                    function: {
+                        name: tool.name,
+                        arguments: JSON.stringify(args),
+                    },
+                },
+            ],
+        }, {
+            role: 'tool',
+            tool_call_id: tool.callId,
+            name: tool.name,
+            content: formatToolResult(modelResult),
+        });
+    };
+    const enqueuePending = (ev) => {
+        pendingHostEvents.push(projectGuardrailTurnEvent(ev, includeMatch));
+    };
+    const sendJson = (payload) => {
+        if (closed) {
+            throw new TheorumError('Live session is closed'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        connection.send(JSON.stringify(payload));
+    };
+    const runCycleStage = async (stage, extra) => {
+        const gen = runStage({
+            ...extra,
+            stage,
+            step: Math.max(1, cycleStep),
+            history,
+            handlers: onStage ? [onStage] : [],
+            guardrails: profile.guardrails,
+            injectAllowed: profileAllowsInject(profile),
+            host: sessionHost,
+            signal,
+        });
+        let result = await gen.next();
+        while (!result.done) {
+            enqueuePending(result.value);
+            result = await gen.next();
+        }
+        return {
+            abort: result.value.abort,
+            injectTexts: liveInjectTexts(result.value.inject),
+        };
+    };
+    const ingestPreparedLiveText = (text) => {
+        const prepared = prepareLiveInboundText(profile, text);
+        if (prepared.guardrail) {
+            enqueuePending(prepared.guardrail);
+        }
+        recordUserText(prepared.text);
+        sendJson(buildGeminiLiveRealtimeText(prepared.text));
+    };
+    const applyInjectTexts = (texts) => {
+        for (const text of texts) {
+            // Cycle already open — write without re-entering pre_turn.
+            assertLiveIngress(profile, 'text');
+            ingestPreparedLiveText(text);
+        }
+    };
+    const openCycleIfNeeded = async () => {
+        if (cycle === 'open')
+            return { aborted: false };
+        cycle = 'open';
+        cycleStep += 1;
+        const pre = await runCycleStage('pre_turn');
+        if (pre.abort) {
+            const done = {
+                type: 'done',
+                stop: { kind: 'cancelled' },
+                interrupted: true,
+            };
+            enqueuePending(done);
+            await runCycleStage('post_turn', { stop: { kind: 'cancelled' } });
+            cycle = 'idle';
+            return { aborted: true };
+        }
+        if (pre.injectTexts.length) {
+            await applyInjectTexts(pre.injectTexts);
+        }
+        return { aborted: false };
+    };
+    const endCycleAroundDone = async function* (doneEvents) {
+        if (cycle !== 'open') {
+            for (const ev of doneEvents)
+                yield ev;
+            return;
+        }
+        const before = await runCycleStage('before_end', {
+            stop: doneEvents.find((e) => e.type === 'done')?.stop,
+        });
+        if (before.abort) {
+            yield { type: 'done', stop: { kind: 'cancelled' }, interrupted: true };
+            await runCycleStage('post_turn', { stop: { kind: 'cancelled' } });
+            cycle = 'idle';
+            return;
+        }
+        if (before.injectTexts.length) {
+            await applyInjectTexts(before.injectTexts);
+        }
+        for (const ev of doneEvents) {
+            yield ev;
+        }
+        const terminal = doneEvents.find((e) => e.type === 'done');
+        await runCycleStage('post_turn', { stop: terminal?.stop });
+        cycle = 'idle';
+    };
+    const withIngress = (fn) => {
+        const next = ingressChain.then(fn, fn);
+        ingressChain = next.then(() => undefined, () => undefined);
+        return next;
+    };
+    const session = {
+        profileId: profile.id,
+        canary,
+        async *events() {
+            try {
+                for await (const item of connection.batches()) {
+                    throwIfAborted(signal);
+                    yield* drainPendingHostEvents(pendingHostEvents);
+                    if (item.type === 'closed') {
+                        break;
+                    }
+                    if (item.type === 'error') {
+                        yield toErrorEvent(item.error);
+                        break;
+                    }
+                    const gated = await applyOutbound(gate, item.events, item.turnPhase, (error) => {
+                        withholdClose = error;
+                    });
+                    const doneBatch = yield* yieldLiveNonDoneEvents(gated, includeMatch, withholdClose, recordAssistantText);
+                    const interrupted = doneBatch.some((ev) => ev.type === 'done' && ev.interrupted);
+                    const completeBoundary = item.turnPhase === 'complete' || item.turnPhase === 'abort' || doneBatch.length > 0;
+                    // Boundary batches (`interactionStatus: IDLE`, or bare `turnComplete` when the
+                    // provider sends no status) often have no folded `done` — still end the cycle.
+                    if (completeBoundary && cycle === 'open') {
+                        const boundaryDone = boundaryDoneEvents(doneBatch, item.turnPhase, interrupted);
+                        for await (const ev of endCycleAroundDone(boundaryDone)) {
+                            yield projectGuardrailTurnEvent(ev, includeMatch);
+                        }
+                        yield* drainPendingHostEvents(pendingHostEvents);
+                    }
+                    else if (doneBatch.length > 0) {
+                        for (const ev of doneBatch) {
+                            yield projectGuardrailTurnEvent(ev, includeMatch);
+                        }
+                    }
+                    if (withholdClose) {
+                        connection.close(1011, 'guardrail withheld');
+                        break;
+                    }
+                }
+                yield* drainPendingHostEvents(pendingHostEvents);
+            }
+            finally {
+                closed = true;
+                connection.close();
+            }
+        },
+        sendAudio(audio) {
+            return withIngress(async () => {
+                if (!audio.data)
+                    return;
+                assertLiveIngress(profile, 'audio');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                sendJson(buildGeminiLiveRealtimeInput({
+                    type: 'audio',
+                    mimeType: audio.mimeType ?? 'audio/pcm;rate=16000',
+                    data: audio.data,
+                }));
+            });
+        },
+        sendVideo(video) {
+            return withIngress(async () => {
+                assertLiveIngress(profile, 'video');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                sendJson(buildGeminiLiveRealtimeInput({
+                    type: 'video',
+                    mimeType: video.mimeType ?? 'image/jpeg',
+                    data: video.data,
+                }));
+            });
+        },
+        sendText(text) {
+            return withIngress(async () => {
+                assertLiveIngress(profile, 'text');
+                const opened = await openCycleIfNeeded();
+                if (opened.aborted)
+                    return;
+                ingestPreparedLiveText(text);
+            });
+        },
+        async executeTool(toolArgs) {
+            if (closed) {
+                throw new TheorumError('Live session is closed'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            const handlers = onStage ? [onStage] : [];
+            const exec = executeRegisteredTool({
+                profile,
+                name: toolArgs.name,
+                input: toolArgs.input ?? {},
+                callId: toolArgs.callId,
+                ctx: {
+                    sessionPermissions,
+                    credentials: toolArgs.credentials ?? sessionCredentials,
+                    path,
+                    signal,
+                    resume: toolArgs.resume,
+                    host: toolArgs.host ?? sessionHost,
+                    turn: { step: Math.max(1, cycleStep) },
+                },
+                snapshot,
+                stages: {
+                    handlers,
+                    profile,
+                    step: Math.max(1, cycleStep),
+                    history: () => history,
+                    injectAllowed: profileAllowsInject(profile),
+                    host: toolArgs.host ?? sessionHost,
+                    signal,
+                },
+            });
+            let settlement;
+            while (true) {
+                const next = await exec.next();
+                if (next.done) {
+                    settlement = next.value;
+                    break;
+                }
+                enqueuePending(next.value);
+            }
+            if (!settlement || typeof settlement !== 'object') {
+                return {};
+            }
+            const s = settlement;
+            if (s.gated) {
+                return { gated: s.gated };
+            }
+            // post_tool inject on live → schedule text ingress
+            if (s.pendingInject?.length) {
+                const texts = liveInjectTexts(s.pendingInject);
+                if (texts.length) {
+                    await withIngress(async () => {
+                        const opened = await openCycleIfNeeded();
+                        if (!opened.aborted)
+                            await applyInjectTexts(texts);
+                    });
+                }
+            }
+            const outputModel = s.modelResult;
+            if (outputModel !== undefined || s.failure) {
+                recordToolSettle({
+                    name: toolArgs.name,
+                    callId: toolArgs.callId,
+                    input: toolArgs.input,
+                    output: s.outputRaw ?? outputModel?.data ?? outputModel,
+                    failure: s.failure,
+                });
+                const upstream = outputModel ??
+                    {
+                        finding: s.failure ? `Tool error (${s.failure.code}): ${s.failure.message}` : 'error',
+                        data: s.failure,
+                    };
+                sendJson(buildGeminiLiveToolResponse(toolArgs.callId, toolArgs.name, upstream.data ?? upstream));
+            }
+            return {
+                outputRaw: s.outputRaw,
+                outputModel,
+                failure: s.failure,
+                awaiting: s.awaiting,
+            };
+        },
+        sendToolResponse(id, name, output) {
+            sendJson(buildGeminiLiveToolResponse(id, name, output));
+        },
+        sendToolResponses(responses) {
+            sendJson(buildGeminiLiveToolResponses(responses));
+        },
+        close(reason = 'session-closed') {
+            if (closed)
+                return Promise.resolve();
+            closed = true;
+            connection.close(1000, reason);
+            return Promise.resolve();
+        },
+    };
+    if (args.openInitialCycle) {
+        void withIngress(async () => {
+            await openCycleIfNeeded();
+        });
+    }
+    return session;
+}
+/**
+ * Open a gated Gemini Live session for a `type: 'live'` profile.
+ *
+ * Hosts bridge browser sockets and tool dispatch; THEORUM owns Gemini WS,
+ * framing, inbound prep, outbound canary/egress gates, and live stages.
+ */
+export async function runSession(req, options) {
+    const turnReq = toTurnRequest(req);
+    const safe = sanitizeTurnRequest(turnReq);
+    throwIfAborted(safe.signal);
+    const { profile, generation: gen0 } = resolveTurn(safe);
+    assertLiveProfile(profile);
+    if (req.snapshot) {
+        gen0.tools = sessionSnapshotWithinAllow(profile, req.snapshot);
+    }
+    gen0.builtins = gen0.tools.builtins;
+    let generation = applyVoiceOverride(gen0, req.voice);
+    const hasInitialInput = Boolean(req.input && req.input.length > 0);
+    generation = applyInitialInput(generation, req.input);
+    const system = bindCanary(generation.resolvedSystem, generation.canary, resolveGuardrailPolicy(profile.guardrails).canaryBindNote);
+    const completeReq = {
+        ...providerCompleteRequest(generation, system),
+        signal: safe.signal,
+    };
+    const gate = createLiveOutboundGateSession(profile, generation.canary || undefined);
+    const connection = await openGoogleLiveSession(completeReq, options.gemini, options.openWebSocket);
+    return buildLiveSession({
+        profile,
+        canary: generation.canary,
+        connection,
+        gate,
+        signal: safe.signal,
+        onStage: req.onStage,
+        host: req.host,
+        credentials: req.credentials,
+        sessionPermissions: req.sessionPermissions,
+        path: req.path,
+        snapshot: gen0.tools,
+        historySeed: req.history,
+        openInitialCycle: hasInitialInput,
+    });
+}

package/esm/src/kernel/interaction-parts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * InteractionPart wire helpers shared by kernel history + provider adapters.
+ *
+ * @module
+ */
+import type { InteractionMediaRefPart, InteractionPart } from './types.js';
+/**
+ * Map an InteractionPart to the Google Interactions / function_result wire shape.
+ * Reference parts emit `{ type, mimeType, uri }`; `toGoogleValue` snake-cases
+ * `mimeType` → `mime_type`, which is the documented Interactions file input.
+ */
+export declare function wireInteractionPart(part: InteractionPart): Record<string, string>;
+/** True when the part carries a provider file reference instead of inline bytes. */
+export declare function isMediaRefPart(part: InteractionPart): part is InteractionMediaRefPart;

package/esm/src/kernel/interaction-parts.js

@@ -0,0 +1,23 @@
+/**
+ * InteractionPart wire helpers shared by kernel history + provider adapters.
+ *
+ * @module
+ */
+/**
+ * Map an InteractionPart to the Google Interactions / function_result wire shape.
+ * Reference parts emit `{ type, mimeType, uri }`; `toGoogleValue` snake-cases
+ * `mimeType` → `mime_type`, which is the documented Interactions file input.
+ */
+export function wireInteractionPart(part) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    if ('uri' in part) {
+        return { type: part.type, mimeType: part.mimeType, uri: part.uri };
+    }
+    return { type: part.type, mimeType: part.mimeType, data: part.data };
+}
+/** True when the part carries a provider file reference instead of inline bytes. */
+export function isMediaRefPart(part) {
+    return part.type !== 'text' && 'uri' in part;
+}

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

@@ -1,22 +1,33 @@
 /**
  * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
  *
- * This entrypoint is type-first. Host applications import from here when they
- * want to declare profiles, tool schemas, provider adapters, turn requests, or
- * trace-safe event handlers without importing provider implementations.
- *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export * from './auth/mod.js';
 export type { CompactionSplit, CompactionTokens } from './engine/compaction.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
+export type { LiveIngressChannel } from './engine/live-ingress.js';
+export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
-export type { ProfileDefinition } from './registry/profiles.js';
+export type { RunSessionOptions } from './engine/session/mod.js';
+export { runSession } from './engine/session/mod.js';
+export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export type { MediaInputChannel } from './registry/catalog.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
+export type { HostProfileDefinition, ImageProfileDefinition, LiveProfileDefinition, ProfileDefinition, ProfileDefinitionBase, SpeechProfileDefinition, TextProfileDefinition, } from './registry/profiles.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
-export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { projectProfile, projectProfileObject, requireModelProfile, resolveTurn, } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
-export { executeTool } from './registry/tools.js';
-export type { ProfileResumeSpec, TurnContinueFrom, TurnStop, TurnStopKind } from './stop.js';
-export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './stop.js';
+export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, PlaygroundAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
+export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, coerceSpeechFormat, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, isSpeechFormatAllowedForProtocol, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOTS, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, OVERFLOW_KEY_SLOTS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SCHEMA_ENFORCEMENTS, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, speechFormatsForProtocol, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageResult, } from './stages.js';
+export { applyStageResult, isAwaitingUserInput, parseAwaitingUserInput, parseToolGate, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export type { ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export type { McpProtocolVersion, McpRpcResponse } from './tools/mod.js';
+export { coerceToolResultParts, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, getTool, hasTool, invokeTool, isUnsupportedMcpProtocolError, leanToolResultData, listBuiltinIds, listFunctionIds, listTools, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, registerTool, registerTools, requireTool, resetTools, resolveToolAuth, } from './tools/mod.js';
+export type { ToolPause } from './tools/types.js';
 export type * from './types.js';

package/esm/src/kernel/mod.js

@@ -1,18 +1,21 @@
 /**
  * Profile, turn, tool, provider, egress, and event contracts for THEORUM.
  *
- * This entrypoint is type-first. Host applications import from here when they
- * want to declare profiles, tool schemas, provider adapters, turn requests, or
- * trace-safe event handlers without importing provider implementations.
- *
  * @module
  */
 import "../../_dnt.polyfills.js";
+export * from './auth/mod.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
+export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { runSession } from './engine/session/mod.js';
+export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
-export { projectProfile, resolveTurn } from './registry/resolve.js';
+export { projectProfile, projectProfileObject, requireModelProfile, resolveTurn, } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
-export { executeTool } from './registry/tools.js';
-export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './stop.js';
+export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, coerceSpeechFormat, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, isSpeechFormatAllowedForProtocol, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOTS, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, OVERFLOW_KEY_SLOTS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SCHEMA_ENFORCEMENTS, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, speechFormatsForProtocol, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export { applyStageResult, isAwaitingUserInput, parseAwaitingUserInput, parseToolGate, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { coerceToolResultParts, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, getTool, hasTool, invokeTool, isUnsupportedMcpProtocolError, leanToolResultData, listBuiltinIds, listFunctionIds, listTools, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, registerTool, registerTools, requireTool, resetTools, resolveToolAuth, } from './tools/mod.js';