@theoremjs/web 0.3.4-next.590.g0246066 → 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`. |

package/package.json

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

package/server/handler.d.ts

@@ -32,7 +32,7 @@ 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';
@@ -71,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

package/server/handler.js

@@ -51,7 +51,7 @@ import { checkRequest } from "./request-check.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',
@@ -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,
     });