@theoremjs/web 0.3.4-next.586.ga59d695 → 0.3.4-next.594.g145ceaf

package/README.md

@@ -237,6 +237,7 @@ const transport = withPageToolDispatch(
 | `session` | Returns the session id of the caller, for example `${userId}:${conversationId}`. Return `undefined` to refuse the request with a 401. Default: a random id in an HttpOnly, SameSite=Lax cookie that lasts 30 days. |
 | `host` | App data for the tool handlers (`ctx.host`), such as the signed-in user. |
 | `prepare` | Your app's own turn, from the one the handler builds (`TurnWiring.prepare` from `@theoremjs/agents`). Set what your app sets per turn, such as `system`, `credentials`, `onStage` and `onAgentCall`; read your app data as `turn.host`. The handler keeps its profile, its tool execution and its abort. Your `onStage` runs before the handler's steering, and your `credentials` are read before the session's. |
+| `onStage` | The server's own stage handler, on every call the handler runs, a host profile's included: after your app's (`prepare`), before steering. For a rule the server adds to whatever the app says, such as a question before each tool that writes. |
 | `pageToolBroker` | Delivers results to active page dispatches. Default: bounded process memory. |
 | `conversationStore` | Where the conversation is kept. Required, except for a stateless profile, which must not have one. See [Keep the conversation](#keep-the-conversation). |
 | `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`. |
@@ -378,26 +379,23 @@ Each saved outcome records its absolute retention deadline. Changing a handler's
 Each issued gate records its absolute expiry. Changing `gateTtlMs` does not extend an issued gate.
 Ready, running, and uncertain operations do not expire.
 
-Use `sessionLimits` when your storage budget requires different finite limits. The defaults are:
+A session store declares its `capacity`: what it holds for one session, in bytes of UTF-8 JSON.
 
-| Limit | Default |
-| --- | --- |
-| `maxGates` | 32 |
-| `maxOperations` | 128 |
-| `maxCheckpoints` | 256 |
-| `maxPermissions` | 2,048 |
-| `maxStateBytes` | 32 MiB |
-| `maxInvocationBytes` | 256 KiB |
-| `maxOutcomeBytes` | 256 KiB |
+| Field | What it bounds | Memory store default |
+| --- | --- | --- |
+| `maxStateBytes` | One session's saved state | 16 MiB |
+| `maxOutcomeBytes` | One tool result | 1 MiB (`DEFAULT_MAX_OUTCOME_BYTES`) |
+
+Pass `capacity` to `createMemorySessionStore` to change them. A store you write declares the capacity of its own storage.
 
 Set `maxRequestBytes` to bound browser JSON before parsing. Its default is 16 MiB.
 The handler rejects oversized requests before provider access or tool preparation.
 Provider host options also accept `limits` for deadlines and upstream output.
-Byte limits measure UTF-8 JSON. The handler reserves one maximum outcome for each gate and unresolved operation.
-A new claim fails before dispatch when it cannot reserve that space.
-An oversized result after dispatch leaves an uncertain claim. It does not restore an approval.
-Limits never remove unresolved authority or shorten retained settlements. The host must reconcile and archive unresolved actions.
-The memory store accepts the same `sessionLimits` options. Shared stores receive checked states through the handler.
+The handler keeps room for one `maxOutcomeBytes` result for each gate and each call that has not settled.
+When a session is full, the handler drops its oldest settled results, then its oldest provider checkpoints.
+It never drops gates, permissions, or calls that have not settled. When those alone do not fit, the new call is refused before it runs, and the user reads `session.full`.
+A result larger than `maxOutcomeBytes` settles as the call's `result_too_large` failure. The call is never left unresolved because of its size.
+The handler fits each state to the store's capacity before `compareAndSwap`.
 
 The default memory store coordinates handlers that share the same store object.
 It retains unexpired gates, unresolved operations, and unexpired outcomes during idle and capacity eviction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.586.ga59d695",
+  "version": "0.3.4-next.594.g145ceaf",
   "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.586.ga59d695"
+    "@theoremjs/agents": "^0.3.4-next.594.g145ceaf"
   }
 }

package/server/checkpoint-ownership.d.ts

@@ -3,4 +3,4 @@ import type { TheoremSessionState } from './session-store.ts';
 export declare function checkpointIdentity(checkpoint: ProviderCheckpoint): Promise<string>;
 export declare function checkpointOwnershipKey(identity: string, operations: TheoremSessionState['operations']): Promise<string>;
 export declare function requireOwnedCheckpoint(identities: readonly string[], checkpoint: ProviderCheckpoint | undefined, operations?: TheoremSessionState['operations'], portableHistory?: readonly TurnHistoryMessage[]): Promise<ProviderCheckpoint | undefined>;
-export declare function retainedCheckpointIdentities(existing: readonly string[], added: readonly string[], limit: number): string[];
+export declare function retainedCheckpointIdentities(existing: readonly string[], added: readonly string[]): string[];

package/server/checkpoint-ownership.js

@@ -37,6 +37,6 @@ export async function requireOwnedCheckpoint(identities, checkpoint, operations
     }
     return parsed;
 }
-export function retainedCheckpointIdentities(existing, added, limit) {
-    return [...new Set([...existing, ...added].reverse())].slice(0, limit).reverse();
+export function retainedCheckpointIdentities(existing, added) {
+    return [...new Set([...existing, ...added].reverse())].reverse();
 }

package/server/handler.d.ts

@@ -32,12 +32,11 @@ import { type PageToolBroker } from './page-dispatch.ts';
  *
  * @module
  */
-import { type Profile, type ProfileDefinition, type ProviderHostOptions, type ToolGate, type TurnWiring, type z } from '@theoremjs/agents';
+import { type Profile, type ProfileDefinition, type ProviderHostOptions, type StageHandler, type ToolGate, type TurnWiring, type z } from '@theoremjs/agents';
 import { type ClientTurnOptions } from '@theoremjs/agents/host';
 import { type TheoremConversationStore } from './conversation-store.ts';
 import { type TheoremCredentialStore } from './credential-store.ts';
 export { theoremSession, theoremSessionId } from './session-identity.ts';
-import { type TheoremSessionLimits } from './session-limits.ts';
 import { type SessionToolOperation, type TheoremSessionStore } from './session-store.ts';
 import { type SteerInbox } from './steer-inbox.ts';
 export type TheoremRequestContext = {
@@ -72,6 +71,12 @@ export type TheoremHandlerOptions = {
      * answered, with the `onStage` and `credentials` it gives for that call's turn.
      */
     prepare?: TurnWiring['prepare'];
+    /**
+     * The server's own stage handler, on every call this handler runs, a host's included: after
+     * the application's, before steering. For a rule the server adds to whatever the application
+     * says, such as a question before each tool that writes.
+     */
+    onStage?: StageHandler;
     /**
      * Resolve the caller's session id — e.g. `${userId}:${conversationId}` from your
      * auth. Return `undefined` to refuse the request (401). Default: an opaque id
@@ -97,8 +102,6 @@ export type TheoremHandlerOptions = {
     gateTtlMs?: number;
     /** Retain settled tool results in milliseconds. Default: 24 hours. */
     operationRetentionMs?: number;
-    /** Finite per-session bounds. Unresolved authority is never evicted to satisfy them. */
-    sessionLimits?: Partial<TheoremSessionLimits>;
     /** Maximum UTF-8 request body bytes before JSON parsing. Default: 16 MiB. */
     maxRequestBytes?: number;
     pageToolBroker?: PageToolBroker;

package/server/handler.js

@@ -42,17 +42,16 @@ import { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremRe
 import { answerReply, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, requiredOperationId, rewindConversation, statelessRefusal, waitingCalls, } from "./conversation.js";
 import { unknownConversation } from "./conversation-store.js";
 import { createMemoryCredentialStore, } from "./credential-store.js";
-import { sessionStateStore } from "./session-authority.js";
+import { sessionStateStore, } from "./session-authority.js";
 import { theoremSession } from "./session-identity.js";
 export { theoremSession, theoremSessionId } from "./session-identity.js";
 import { jsonResponse } from "./json-response.js";
 import { boundedRequestJson, requestByteLimit } from "./request-body.js";
 import { checkRequest } from "./request-check.js";
-import { resolveSessionLimits } from "./session-limits.js";
 import { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, } from "./session-store.js";
 import { createMemorySteerInbox, steerStage, steerUnitOf, stopOnRequest, } from "./steer-inbox.js";
 import { sameAcceptedAnswer, sessionToolCoordinator } from "./tool-operations.js";
-import { preparedTurn } from "./turn-wiring.js";
+import { preparedTurn, stagesInOrder } from "./turn-wiring.js";
 const NDJSON_HEADERS = {
     'content-type': 'application/x-ndjson; charset=utf-8',
     'cache-control': 'no-store',
@@ -216,7 +215,8 @@ async function recordOutcome(sessions, sessionId, events, context) {
         for (const { gate } of pending) {
             const operation = state.operations[gate.operationId];
             if (operation && operation.status !== 'ready')
-                throw new TheoremError('unavailable', labelText('error.unavailable'));
+                throw new TheoremError('unavailable', `Tool operation ${gate.operationId} is ${operation.status}, not ready, so its gate was not saved`, // labels-exempt: internal diagnostic; the user reads session.busy
+                { copy: { key: 'session.busy' } });
             delete state.operations[gate.operationId];
             Object.defineProperty(state.gates, gate.operationId, {
                 value: gate,
@@ -361,7 +361,10 @@ async function* settleAnswered(ctx, request, session, answered) {
 async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
     const host = await ctx.options.host?.(request);
     // why: The held call goes on with what the application set for its turn: its stage handler and credentials.
-    const { credentials, onStage } = await preparedTurn(ctx.options.prepare, { profile: ctx.profile.id, input: pending.turnInput ?? {}, host, signal: request.signal }, { credentials: sessionCredentials(ctx, sessionId) });
+    const { credentials, onStage } = await preparedTurn(ctx.options.prepare, { profile: ctx.profile.id, input: pending.turnInput ?? {}, host, signal: request.signal }, {
+        credentials: sessionCredentials(ctx, sessionId),
+        ...(ctx.options.onStage ? { onStage: ctx.options.onStage } : {}),
+    });
     yield* invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, sessionId),
@@ -400,6 +403,7 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
         stopOnRequest(ctx.inbox, key, stop);
     }
     try {
+        const onStage = stagesInOrder(ctx.options.onStage, key ? steerStage(ctx.inbox, key) : undefined);
         const prepared = await preparedTurn(ctx.options.prepare, {
             profile: ctx.profile.id,
             execution: sessionToolCoordinator(ctx.sessions, session.id),
@@ -413,7 +417,7 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
             ...(turn.effort ? { effort: turn.effort } : {}),
         }, {
             credentials: sessionCredentials(ctx, session.id),
-            ...(key ? { onStage: steerStage(ctx.inbox, key) } : {}),
+            ...(onStage ? { onStage } : {}),
         });
         const events = runTurn(prepared, provider);
         yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
@@ -575,6 +579,7 @@ async function* callEvents(ctx, request, session, body) {
         input: body.input,
         sessionPermissions: state.permissions,
         credentials: sessionCredentials(ctx, session.id),
+        ...(ctx.options.onStage ? { onStage: ctx.options.onStage } : {}),
         signal: request.signal,
         host,
     });
@@ -773,7 +778,6 @@ function serve(name, profile, options, chatOptions = {}) {
             cause: { code: 'operation_retention' },
         });
     }
-    const limits = resolveSessionLimits(options.sessionLimits);
     requestByteLimit(options.maxRequestBytes);
     registerProfile(profile);
     const ctx = {
@@ -782,7 +786,7 @@ function serve(name, profile, options, chatOptions = {}) {
         profile,
         ...(chatOptions.chat ? { chat: chatOptions.chat } : {}),
         inbox: chatOptions.steerInbox ?? createMemorySteerInbox(),
-        sessions: sessionStateStore(options.sessionStore ?? createMemorySessionStore({ sessionLimits: limits }), gateTtlMs, operationRetentionMs, limits),
+        sessions: sessionStateStore(options.sessionStore ?? createMemorySessionStore(), gateTtlMs, operationRetentionMs),
         credentials: lockedStore(options.credentialStore ?? createMemoryCredentialStore(), (saved = {}) => saved),
     };
     return async (request) => {

package/server/mod.d.ts

@@ -19,8 +19,8 @@ export { createMemoryPageToolBroker, type PageToolBroker, type PageToolResult, p
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from './request-check.ts';
 export { sessionStateStore } from './session-authority.ts';
 export { createTheoremSessionBoundary, type PreparedLiveOpen, type SessionBoundaryOptions, type TheoremSessionBoundary, } from './session-boundary.ts';
-export type { TheoremSessionLimits } from './session-limits.ts';
-export { resolveSessionLimits } from './session-limits.ts';
+export type { TheoremSessionCapacity } from './session-limits.ts';
+export { DEFAULT_SESSION_CAPACITY } from './session-limits.ts';
 export { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, type MemorySessionStoreOptions, type PendingToolGate, type SessionSnapshot, type SessionToolOperation, type SessionWriteResult, type TheoremSessionState, type TheoremSessionStore, theoremSessionStateSchema, } from './session-store.ts';
 export { createMemorySteerInbox, type SteerInbox, type SteerUnit, steerStage, steerUnitOf, stopOnRequest, } from './steer-inbox.ts';
 export { sessionToolCoordinator } from './tool-operations.ts';

package/server/mod.js

@@ -18,7 +18,7 @@ export { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch,
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from "./request-check.js";
 export { sessionStateStore } from "./session-authority.js";
 export { createTheoremSessionBoundary, } from "./session-boundary.js";
-export { resolveSessionLimits } from "./session-limits.js";
+export { DEFAULT_SESSION_CAPACITY } from "./session-limits.js";
 export { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, theoremSessionStateSchema, } from "./session-store.js";
 export { createMemorySteerInbox, steerStage, steerUnitOf, stopOnRequest, } from "./steer-inbox.js";
 export { sessionToolCoordinator } from "./tool-operations.js";

package/server/session-authority.d.ts

@@ -1,8 +1,12 @@
-import { type TheoremSessionLimits } from './session-limits.ts';
+import { type TheoremSessionCapacity } 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 the capacity its store declared. */
+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, limits: TheoremSessionLimits): MutableStore<TheoremSessionState>;
+export declare function sessionStateStore(store: TheoremSessionStore, gateTtlMs: number, operationRetentionMs: number): SessionStateStore;

package/server/session-authority.js

@@ -1,13 +1,14 @@
 import { labelText, TheoremError, z } from '@theoremjs/agents';
-import { checkSessionLimits } from "./session-limits.js";
+import { checkedCapacity, fitSession } 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) {
+export function sessionStateStore(store, gateTtlMs, operationRetentionMs) {
     if (typeof store.compareAndSwap !== 'function') {
         throw new TheoremError('config', labelText('error.config'), {
             cause: { code: 'session_store_contract', required: 'compareAndSwap' },
         });
     }
+    const capacity = checkedCapacity(store.capacity);
     const writeResult = z.discriminatedUnion('written', [
         z.strictObject({ written: z.literal(false) }),
         z.strictObject({ written: z.literal(true), revision: z.string().min(1) }),
@@ -34,6 +35,7 @@ export function sessionStateStore(store, gateTtlMs, operationRetentionMs, limits
         return { revision: snapshot?.revision ?? null, state };
     };
     return {
+        capacity,
         async read(sessionId) {
             return (await load(sessionId, Date.now())).state;
         },
@@ -48,7 +50,7 @@ export function sessionStateStore(store, gateTtlMs, operationRetentionMs, limits
                     if (operation.status === 'settled')
                         operation.retainUntil ??= operation.settledAt + operationRetentionMs;
                 }
-                checkSessionLimits(state, limits);
+                fitSession(state, capacity);
                 const next = theoremSessionStateSchema.safeParse(state);
                 if (!next.success) {
                     throw new TheoremError('config', labelText('error.config'), {
@@ -70,9 +72,8 @@ export function sessionStateStore(store, gateTtlMs, operationRetentionMs, limits
                     return result;
                 }
             }
-            throw new TheoremError('unavailable', labelText('error.unavailable'), {
-                cause: { code: 'session_store_contention' },
-            });
+            throw new TheoremError('unavailable', 'Other writes changed the session on each of 8 tries, so this change was not saved', // labels-exempt: internal diagnostic; the user reads session.busy
+            { copy: { key: 'session.busy' }, cause: { code: 'session_store_contention' } });
         },
     };
 }

package/server/session-boundary.d.ts

@@ -1,7 +1,6 @@
 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;
@@ -9,7 +8,6 @@ export interface SessionBoundaryOptions {
     sessionStore: TheoremSessionStore;
     gateTtlMs?: number;
     operationRetentionMs?: number;
-    sessionLimits?: Partial<TheoremSessionLimits>;
     pageToolBroker?: PageToolBroker;
 }
 export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs'>;

package/server/session-boundary.js

@@ -6,7 +6,6 @@ import { createMemoryPageToolBroker, sessionPageDispatch, } from "./page-dispatc
 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";
@@ -20,8 +19,7 @@ export async function createTheoremSessionBoundary(options) {
     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);
+    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());
@@ -56,7 +54,9 @@ export async function createTheoremSessionBoundary(options) {
         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);
+                state.providerCheckpoints = retainedCheckpointIdentities(state.providerCheckpoints, [
+                    await checkpointOwnershipKey(identity, state.operations),
+                ]);
             });
         },
     };

package/server/session-limits.d.ts

@@ -1,12 +1,19 @@
 import type { TheoremSessionState } from './session-store.ts';
-export interface TheoremSessionLimits {
-    maxGates: number;
-    maxOperations: number;
-    maxCheckpoints: number;
-    maxPermissions: number;
+/** What a session store holds for one session, in bytes of UTF-8 JSON. The store declares it. */
+export interface TheoremSessionCapacity {
+    /** The most one session's saved state may take. */
     maxStateBytes: number;
-    maxInvocationBytes: number;
+    /** The most one tool result may take. Room for one is kept for each call that has not settled. */
     maxOutcomeBytes: number;
 }
-export declare function resolveSessionLimits(options?: Partial<TheoremSessionLimits>): TheoremSessionLimits;
-export declare function checkSessionLimits(state: TheoremSessionState, limits: TheoremSessionLimits): void;
+/** The memory store's default: room for sixteen full-size tool results in each session. */
+export declare const DEFAULT_SESSION_CAPACITY: TheoremSessionCapacity;
+/** The store's declared capacity, refused as `config` unless both are positive and one result fits. */
+export declare function checkedCapacity(capacity: unknown): TheoremSessionCapacity;
+/**
+ * Fits the state in the store's capacity: drops the oldest settled results, then the oldest
+ * provider checkpoints, and refuses with `session.full` when open work alone does not fit.
+ *
+ * invariant: Gates, permissions and calls that have not settled are never dropped to make room.
+ */
+export declare function fitSession(state: TheoremSessionState, capacity: TheoremSessionCapacity): void;

package/server/session-limits.js

@@ -1,59 +1,57 @@
-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,
+import { DEFAULT_MAX_OUTCOME_BYTES, labelText, TheoremError } from '@theoremjs/agents';
+/** The memory store's default: room for sixteen full-size tool results in each session. */
+export const DEFAULT_SESSION_CAPACITY = {
+    maxStateBytes: 16 * DEFAULT_MAX_OUTCOME_BYTES,
+    maxOutcomeBytes: DEFAULT_MAX_OUTCOME_BYTES,
 };
-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)) {
+/** The store's declared capacity, refused as `config` unless both are positive and one result fits. */
+export function checkedCapacity(capacity) {
+    const { maxStateBytes, maxOutcomeBytes } = (capacity ?? {});
+    if (!Number.isSafeInteger(maxStateBytes) ||
+        !Number.isSafeInteger(maxOutcomeBytes) ||
+        maxOutcomeBytes <= 0 ||
+        maxStateBytes < maxOutcomeBytes) {
         throw new TheoremError('config', labelText('error.config'), {
-            cause: { code: 'session_limits' },
+            cause: { code: 'session_store_capacity_declared' },
         });
     }
-    return limits;
+    return { maxStateBytes: maxStateBytes, maxOutcomeBytes: maxOutcomeBytes };
 }
 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' },
-    });
+/** The bytes the state takes with room kept for the result of each gate and each call that has not settled. */
+function needed(state, capacity) {
+    const open = Object.keys(state.gates).length +
+        Object.values(state.operations).filter((operation) => operation.status !== 'settled').length;
+    return bytes(state) + open * capacity.maxOutcomeBytes;
 }
-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();
-        }
+/**
+ * Fits the state in the store's capacity: drops the oldest settled results, then the oldest
+ * provider checkpoints, and refuses with `session.full` when open work alone does not fit.
+ *
+ * invariant: Gates, permissions and calls that have not settled are never dropped to make room.
+ */
+export function fitSession(state, capacity) {
+    if (needed(state, capacity) <= capacity.maxStateBytes)
+        return;
+    const settled = Object.values(state.operations)
+        .flatMap((operation) => (operation.status === 'settled' ? [operation] : []))
+        .sort((a, b) => a.settledAt - b.settledAt);
+    for (const operation of settled) {
+        delete state.operations[operation.operationId];
+        if (needed(state, capacity) <= capacity.maxStateBytes)
+            return;
+    }
+    while (state.providerCheckpoints.length) {
+        state.providerCheckpoints.shift();
+        if (needed(state, capacity) <= capacity.maxStateBytes)
+            return;
     }
-    // invariant: Reserve terminal evidence before dispatch; unresolved records are never evicted to make room.
-    if (bytes(state) + reserved > limits.maxStateBytes)
-        capacity();
+    const need = needed(state, capacity);
+    throw new TheoremError('unavailable', `The session's open work needs ${need} bytes with room for its results, more than the store's maxStateBytes of ${capacity.maxStateBytes}`, // labels-exempt: internal diagnostic; the user reads session.full
+    {
+        copy: { key: 'session.full' },
+        cause: { code: 'session_state_capacity', need, maxStateBytes: capacity.maxStateBytes },
+    });
 }

package/server/session-store.d.ts

@@ -11,7 +11,7 @@
 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';
+import { type TheoremSessionCapacity } from './session-limits.ts';
 /** A tool call the kernel paused on a gate, as the server saw it. */
 export type PendingToolGate = {
     profileId: string;
@@ -88,6 +88,8 @@ export type SessionWriteResult = {
  * store (KV, Redis, a database row) when requests can reach different instances.
  */
 export interface TheoremSessionStore {
+    /** What it holds for one session. The handler fits each write to it before `compareAndSwap`. */
+    readonly capacity: TheoremSessionCapacity;
     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>;
@@ -99,8 +101,8 @@ export declare function pruneGates<Gate extends {
     expiresAt?: number;
 }>(gates: Record<string, Gate>, now: number, ttlMs: number): Record<string, Gate>;
 export type MemorySessionStoreOptions = {
-    /** Finite authority storage bounds. */
-    sessionLimits?: Partial<TheoremSessionLimits>;
+    /** What it holds for one session. Default {@linkcode DEFAULT_SESSION_CAPACITY}. */
+    capacity?: Partial<TheoremSessionCapacity>;
     /** invariant: Idle retention is in milliseconds. Protected authority remains. Default 24h. */
     ttlMs?: number;
     /** Oldest sessions are evicted past this count. Default 10 000. */

package/server/session-store.js

@@ -10,7 +10,7 @@
  */
 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";
+import { checkedCapacity, DEFAULT_SESSION_CAPACITY, } from "./session-limits.js";
 export const DEFAULT_OPERATION_RETENTION_MS = 24 * 60 * 60 * 1000;
 const blobSchema = z.strictObject({
     data: z.string(),
@@ -219,7 +219,7 @@ export function createMemorySessionMap(options = {}) {
 }
 export function createMemorySessionStore(options = {}) {
     const { ttlMs, maxSessions } = memoryStoreLimits(options);
-    const limits = resolveSessionLimits(options.sessionLimits);
+    const capacity = checkedCapacity({ ...DEFAULT_SESSION_CAPACITY, ...options.capacity });
     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' ||
@@ -234,6 +234,7 @@ export function createMemorySessionStore(options = {}) {
         return entry?.snapshot;
     };
     return {
+        capacity,
         load(sessionId) {
             return Promise.resolve(structuredClone(current(sessionId)));
         },
@@ -242,13 +243,11 @@ export function createMemorySessionStore(options = {}) {
             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' },
-                    });
+                    throw new TheoremError('unavailable', `The memory session store holds ${maxSessions} sessions and each has work in progress, so a new one was not saved`, // labels-exempt: internal diagnostic; the user reads session.busy
+                    { copy: { key: 'session.busy' }, cause: { code: 'session_store_capacity' } });
                 }
                 sessions.delete(removable[0]);
             }

package/server/tool-operations.d.ts

@@ -1,6 +1,9 @@
 import { type ToolExecutionCoordinator } from '@theoremjs/agents';
 import type { TheoremSessionState } from './session-store.ts';
 export declare function sessionToolCoordinator(store: {
+    readonly capacity: {
+        maxOutcomeBytes: number;
+    };
     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

@@ -1,6 +1,7 @@
-import { labelText, TheoremError, } from '@theoremjs/agents';
-function unavailable() {
-    throw new TheoremError('unavailable', labelText('error.unavailable'));
+import { TheoremError, } from '@theoremjs/agents';
+/** The session's record of a tool operation does not match the call: the user reads `tool.execution_uncertain`. */
+function unavailable(reason) {
+    throw new TheoremError('unavailable', reason, { copy: { key: 'tool.execution_uncertain' } });
 }
 function sameOperation(record, identity) {
     return (record.operationId === identity.operationId &&
@@ -10,8 +11,9 @@ function sameOperation(record, identity) {
         record.invocationHash === identity.invocationHash);
 }
 function checkedRecord(state, identity) {
+    // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
     if (identity.operationId === '__proto__')
-        unavailable();
+        unavailable('The tool operation id is __proto__');
     const record = Object.hasOwn(state.operations, identity.operationId)
         ? state.operations[identity.operationId]
         : undefined;
@@ -20,10 +22,12 @@ function checkedRecord(state, identity) {
             record.pending.profileId !== identity.profileId ||
             record.pending.name !== identity.toolId ||
             record.profileId !== identity.profileId)
-            unavailable();
+            // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+            unavailable(`The ready tool operation ${identity.operationId} is for another call`);
     }
     else if (record && !sameOperation(record, identity))
-        unavailable();
+        // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+        unavailable(`The session holds tool operation ${identity.operationId} for another call`);
     return record;
 }
 function checkedClaim(state, claim) {
@@ -31,7 +35,9 @@ function checkedClaim(state, claim) {
     if (!record ||
         (record.status !== 'running' && record.status !== 'uncertain') ||
         record.claimToken !== claim.claimToken)
-        unavailable();
+        unavailable(
+        // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+        `The claim on tool operation ${claim.operationId} is not the session's running claim`);
     return record;
 }
 function existingResult(record) {
@@ -63,6 +69,7 @@ function saveOutcome(state, identity, outcome) {
 }
 export function sessionToolCoordinator(store, sessionId) {
     return {
+        maxOutcomeBytes: store.capacity.maxOutcomeBytes,
         lookup(identity) {
             return store.mutate(sessionId, (state) => {
                 const record = checkedRecord(state, identity);
@@ -96,9 +103,13 @@ export function sessionToolCoordinator(store, sessionId) {
             return store.mutate(sessionId, (state) => {
                 const record = checkedRecord(state, identity);
                 if (record && record.status !== 'ready')
-                    unavailable();
+                    unavailable(
+                    // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+                    `Tool operation ${identity.operationId} is ${record.status}, so it cannot settle as not started`);
                 if (outcome.effects !== 'not_started')
-                    unavailable();
+                    unavailable(
+                    // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+                    `A not-started settlement of ${identity.operationId} has effects ${outcome.effects}`);
                 saveOutcome(state, identity, outcome);
             });
         },