@theoremjs/web 0.3.4-next.747.g0909061 → 0.3.4-next.755.g88665bd

package/README.md

@@ -270,6 +270,7 @@ const transport = withPageToolDispatch(
 | `pageStatesTurn` | Let the page say which prompt lines a turn gets, through `stated` on a turn or a live call. Set it only for a page you trust as yourself, such as a builder's own tool. Without it, a request with `stated` is refused. |
 | `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`. |
+| `notifier`, `notifyRetryMs` | Tell an open page that a background call ended, and how long the page waits to reopen a cut stream. Unset, the page reads the end on its next turn or reload. See [the background section](#share-session-authority). |
 | `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. A later answer fails with `session.gate_expired`. Unset, a gate waits until it is answered. |
@@ -456,7 +457,13 @@ To retain execution claims across connections, supply a durable coordinator as `
 Browser dispatch uses a host-owned `PageToolExecution` service beside the execution coordinator.
 `createTheoremHandler` supplies both services. Live relays put the session boundary's `pageExecution` and `toolExecution` on `SessionRequest`.
 
-A tool with a `background` setting runs inline until you pass the `background` option to `createTheoremHandler`. The option takes `{ request, sessionId }` and returns a `ToolBackgroundService`, which receives each detached call and its late events. The session keeps the call as `background` until it settles, and a late settlement does not invalidate a checkpoint. A conversation read shows the call as it stands: running, then its result, or an error for a marked call. An open page reads it on its next turn or reload. When the session has dropped a settled operation, the block reads an error with the code `outcome_not_retained`. On a durable store, a worker that dies leaves the operation as `background`, so your sweep marks it `uncertain` with `worker_lost` through `compareAndSwap`. Keep the service's values valid after the request ends. A live relay passes its service to `runSession`.
+A tool with a `background` setting runs inline until you pass the `background` option to `createTheoremHandler`. The option takes `{ request, sessionId }` and returns a `ToolBackgroundService`, which receives each detached call and its late events. The session keeps the call as `background` until it settles, and a late settlement does not invalidate a checkpoint. A conversation read shows the call as it stands: running, then its result, or an error for a marked call. An open page reads it on its next turn or reload, unless you set `notifier`. When the session has dropped a settled operation, the block reads an error with the code `outcome_not_retained`. On a durable store, a worker that dies leaves the operation as `background`, so your sweep marks it `uncertain` with `worker_lost` through `compareAndSwap`. Keep the service's values valid after the request ends. A live relay passes its service to `runSession`.
+To show an open page that a background call ended, with no turn or reload, pass `notifier: createMemoryNotifier()` to `createTheoremHandler`. While a call runs, the conversation read tells the page to open `POST <base>/notify`. The handler sends one `changed` line when the stream opens, and one when each background call in the session ends. The line carries no content, so the page calls the same conversation read as before. The page closes the stream when no call runs. The model reads nothing new: a late result still reaches it through `input.lateResults`.
+
+`createMemoryNotifier` reaches only pages connected to the process that ran the call. On more than one instance, give a shared `TheoremNotifier`. Your sweep calls `publish` with the session id after it marks a call `worker_lost`, because that write does not pass through the handler. Hosting platforms cut long responses. Set `notifyRetryMs` so that the page reopens the stream after that wait. Unset, the page does not reopen it, and reads the end on its next turn or reload.
+
+To reach a closed tab, send a Web Push from your `background` service, when the handle's `done` resolves. Theorem does not hold push subscriptions or VAPID keys. If your service worker then reaches an open page, call `refresh()` on the `ChatController`. It runs the same read.
+
 Forward live page results to `answerPageResult`. Preserve checkpoint ownership through `beforeEvent` when using the Studio bridge.
 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.

package/client/chat.d.ts

@@ -120,6 +120,12 @@ export type ChatController = {
      * `conversationView` is read then, and a restored page gate answered then.
      */
     subscribe(listener: () => void): () => void;
+    /**
+     * Reads the conversation from the host and draws it. For a page told by its own channel that
+     * something ended, such as a service worker that receives a Web Push. A run in flight reads it
+     * anyway when it ends, and a failed read leaves the chat as it stands.
+     */
+    refresh(): Promise<void>;
     /** The latest options. `conversation`, `conversationView` and `initialText` are read only at creation. */
     update(options: ChatOptions): void;
     setDraftText(value: ChatUpdate<string>): void;

package/client/chat.js

@@ -112,6 +112,11 @@ class Chat {
     #pageToolsWarned;
     #frame = null;
     #frameBlocks = null;
+    /** What the last view said about the host's push; unset, nothing is listened for. */
+    #notify;
+    #listening = null;
+    #reading = null;
+    #readAgain = false;
     constructor(options) {
         this.#options = options;
         this.#conversation = options.conversation;
@@ -144,8 +149,95 @@ class Chat {
             this.#live = true;
             this.#settle();
         }
-        return () => this.#listeners.delete(listener);
+        this.#followPush();
+        return () => {
+            this.#listeners.delete(listener);
+            this.#followPush();
+        };
+    };
+    refresh = () => {
+        if (this.#reading) {
+            this.#readAgain = true;
+            return this.#reading;
+        }
+        this.#reading = this.#readHost().finally(() => {
+            this.#reading = null;
+        });
+        return this.#reading;
     };
+    /** invariant: Reads never overlap, so an older view never draws over a newer one. */
+    async #readHost() {
+        do {
+            this.#readAgain = false;
+            await this.#readOnce();
+        } while (this.#readAgain);
+    }
+    async #readOnce() {
+        const { iface, transport } = this.#options;
+        const ref = this.#conversation;
+        if (!iface || ref === undefined || !keepsConversation(iface) || this.#busy)
+            return;
+        const before = this.#state.blocks;
+        let view;
+        try {
+            view = await transport.conversation({ conversation: ref });
+        }
+        catch (err) {
+            // why: Nobody asked for this read, and the next one heals a passing failure.
+            if (isUnknownConversation(err))
+                this.#setPush(undefined);
+            return;
+        }
+        // why: A run reads the conversation once it ends, later than this.
+        if (this.#busy)
+            return;
+        // why: Another read drew first. It may have started before the call ended, so read again.
+        if (this.#state.blocks !== before || this.#conversation !== ref) {
+            this.#readAgain = true;
+            return;
+        }
+        this.#draw(view, this.#state.session, []);
+    }
+    #setPush(notify) {
+        this.#notify = notify;
+        this.#followPush();
+    }
+    /** Holds the host's push open while the last view asks for it and someone is here to see it. */
+    #followPush() {
+        if (!this.#notify || this.#listeners.size === 0 || !this.#options.transport.notify) {
+            this.#listening?.abort();
+            this.#listening = null;
+            return;
+        }
+        if (this.#listening)
+            return;
+        const listening = new AbortController();
+        this.#listening = listening;
+        void this.#listen(listening);
+    }
+    async #listen(listening) {
+        const { signal } = listening;
+        while (!signal.aborted) {
+            try {
+                await this.#options.transport.notify?.(() => void this.refresh(), signal);
+            }
+            catch {
+                // why: The push is a convenience; the page still reads on its next turn or reload.
+            }
+            const retryMs = this.#notify?.retryMs;
+            if (signal.aborted || retryMs === undefined)
+                break;
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, retryMs);
+                signal.addEventListener('abort', () => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+        }
+        if (this.#listening === listening)
+            this.#listening = null;
+    }
     update = (options) => {
         this.#options = options;
         this.#warnPageTools();
@@ -435,6 +527,7 @@ class Chat {
             session: this.#sessionAfter(session, view.paused?.events ?? events),
             chatStarted: view.transcript.length > 0 || view.paused !== undefined,
         });
+        this.#setPush(view.notify);
     }
     /**
      * Keeps the model and effort valid as the interface changes: a pick still on the old defaults

package/client/index.d.ts

@@ -33,5 +33,5 @@ export { hasLead, layoutResult, type ResultChart, type ResultFigure, type Result
 export type { AnsweringGate, ToolDecisionAction, ToolGateResolution, } from './tool-resume.ts';
 export { continueGatedToolInvocation, type PersonGateResolution } from './tool-resume.ts';
 export { createTraceFeed, recordedFeed, type TraceFeed } from './trace-feed.ts';
-export { CHAT_LINES, type ChatLine, type ChatLineSink, type ClientTurnEvent, type ConversationLine, type ConversationView, createHttpTransport, fetchConversation, fetchRewound, fetchStarted, type HostErrorBody, type HttpOptions, type HttpTransportOptions, hostError, isTheoremStreamError, type MalformedEvent, postJson, postNdjson, readNdjsonStream, type StatedTurn, type TheoremConversationRequest, type TheoremInvokeRequest, type TheoremReplay, type TheoremRewindRequest, type TheoremRewound, type TheoremStartRequest, type TheoremSteerRequest, type TheoremStopRequest, TheoremStreamError, type TheoremTransport, type TheoremTurnInput, type TheoremTurnRequest, type TurnEventSink, type UnsupportedEvent, type WireLines, } from './transport.ts';
+export { CHAT_LINES, type ChatLine, type ChatLineSink, type ClientTurnEvent, type ConversationLine, type ConversationView, createHttpTransport, fetchConversation, fetchRewound, fetchStarted, type HostErrorBody, type HttpOptions, type HttpTransportOptions, hostError, isTheoremStreamError, type MalformedEvent, type NotifyLine, postJson, postNdjson, readNdjsonStream, type StatedTurn, type TheoremConversationRequest, type TheoremInvokeRequest, type TheoremReplay, type TheoremRewindRequest, type TheoremRewound, type TheoremStartRequest, type TheoremSteerRequest, type TheoremStopRequest, TheoremStreamError, type TheoremTransport, type TheoremTurnInput, type TheoremTurnRequest, type TurnEventSink, type UnsupportedEvent, type WireLines, } from './transport.ts';
 export { buildInvokeRequest, buildTurnRequest, foldAssistantTurn, issuedOperationId, type RunScope, type WalkAway, } from './turn-client.ts';

package/client/transport.d.ts

@@ -156,6 +156,10 @@ export type ConversationView = {
         events: TurnEvent[];
         blocks: TranscriptBlock[];
     };
+    /** The host pushes the end of a call that still runs. `retryMs` is its wait to reopen the push. */
+    notify?: {
+        retryMs?: number;
+    };
 };
 /** Read a conversation: a `/conversation` body. */
 export type TheoremConversationRequest = {
@@ -163,6 +167,14 @@ export type TheoremConversationRequest = {
 };
 /** A `/conversation` body as `createTheoremHandler` reads it. */
 export declare const theoremConversationRequestSchema: z.ZodType<TheoremConversationRequest>;
+/** Listen for the ends of this session's background calls: a `/notify` body. */
+export type TheoremNotifyRequest = Record<string, never>;
+/** A `/notify` body as `createTheoremHandler` reads it. */
+export declare const theoremNotifyRequestSchema: z.ZodType<TheoremNotifyRequest>;
+/** A line of `/notify`: something in the session changed, so read the conversation again. */
+export type NotifyLine = {
+    type: 'changed';
+};
 /**
  * Cut the conversation after transcript block `at` (-1 empties it): a
  * `/rewind` body. A reply waiting on gates is walked away from first.
@@ -200,6 +212,8 @@ export interface TheoremTransport {
     stop(request: TheoremStopRequest): Promise<void>;
     /** The conversation under `ref`, as the host shows it. */
     conversation(request: TheoremConversationRequest, signal?: AbortSignal): Promise<ConversationView>;
+    /** Calls `changed` for each line of the host's push, and settles when the push ends. */
+    notify?(changed: () => void, signal: AbortSignal): Promise<void>;
     /** The conversation cut after a transcript block, under the ref the host issued for it. */
     rewind(request: TheoremRewindRequest, signal?: AbortSignal): Promise<TheoremRewound>;
     pageResult?(result: PageDispatchResult, signal?: AbortSignal): Promise<void>;

package/client/transport.js

@@ -111,12 +111,17 @@ const conversationView = z.object({
     paused: z
         .object({ events: z.array(turnEventSchema), blocks: z.array(transcriptBlockSchema) })
         .optional(),
+    notify: z.object({ retryMs: z.number().optional() }).optional(),
 });
 true;
 const theoremConversationRequest = z.object({ conversation: z.string().min(1) });
 true;
 /** A `/conversation` body as `createTheoremHandler` reads it. */
 export const theoremConversationRequestSchema = theoremConversationRequest;
+const theoremNotifyRequest = z.strictObject({});
+/** A `/notify` body as `createTheoremHandler` reads it. */
+export const theoremNotifyRequestSchema = theoremNotifyRequest;
+const NOTIFY_LINES = { changed: z.object({ type: z.literal('changed') }) };
 const theoremRewindRequest = z.object({
     conversation: z.string().min(1),
     at: z.number().int().min(-1),
@@ -348,6 +353,10 @@ export function createHttpTransport(options = {}) {
         turn: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/turn`, body, CHAT_LINES, onEvent, { ...options, signal }),
         invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, CHAT_LINES, onEvent, { ...options, signal }),
         conversation: (body, signal) => fetchConversation(`${base}/conversation`, body, { ...options, signal }),
+        notify: (changed, signal) => postNdjson(`${base}/notify`, {}, NOTIFY_LINES, (line) => {
+            if (line.type === 'changed')
+                changed();
+        }, { ...options, signal }),
         rewind: (body, signal) => fetchRewound(`${base}/rewind`, body, { ...options, signal }),
         pageResult: (body, signal) => postJson(`${base}/page-result`, body, { ...options, signal }),
         steer: (body) => postJson(`${base}/steer`, body, options),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.747.g0909061",
+  "version": "0.3.4-next.755.g88665bd",
   "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.747.g0909061"
+    "@theoremjs/agents": "^0.3.4-next.755.g88665bd"
   }
 }

package/server/conversation.js

@@ -363,8 +363,7 @@ function requireWalkAway(conversation, abandon) {
 function requireWaitingOn(conversation, reference) {
     if (waitingOn(conversation, reference))
         return;
-    // labels-exempt: internal diagnostic; the user reads the copy key's wording
-    throw new TheoremError('request', `the reply is not waiting on ${reference.callId}`, {
+    throw new TheoremError('request', labelText('session.gate_expired'), {
         copy: { key: 'session.gate_expired' },
     });
 }

package/server/handler.d.ts

@@ -13,6 +13,8 @@ import { type PageToolBroker } from './page-dispatch.ts';
  * - `POST <base>/stop`    → stop a running turn where it stands
  * - `POST <base>/page-result` → the page's result for a tool the turn ran in the page
  * - `POST <base>/conversation` → the transcript and the paused reply, to draw
+ * - `POST <base>/notify`  → NDJSON that stays open: one line now, and one each time a background
+ *                            call in this session ends. Set `notifier` to serve it
  * - `POST <base>/rewind`  → `{ conversation, view }` the conversation cut after one block, and its new ref
  *
  * `createTheoremHostHandler` serves a host profile the same way, with no model:
@@ -39,6 +41,7 @@ import { type ClientTurnOptions } from '@theoremjs/agents/host';
 import { type ToolBackgroundService } from '@theoremjs/agents/kernel';
 import { type TheoremConversationStore } from './conversation-store.ts';
 import { type TheoremCredentialStore } from './credential-store.ts';
+import type { TheoremNotifier } from './notifier.ts';
 export { theoremSession, theoremSessionId } from './session-identity.ts';
 import { type SessionToolOperation, type TheoremSessionStore } from './session-store.ts';
 import { type SteerInbox } from './steer-inbox.ts';
@@ -127,6 +130,17 @@ export type TheoremHandlerOptions = {
         request: Request;
         sessionId: string;
     }) => ToolBackgroundService;
+    /**
+     * Tells an open page that a background call ended, so it redraws with no turn or reload. Unset,
+     * the page reads the end on its next turn or reload. A sweep that marks a call itself calls
+     * `publish` too. `createMemoryNotifier` for one instance.
+     */
+    notifier?: TheoremNotifier;
+    /**
+     * How long an open page waits to reopen `notifier`'s stream after it ends, in milliseconds.
+     * Hosting platforms cut long responses. Unset, the page does not reopen it.
+     */
+    notifyRetryMs?: number;
     /** Check current resource access before disclosing a saved tool result. This callback must be read-only. */
     authorizeToolReplay?: (context: {
         request: Request;
@@ -167,7 +181,7 @@ export type TheoremHandlerOptions = {
     }) => void;
 };
 /** A host profile runs no model, and takes no turns to steer. */
-export type TheoremHostHandlerOptions = Omit<TheoremHandlerOptions, 'profile' | 'provider' | 'steerInbox' | 'conversationStore' | 'prepare'> & {
+export type TheoremHostHandlerOptions = Omit<TheoremHandlerOptions, 'profile' | 'provider' | 'steerInbox' | 'conversationStore' | 'prepare' | 'notifier' | 'notifyRetryMs'> & {
     /** Host profile to serve. Registered with the kernel when the handler is created. */
     profile: Extract<Profile, {
         type: 'host';

package/server/handler.js

@@ -14,6 +14,8 @@ import { checkPageToolTimeout, createMemoryPageToolBroker, pageToolResultSchema,
  * - `POST <base>/stop`    → stop a running turn where it stands
  * - `POST <base>/page-result` → the page's result for a tool the turn ran in the page
  * - `POST <base>/conversation` → the transcript and the paused reply, to draw
+ * - `POST <base>/notify`  → NDJSON that stays open: one line now, and one each time a background
+ *                            call in this session ends. Set `notifier` to serve it
  * - `POST <base>/rewind`  → `{ conversation, view }` the conversation cut after one block, and its new ref
  *
  * `createTheoremHostHandler` serves a host profile the same way, with no model:
@@ -40,7 +42,7 @@ import { caughtStatus, clientError, forClient, HTTP_NOT_FOUND, } from '@theoremj
 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";
-import { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+import { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremNotifyRequestSchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
 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";
@@ -94,6 +96,7 @@ function routeOf(request) {
         last === 'steer' ||
         last === 'stop' ||
         last === 'conversation' ||
+        last === 'notify' ||
         last === 'rewind' ||
         last === 'call' ||
         last === 'page-result'
@@ -304,8 +307,7 @@ function answerPendingGate(state, request, profileId) {
         ? state.gates[request.operationId]
         : undefined;
     if (!pending || pending.profileId !== profileId || pending.callId !== request.callId) {
-        // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
-        throw new TheoremError('request', `gate ${request.callId} is not pending`, {
+        throw new TheoremError('request', labelText('session.gate_expired'), {
             copy: { key: 'session.gate_expired' },
         });
     }
@@ -400,9 +402,23 @@ async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answe
 }
 /** The host's service for a call in this session, for a request that runs a tool. */
 function backgroundWiring(ctx, request, sessionId) {
-    return ctx.options.background
-        ? { background: ctx.options.background({ request, sessionId }) }
-        : {};
+    const service = ctx.options.background?.({ request, sessionId });
+    if (!service)
+        return {};
+    const { notifier } = ctx.options;
+    if (!notifier)
+        return { background: service };
+    return {
+        background: {
+            detached(call) {
+                service.detached(call);
+                void call.done
+                    .then(() => notifier.publish(sessionId))
+                    .catch((err) => ctx.options.onError?.(err, { request }));
+            },
+            event: (event, call) => service.event(event, call),
+        },
+    };
 }
 /** A settled call's answer, streamed again. */
 async function* once(event, labels) {
@@ -525,32 +541,94 @@ async function conversation(ctx, request, session) {
     if (!host)
         throw statelessRefusal('read');
     const opened = await openConversation(host, body.conversation, { kind: 'read' });
-    return jsonResponse(200, await currentView(ctx, session, host, opened.conversation));
+    return jsonResponse(200, await currentView(ctx, request, session, host, opened.conversation));
+}
+const CHANGED_LINE = new TextEncoder().encode('{"type":"changed"}\n');
+/**
+ * One line now, then one for each background call that ends. The stream names no conversation,
+ * because a store's ref can change with each write; the page reads under the ref it holds.
+ * invariant: The first line follows the subscribe, so a call that ends before the page's first
+ * read is never missed.
+ */
+async function notify(ctx, request, session, notifier) {
+    await readBody(request, theoremNotifyRequestSchema, ctx.options.maxRequestBytes);
+    let send = () => { };
+    const unsubscribe = await notifier.subscribe(session.id, () => send());
+    let open = true;
+    const end = () => {
+        if (!open)
+            return;
+        open = false;
+        unsubscribe();
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            send = () => {
+                if (open)
+                    controller.enqueue(CHANGED_LINE);
+            };
+            send();
+            const leave = () => {
+                if (!open)
+                    return;
+                end();
+                controller.close();
+            };
+            if (request.signal.aborted)
+                leave();
+            else
+                request.signal.addEventListener('abort', leave, { once: true });
+        },
+        cancel: end,
+    });
+    return new Response(stream, { headers: NDJSON_HEADERS });
 }
 /**
  * why: The transcript keeps a detached call as the turn left it. The session holds what became of
  * it, so a call that has ended does not read as running.
  */
-async function currentView(ctx, session, host, conversation) {
+async function currentView(ctx, request, session, host, conversation) {
     const view = conversationView(host, conversation);
     if (!view.transcript.some(isDetachedBlock))
         return view;
     const { operations } = await ctx.sessions.read(session.id);
+    const transcript = await Promise.all(view.transcript.map((block) => isDetachedBlock(block) ? lateBlock(ctx, request, block, operations, host) : block));
+    const { notifier, notifyRetryMs } = ctx.options;
     return {
         ...view,
-        transcript: view.transcript.map((block) => isDetachedBlock(block) ? lateBlock(block, operations, host, ctx.profile) : block),
+        transcript,
+        ...(notifier && transcript.some(isDetachedBlock)
+            ? { notify: notifyRetryMs === undefined ? {} : { retryMs: notifyRetryMs } }
+            : {}),
     };
 }
 function isDetachedBlock(block) {
     return block.kind === 'tool' && block.tool.state?.phase === 'background';
 }
 /** A detached call's block as its operation stands. One the session no longer holds has no known end. */
-function lateBlock(block, operations, host, profile) {
+async function lateBlock(ctx, request, block, operations, host) {
     const { tool } = block;
     const id = tool.operationId;
     const operation = id && Object.hasOwn(operations, id) ? operations[id] : undefined;
     if (operation?.status === 'running' || operation?.status === 'background')
         return block;
+    const { labels } = ctx.profile;
+    if (operation?.status === 'settled' &&
+        ctx.options.authorizeToolReplay &&
+        !(await ctx.options.authorizeToolReplay({ request, operation }))) {
+        const message = labelText('error.blocked', {}, labels);
+        const failure = { code: 'outcome_withheld', kind: 'blocked', message };
+        const { name, callId } = tool;
+        const at = operation.settledAt;
+        return {
+            ...block,
+            tool: {
+                ...tool,
+                state: { name, callId, at, phase: 'error', failure, readBack: message },
+                endedAt: at,
+            },
+        };
+    }
     if (operation?.status === 'settled') {
         const settled = host.forReader(operation.outcome.event);
         if (settled.type !== 'tool')
@@ -560,7 +638,7 @@ function lateBlock(block, operations, host, profile) {
             return block;
         return { ...block, tool: { ...tool, state, endedAt: operation.settledAt } };
     }
-    const message = labelText('tool.execution_uncertain', {}, profile.labels);
+    const message = labelText('tool.execution_uncertain', {}, labels);
     const failure = {
         code: operation?.status === 'uncertain' ? operation.reason : 'outcome_not_retained',
         kind: 'internal',
@@ -598,7 +676,7 @@ async function rewind(ctx, request, session) {
         throw new TheoremError('internal', labelText('error.internal'));
     const rewound = {
         conversation: next.ref,
-        view: await currentView(ctx, session, host, next.conversation),
+        view: await currentView(ctx, request, session, host, next.conversation),
     };
     return jsonResponse(200, rewound);
 }
@@ -792,6 +870,12 @@ async function route(ctx, request, session) {
         return invoke(ctx, request, session);
     if (target === 'conversation')
         return conversation(ctx, request, session);
+    if (target === 'notify') {
+        const { notifier } = ctx.options;
+        if (!notifier || !chat.conversations)
+            return refused(ctx);
+        return notify(ctx, request, session, notifier);
+    }
     if (target === 'rewind')
         return rewind(ctx, request, session);
     if (target === 'stop')
@@ -850,6 +934,13 @@ export function hostTool(name) {
     const registered = defaultKernelScope.tools.get(name);
     return registered?.type === 'builtin' ? undefined : registered;
 }
+function checkNotifyRetry(ms) {
+    if (ms === undefined || (Number.isFinite(ms) && ms >= 0))
+        return;
+    throw new TheoremError('config', labelText('error.config'), {
+        cause: { code: 'notify_retry' },
+    });
+}
 function serve(name, profile, options, chatOptions = {}) {
     const gateTtlMs = resolveGateTtlMs(name, options.gateTtlMs);
     const operationRetentionMs = options.operationRetentionMs ?? DEFAULT_OPERATION_RETENTION_MS;
@@ -860,6 +951,7 @@ function serve(name, profile, options, chatOptions = {}) {
     }
     requestByteLimit(options.maxRequestBytes);
     checkPageToolTimeout(options.pageToolTimeoutMs);
+    checkNotifyRetry(options.notifyRetryMs);
     registerProfile(profile);
     const ctx = {
         options,

package/server/mod.d.ts

@@ -7,7 +7,7 @@
  */
 export { theoremHostCallRequestSchema } from '../client/host-transport.ts';
 export type { LiveClientMessage, LiveOpenMessage } from '../client/live-messages.ts';
-export { type StatedTurn, theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from '../client/transport.ts';
+export { type StatedTurn, theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremNotifyRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from '../client/transport.ts';
 export { answerReply, type ConversationHost, type ConversationUse, conversationView, type IssuedWalkAway, messageReply, type OpenedConversation, openConversation, type PostedMessage, postedMessage, type ReplyLine, type ReplyRunner, type ReplyTurn, readerConversationHost, rewindConversation, startConversation, statelessRefusal, type WalkedAwayCall, waitingCalls, } from './conversation.ts';
 export { type ConversationSnapshot, type ConversationWriteResult, createMemoryConversationStore, createSealedConversationStore, emptyConversation, type PausedReply, type SealedConversationStoreOptions, type StoredConversation, storedConversationSchema, type TheoremConversationStore, unknownConversation, } from './conversation-store.ts';
 export { createMemoryCredentialStore, type TheoremCredentialStore, type TheoremCredentials, } from './credential-store.ts';
@@ -15,6 +15,7 @@ export { createTheoremDecisionHandler, type DecisionQuestionsBuilder, isQuestion
 export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, type TheoremEmbeddingHandlerOptions, } from './embedding-handler.ts';
 export { createTheoremHandler, createTheoremHostHandler, readBody, type TheoremHandlerOptions, type TheoremHostHandlerOptions, type TheoremRequestContext, theoremSession, theoremSessionId, } from './handler.ts';
 export { createTheoremMcpHandler, type TheoremMcpHandlerOptions } from './mcp-handler.ts';
+export { createMemoryNotifier, type TheoremNotifier } from './notifier.ts';
 export { createMemoryPageToolBroker, type PageToolBroker, type PageToolResult, pageToolResultSchema, sessionPageDispatch, } from './page-dispatch.ts';
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from './request-check.ts';
 export { sessionStateStore } from './session-authority.ts';

package/server/mod.js

@@ -6,7 +6,7 @@
  * @module
  */
 export { theoremHostCallRequestSchema } from "../client/host-transport.js";
-export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremNotifyRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
 export { answerReply, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, rewindConversation, startConversation, statelessRefusal, waitingCalls, } from "./conversation.js";
 export { createMemoryConversationStore, createSealedConversationStore, emptyConversation, storedConversationSchema, unknownConversation, } from "./conversation-store.js";
 export { createMemoryCredentialStore, } from "./credential-store.js";
@@ -14,6 +14,7 @@ export { createTheoremDecisionHandler, isQuestionsBuilder, } from "./decision-ha
 export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, } from "./embedding-handler.js";
 export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSession, theoremSessionId, } from "./handler.js";
 export { createTheoremMcpHandler } from "./mcp-handler.js";
+export { createMemoryNotifier } from "./notifier.js";
 export { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from "./request-check.js";
 export { sessionStateStore } from "./session-authority.js";

package/server/notifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a session's open pages hear that a background call ended. The line carries no content: a
+ * page that hears it reads the conversation, so one read decides what a reader sees.
+ *
+ * @module
+ */
+/**
+ * Keyed by session id. The default lives in process memory, which reaches only pages connected to
+ * the process that ran the call. Bring a shared one (Redis, a Durable Object) for several instances.
+ */
+export interface TheoremNotifier {
+    /** Calls `changed` for each `publish` under `sessionId`, until the returned function runs. */
+    subscribe(sessionId: string, changed: () => void): (() => void) | Promise<() => void>;
+    publish(sessionId: string): void | Promise<void>;
+}
+export declare function createMemoryNotifier(): TheoremNotifier;

package/server/notifier.js

@@ -0,0 +1,25 @@
+/**
+ * Where a session's open pages hear that a background call ended. The line carries no content: a
+ * page that hears it reads the conversation, so one read decides what a reader sees.
+ *
+ * @module
+ */
+export function createMemoryNotifier() {
+    const listeners = new Map();
+    return {
+        subscribe(sessionId, changed) {
+            const listening = listeners.get(sessionId) ?? new Set();
+            listeners.set(sessionId, listening);
+            listening.add(changed);
+            return () => {
+                listening.delete(changed);
+                if (listening.size === 0 && listeners.get(sessionId) === listening)
+                    listeners.delete(sessionId);
+            };
+        },
+        publish(sessionId) {
+            for (const changed of [...(listeners.get(sessionId) ?? [])])
+                changed();
+        },
+    };
+}