@theoremjs/web 0.3.4-next.528.g44c76f9 → 0.3.4-next.540.g67b727f

package/README.md

@@ -282,7 +282,7 @@ The session store keeps gates, permissions, and operations. The two stores are s
 | `createSealedConversationStore({ keys, keyVersion })` | Nowhere on the server. The ref is the conversation itself, encrypted and signed with your key, and bound to the session. The browser cannot read it or change it. |
 | Your own `TheoremConversationStore` | Your database. |
 
-A ref that the store cannot open fails with `session.conversation_unknown`. This includes a ref from another session.
+A ref that the store cannot open fails with `session.conversation_unknown`, kind `not_found` (HTTP 404). This includes a ref from another session. A route or method the handler does not serve also answers 404 with kind `not_found`.
 
 The sealed store:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.528.g44c76f9",
+  "version": "0.3.4-next.540.g67b727f",
   "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.528.g44c76f9"
+    "@theoremjs/agents": "^0.3.4-next.540.g67b727f"
   }
 }

package/server/conversation-store.js

@@ -41,7 +41,7 @@ export function emptyConversation() {
 }
 /** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
 export function unknownConversation(cause) {
-    return new TheoremError('request', labelText('session.conversation_unknown'), {
+    return new TheoremError('not_found', labelText('session.conversation_unknown'), {
         copy: { key: 'session.conversation_unknown' },
         ...(cause === undefined ? {} : { cause }),
     });

package/server/handler.js

@@ -34,7 +34,7 @@ import { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch,
  * @module
  */
 import { authorizeToolReplay, compactHistory, defaultKernelScope, defineProfile, invokeTool, jsonObjectSchema, labelText, registerProfile, runTurn, TheoremError, toolInvocationHash, } from '@theoremjs/agents';
-import { caughtStatus, clientError, forClient, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { caughtStatus, clientError, forClient, HTTP_NOT_FOUND, } from '@theoremjs/agents/host';
 import { clientProfileInterface, gatedToolsFromEvents, interfaceFromProfile, promotedToolIdsFromEvents, toolSnapshotFromEvents, } from '@theoremjs/agents/interface';
 import { answerGatedCall, resolveGateTtlMs, } from '@theoremjs/agents/kernel';
 import { hostInterface, theoremHostCallRequestSchema, } from "../client/host-transport.js";
@@ -589,9 +589,9 @@ function answerRequest(body) {
 }
 /** A route this profile doesn't serve. */
 function refused(ctx) {
-    return jsonResponse(HTTP_METHOD, {
-        error: labelText('error.request', {}, ctx.profile.labels),
-        errorKind: 'request',
+    return jsonResponse(HTTP_NOT_FOUND, {
+        error: labelText('error.not_found', {}, ctx.profile.labels),
+        errorKind: 'not_found',
     });
 }
 async function* replayOperation(ctx, request, operation) {
@@ -646,9 +646,8 @@ async function settlingOf(ctx, request, session, body) {
         operation.callId === body.gateId &&
         operation.profileId === ctx.profile.id &&
         (operation.status === 'running' || operation.status === 'uncertain')) {
-        throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
-            copy: { key: 'tool.execution_uncertain' },
-        });
+        throw new TheoremError('conflict', `The tool operation is ${operation.status}, so it does not run again until the host settles it`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        { copy: { key: 'tool.execution_uncertain' } });
     }
     if (operation?.status === 'settled' &&
         operation.profileId === ctx.profile.id &&

package/server/page-dispatch.js

@@ -9,10 +9,9 @@ export const pageToolResultSchema = z.strictObject({
         z.strictObject({ timedOut: z.literal(true) }),
     ]),
 });
-function unavailable() {
-    throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
-        copy: { key: 'tool.execution_uncertain' },
-    });
+/** The user reads that the action is unresolved; the builder reads why, under the kind of what happened. */
+function refused(kind, reason) {
+    throw new TheoremError(kind, reason, { copy: { key: 'tool.execution_uncertain' } });
 }
 export function createMemoryPageToolBroker(maxPending = 128) {
     if (!Number.isSafeInteger(maxPending) || maxPending <= 0)
@@ -22,8 +21,12 @@ export function createMemoryPageToolBroker(maxPending = 128) {
     return {
         reserve(sessionId, grantId, signal) {
             const id = key(sessionId, grantId);
-            if (signal?.aborted || waiting.has(id) || waiting.size >= maxPending)
-                unavailable();
+            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)
+            if (waiting.has(id))
+                refused('internal', 'The page broker already waits for this grant'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            if (waiting.size >= maxPending)
+                refused('rate_limit', `The page broker already waits for its maxPending of ${maxPending} answers`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             let finish = () => { };
             const result = new Promise((resolve) => {
                 finish = resolve;
@@ -44,7 +47,8 @@ export function createMemoryPageToolBroker(maxPending = 128) {
         deliver(sessionId, grantId, page) {
             const finish = waiting.get(key(sessionId, grantId));
             if (!finish)
-                return Promise.reject(new TheoremError('unavailable', labelText('tool.execution_uncertain')));
+                return Promise.reject(new TheoremError('conflict', 'No dispatch in this process waits for the page answer to this grant', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                { copy: { key: 'tool.execution_uncertain' } }));
             finish(page);
             return Promise.resolve();
         },
@@ -57,7 +61,7 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
         execution: {
             async dispatch(claim, signal) {
                 if (!claim.invocation)
-                    unavailable();
+                    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 pending = broker.reserve(sessionId, grantId, signal);
@@ -68,7 +72,7 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                             record.claimToken !== claim.claimToken ||
                             record.invocationHash !== claim.invocationHash ||
                             record.pageGrant)
-                            unavailable();
+                            refused('internal', 'The session store holds no running claim for this page dispatch');
                         record.pageGrant = { grantId, expiresAt };
                     });
                 }
@@ -79,7 +83,9 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                 const remaining = expiresAt - Date.now();
                 if (remaining <= 0 || signal?.aborted) {
                     pending.cancel();
-                    unavailable();
+                    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)
+                    refused('timeout', 'The page dispatch used its timeoutMs before it was sent'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 }
                 let expire = () => { };
                 const expired = new Promise((resolve) => {
@@ -106,16 +112,18 @@ export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000
                     record.status === 'ready' ||
                     record.callId !== result.callId ||
                     record.pageGrant?.grantId !== result.grantId)
-                    unavailable();
+                    refused('request', 'The page answered a grant this session did not issue for that call'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 if (record.pageGrant.resultHash !== undefined) {
                     if (record.pageGrant.resultHash !== hash)
-                        unavailable();
+                        refused('request', 'The page answered this grant twice with different results'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                     if (record.status === 'uncertain')
-                        unavailable();
+                        refused('request', 'The page answered again for a call that is uncertain'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                     return { duplicate: true, settled: record.status === 'settled' };
                 }
-                if (record.status !== 'running' || Date.now() >= record.pageGrant.expiresAt)
-                    unavailable();
+                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)
+                    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/session-boundary.js

@@ -38,9 +38,8 @@ export async function createTheoremSessionBoundary(options) {
             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' },
-                });
+                throw new TheoremError('conflict', 'The session holds a tool operation that is not settled, so its provider state does not resume', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                { copy: { key: 'tool.execution_uncertain' } });
             }
             return {
                 ...prepared,

package/server/single-action.js

@@ -6,7 +6,7 @@
  * @module
  */
 import { labelText } from '@theoremjs/agents';
-import { caughtStatus, clientError, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { caughtStatus, clientError, HTTP_NOT_FOUND, } 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;
@@ -15,9 +15,9 @@ export function singleActionHandler({ action, iface, labels, clientEvents, onErr
             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(HTTP_NOT_FOUND, {
+                    error: labelText('error.not_found', {}, labels),
+                    errorKind: 'not_found',
                 });
             }
             return jsonResponse(200, { result: await run(request) });