@theoremjs/web 0.0.0-stage → 0.3.4-next.375.ga2d1878

package/server/request-check.js

@@ -0,0 +1,49 @@
+/**
+ * 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 { labelText, TheoremError } from '@theoremjs/agents';
+import { liveClientMessageSchema, liveOpenMessageSchema, } from "../client/live-messages.js";
+import { issueSummary } from "../client/wire-line.js";
+import { requestByteLimit } from "./request-body.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) {
+        // labels-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;
+}
+function liveFrame(text) {
+    const limit = requestByteLimit();
+    if (text.length > limit || new TextEncoder().encode(text).byteLength > limit)
+        throw new TheoremError('request', labelText('error.request'));
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // invariant: JSON parser diagnostics can contain browser values.
+        throw new TheoremError('request', labelText('error.request'), {
+            cause: { code: 'request_json' },
+        });
+    }
+}
+/**
+ * One text frame from the live client, as a relay reads it: JSON that passes
+ * `liveClientMessageSchema`, else a `request` error.
+ */
+export function parseLiveClientMessage(text) {
+    return checkRequest(liveClientMessageSchema, liveFrame(text), 'live message');
+}
+/**
+ * The live client's first frame, as a relay reads it before it opens the
+ * session: JSON that passes `liveOpenMessageSchema`, else a `request` error.
+ */
+export function parseLiveOpenMessage(text) {
+    // labels-exempt: internal diagnostic; the user reads the error kind's wording
+    return checkRequest(liveOpenMessageSchema, liveFrame(text), 'live open message');
+}

package/server/session-authority.d.ts

@@ -0,0 +1,8 @@
+import { type TheoremSessionLimits } from './session-limits.ts';
+import { type TheoremSessionState, type TheoremSessionStore } from './session-store.ts';
+export type MutableStore<T> = {
+    read(sessionId: string): Promise<T>;
+    mutate<R>(sessionId: string, change: (value: T) => R | Promise<R>): Promise<R>;
+};
+/** Session state, with expired gates dropped as it loads so they can't be answered. */
+export declare function sessionStateStore(store: TheoremSessionStore, gateTtlMs: number, operationRetentionMs: number, limits: TheoremSessionLimits): MutableStore<TheoremSessionState>;

package/server/session-authority.js

@@ -0,0 +1,78 @@
+import { labelText, TheoremError, z } from '@theoremjs/agents';
+import { checkSessionLimits } from "./session-limits.js";
+import { emptySessionState, pruneGates, theoremSessionStateSchema, } from "./session-store.js";
+/** Session state, with expired gates dropped as it loads so they can't be answered. */
+export function sessionStateStore(store, gateTtlMs, operationRetentionMs, limits) {
+    if (typeof store.compareAndSwap !== 'function') {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_store_contract', required: 'compareAndSwap' },
+        });
+    }
+    const writeResult = z.discriminatedUnion('written', [
+        z.strictObject({ written: z.literal(false) }),
+        z.strictObject({ written: z.literal(true), revision: z.string().min(1) }),
+    ]);
+    const load = async (sessionId, now) => {
+        const snapshot = await store.load(sessionId);
+        const parsed = theoremSessionStateSchema.safeParse(snapshot === undefined ? emptySessionState() : snapshot.state);
+        if (!parsed.success ||
+            (snapshot !== undefined && (typeof snapshot.revision !== 'string' || !snapshot.revision))) {
+            throw new TheoremError('config', labelText('error.config'), {
+                cause: { code: 'session_store_state' },
+            });
+        }
+        const state = structuredClone(parsed.data);
+        for (const gate of Object.values(state.gates))
+            gate.expiresAt ??= gate.createdAt + gateTtlMs;
+        state.gates = pruneGates(state.gates, now, gateTtlMs);
+        for (const operation of Object.values(state.operations)) {
+            if (operation.status === 'ready' && operation.answer.resume.granted === true)
+                operation.answer.resume.gateKind ??= operation.pending.gate.kind;
+        }
+        state.operations = Object.fromEntries(Object.entries(state.operations).filter(([, operation]) => operation.status !== 'settled' ||
+            now < (operation.retainUntil ?? operation.settledAt + operationRetentionMs)));
+        return { revision: snapshot?.revision ?? null, state };
+    };
+    return {
+        async read(sessionId) {
+            return (await load(sessionId, Date.now())).state;
+        },
+        async mutate(sessionId, change) {
+            const now = Date.now();
+            for (let conflict = 0; conflict < 8; conflict++) {
+                const { revision, state } = await load(sessionId, now);
+                const result = await change(state);
+                for (const gate of Object.values(state.gates))
+                    gate.expiresAt ??= gate.createdAt + gateTtlMs;
+                for (const operation of Object.values(state.operations)) {
+                    if (operation.status === 'settled')
+                        operation.retainUntil ??= operation.settledAt + operationRetentionMs;
+                }
+                checkSessionLimits(state, limits);
+                const next = theoremSessionStateSchema.safeParse(state);
+                if (!next.success) {
+                    throw new TheoremError('config', labelText('error.config'), {
+                        cause: { code: 'session_store_transition' },
+                    });
+                }
+                const written = writeResult.safeParse(await store.compareAndSwap(sessionId, revision, next.data));
+                if (!written.success) {
+                    throw new TheoremError('config', labelText('error.config'), {
+                        cause: { code: 'session_store_write_result' },
+                    });
+                }
+                if (written.data.written) {
+                    if (written.data.revision === revision) {
+                        throw new TheoremError('config', labelText('error.config'), {
+                            cause: { code: 'session_store_revision' },
+                        });
+                    }
+                    return result;
+                }
+            }
+            throw new TheoremError('unavailable', labelText('error.unavailable'), {
+                cause: { code: 'session_store_contention' },
+            });
+        },
+    };
+}

package/server/session-boundary.d.ts

@@ -0,0 +1,26 @@
+import { type PageToolExecution, type ProviderCheckpoint, type SessionRequest, type ToolExecutionCoordinator, type TurnHistoryMessage } from '@theoremjs/agents';
+import { type LiveOpenMessage } from '../client/live-messages.ts';
+import { type PageToolBroker, type PageToolResult } from './page-dispatch.ts';
+import { type TheoremSessionLimits } from './session-limits.ts';
+import { type TheoremSessionStore } from './session-store.ts';
+export interface SessionBoundaryOptions {
+    request: Request;
+    session?: (request: Request) => string | undefined | Promise<string | undefined>;
+    sessionStore: TheoremSessionStore;
+    gateTtlMs?: number;
+    operationRetentionMs?: number;
+    sessionLimits?: Partial<TheoremSessionLimits>;
+    pageToolBroker?: PageToolBroker;
+}
+export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs'>;
+export interface TheoremSessionBoundary {
+    sessionId: string;
+    setCookie?: string;
+    prepareLiveOpen(open: LiveOpenMessage, serverContext?: unknown): Promise<PreparedLiveOpen>;
+    prepareProviderState(checkpoint: ProviderCheckpoint | undefined, history?: readonly TurnHistoryMessage[]): Promise<ProviderCheckpoint | undefined>;
+    recordCheckpoint(checkpoint: ProviderCheckpoint): Promise<void>;
+    toolExecution: ToolExecutionCoordinator;
+    pageExecution: PageToolExecution;
+    answerPageResult(result: PageToolResult): Promise<boolean>;
+}
+export declare function createTheoremSessionBoundary(options: SessionBoundaryOptions): Promise<TheoremSessionBoundary>;

package/server/session-boundary.js

@@ -0,0 +1,64 @@
+import { labelText, TheoremError, } from '@theoremjs/agents';
+import { resolveGateTtlMs } from '@theoremjs/agents/kernel';
+import { liveOpenMessageSchema } from "../client/live-messages.js";
+import { checkpointIdentity, checkpointOwnershipKey, requireOwnedCheckpoint, retainedCheckpointIdentities, } from "./checkpoint-ownership.js";
+import { createMemoryPageToolBroker, sessionPageDispatch, } from "./page-dispatch.js";
+import { checkRequest } from "./request-check.js";
+import { sessionStateStore } from "./session-authority.js";
+import { theoremSession } from "./session-identity.js";
+import { resolveSessionLimits } from "./session-limits.js";
+import { DEFAULT_OPERATION_RETENTION_MS } from "./session-store.js";
+import { sessionToolCoordinator } from "./tool-operations.js";
+import { liveSessionOpen } from "./turn-input.js";
+export async function createTheoremSessionBoundary(options) {
+    const cookie = options.session ? undefined : theoremSession(options.request);
+    const id = options.session ? (await options.session(options.request))?.trim() : cookie?.id;
+    if (!id)
+        throw new TheoremError('auth', labelText('session.sign_in'), {
+            copy: { key: 'session.sign_in' },
+        });
+    const retention = options.operationRetentionMs ?? DEFAULT_OPERATION_RETENTION_MS;
+    if (!Number.isSafeInteger(retention) || retention <= 0)
+        throw new TheoremError('config', labelText('error.config'));
+    const limits = resolveSessionLimits(options.sessionLimits);
+    const store = sessionStateStore(options.sessionStore, resolveGateTtlMs('session boundary', options.gateTtlMs), retention, limits);
+    // invariant: Refuse unavailable or malformed authority before an upstream connection opens.
+    await store.read(id);
+    const page = sessionPageDispatch(store, id, options.pageToolBroker ?? createMemoryPageToolBroker());
+    return {
+        pageExecution: page.execution,
+        answerPageResult: page.answer,
+        sessionId: id,
+        ...(cookie?.setCookie ? { setCookie: cookie.setCookie } : {}),
+        toolExecution: sessionToolCoordinator(store, id),
+        async prepareLiveOpen(raw, server) {
+            const open = checkRequest(liveOpenMessageSchema, raw, 'live open');
+            const prepared = liveSessionOpen(open, server);
+            const state = await store.read(id);
+            const providerState = await requireOwnedCheckpoint(state.providerCheckpoints, prepared.providerState, state.operations);
+            if (providerState &&
+                Object.values(state.operations).some((operation) => operation.status !== 'settled')) {
+                throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+                    copy: { key: 'tool.execution_uncertain' },
+                });
+            }
+            return {
+                ...prepared,
+                providerState,
+                ...(prepared.history
+                    ? { history: prepared.history.filter((message) => message.role !== 'system') }
+                    : {}),
+            };
+        },
+        async prepareProviderState(checkpoint, history) {
+            const state = await store.read(id);
+            return requireOwnedCheckpoint(state.providerCheckpoints, checkpoint, state.operations, history);
+        },
+        async recordCheckpoint(checkpoint) {
+            const identity = await checkpointIdentity(checkpoint);
+            await store.mutate(id, async (state) => {
+                state.providerCheckpoints = retainedCheckpointIdentities(state.providerCheckpoints, [await checkpointOwnershipKey(identity, state.operations)], limits.maxCheckpoints);
+            });
+        },
+    };
+}

package/server/session-identity.d.ts

@@ -0,0 +1,16 @@
+export type Session = {
+    id: string;
+    setCookie?: string;
+};
+/**
+ * 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 declare function theoremSessionId(request: Request): string | undefined;
+/**
+ * The handler's cookie session for `request`: its id, and the `Set-Cookie` header to send when
+ * the request had none. A page that starts a conversation before the chat's first request uses
+ * it, so the chat and the conversation share one session.
+ */
+export declare function theoremSession(request: Request): Session;

package/server/session-identity.js

@@ -0,0 +1,41 @@
+import { toBase64Url } from '@theoremjs/agents/kernel';
+const SESSION_COOKIE = 'theorem_session';
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+/** How long a visitor keeps their session, so a chat they come back to opens as theirs: 30 days. */
+const SESSION_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+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;
+}
+/**
+ * The handler's cookie session for `request`: its id, and the `Set-Cookie` header to send when
+ * the request had none. A page that starts a conversation before the chat's first request uses
+ * it, so the chat and the conversation share one session.
+ */
+export function theoremSession(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=/; Max-Age=${SESSION_MAX_AGE_SECONDS}; HttpOnly; SameSite=Lax${secure}`,
+    };
+}

package/server/session-limits.d.ts

@@ -0,0 +1,12 @@
+import type { TheoremSessionState } from './session-store.ts';
+export interface TheoremSessionLimits {
+    maxGates: number;
+    maxOperations: number;
+    maxCheckpoints: number;
+    maxPermissions: number;
+    maxStateBytes: number;
+    maxInvocationBytes: number;
+    maxOutcomeBytes: number;
+}
+export declare function resolveSessionLimits(options?: Partial<TheoremSessionLimits>): TheoremSessionLimits;
+export declare function checkSessionLimits(state: TheoremSessionState, limits: TheoremSessionLimits): void;

package/server/session-limits.js

@@ -0,0 +1,59 @@
+import { labelText, TheoremError } from '@theoremjs/agents';
+const DEFAULTS = {
+    maxGates: 32,
+    maxOperations: 128,
+    maxCheckpoints: 256,
+    maxPermissions: 2048,
+    maxStateBytes: 32 * 1024 * 1024,
+    maxInvocationBytes: 256 * 1024,
+    maxOutcomeBytes: 256 * 1024,
+};
+export function resolveSessionLimits(options = {}) {
+    const limits = { ...DEFAULTS, ...options };
+    if (Object.keys(options).some((key) => !Object.hasOwn(DEFAULTS, key)) ||
+        Object.values(limits).some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_limits' },
+        });
+    }
+    return limits;
+}
+function bytes(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function capacity() {
+    throw new TheoremError('unavailable', labelText('error.unavailable'), {
+        cause: { code: 'session_state_capacity' },
+    });
+}
+export function checkSessionLimits(state, limits) {
+    const gates = Object.values(state.gates);
+    const operations = Object.values(state.operations);
+    if (gates.length > limits.maxGates ||
+        operations.length > limits.maxOperations ||
+        state.providerCheckpoints.length > limits.maxCheckpoints ||
+        state.permissions.length > limits.maxPermissions)
+        capacity();
+    for (const gate of gates)
+        if (bytes(gate) > limits.maxInvocationBytes)
+            capacity();
+    let reserved = gates.length * limits.maxOutcomeBytes;
+    for (const operation of operations) {
+        if (operation.status !== 'ready' &&
+            operation.invocation &&
+            bytes(operation.invocation) > limits.maxInvocationBytes)
+            capacity();
+        if (operation.status === 'settled') {
+            if (bytes(operation.outcome) > limits.maxOutcomeBytes)
+                capacity();
+        }
+        else {
+            reserved += limits.maxOutcomeBytes;
+            if (operation.status === 'ready' && bytes(operation) > limits.maxInvocationBytes)
+                capacity();
+        }
+    }
+    // invariant: Reserve terminal evidence before dispatch; unresolved records are never evicted to make room.
+    if (bytes(state) + reserved > limits.maxStateBytes)
+        capacity();
+}

package/server/session-store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Server-held session state for `createTheoremHandler`.
+ *
+ * Everything that grants authority lives here, never in the request body:
+ * which tools the user allowed for the session, which paused tool calls may be
+ * resumed (and with exactly what input), and which provider interactions this
+ * session may continue.
+ *
+ * @module
+ */
+import { z } from '@theoremjs/agents';
+import type { ToolGateAuth } from '@theoremjs/agents/interface';
+import type { AnsweredGate, ToolGate, ToolId, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, TurnInput, TurnToolSnapshot } from '@theoremjs/agents/kernel';
+import { type TheoremSessionLimits } from './session-limits.ts';
+/** A tool call the kernel paused on a gate, as the server saw it. */
+export type PendingToolGate = {
+    profileId: string;
+    operationId: string;
+    callId: string;
+    name: string;
+    /** The model's arguments; an approval runs the call with exactly these. */
+    arguments: Record<string, unknown>;
+    /** The gate, and for a sign-in gate the credential slot and kind it waits for. */
+    gate: Pick<ToolGate, 'kind' | 'permission'> & {
+        auth?: ToolGateAuth;
+    };
+    snapshot?: TurnToolSnapshot;
+    promoted: ToolId[];
+    turnInput: TurnInput;
+    model?: string;
+    createdAt: number;
+    expiresAt?: number;
+};
+export type SessionPageGrant = {
+    grantId: string;
+    expiresAt: number;
+    resultHash?: string;
+};
+export type SessionToolOperation = {
+    status: 'ready';
+    profileId: string;
+    pending: PendingToolGate;
+    answer: Omit<AnsweredGate, 'typed'>;
+    readyAt: number;
+} | (ToolOperationIdentity & {
+    status: 'running';
+    claimToken: string;
+    startedAt: number;
+    pageGrant?: SessionPageGrant;
+}) | (ToolOperationIdentity & {
+    status: 'settled';
+    pageGrant?: SessionPageGrant;
+    outcome: ToolOperationOutcome;
+    settledAt: number;
+    retainUntil?: number;
+}) | (ToolOperationIdentity & {
+    status: 'uncertain';
+    pageGrant?: SessionPageGrant;
+    claimToken: string;
+    reason: ToolOperationUncertainty;
+    detectedAt: number;
+});
+export declare const DEFAULT_OPERATION_RETENTION_MS: number;
+export type TheoremSessionState = {
+    version: 3;
+    operations: Record<string, SessionToolOperation>;
+    /** Tool ids the user allowed for the rest of this session. */
+    permissions: string[];
+    /** invariant: Operation IDs index issued gates; both IDs must match an answer. */
+    gates: Record<string, PendingToolGate>;
+    /** Checkpoint identities this session produced, newest last. */
+    providerCheckpoints: string[];
+};
+/** Stored authority is checked before the handler reads or changes it. */
+export declare const theoremSessionStateSchema: z.ZodType<TheoremSessionState>;
+export interface SessionSnapshot {
+    revision: string;
+    state: TheoremSessionState;
+}
+export type SessionWriteResult = {
+    written: true;
+    revision: string;
+} | {
+    written: false;
+};
+/**
+ * Where session state lives. The default is process memory — use a shared
+ * store (KV, Redis, a database row) when requests can reach different instances.
+ */
+export interface TheoremSessionStore {
+    load(sessionId: string): Promise<SessionSnapshot | undefined>;
+    /** Compare and replace atomically; null creates only an absent session. */
+    compareAndSwap(sessionId: string, expectedRevision: string | null, next: TheoremSessionState): Promise<SessionWriteResult>;
+}
+export declare function emptySessionState(): TheoremSessionState;
+/** Drop gates (waiting or settled) older than `ttlMs`. */
+export declare function pruneGates<Gate extends {
+    createdAt: number;
+    expiresAt?: number;
+}>(gates: Record<string, Gate>, now: number, ttlMs: number): Record<string, Gate>;
+export type MemorySessionStoreOptions = {
+    /** Finite authority storage bounds. */
+    sessionLimits?: Partial<TheoremSessionLimits>;
+    /** invariant: Idle retention is in milliseconds. Protected authority remains. Default 24h. */
+    ttlMs?: number;
+    /** Oldest sessions are evicted past this count. Default 10 000. */
+    maxSessions?: number;
+};
+export declare function memoryStoreLimits(options: MemorySessionStoreOptions): {
+    ttlMs: number;
+    maxSessions: number;
+};
+/** A value kept per session id for the separate credential store. */
+export type PerSessionStore<T> = {
+    load(sessionId: string): T | undefined | Promise<T | undefined>;
+    save(sessionId: string, value: T): void | Promise<void>;
+};
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export declare function createMemorySessionMap<T>(options?: MemorySessionStoreOptions): {
+    load(sessionId: string): T | undefined;
+    save(sessionId: string, value: T): void;
+};
+export declare function createMemorySessionStore(options?: MemorySessionStoreOptions): TheoremSessionStore;