@theoremjs/react 0.3.0 → 0.3.2

package/server/session-store.js

@@ -8,18 +8,191 @@
  *
  * @module
  */
+import { jsonObjectSchema, jsonValueSchema, labelText, savedToolInvocationSchema, TheoremError, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_PERMISSION, toolOperationOutcomeSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
 import { gateExpired } from '@theoremjs/agents/kernel';
+import { checkSessionLimits, resolveSessionLimits, } from "./session-limits.js";
+export const DEFAULT_OPERATION_RETENTION_MS = 24 * 60 * 60 * 1000;
+const blobSchema = z.strictObject({
+    data: z.string(),
+    mimeType: z.string(),
+    name: z.string().optional(),
+});
+const inputSchema = z.strictObject({
+    text: z.string().optional(),
+    role: z.string().optional(),
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z
+        .strictObject({ client: jsonValueSchema.optional(), server: jsonValueSchema.optional() })
+        .optional(),
+    attachments: z
+        .array(z.union([
+        blobSchema,
+        z.strictObject({
+            uri: z.string(),
+            mimeType: z.string(),
+            name: z.string().optional(),
+        }),
+    ]))
+        .optional(),
+    voice: z.array(blobSchema).optional(),
+    history: z.array(turnHistoryMessageSchema).optional(),
+    repair: z
+        .strictObject({ previousOutput: z.string(), rejection: z.string(), guidance: z.string() })
+        .optional(),
+    historyTokens: z.number().nonnegative().optional(),
+    inputTokens: z.number().nonnegative().optional(),
+});
+const pendingSchema = z.strictObject({
+    profileId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
+    callId: z.string().min(1),
+    name: z.string().min(1),
+    arguments: jsonObjectSchema,
+    gate: z
+        .strictObject({
+        kind: z.enum(TOOL_GATE_KINDS),
+        permission: z.enum(TOOL_PERMISSION).optional(),
+        auth: z
+            .strictObject({
+            slot: z.string().min(1),
+            authType: z.enum(TOOL_AUTH_TYPES),
+            service: z.string().min(1),
+        })
+            .optional(),
+    })
+        .superRefine((gate, ctx) => {
+        if ((gate.kind === 'auth') !== (gate.auth !== undefined)) {
+            ctx.addIssue({ code: 'custom', path: ['auth'] });
+        }
+    }),
+    snapshot: turnToolSnapshotSchema.optional(),
+    promoted: z.array(z.string().min(1)),
+    turnInput: inputSchema,
+    model: z.string().optional(),
+    createdAt: z.number().finite().nonnegative(),
+    expiresAt: z.number().finite().nonnegative().optional(),
+});
+const acceptedAnswerSchema = z.strictObject({
+    input: jsonObjectSchema,
+    resume: z.strictObject({
+        granted: z.boolean().optional(),
+        gateKind: z.enum(TOOL_GATE_KINDS).optional(),
+        cause: z.enum(['declined', 'abandoned', 'expired']).optional(),
+        signIn: z.boolean().optional(),
+        edited: z.strictObject({ from: jsonObjectSchema }).optional(),
+    }),
+    sessionPermissions: z.array(z.string().min(1)),
+    page: z
+        .union([
+        z.strictObject({ output: jsonValueSchema }),
+        z.strictObject({ timedOut: z.literal(true) }),
+        z.strictObject({ unanswered: z.literal(true) }),
+    ])
+        .optional(),
+});
+const identityFields = {
+    operationId: z.string().min(1).max(256),
+    callId: z.string().min(1),
+    profileId: z.string().min(1),
+    toolId: z.string().min(1),
+    invocationHash: z.string().min(1),
+    invocation: savedToolInvocationSchema.optional(),
+};
+const pageGrant = z.strictObject({
+    grantId: z.string().min(1),
+    expiresAt: z.number().finite().positive(),
+    resultHash: z.string().optional(),
+});
+const operationSchema = z.discriminatedUnion('status', [
+    z.strictObject({
+        status: z.literal('ready'),
+        profileId: z.string().min(1),
+        pending: pendingSchema,
+        answer: acceptedAnswerSchema,
+        readyAt: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('running'),
+        pageGrant: pageGrant.optional(),
+        claimToken: z.string().min(1),
+        startedAt: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('settled'),
+        pageGrant: pageGrant.optional(),
+        outcome: toolOperationOutcomeSchema,
+        settledAt: z.number().finite().nonnegative(),
+        retainUntil: z.number().finite().nonnegative().optional(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('uncertain'),
+        pageGrant: pageGrant.optional(),
+        claimToken: z.string().min(1),
+        reason: z.enum(['execution_interrupted', 'settlement_write_failed', 'worker_lost']),
+        detectedAt: z.number().finite().nonnegative(),
+    }),
+]);
+/** Stored authority is checked before the handler reads or changes it. */
+export const theoremSessionStateSchema = z
+    .strictObject({
+    version: z.literal(3),
+    operations: z.record(z.string().min(1), operationSchema),
+    permissions: z.array(z.string().min(1)),
+    gates: z.record(z.string().min(1), pendingSchema),
+    providerCheckpoints: z.array(z.string().min(1)),
+})
+    .superRefine((state, ctx) => {
+    for (const [operationId, operation] of Object.entries(state.operations)) {
+        const reference = operation.status === 'ready' ? operation.pending : operation;
+        if (reference.operationId !== operationId ||
+            (operation.status === 'ready' && operation.profileId !== operation.pending.profileId) ||
+            operationId in state.gates ||
+            (operation.status === 'settled' &&
+                (operation.outcome.event.tool.operationId !== operationId ||
+                    operation.outcome.event.tool.callId !== operation.callId ||
+                    operation.outcome.event.tool.name !== operation.toolId))) {
+            ctx.addIssue({ code: 'custom', path: ['operations', operationId] });
+        }
+    }
+    for (const [operationId, gate] of Object.entries(state.gates)) {
+        if (operationId !== gate.operationId)
+            ctx.addIssue({ code: 'custom', path: ['gates', operationId] });
+    }
+});
 export function emptySessionState() {
-    return { permissions: [], gates: {}, settled: {}, interactions: [] };
+    return {
+        version: 3,
+        operations: {},
+        permissions: [],
+        gates: {},
+        providerCheckpoints: [],
+    };
 }
 /** Drop gates (waiting or settled) older than `ttlMs`. */
 export function pruneGates(gates, now, ttlMs) {
-    return Object.fromEntries(Object.entries(gates).filter(([, gate]) => !gateExpired(gate.createdAt, now, ttlMs)));
+    return Object.fromEntries(Object.entries(gates).filter(([, gate]) => gate.expiresAt !== undefined
+        ? now < gate.expiresAt
+        : !gateExpired(gate.createdAt, now, ttlMs)));
 }
-/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
-export function createMemorySessionMap(options = {}) {
+export function memoryStoreLimits(options) {
     const ttlMs = options.ttlMs ?? 24 * 60 * 60 * 1000;
     const maxSessions = options.maxSessions ?? 10_000;
+    if (!Number.isFinite(ttlMs) ||
+        ttlMs <= 0 ||
+        !Number.isSafeInteger(maxSessions) ||
+        maxSessions <= 0) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_store_options', ttlMs, maxSessions },
+        });
+    }
+    return { ttlMs, maxSessions };
+}
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export function createMemorySessionMap(options = {}) {
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
     const sessions = new Map();
     return {
         load(sessionId) {
@@ -45,5 +218,47 @@ export function createMemorySessionMap(options = {}) {
     };
 }
 export function createMemorySessionStore(options = {}) {
-    return createMemorySessionMap(options);
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
+    const limits = resolveSessionLimits(options.sessionLimits);
+    const sessions = new Map();
+    const held = (entry) => Object.values(entry.snapshot.state.gates).some((gate) => gate.expiresAt === undefined || Date.now() < gate.expiresAt) ||
+        Object.values(entry.snapshot.state.operations).some((operation) => operation.status !== 'settled' ||
+            Date.now() <
+                (operation.retainUntil ?? operation.settledAt + DEFAULT_OPERATION_RETENTION_MS));
+    const current = (sessionId) => {
+        const entry = sessions.get(sessionId);
+        if (entry && !held(entry) && Date.now() - entry.touched >= ttlMs) {
+            sessions.delete(sessionId);
+            return undefined;
+        }
+        return entry?.snapshot;
+    };
+    return {
+        load(sessionId) {
+            return Promise.resolve(structuredClone(current(sessionId)));
+        },
+        compareAndSwap(sessionId, expectedRevision, next) {
+            const snapshot = current(sessionId);
+            if ((snapshot?.revision ?? null) !== expectedRevision)
+                return Promise.resolve({ written: false });
+            const state = theoremSessionStateSchema.parse(next);
+            checkSessionLimits(state, limits);
+            if (!snapshot && sessions.size >= maxSessions) {
+                const removable = [...sessions].find(([, entry]) => !held(entry));
+                if (!removable) {
+                    throw new TheoremError('unavailable', labelText('error.unavailable'), {
+                        cause: { code: 'session_store_capacity' },
+                    });
+                }
+                sessions.delete(removable[0]);
+            }
+            const revision = crypto.randomUUID();
+            sessions.delete(sessionId);
+            sessions.set(sessionId, {
+                snapshot: { revision, state: structuredClone(state) },
+                touched: Date.now(),
+            });
+            return Promise.resolve({ written: true, revision });
+        },
+    };
 }

package/server/single-action.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The shape the decision and embedding handlers share: `GET <base>` answers the profile's
+ * interface, `POST <base>/<action>` answers `{ result }`, and a failure is worded with the
+ * profile's labels.
+ *
+ * @module
+ */
+import { type ProfileDefinition } from '@theoremjs/agents';
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+export type SingleActionOptions = {
+    /** The last path segment the POST is sent to, such as `decide`. */
+    action: string;
+    /** What `GET <base>` answers, as `{ interface }`. */
+    iface: unknown;
+    labels: ProfileDefinition['labels'];
+    clientEvents?: ClientTurnOptions;
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+export declare function singleActionHandler({ action, iface, labels, clientEvents, onError }: SingleActionOptions, run: (request: Request) => Promise<unknown>): (request: Request) => Promise<Response>;

package/server/single-action.js

@@ -0,0 +1,30 @@
+/**
+ * The shape the decision and embedding handlers share: `GET <base>` answers the profile's
+ * interface, `POST <base>/<action>` answers `{ result }`, and a failure is worded with the
+ * profile's labels.
+ *
+ * @module
+ */
+import { labelText } from '@theoremjs/agents';
+import { caughtStatus, clientError, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { jsonResponse } from "./json-response.js";
+export function singleActionHandler({ action, iface, labels, clientEvents, onError }, run) {
+    const isAction = (request) => new URL(request.url).pathname.split('/').filter(Boolean).at(-1) === action;
+    return async (request) => {
+        try {
+            if (request.method === 'GET' && !isAction(request))
+                return jsonResponse(200, { interface: iface });
+            if (request.method !== 'POST' || !isAction(request)) {
+                return jsonResponse(HTTP_METHOD, {
+                    error: labelText('error.request', {}, labels),
+                    errorKind: 'request',
+                });
+            }
+            return jsonResponse(200, { result: await run(request) });
+        }
+        catch (err) {
+            onError?.(err, { request });
+            return jsonResponse(caughtStatus(err), clientError(err, labels, clientEvents));
+        }
+    };
+}

package/server/steer-inbox.js

@@ -14,7 +14,7 @@ const STEER_STAGES = new Set(['pre_turn', 'post_tool', 'before_end']);
  */
 export function steerUnitOf(steer) {
     const messages = steer.inject.filter((message) => message.role === 'user');
-    // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+    // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
     if (!messages.length)
         throw new TheoremError('request', 'inject must contain user messages');
     return { id: steer.id, messages };

package/server/tool-operations.d.ts

@@ -0,0 +1,6 @@
+import { type ToolExecutionCoordinator } from '@theoremjs/agents';
+import type { TheoremSessionState } from './session-store.ts';
+export declare function sessionToolCoordinator(store: {
+    mutate<T>(id: string, change: (state: TheoremSessionState) => T): Promise<T>;
+}, sessionId: string): ToolExecutionCoordinator;
+export declare function sameAcceptedAnswer(left: unknown, right: unknown): boolean;

package/server/tool-operations.js

@@ -0,0 +1,132 @@
+import { labelText, TheoremError, } from '@theoremjs/agents';
+function unavailable() {
+    throw new TheoremError('unavailable', labelText('error.unavailable'));
+}
+function sameOperation(record, identity) {
+    return (record.operationId === identity.operationId &&
+        record.callId === identity.callId &&
+        record.profileId === identity.profileId &&
+        record.toolId === identity.toolId &&
+        record.invocationHash === identity.invocationHash);
+}
+function checkedRecord(state, identity) {
+    if (identity.operationId === '__proto__')
+        unavailable();
+    const record = Object.hasOwn(state.operations, identity.operationId)
+        ? state.operations[identity.operationId]
+        : undefined;
+    if (record?.status === 'ready') {
+        if (record.pending.callId !== identity.callId ||
+            record.pending.profileId !== identity.profileId ||
+            record.pending.name !== identity.toolId ||
+            record.profileId !== identity.profileId)
+            unavailable();
+    }
+    else if (record && !sameOperation(record, identity))
+        unavailable();
+    return record;
+}
+function checkedClaim(state, claim) {
+    const record = checkedRecord(state, claim);
+    if (!record ||
+        (record.status !== 'running' && record.status !== 'uncertain') ||
+        record.claimToken !== claim.claimToken)
+        unavailable();
+    return record;
+}
+function existingResult(record) {
+    if (record?.status === 'settled')
+        return { kind: 'settled', outcome: record.outcome };
+    if (record?.status === 'running')
+        return { kind: 'running' };
+    if (record?.status === 'uncertain')
+        return { kind: 'uncertain' };
+    return undefined;
+}
+function saveOutcome(state, identity, outcome) {
+    const before = state.operations[identity.operationId];
+    const pageGrant = before && before.status !== 'ready' ? before.pageGrant : undefined;
+    const settledAt = Date.now();
+    const { operationId, callId, profileId, toolId, invocationHash, invocation } = identity;
+    state.operations[identity.operationId] = {
+        operationId,
+        callId,
+        profileId,
+        toolId,
+        invocationHash,
+        ...(invocation ? { invocation } : {}),
+        status: 'settled',
+        ...(pageGrant ? { pageGrant } : {}),
+        outcome,
+        settledAt,
+    };
+}
+export function sessionToolCoordinator(store, sessionId) {
+    return {
+        lookup(identity) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                return existingResult(record);
+            });
+        },
+        begin(identity) {
+            const claimToken = crypto.randomUUID();
+            const startedAt = Date.now();
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                const existing = existingResult(record);
+                if (existing)
+                    return existing;
+                state.operations[identity.operationId] = {
+                    ...identity,
+                    status: 'running',
+                    claimToken,
+                    startedAt,
+                };
+                return { kind: 'acquired', claimToken };
+            });
+        },
+        settle(claim, outcome) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedClaim(state, claim);
+                saveOutcome(state, { ...claim, invocation: record.invocation }, outcome);
+            });
+        },
+        settleNotStarted(identity, outcome) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                if (record && record.status !== 'ready')
+                    unavailable();
+                if (outcome.effects !== 'not_started')
+                    unavailable();
+                saveOutcome(state, identity, outcome);
+            });
+        },
+        markUncertain(claim, reason) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedClaim(state, claim);
+                state.operations[claim.operationId] = {
+                    ...claim,
+                    invocation: record.invocation,
+                    ...(record.pageGrant ? { pageGrant: record.pageGrant } : {}),
+                    status: 'uncertain',
+                    reason,
+                    detectedAt: Date.now(),
+                };
+            });
+        },
+    };
+}
+export function sameAcceptedAnswer(left, right) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value)
+                .filter(([, item]) => item !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([key, item]) => [key, canonical(item)]));
+        return value;
+    };
+    return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}

package/server/turn-input.d.ts

@@ -0,0 +1,10 @@
+import type { SessionRequest, TurnInput } from '@theoremjs/agents';
+import type { LiveOpenMessage } from '../client/live-messages.ts';
+import type { TheoremTurnInput } from '../client/transport.ts';
+/** A turn input off the wire as the kernel takes it: the page's context is the client's. */
+export declare function kernelTurnInput(input: TheoremTurnInput, server?: unknown): TurnInput;
+/**
+ * What a live call's first message asks of the session, as `runSession` takes
+ * it: the page's context is the client's, and `server` is the host's own.
+ */
+export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history'>;

package/server/turn-input.js

@@ -0,0 +1,29 @@
+/** The page's context as the client's and the host's as the server's; nothing when neither gave any. */
+function turnContext(client, server) {
+    const context = {
+        ...(client === undefined ? {} : { client }),
+        ...(server === undefined ? {} : { server }),
+    };
+    return Object.keys(context).length > 0 ? context : undefined;
+}
+/** A turn input off the wire as the kernel takes it: the page's context is the client's. */
+export function kernelTurnInput(input, server) {
+    const { context: client, ...rest } = input;
+    const context = turnContext(client, server);
+    return context ? { ...rest, context } : rest;
+}
+/**
+ * What a live call's first message asks of the session, as `runSession` takes
+ * it: the page's context is the client's, and `server` is the host's own.
+ */
+export function liveSessionOpen(open, server) {
+    const context = turnContext(open.context, server);
+    return {
+        ...(open.history ? { history: open.history } : {}),
+        ...(open.slots ? { slots: open.slots } : {}),
+        ...(context ? { context } : {}),
+        ...(open.resume
+            ? { providerState: open.resume.providerState, awayMs: open.resume.awayMs }
+            : {}),
+    };
+}