@theoremjs/react 0.0.0-stage → 0.3.0

package/server/handler.js

@@ -0,0 +1,568 @@
+/**
+ * One Web-standard handler that serves a Theorem chat UI for a single profile.
+ *
+ * Mount it on any framework that speaks `Request` → `Response` (Deno.serve,
+ * Hono, Next route handlers, SvelteKit, Workers) under a catch-all route:
+ *
+ * - `GET  <base>`         → `{ interface }` client-safe profile interface
+ * - `POST <base>/turn`    → NDJSON turn events; a message sent while the reply
+ *                            waits on gates walks away from them first (`abandon`)
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused tool call
+ * - `POST <base>/steer`   → inject messages into a running turn
+ *
+ * `createTheoremHostHandler` serves a host profile the same way, with no model:
+ *
+ * - `GET  <base>`         → `{ interface }` the tools the page may call, with their schemas
+ * - `POST <base>/call`    → NDJSON events for one call of one of those tools
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused call
+ *
+ * Trust boundary: the browser owns the conversation text; the server owns every
+ * decision that grants authority. Tool permissions, which paused calls may run
+ * (and with what input), and which provider interactions may be continued are
+ * kept in a server-side session — request bodies can't grant any of them.
+ * Tool credentials are held on the server too: a key the user types at a gate
+ * is sent once and saved, and no credential is ever sent back to the browser.
+ *
+ * @module
+ */
+import { createProvider, defaultKernelScope, defineProfile, errorKind, invokeTool, lexiconText, publicError, registerProfile, runTurn, TheoremError, } from '@theoremjs/agents';
+import { caughtStatus, forClient, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { answerGatedCall, resolveGateTtlMs, toBase64Url, } from '@theoremjs/agents/kernel';
+import { hostInterface, theoremHostCallRequestSchema, } from "../client/host-transport.js";
+import { gatedToolsFromEvents, interfaceFromProfile, promotedToolIdsFromEvents, settlesToolCall, toolSnapshotFromEvents, } from '@theoremjs/agents/interface';
+import { theoremInvokeRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+import { createMemoryCredentialStore, } from "./credential-store.js";
+import { checkRequest } from "./request-check.js";
+import { createMemorySessionStore, emptySessionState, pruneGates, } from "./session-store.js";
+import { createMemorySteerInbox, steerStage, steerUnitOf } from "./steer-inbox.js";
+import { checkWalkAway, walkAway } from "./walk-away.js";
+import { jsonResponse } from "./json-response.js";
+const SESSION_COOKIE = 'theorem_session';
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+const NDJSON_HEADERS = {
+    'content-type': 'application/x-ndjson; charset=utf-8',
+    'cache-control': 'no-store',
+};
+function withSessionCookie(response, session) {
+    if (session?.setCookie)
+        response.headers.append('set-cookie', session.setCookie);
+    return response;
+}
+/** Strip server-only identity (system prompts) from the projected interface. */
+function clientInterface(profile) {
+    const iface = interfaceFromProfile(profile, defaultKernelScope.tools);
+    return { ...iface, identity: { handle: iface.identity.handle } };
+}
+/** A JSON body checked against `schema`; a missing or malformed field is a `request` error (400). */
+export async function readBody(request, schema) {
+    // JSON-only POSTs can't be sent by a cross-site form, and force a CORS preflight.
+    const type = request.headers.get('content-type') ?? '';
+    if (!type.toLowerCase().startsWith('application/json')) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', 'Content-Type must be application/json');
+    }
+    let raw;
+    try {
+        raw = await request.json();
+    }
+    catch (cause) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', 'Request body must be JSON', { cause });
+    }
+    return checkRequest(schema, raw, 'request body');
+}
+/** Conversation messages a browser may supply — never system instructions. */
+function conversationOnly(messages) {
+    return messages.filter((message) => message.role === 'user' || message.role === 'assistant' || message.role === 'tool');
+}
+/**
+ * Keep the user-authored parts of a turn input. Drops fields that would let a
+ * client speak as the host: system-role history, `role`, `repair` guidance,
+ * token-meter overrides, and live resumption handles.
+ */
+function userTurnInput(input) {
+    return {
+        ...(input.text !== undefined ? { text: input.text } : {}),
+        ...(input.attachments ? { attachments: input.attachments } : {}),
+        ...(input.voice ? { voice: input.voice } : {}),
+        ...(input.history ? { history: conversationOnly(input.history) } : {}),
+    };
+}
+/** Last path segment after the mount point: '', 'turn', 'invoke', 'steer', or a host's 'call'. */
+function routeOf(request) {
+    const segments = new URL(request.url).pathname.split('/').filter(Boolean);
+    const last = segments.at(-1) ?? '';
+    return last === 'turn' || last === 'invoke' || last === 'steer' || last === 'call' ? last : '';
+}
+function readCookie(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === name)
+            return rest.join('=');
+    }
+    return undefined;
+}
+function newSessionId() {
+    return toBase64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/**
+ * The session id the handler issued in its cookie, for a host route outside the
+ * handler (an OAuth callback) that saves credentials under it. Hosts that pass
+ * a `session` resolver use their own id instead.
+ */
+export function theoremSessionId(request) {
+    const existing = readCookie(request, SESSION_COOKIE);
+    return existing && SESSION_ID_PATTERN.test(existing) ? existing : undefined;
+}
+function cookieSession(request) {
+    const existing = theoremSessionId(request);
+    if (existing)
+        return { id: existing };
+    const id = newSessionId();
+    const secure = new URL(request.url).protocol === 'https:' ? '; Secure' : '';
+    return {
+        id,
+        setCookie: `${SESSION_COOKIE}=${id}; Path=/; HttpOnly; SameSite=Lax${secure}`,
+    };
+}
+function lockedStore(store, loaded) {
+    const locks = new Map();
+    const read = async (sessionId) => loaded(await store.load(sessionId));
+    return {
+        read,
+        mutate(sessionId, change) {
+            const next = (locks.get(sessionId) ?? Promise.resolve()).then(async () => {
+                const value = await read(sessionId);
+                const result = change(value);
+                await store.save(sessionId, value);
+                return result;
+            });
+            const settled = next.catch(() => { });
+            locks.set(sessionId, settled);
+            void settled.then(() => {
+                if (locks.get(sessionId) === settled)
+                    locks.delete(sessionId);
+            });
+            return next;
+        },
+    };
+}
+/** Session state, with expired gates dropped as it loads so they can't be answered. */
+function sessionStateStore(store, gateTtlMs) {
+    return lockedStore(store, (state = emptySessionState()) => ({
+        ...state,
+        gates: pruneGates(state.gates, Date.now(), gateTtlMs),
+        settled: pruneGates(state.settled, Date.now(), gateTtlMs),
+    }));
+}
+async function sessionOf(ctx, request) {
+    if (!ctx.options.session)
+        return cookieSession(request);
+    const id = (await ctx.options.session(request))?.trim();
+    if (!id) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('auth', 'the session resolver refused the request', {
+            copy: { key: 'session.sign_in' },
+        });
+    }
+    return { id };
+}
+/** Reports the error to the host, then words it for the user from the profile's lexicon. */
+function publicMessage(ctx, err, request) {
+    ctx.options.onError?.(err, { request });
+    return publicError(err, ctx.profile.lexicon);
+}
+function eventStream(ctx, request, source) {
+    const encoder = new TextEncoder();
+    const line = (value) => encoder.encode(`${JSON.stringify(value)}\n`);
+    const stream = new ReadableStream({
+        async start(controller) {
+            try {
+                for await (const event of source()) {
+                    controller.enqueue(line(forClient(event, ctx.options.clientEvents)));
+                }
+            }
+            catch (err) {
+                if (!request.signal.aborted) {
+                    controller.enqueue(line({ type: 'error', error: publicMessage(ctx, err, request), errorKind: errorKind(err) }));
+                }
+            }
+            controller.close();
+        },
+    });
+    return new Response(stream, { headers: NDJSON_HEADERS });
+}
+function providerFor(ctx, request, model) {
+    const { provider } = ctx.options;
+    // lexicon-exempt: builder config error; the user reads error.config
+    if (!provider)
+        throw new TheoremError('config', `profile ${ctx.profile.id} has no provider`);
+    if (typeof provider === 'function')
+        return provider({ request, model });
+    return createProvider(ctx.profile, provider, model);
+}
+/** Steer inboxes are scoped to the session, so a turn id alone can't reach another user's turn. */
+function inboxKey(sessionId, turnId) {
+    return `${sessionId}\u0000${turnId}`;
+}
+/** The exact paused calls the user may now approve, when the stream stopped on gates. */
+function pendingGatesFrom(events, context) {
+    return gatedToolsFromEvents(events).map((gated) => ({
+        callId: gated.callId,
+        gate: {
+            name: gated.name,
+            arguments: gated.arguments,
+            gate: { kind: gated.gateKind, permission: gated.permission, ...(gated.auth ? { auth: gated.auth } : {}) },
+            snapshot: toolSnapshotFromEvents(events),
+            promoted: [...new Set([...(context.promoted ?? []), ...promotedToolIdsFromEvents(events)])],
+            turnInput: context.turnInput,
+            model: context.model,
+            createdAt: Date.now(),
+        },
+    }));
+}
+/**
+ * Record what the stream established: interaction ids for continuation and,
+ * when it paused on gates, the exact calls the user may now approve.
+ */
+async function recordOutcome(sessions, sessionId, events, context) {
+    const interactionIds = events.flatMap((event) => event.type === 'done' && event.interactionId ? [event.interactionId] : []);
+    const pending = pendingGatesFrom(events, context);
+    if (!interactionIds.length && !pending.length)
+        return;
+    await sessions.mutate(sessionId, (state) => {
+        state.interactions.push(...interactionIds);
+        for (const { callId, gate } of pending)
+            state.gates[callId] = gate;
+    });
+}
+async function* recorded(sessions, sessionId, events, context) {
+    const seen = [];
+    for await (const event of events) {
+        seen.push(event);
+        if (event.type === 'done')
+            await recordOutcome(sessions, sessionId, seen, context);
+        yield event;
+    }
+}
+/** Save one credential, leaving the session's others as they are. */
+function saveCredential(ctx, sessionId, slot, credential) {
+    return ctx.credentials.mutate(sessionId, (saved) => {
+        saved[slot] = credential;
+    });
+}
+/**
+ * The session's credentials as a call reads them: one slot when a tool needs it,
+ * saved the moment the kernel sets one, so a rotated refresh token is never lost
+ * to a closed stream.
+ */
+function sessionCredentials(ctx, sessionId) {
+    return {
+        get: async (slot) => (await ctx.credentials.read(sessionId))[slot],
+        set: (slot, credential) => saveCredential(ctx, sessionId, slot, credential),
+    };
+}
+/** An OAuth gate given the host's sign-in URL. */
+async function withAuthorizationUrl(ctx, request, sessionId, event) {
+    if (event.type !== 'tool' || event.tool.phase !== 'gate')
+        return event;
+    const { tool } = event;
+    const gate = tool.gate.kind === 'auth' ? tool.gate : undefined;
+    if (!gate || gate.authChallenge.authType !== 'oauth2' || !ctx.options.authorizationUrl)
+        return event;
+    const challenge = gate.authChallenge;
+    const authorizationUrl = await ctx.options.authorizationUrl(challenge, { request, sessionId });
+    return {
+        ...event,
+        tool: { ...tool, gate: { ...gate, authChallenge: { ...challenge, authorizationUrl } } },
+    };
+}
+/** Every OAuth gate in the stream, given the host's sign-in URL. */
+async function* withAuthorizationUrls(ctx, request, sessionId, events) {
+    for await (const event of events)
+        yield await withAuthorizationUrl(ctx, request, sessionId, event);
+}
+function answerPendingGate(state, request) {
+    const pending = state.gates[request.callId];
+    if (!pending) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', `gate ${request.callId} is not pending`, {
+            copy: { key: 'session.gate_expired' },
+        });
+    }
+    // A refused answer (a refused secret, an edit without an approval) throws here and leaves the gate pending.
+    const answer = answerGatedCall(request, {
+        name: pending.name,
+        arguments: pending.arguments,
+        permission: pending.gate.permission,
+        ...(pending.gate.kind === 'auth' && pending.gate.auth ? { auth: pending.gate.auth } : {}),
+    }, state.permissions);
+    delete state.gates[request.callId];
+    state.permissions = answer.sessionPermissions;
+    return { callId: request.callId, pending, answer };
+}
+function walkedCallOf(state, callId) {
+    const settled = state.settled[callId];
+    return settled ? { callId, settled } : answerPendingGate(state, { callId, decision: 'abandon' });
+}
+/**
+ * Take the calls a message walks away from out of the session, answered
+ * `abandon`: every one of them, or none when one is neither waiting nor
+ * settled. The message's history must leave exactly those calls open.
+ */
+function takeWalkedAway(ctx, session, input, abandon) {
+    checkWalkAway(input, abandon);
+    // A throw leaves the session unsaved, so no call is taken unless all are.
+    return ctx.sessions.mutate(session.id, (state) => abandon.map((callId) => walkedCallOf(state, callId)));
+}
+/**
+ * The run that settles an answered call, as the model asked it. The session
+ * keeps the event that settles it, and `ended` names the call once it has
+ * (see `restoreUnended`).
+ */
+async function* settleAnswered(ctx, request, session, answered, ended) {
+    const { callId, pending } = answered;
+    for await (const event of invokeAnswered(ctx, request, session.id, answered)) {
+        if (!ended.has(callId) && settlesToolCall(event, callId)) {
+            ended.add(callId);
+            await ctx.sessions.mutate(session.id, (state) => {
+                state.settled[callId] = { event, createdAt: pending.createdAt };
+            });
+        }
+        yield event;
+    }
+}
+/**
+ * A request that took calls and ended before they settled (the client went
+ * away, the host failed, an earlier call's run threw) puts each back to wait
+ * as it did, to be answered again, unless it paused on a gate again: the run
+ * recorded that gate with its outcome.
+ */
+async function restoreUnended(ctx, session, calls, ended) {
+    const unended = calls.flatMap((call) => ('pending' in call && !ended.has(call.callId) ? [call] : []));
+    if (!unended.length)
+        return;
+    await ctx.sessions.mutate(session.id, (state) => {
+        for (const { callId, pending } of unended)
+            state.gates[callId] ??= pending;
+    });
+}
+function invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
+    return invokeTool({
+        profile: ctx.profile.id,
+        name: pending.name,
+        callId,
+        input: answer.input,
+        resume: answer.resume,
+        sessionPermissions: answer.sessionPermissions,
+        credentials: sessionCredentials(ctx, sessionId),
+        turnInput: pending.turnInput,
+        snapshot: pending.snapshot,
+        promoted: pending.promoted,
+        model: pending.model,
+        signal: request.signal,
+        host: ctx.options.host?.(request),
+    });
+}
+/** Settles each walked-away call, and returns the input with their answers. */
+async function* walkAwayFrom(ctx, request, session, walked, ended) {
+    return yield* walkAway(walked.input, walked.calls.map((call) => ({
+        callId: call.callId,
+        events: 'settled' in call
+            ? once(call.settled.event)
+            : settleAnswered(ctx, request, session, call, ended),
+    })));
+}
+/** A settled call's answer, streamed again. */
+async function* once(event) {
+    yield event;
+}
+async function* turnEvents(ctx, request, session, body, walked) {
+    const ended = new Set();
+    let input;
+    try {
+        input = walked.calls.length ? yield* walkAwayFrom(ctx, request, session, walked, ended) : walked.input;
+    }
+    finally {
+        await restoreUnended(ctx, session, walked.calls, ended);
+    }
+    if (!input)
+        return;
+    const state = await ctx.sessions.read(session.id);
+    const provider = await providerFor(ctx, request, body.model);
+    // Only continue provider-side conversations this session started.
+    const previousInteractionId = body.previousInteractionId && state.interactions.includes(body.previousInteractionId)
+        ? body.previousInteractionId
+        : undefined;
+    const key = body.turnId ? inboxKey(session.id, body.turnId) : undefined;
+    if (key)
+        await ctx.inbox.open(key);
+    try {
+        const events = runTurn({
+            profile: ctx.profile.id,
+            input,
+            previousInteractionId,
+            sessionPermissions: state.permissions,
+            credentials: sessionCredentials(ctx, session.id),
+            signal: request.signal,
+            host: ctx.options.host?.(request),
+            ...(body.model ? { model: body.model } : {}),
+            ...(body.effort ? { effort: body.effort } : {}),
+            ...(key ? { onStage: steerStage(ctx.inbox, key) } : {}),
+        }, provider);
+        yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+            turnInput: input,
+            model: body.model,
+        });
+    }
+    finally {
+        if (key)
+            await ctx.inbox.close(key);
+    }
+}
+async function* invokeEvents(ctx, request, session, answered) {
+    const { pending, answer } = answered;
+    const ended = new Set();
+    try {
+        if (answer.typed)
+            await saveCredential(ctx, session.id, answer.typed.slot, answer.typed.credential);
+        const events = settleAnswered(ctx, request, session, answered, ended);
+        yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+            turnInput: pending.turnInput,
+            model: pending.model,
+            promoted: pending.promoted,
+        });
+    }
+    finally {
+        await restoreUnended(ctx, session, [answered], ended);
+    }
+}
+async function steer(ctx, request, session) {
+    const body = await readBody(request, theoremSteerRequestSchema);
+    if (!(await ctx.inbox.enqueue(inboxKey(session.id, body.turnId), steerUnitOf(body)))) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', `turn ${body.turnId} is not running`, {
+            copy: { key: 'session.turn_ended' },
+        });
+    }
+    return jsonResponse(200, { ok: true });
+}
+/** One call of one of a host's tools, run as the page asked it; a gate it pauses on waits in the session. */
+async function* callEvents(ctx, request, session, body) {
+    const state = await ctx.sessions.read(session.id);
+    const events = invokeTool({
+        profile: ctx.profile.id,
+        name: body.name,
+        input: body.input,
+        sessionPermissions: state.permissions,
+        credentials: sessionCredentials(ctx, session.id),
+        signal: request.signal,
+        host: ctx.options.host?.(request),
+    });
+    yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+        turnInput: {},
+    });
+}
+function answerRequest(body) {
+    return { callId: body.gateId, decision: body.decision, input: body.input, secret: body.secret };
+}
+/** A route this profile doesn't serve. */
+function refused(ctx) {
+    return jsonResponse(HTTP_METHOD, {
+        error: lexiconText('error.request', {}, ctx.profile.lexicon),
+        errorKind: 'request',
+    });
+}
+/** The user's answer to a paused call. */
+async function invoke(ctx, request, session) {
+    const body = await readBody(request, theoremInvokeRequestSchema);
+    // Take the answered call before streaming, so a stale answer is a reply status, not a stream error.
+    const answered = await ctx.sessions.mutate(session.id, (state) => answerPendingGate(state, answerRequest(body)));
+    return eventStream(ctx, request, () => invokeEvents(ctx, request, session, answered));
+}
+async function hostRoute(ctx, request, session) {
+    const target = routeOf(request);
+    if (request.method === 'GET' && target === '') {
+        const tool = (name) => {
+            const registered = defaultKernelScope.tools.get(name);
+            return registered?.type === 'builtin' ? undefined : registered;
+        };
+        return jsonResponse(200, { interface: hostInterface(ctx.profile, tool) });
+    }
+    if (request.method === 'POST' && target === 'call') {
+        const body = await readBody(request, theoremHostCallRequestSchema);
+        return eventStream(ctx, request, () => callEvents(ctx, request, session, body));
+    }
+    if (request.method === 'POST' && target === 'invoke')
+        return invoke(ctx, request, session);
+    return refused(ctx);
+}
+async function route(ctx, request, session) {
+    if (ctx.profile.type === 'host')
+        return hostRoute({ ...ctx, profile: ctx.profile }, request, session);
+    const target = routeOf(request);
+    if (request.method === 'GET' && target === '')
+        return jsonResponse(200, { interface: clientInterface(ctx.profile) });
+    if (request.method !== 'POST' || target === '' || target === 'call')
+        return refused(ctx);
+    if (target === 'turn') {
+        const body = await readBody(request, theoremTurnRequestSchema);
+        const input = userTurnInput(body.input);
+        // Take the walked-away calls before streaming, so a stale one is a reply status, not a stream error.
+        const calls = body.abandon ? await takeWalkedAway(ctx, session, input, body.abandon) : [];
+        return eventStream(ctx, request, () => turnEvents(ctx, request, session, body, { input, calls }));
+    }
+    if (target === 'invoke')
+        return invoke(ctx, request, session);
+    return steer(ctx, request, session);
+}
+export function createTheoremHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type === 'decision') {
+        // lexicon-exempt: builder config error at setup; no user sees it
+        throw new Error("createTheoremHandler serves turn-based profiles; serve type 'decision' with createTheoremDecisionHandler.");
+    }
+    if (profile.type === 'host') {
+        // lexicon-exempt: builder config error at setup; no user sees it
+        throw new Error("createTheoremHandler serves turn-based profiles; serve type 'host' with createTheoremHostHandler.");
+    }
+    if (profile.type === 'live') {
+        // lexicon-exempt: builder config error at setup; no user sees it
+        throw new Error(`createTheoremHandler serves turn-based profiles; got type '${profile.type}'.`);
+    }
+    return serve('createTheoremHandler', profile, options, options.steerInbox);
+}
+/**
+ * Serves a host profile to `<TheoremHost />`: the page calls the profile's tools
+ * directly, and every call runs through the kernel's gates and guardrails.
+ */
+export function createTheoremHostHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type !== 'host') {
+        // lexicon-exempt: builder config error at setup; no user sees it
+        throw new Error(`createTheoremHostHandler serves type 'host'; got type '${profile.type}'.`);
+    }
+    return serve('createTheoremHostHandler', profile, options);
+}
+function serve(name, profile, options, steerInbox) {
+    const gateTtlMs = resolveGateTtlMs(name, options.gateTtlMs);
+    registerProfile(profile);
+    const ctx = {
+        options,
+        profile,
+        inbox: steerInbox ?? createMemorySteerInbox(),
+        sessions: sessionStateStore(options.sessionStore ?? createMemorySessionStore(), gateTtlMs),
+        credentials: lockedStore(options.credentialStore ?? createMemoryCredentialStore(), (saved = {}) => saved),
+    };
+    return async (request) => {
+        let session;
+        try {
+            session = await sessionOf(ctx, request);
+            return withSessionCookie(await route(ctx, request, session), session);
+        }
+        catch (err) {
+            const error = publicMessage(ctx, err, request);
+            return withSessionCookie(jsonResponse(caughtStatus(err), { error, errorKind: errorKind(err) }), session);
+        }
+    };
+}

package/server/json-response.d.ts

@@ -0,0 +1,2 @@
+/** A JSON reply no cache keeps. */
+export declare function jsonResponse(status: number, body: unknown): Response;

package/server/json-response.js

@@ -0,0 +1,7 @@
+/** A JSON reply no cache keeps. */
+export function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}

package/server/mod.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Server half of `@theoremjs/react`: serve one profile to the chat UI, a
+ * decision profile to the decision UI, or a host profile's tools to the host UI.
+ *
+ * @module
+ */
+export { theoremHostCallRequestSchema } from '../client/host-transport.ts';
+export type { LiveClientMessage } from '../client/live-messages.ts';
+export { theoremInvokeRequestSchema, theoremReplaySchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '../client/transport.ts';
+export { createMemoryCredentialStore, type TheoremCredentialStore, type TheoremCredentials, } from './credential-store.ts';
+export { createTheoremDecisionHandler, type TheoremDecisionHandlerOptions, } from './decision-handler.ts';
+export { createTheoremHandler, createTheoremHostHandler, readBody, type TheoremHandlerOptions, type TheoremHostHandlerOptions, type TheoremRequestContext, theoremSessionId, } from './handler.ts';
+export { checkRequest, parseLiveClientMessage } from './request-check.ts';
+export { createMemorySessionStore, type MemorySessionStoreOptions, type PendingToolGate, type SettledToolGate, type TheoremSessionState, type TheoremSessionStore, } from './session-store.ts';
+export { createMemorySteerInbox, type SteerInbox, type SteerUnit, steerStage, steerUnitOf, } from './steer-inbox.ts';
+export { checkWalkAway, type WalkedAwayCall, walkAway } from './walk-away.ts';

package/server/mod.js

@@ -0,0 +1,15 @@
+/**
+ * Server half of `@theoremjs/react`: serve one profile to the chat UI, a
+ * decision profile to the decision UI, or a host profile's tools to the host UI.
+ *
+ * @module
+ */
+export { theoremHostCallRequestSchema } from "../client/host-transport.js";
+export { theoremInvokeRequestSchema, theoremReplaySchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+export { createMemoryCredentialStore, } from "./credential-store.js";
+export { createTheoremDecisionHandler, } from "./decision-handler.js";
+export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSessionId, } from "./handler.js";
+export { checkRequest, parseLiveClientMessage } from "./request-check.js";
+export { createMemorySessionStore, } from "./session-store.js";
+export { createMemorySteerInbox, steerStage, steerUnitOf, } from "./steer-inbox.js";
+export { checkWalkAway, walkAway } from "./walk-away.js";

package/server/request-check.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a browser sends a host, checked: the handler's request bodies and a
+ * relay's live messages. A malformed one is a `request` error, which names
+ * only the paths and codes that broke, never the value.
+ *
+ * @module
+ */
+import { type z } from '@theoremjs/agents';
+import { type LiveClientMessage } from '../client/live-messages.ts';
+/** `raw` checked against `schema`; a missing or malformed field is a `request` error. */
+export declare function checkRequest<T>(schema: z.ZodType<T>, raw: unknown, what: string): T;
+/**
+ * One text frame from the live client, as a relay reads it: JSON that passes
+ * `liveClientMessageSchema`, else a `request` error.
+ */
+export declare function parseLiveClientMessage(text: string): LiveClientMessage;

package/server/request-check.js

@@ -0,0 +1,34 @@
+/**
+ * What a browser sends a host, checked: the handler's request bodies and a
+ * relay's live messages. A malformed one is a `request` error, which names
+ * only the paths and codes that broke, never the value.
+ *
+ * @module
+ */
+import { TheoremError } from '@theoremjs/agents';
+import { liveClientMessageSchema } from "../client/live-messages.js";
+import { issueSummary } from "../client/wire-line.js";
+/** `raw` checked against `schema`; a missing or malformed field is a `request` error. */
+export function checkRequest(schema, raw, what) {
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', `${what} failed its check: ${issueSummary(parsed.error)}`);
+    }
+    return parsed.data;
+}
+/**
+ * One text frame from the live client, as a relay reads it: JSON that passes
+ * `liveClientMessageSchema`, else a `request` error.
+ */
+export function parseLiveClientMessage(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (cause) {
+        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', 'live message must be JSON', { cause });
+    }
+    return checkRequest(liveClientMessageSchema, raw, 'live message');
+}