@theoremjs/web 0.3.4-next.604.ge4d5866 → 0.3.4-next.608.gd007c52

package/README.md

@@ -243,10 +243,26 @@ const transport = withPageToolDispatch(
 | `sessionStore`, `steerInbox` | Where open gates are kept, and where steers and stops reach a running turn. Default: process memory, which reaches only turns this process runs. On more than one instance, give a shared `SteerInbox`. |
 | `credentialStore` | Where tool credentials are kept, by session. Default: process memory. |
 | `authorizationUrl` | Returns the sign-in URL for an OAuth gate. Without it, an OAuth gate has no URL. |
-| `gateTtlMs` | How long a gate waits for an answer. Default: 30 minutes. A later answer fails with `session.gate_expired`. |
+| `gateTtlMs` | How long a gate waits for an answer. A later answer fails with `session.gate_expired`. Unset, a gate waits until it is answered. |
+| `maxRequestBytes` | The largest browser request body, in bytes. Unset, a body of any size is read. |
+| `pageToolTimeoutMs` | How long the page has to answer a tool call it runs. A call it has not answered by then settles as timed out. Unset, the call waits until the page answers or the turn stops. |
+| `operationRetentionMs` | How long a settled tool result is kept. Default: 24 hours. |
 | `clientEvents` | Options for `forClient` and `clientError`, which prepare each event and each caught failure for the browser. `reader: 'builder'` sends the raw reason in place of the wording of the profile. Use it only in a development tool on your own machine. |
 | `onError` | Receives each error that the handler catches. A visitor sees the wording of the profile for that kind of error, never the error. |
 
+### Defaults
+
+A limit that stops a turn or refuses a request is unset unless you set it: `gateTtlMs`, `maxRequestBytes`, `pageToolTimeoutMs`, and a session store's `capacity`. Only what keeps stored data from growing without end has a default:
+
+| What | Default | Set it with |
+| --- | --- | --- |
+| A settled tool result | Kept 24 hours | `operationRetentionMs` |
+| A session in `createMemorySessionStore` | Dropped after 24 idle hours; at most 10,000 kept | `ttlMs`, `maxSessions` |
+| A conversation in `createMemoryConversationStore` | Dropped after 24 hours unsaved; at most 10,000 kept | `ttlMs`, `maxSessions` |
+| The session cookie | Lasts 30 days | `session` |
+
+A model profile that leaves out `maxSteps` makes at most 20 model calls a turn.
+
 ### Start a conversation with content
 
 `startConversation` stores a conversation that opens on blocks you wrote, and returns its ref and its view. The model reads the blocks as history, so the user's next message is a follow-up.
@@ -388,7 +404,7 @@ A session store with a real limit declares its `capacity`: what it holds for one
 
 A store that declares no `capacity` holds any size. `createMemorySessionStore` declares none unless you pass `capacity`, with both fields. A store you write declares the capacity of its own storage, if it has one.
 
-Set `maxRequestBytes` to bound browser JSON before parsing. Its default is 16 MiB.
+Set `maxRequestBytes` to bound browser JSON before parsing. Unset, a body of any size is read. A relay passes the same number to `parseLiveOpenMessage` and `parseLiveClientMessage`.
 The handler rejects oversized requests before provider access or tool preparation.
 Provider host options also accept `limits` for deadlines and upstream output.
 When the store declares a capacity, the handler keeps room for one `maxOutcomeBytes` result for each gate and each call that has not settled.
@@ -413,7 +429,7 @@ Forward live page results to `answerPageResult`. Preserve checkpoint ownership t
 The default `PageToolBroker` keeps active result waiters in process memory. Several workers need a shared broker or request affinity.
 Use `pageToolBroker` to supply that broker. It carries results; the atomic session store retains execution authority.
 Lost result delivery does not permit another dispatch. The operation retains its claim or an uncertain outcome.
-The default result deadline is 20 seconds. An expired or interrupted result cannot reopen approval.
+Set `pageToolTimeoutMs` to give the page a deadline for a result. Unset, a dispatch waits until the page answers or the turn stops. An expired or interrupted result cannot reopen approval.
 
 ## Build your own server
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.604.ge4d5866",
+  "version": "0.3.4-next.608.gd007c52",
   "description": "Theorem on the web platform, with no UI framework: Web-standard server handlers that serve a profile, and the browser client that talks to them.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,6 @@
   },
   "peerDependencies": {
     "zod": "^4.6.5",
-    "@theoremjs/agents": "^0.3.4-next.604.ge4d5866"
+    "@theoremjs/agents": "^0.3.4-next.608.gd007c52"
   }
 }

package/server/handler.d.ts

@@ -97,14 +97,19 @@ export type TheoremHandlerOptions = {
     /**
      * How long a gate (permission, confirmation, sign-in) waits for its answer, in
      * milliseconds. An answer after that is refused with `session.gate_expired`.
-     * Default: 30 minutes.
+     * Unset, a gate waits until it is answered.
      */
     gateTtlMs?: number;
     /** Retain settled tool results in milliseconds. Default: 24 hours. */
     operationRetentionMs?: number;
-    /** Maximum UTF-8 request body bytes before JSON parsing. Default: 16 MiB. */
+    /** Maximum UTF-8 request body bytes before JSON parsing. Unset, a body of any size is read. */
     maxRequestBytes?: number;
     pageToolBroker?: PageToolBroker;
+    /**
+     * How long the page has to answer a tool call it runs, in milliseconds. A call it has not
+     * answered by then settles as timed out. Unset, it waits until the page answers or the turn stops.
+     */
+    pageToolTimeoutMs?: number;
     /** Check current resource access before disclosing a saved tool result. This callback must be read-only. */
     authorizeToolReplay?: (context: {
         request: Request;

package/server/handler.js

@@ -1,5 +1,5 @@
 import { withPublicLabels } from '@theoremjs/agents/guardrails';
-import { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
+import { checkPageToolTimeout, createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
 /**
  * One Web-standard handler that serves a Theorem chat UI for a single profile.
  *
@@ -368,7 +368,7 @@ async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answe
     yield* invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, sessionId),
-        pageExecution: sessionPageDispatch(ctx.sessions, sessionId, ctx.pageToolBroker).execution,
+        pageExecution: sessionPageDispatch(ctx.sessions, sessionId, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
         name: pending.name,
         callId,
         operationId: pending.operationId,
@@ -407,7 +407,7 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
         const prepared = await preparedTurn(ctx.options.prepare, {
             profile: ctx.profile.id,
             execution: sessionToolCoordinator(ctx.sessions, session.id),
-            pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).execution,
+            pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
             input: turn.input,
             ...(turn.providerState ? { providerState: turn.providerState } : {}),
             sessionPermissions: state.permissions,
@@ -574,7 +574,7 @@ async function* callEvents(ctx, request, session, body) {
     const events = invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, session.id),
-        pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).execution,
+        pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
         name: body.name,
         input: body.input,
         sessionPermissions: state.permissions,
@@ -691,7 +691,7 @@ async function hostRoute(ctx, request, session) {
 async function route(ctx, request, session) {
     if (request.method === 'POST' && routeOf(request) === 'page-result') {
         const body = await readBody(request, pageToolResultSchema, ctx.options.maxRequestBytes);
-        await sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).answer(body);
+        await sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).answer(body);
         return jsonResponse(200, { accepted: true });
     }
     if (ctx.profile.type === 'host')
@@ -779,6 +779,7 @@ function serve(name, profile, options, chatOptions = {}) {
         });
     }
     requestByteLimit(options.maxRequestBytes);
+    checkPageToolTimeout(options.pageToolTimeoutMs);
     registerProfile(profile);
     const ctx = {
         options,

package/server/mcp-handler.d.ts

@@ -30,7 +30,7 @@ export type TheoremMcpHandlerOptions = {
     origins?: readonly string[];
     /** Handed to each tool as `ctx.host`. */
     host?: (request: Request) => unknown;
-    /** Largest request body read, in bytes. */
+    /** Largest request body read, in bytes. Unset, a body of any size is read. */
     maxRequestBytes?: number;
     /** Who reads this host's replies: forwarded to `clientError` for a failure the handler catches. */
     clientEvents?: ClientTurnOptions;

package/server/page-dispatch.d.ts

@@ -16,6 +16,8 @@ export interface PageToolBroker {
     deliver(sessionId: string, grantId: string, page: PageAnswer): Promise<void>;
 }
 export declare function createMemoryPageToolBroker(maxPending?: number): PageToolBroker;
+/** Refuses a page tool timeout that is not a whole number of milliseconds a timer can hold. */
+export declare function checkPageToolTimeout(timeoutMs: number | undefined): void;
 export declare function sessionPageDispatch(store: MutableStore<TheoremSessionState>, sessionId: string, broker: PageToolBroker, timeoutMs?: number): {
     execution: PageToolExecution;
     answer(result: PageToolResult): Promise<boolean>;

package/server/page-dispatch.js

@@ -54,16 +54,21 @@ export function createMemoryPageToolBroker(maxPending = 128) {
         },
     };
 }
-export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000) {
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647)
+/** Refuses a page tool timeout that is not a whole number of milliseconds a timer can hold. */
+export function checkPageToolTimeout(timeoutMs) {
+    if (timeoutMs !== undefined &&
+        (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647))
         throw new TheoremError('config', labelText('error.config'));
+}
+export function sessionPageDispatch(store, sessionId, broker, timeoutMs) {
+    checkPageToolTimeout(timeoutMs);
     return {
         execution: {
             async dispatch(claim, signal) {
                 if (!claim.invocation)
                     refused('internal', 'The page dispatch got a claim with no invocation'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 const grantId = crypto.randomUUID();
-                const expiresAt = Date.now() + timeoutMs;
+                const expiresAt = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
                 const pending = broker.reserve(sessionId, grantId, signal);
                 try {
                     await store.mutate(sessionId, (state) => {
@@ -73,15 +78,15 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                             record.invocationHash !== claim.invocationHash ||
                             record.pageGrant)
                             refused('internal', 'The session store holds no running claim for this page dispatch');
-                        record.pageGrant = { grantId, expiresAt };
+                        record.pageGrant = { grantId, ...(expiresAt === undefined ? {} : { expiresAt }) };
                     });
                 }
                 catch (error) {
                     pending.cancel();
                     throw error;
                 }
-                const remaining = expiresAt - Date.now();
-                if (remaining <= 0 || signal?.aborted) {
+                const remaining = expiresAt === undefined ? undefined : expiresAt - Date.now();
+                if ((remaining !== undefined && remaining <= 0) || signal?.aborted) {
                     pending.cancel();
                     if (signal?.aborted)
                         refused('cancelled', 'The page dispatch was stopped before it was sent'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
@@ -91,7 +96,7 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                 const expired = new Promise((resolve) => {
                     expire = () => resolve({ timedOut: true });
                 });
-                const timer = setTimeout(expire, remaining);
+                const timer = remaining === undefined ? undefined : setTimeout(expire, remaining);
                 signal?.addEventListener('abort', expire, { once: true });
                 return {
                     grantId,
@@ -122,7 +127,7 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                 }
                 if (record.status !== 'running')
                     refused('request', `The page answered a call that is ${record.status}, not running`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-                if (Date.now() >= record.pageGrant.expiresAt)
+                if (record.pageGrant.expiresAt !== undefined && Date.now() >= record.pageGrant.expiresAt)
                     refused('timeout', 'The page answered after its grant expired'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 record.pageGrant.resultHash = hash;
                 return { duplicate: false, settled: false };

package/server/request-body.d.ts

@@ -1,2 +1,3 @@
-export declare function requestByteLimit(bytes?: number): number;
-export declare function boundedRequestJson(request: Request, maxBytes: number): Promise<unknown>;
+/** The host's request byte limit, checked. Unset, a request of any size is read. */
+export declare function requestByteLimit(bytes: number | undefined): number | undefined;
+export declare function boundedRequestJson(request: Request, maxBytes: number | undefined): Promise<unknown>;

package/server/request-body.js

@@ -1,13 +1,16 @@
 import { labelText, TheoremError, throwIfAborted } from '@theoremjs/agents';
-const DEFAULT_REQUEST_BYTES = 16 * 1024 * 1024;
-export function requestByteLimit(bytes = DEFAULT_REQUEST_BYTES) {
+/** The host's request byte limit, checked. Unset, a request of any size is read. */
+export function requestByteLimit(bytes) {
+    if (bytes === undefined)
+        return undefined;
     if (!Number.isSafeInteger(bytes) || bytes <= 0) {
         throw new TheoremError('config', labelText('error.config'));
     }
     return bytes;
 }
 export async function boundedRequestJson(request, maxBytes) {
-    if (Number(request.headers.get('content-length')) > maxBytes || !request.body) {
+    if ((maxBytes !== undefined && Number(request.headers.get('content-length')) > maxBytes) ||
+        !request.body) {
         throw new TheoremError('request', labelText('error.request'));
     }
     const reader = request.body.getReader();
@@ -26,7 +29,7 @@ export async function boundedRequestJson(request, maxBytes) {
             if (next.done)
                 break;
             bytes += next.value.byteLength;
-            if (bytes > maxBytes)
+            if (maxBytes !== undefined && bytes > maxBytes)
                 throw new TheoremError('request', labelText('error.request'));
             if (next.value.byteLength)
                 text.push(decoder.decode(next.value, { stream: true }));

package/server/request-check.d.ts

@@ -11,11 +11,12 @@ import { type LiveClientMessage, type LiveOpenMessage } from '../client/live-mes
 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.
+ * `liveClientMessageSchema`, else a `request` error. A frame over `maxBytes`, when set, is refused.
  */
-export declare function parseLiveClientMessage(text: string): LiveClientMessage;
+export declare function parseLiveClientMessage(text: string, maxBytes?: number): LiveClientMessage;
 /**
  * The live client's first frame, as a relay reads it before it opens the
- * session: JSON that passes `liveOpenMessageSchema`, else a `request` error.
+ * session: JSON that passes `liveOpenMessageSchema`, else a `request` error. A frame over
+ * `maxBytes`, when set, is refused.
  */
-export declare function parseLiveOpenMessage(text: string): LiveOpenMessage;
+export declare function parseLiveOpenMessage(text: string, maxBytes?: number): LiveOpenMessage;

package/server/request-check.js

@@ -18,9 +18,10 @@ export function checkRequest(schema, raw, what) {
     }
     return parsed.data;
 }
-function liveFrame(text) {
-    const limit = requestByteLimit();
-    if (text.length > limit || new TextEncoder().encode(text).byteLength > limit)
+function liveFrame(text, maxBytes) {
+    const limit = requestByteLimit(maxBytes);
+    if (limit !== undefined &&
+        (text.length > limit || new TextEncoder().encode(text).byteLength > limit))
         throw new TheoremError('request', labelText('error.request'));
     try {
         return JSON.parse(text);
@@ -34,16 +35,17 @@ function liveFrame(text) {
 }
 /**
  * One text frame from the live client, as a relay reads it: JSON that passes
- * `liveClientMessageSchema`, else a `request` error.
+ * `liveClientMessageSchema`, else a `request` error. A frame over `maxBytes`, when set, is refused.
  */
-export function parseLiveClientMessage(text) {
-    return checkRequest(liveClientMessageSchema, liveFrame(text), 'live message');
+export function parseLiveClientMessage(text, maxBytes) {
+    return checkRequest(liveClientMessageSchema, liveFrame(text, maxBytes), '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.
+ * session: JSON that passes `liveOpenMessageSchema`, else a `request` error. A frame over
+ * `maxBytes`, when set, is refused.
  */
-export function parseLiveOpenMessage(text) {
+export function parseLiveOpenMessage(text, maxBytes) {
     // labels-exempt: internal diagnostic; the user reads the error kind's wording
-    return checkRequest(liveOpenMessageSchema, liveFrame(text), 'live open message');
+    return checkRequest(liveOpenMessageSchema, liveFrame(text, maxBytes), 'live open message');
 }

package/server/session-authority.d.ts

@@ -9,4 +9,4 @@ export type SessionStateStore = MutableStore<TheoremSessionState> & {
     readonly capacity?: TheoremSessionCapacity;
 };
 /** 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): SessionStateStore;
+export declare function sessionStateStore(store: TheoremSessionStore, gateTtlMs: number | undefined, operationRetentionMs: number): SessionStateStore;

package/server/session-authority.js

@@ -23,8 +23,9 @@ export function sessionStateStore(store, gateTtlMs, operationRetentionMs) {
             });
         }
         const state = structuredClone(parsed.data);
-        for (const gate of Object.values(state.gates))
-            gate.expiresAt ??= gate.createdAt + gateTtlMs;
+        if (gateTtlMs !== undefined)
+            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)
@@ -44,8 +45,9 @@ export function sessionStateStore(store, gateTtlMs, operationRetentionMs) {
             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;
+                if (gateTtlMs !== undefined)
+                    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;

package/server/session-boundary.d.ts

@@ -9,6 +9,8 @@ export interface SessionBoundaryOptions {
     gateTtlMs?: number;
     operationRetentionMs?: number;
     pageToolBroker?: PageToolBroker;
+    /** How long the page has to answer a tool call it runs, in milliseconds. Unset, it waits. */
+    pageToolTimeoutMs?: number;
 }
 export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs'>;
 export interface TheoremSessionBoundary {

package/server/session-boundary.js

@@ -22,7 +22,7 @@ export async function createTheoremSessionBoundary(options) {
     const store = sessionStateStore(options.sessionStore, resolveGateTtlMs('session boundary', options.gateTtlMs), retention);
     // invariant: Refuse unavailable or malformed authority before an upstream connection opens.
     await store.read(id);
-    const page = sessionPageDispatch(store, id, options.pageToolBroker ?? createMemoryPageToolBroker());
+    const page = sessionPageDispatch(store, id, options.pageToolBroker ?? createMemoryPageToolBroker(), options.pageToolTimeoutMs);
     return {
         pageExecution: page.execution,
         answerPageResult: page.answer,

package/server/session-store.d.ts

@@ -33,7 +33,7 @@ export type PendingToolGate = {
 };
 export type SessionPageGrant = {
     grantId: string;
-    expiresAt: number;
+    expiresAt?: number;
     resultHash?: string;
 };
 export type SessionToolOperation = {
@@ -98,11 +98,11 @@ export interface TheoremSessionStore {
     compareAndSwap(sessionId: string, expectedRevision: string | null, next: TheoremSessionState): Promise<SessionWriteResult>;
 }
 export declare function emptySessionState(): TheoremSessionState;
-/** Drop gates (waiting or settled) older than `ttlMs`. */
+/** Drop gates (waiting or settled) older than `ttlMs`, or past their own `expiresAt`. */
 export declare function pruneGates<Gate extends {
     createdAt: number;
     expiresAt?: number;
-}>(gates: Record<string, Gate>, now: number, ttlMs: number): Record<string, Gate>;
+}>(gates: Record<string, Gate>, now: number, ttlMs: number | undefined): Record<string, Gate>;
 export type MemorySessionStoreOptions = {
     /** What it holds for one session. Unset, it holds any size. */
     capacity?: TheoremSessionCapacity;

package/server/session-store.js

@@ -100,7 +100,7 @@ const identityFields = {
 };
 const pageGrant = z.strictObject({
     grantId: z.string().min(1),
-    expiresAt: z.number().finite().positive(),
+    expiresAt: z.number().finite().positive().optional(),
     resultHash: z.string().optional(),
 });
 const operationSchema = z.discriminatedUnion('status', [
@@ -171,7 +171,7 @@ export function emptySessionState() {
         providerCheckpoints: [],
     };
 }
-/** Drop gates (waiting or settled) older than `ttlMs`. */
+/** Drop gates (waiting or settled) older than `ttlMs`, or past their own `expiresAt`. */
 export function pruneGates(gates, now, ttlMs) {
     return Object.fromEntries(Object.entries(gates).filter(([, gate]) => gate.expiresAt !== undefined
         ? now < gate.expiresAt