@theoremjs/web 0.3.4-next.679.gcdf1a3a → 0.3.4-next.711.g78e504a

package/README.md

@@ -199,6 +199,7 @@ await chat.submit();
 - `getState()` returns a `ChatState`. It is a new object after each change, and the same object between changes. So you can compare it by reference, as React's `useSyncExternalStore` does.
 - `subscribe(listener)` calls the listener once for each group of changes, after the code that made them has run. It returns the function that unsubscribes. Until the first subscribe or send, the chat asks nothing of the host. Then it reads a resumed conversation that came without its `conversationView`, and answers a restored page gate as unanswered.
 - `update(options)` gives the controller your latest options, such as a new `context`, `slots`, or `pageTools`. Each turn reads the options as they are when it is sent. `conversation`, `conversationView`, `initialText`, `initialFiles`, `initialVoice`, and `initialPending` are read only when the controller is created.
+- A live call takes `stated` in its options, and `setStated(stated)` changes it during the call. As with `setSlots`, the call is taken up again with the prompt lines the new value chooses.
 - Each method is bound to the controller. Pass it as a callback as it is.
 
 `state.phase` is `'idle'`, `'streaming'`, or `'gated'`. The methods for the composer depend on it:
@@ -261,6 +262,7 @@ const transport = withPageToolDispatch(
 | `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. A call held at a gate runs on, once answered, with the `host`, `onStage` and `credentials` you give for that call's turn. |
 | `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. |
+| `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`. |
 | `credentialStore` | Where tool credentials are kept, by session. Default: process memory. |
@@ -416,7 +418,7 @@ Saved outcomes include guarded model read-back, media, provenance, and suspiciou
 The handler retains settled operations for 24 hours from settlement by default. Set `operationRetentionMs` to change this window.
 Each saved outcome records its absolute retention deadline. Changing a handler's policy does not shorten that deadline.
 Each issued gate records its absolute expiry. Changing `gateTtlMs` does not extend an issued gate.
-Ready, running, and uncertain operations do not expire.
+Ready, running, background, and uncertain operations do not expire.
 
 A session store with a real limit declares its `capacity`: what it holds for one session, in bytes of UTF-8 JSON.
 
@@ -448,6 +450,8 @@ A live session does not restore a dispatched call after an unexpected failure. I
 To retain execution claims across connections, supply a durable coordinator through `RunSessionOptions.execution`.
 Browser dispatch uses a host-owned `PageToolExecution` service beside the execution coordinator.
 `createTheoremHandler` supplies both services. Live relays pass the session boundary's `pageExecution` and `toolExecution` 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. Keep the service's values valid after the request ends. A live relay passes its service to `runSession`.
 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

@@ -2,7 +2,7 @@ import { type AttachmentValidationIssue, type ComposerMenuAction, type ComposerP
 import { type ClientFailure } from './failure.ts';
 import { type PageTools } from './live/live-page-tool.ts';
 import type { AnsweringGate, ToolDecisionAction } from './tool-resume.ts';
-import { type ConversationView, type TheoremTransport, type TurnEventSink } from './transport.ts';
+import { type ConversationView, type StatedTurn, type TheoremTransport, type TurnEventSink } from './transport.ts';
 export type ChatOptions = {
     transport: TheoremTransport;
     /** The profile's composer interface, as `transport.describe()` returns it. `null` while it loads. */
@@ -42,6 +42,8 @@ export type ChatOptions = {
      * `pickSlot`), starting at its first allowed value.
      */
     slots?: Record<string, string>;
+    /** Which prompt lines each turn gets, for a host that lets its page choose (`pageStatesTurn`). */
+    stated?: StatedTurn;
     /** Told each time the visitor picks a slot, with every slot's value. */
     onSlotsChange?: (slots: Record<string, string>) => void;
     /** What the page wants the agent to know: any JSON. The latest value goes with every turn. */

package/client/chat.js

@@ -653,12 +653,13 @@ class Chat {
         };
     }
     #withValues(request) {
-        const { iface, slots: fixed, context } = this.#options;
+        const { iface, slots: fixed, context, stated } = this.#options;
         const slots = slotsOf(iface, fixed, this.#picked).values;
-        if (slots === undefined && context === undefined)
+        if (slots === undefined && context === undefined && stated === undefined)
             return request;
         return {
             ...request,
+            ...(stated === undefined ? {} : { stated }),
             input: {
                 ...request.input,
                 ...(slots === undefined ? {} : { slots }),

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 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, 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/live/live-page-tool.d.ts

@@ -1,3 +1,4 @@
+import type { StatedTurn } from '../transport.ts';
 /** The page's result for a call: the tool's output schema checks it, then the model reads it. */
 export type PageToolAnswer = {
     output: unknown;
@@ -16,6 +17,8 @@ export type PageTools = Record<string, PageTool>;
 export type LiveCallOptions = {
     /** The value chosen for each of the profile's `inputs.slots`, read as the call starts. */
     slots?: Record<string, string>;
+    /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
+    stated?: StatedTurn;
     /**
      * What the page tells the agent: any JSON. It goes with the call's opening, and
      * again whenever it changes, as background the agent reads without replying.

package/client/live-client.d.ts

@@ -15,7 +15,7 @@ import { type SessionEventOf, type TraceRecord } from '@theoremjs/agents';
 import type { PageTools } from './live/live-page-tool.ts';
 import type { LiveConnectPhase, LiveSessionStatus } from './live/live-state.ts';
 import type { LiveGateReply, LiveToolGatePrompt } from './live/live-tool.ts';
-import { type ClientTurnEvent } from './transport.ts';
+import { type ClientTurnEvent, type StatedTurn } from './transport.ts';
 export type { LiveConnection, LiveSocket } from './live-messages.ts';
 import type { LiveSocket } from './live-messages.ts';
 export interface LiveClientOptions {
@@ -24,6 +24,8 @@ export interface LiveClientOptions {
     openMessage?: Record<string, unknown>;
     /** The value chosen for each of the profile's `inputs.slots`, fixed for the call. */
     slots?: Record<string, string>;
+    /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
+    stated?: StatedTurn;
     /** What the page tells the agent as the call opens; `setContext` replaces it during the call. */
     context?: unknown;
     relayUrl?: string;
@@ -181,6 +183,9 @@ export declare class LiveSessionClient {
      * handle; with none, the next call has them.
      */
     setSlots(slots: Record<string, string> | undefined): void;
+    /** The call's prompt lines, as `setSlots` takes its slots. */
+    setStated(stated: StatedTurn | undefined): void;
+    private takeUpAgain;
     /**
      * Replace the page's context package. In a call it reaches the agent as
      * background, with no reply; before one, it goes with the call's opening.

package/client/live-client.js

@@ -228,11 +228,12 @@ export class LiveSessionClient {
     }
     /** The first message: the call's values, and the handle and time away when it takes a dropped call up again. */
     openMessage() {
-        const { slots, openMessage: host } = this.options;
+        const { slots, stated, openMessage: host } = this.options;
         return {
             type: 'open',
             ...(this.history.length ? { history: structuredClone(this.history) } : {}),
             ...(slots ? { slots } : {}),
+            ...(stated ? { stated } : {}),
             ...(this.context === undefined ? {} : { context: this.context }),
             ...(this.providerState
                 ? {
@@ -771,6 +772,16 @@ export class LiveSessionClient {
         if (JSON.stringify(slots) === JSON.stringify(this.options.slots))
             return;
         this.options = { ...this.options, slots };
+        this.takeUpAgain();
+    }
+    /** The call's prompt lines, as `setSlots` takes its slots. */
+    setStated(stated) {
+        if (JSON.stringify(stated) === JSON.stringify(this.options.stated))
+            return;
+        this.options = { ...this.options, stated };
+        this.takeUpAgain();
+    }
+    takeUpAgain() {
         if (this.providerState && !this.opening && this.ws?.readyState === WebSocket.OPEN) {
             this.handleDrop();
         }

package/client/live-messages.d.ts

@@ -7,7 +7,7 @@ import { type ProviderCheckpoint } from '@theoremjs/agents';
  * @module
  */
 import { type GateDecision, type ToolGate, type TraceRecord, type TurnEvent, type TurnHistoryMessage, z } from '@theoremjs/agents';
-import { type HostErrorBody } from './transport.ts';
+import { type HostErrorBody, type StatedTurn } from './transport.ts';
 import { type MalformedEvent, type UnsupportedEvent } from './wire-line.ts';
 /**
  * The live client's first message, before the relay opens the session: the
@@ -20,6 +20,8 @@ export type LiveOpenMessage = {
     slots?: Record<string, string>;
     /** What the page tells the agent as the call opens: the client's context package. */
     context?: unknown;
+    /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
+    stated?: StatedTurn;
     /** A call that dropped, taken up again: the provider's handle, and how long the caller was away. */
     resume?: {
         providerState: ProviderCheckpoint;

package/client/live-messages.js

@@ -7,13 +7,14 @@ import { providerCheckpointSchema } from '@theoremjs/agents';
  * @module
  */
 import { GATE_DECISIONS, TURN_EVENT_SCHEMAS, toolGateSchema, traceRecordSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
-import { hostErrorBodySchema } from "./transport.js";
+import { hostErrorBodySchema, statedTurnSchema, } from "./transport.js";
 import { readWireLine, readWireValue, } from "./wire-line.js";
 const liveOpenMessage = z.object({
     type: z.literal('open'),
     history: z.array(turnHistoryMessageSchema).optional(),
     slots: z.record(z.string(), z.string()).optional(),
     context: z.unknown().optional(),
+    stated: statedTurnSchema.optional(),
     resume: z
         .object({ providerState: providerCheckpointSchema, awayMs: z.number().nonnegative() })
         .optional(),

package/client/transcript-schema.js

@@ -13,6 +13,7 @@ function eventPart(probe) {
 const TOOL_CALL_STATE_PHASES = [
     'running',
     'gate',
+    'background',
     'complete',
     'error',
     'cancel',

package/client/transport.d.ts

@@ -49,6 +49,13 @@ export type TheoremReplay = {
 };
 /** For a host that reads the studio's client-held state. */
 export declare const theoremReplaySchema: z.ZodType<TheoremReplay>;
+/** Which prompt lines a turn gets: the path it says it came by, and its `identity.conditions`. */
+export type StatedTurn = {
+    path?: string;
+    conditions?: Record<string, string>;
+};
+/** A stated turn off the wire. */
+export declare const statedTurnSchema: z.ZodType<StatedTurn>;
 /**
  * One message. The host resolves the profile and owns the conversation: the
  * client sends only the message and the ref of the conversation it continues.
@@ -63,6 +70,8 @@ export type TheoremTurnRequest = {
     conversation?: string;
     model?: string;
     effort?: string;
+    /** For a host that lets its page choose (`pageStatesTurn`); any other host refuses it. */
+    stated?: StatedTurn;
     /** Client-generated id so mid-turn steers can find this turn's inbox. */
     turnId?: string;
     /** invariant: Both issued IDs identify each paused action that this message abandons. */

package/client/transport.js

@@ -39,11 +39,19 @@ true;
 export const theoremReplaySchema = theoremReplay;
 /** An id the client made: trimmed, never blank. */
 const clientId = z.string().trim().min(1);
+const statedTurn = z.object({
+    path: z.string().optional(),
+    conditions: z.record(z.string(), z.string()).optional(),
+});
+true;
+/** A stated turn off the wire. */
+export const statedTurnSchema = statedTurn;
 const theoremTurnRequest = z.object({
     input: theoremTurnInput,
     conversation: z.string().min(1).optional(),
     model: z.string().optional(),
     effort: z.string().optional(),
+    stated: statedTurn.optional(),
     turnId: clientId.optional(),
     abandon: z.array(gateReferenceSchema).min(1).optional(),
     replay: theoremReplay.pick({ sessionPermissions: true }).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.679.gcdf1a3a",
+  "version": "0.3.4-next.711.g78e504a",
   "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.679.gcdf1a3a"
+    "@theoremjs/agents": "^0.3.4-next.711.g78e504a"
   }
 }

package/server/checkpoint-ownership.d.ts

@@ -1,5 +1,5 @@
 import { type ProviderCheckpoint, type TurnHistoryMessage } from '@theoremjs/agents';
-import type { TheoremSessionState } from './session-store.ts';
+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>;

package/server/checkpoint-ownership.js

@@ -1,4 +1,5 @@
 import { labelText, providerCheckpointSchema, TheoremError, toolInvocationHash, } from '@theoremjs/agents';
+import { detachedReply } from "./session-store.js";
 export function checkpointIdentity(checkpoint) {
     return toolInvocationHash(providerCheckpointSchema.parse(checkpoint));
 }
@@ -7,10 +8,26 @@ export async function checkpointOwnershipKey(identity, operations) {
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
         .map(([id, operation]) => operation.status === 'ready'
         ? [id, operation.status, operation.profileId, operation.readyAt]
-        : [id, operation.status, operation.profileId, operation.toolId, operation.invocationHash]);
+        : [
+            id,
+            // invariant: A late settlement of a detached call leaves this row, and its checkpoint, as it was.
+            detachedReply(operation) ? 'background' : operation.status,
+            operation.profileId,
+            operation.toolId,
+            operation.invocationHash,
+        ]);
     const epoch = await toolInvocationHash(rows);
     return `${identity}:${epoch}`;
 }
+/** What the model read for this call: a detached call's reply, or a settled call's result. */
+function readBackOf(operation) {
+    const reply = detachedReply(operation);
+    if (reply)
+        return reply.event.tool.readBack;
+    return operation.status === 'settled' && operation.outcome.effects !== 'unknown'
+        ? operation.outcome.event.tool.readBack
+        : undefined;
+}
 export async function requireOwnedCheckpoint(identities, checkpoint, operations = {}, portableHistory) {
     if (checkpoint === undefined)
         return undefined;
@@ -21,13 +38,15 @@ export async function requireOwnedCheckpoint(identities, checkpoint, operations
     const portableSettlements = portableHistory !== undefined &&
         records.length > 0 &&
         identities.some((saved) => saved.startsWith(`${identity}:`)) &&
-        records.every((operation) => operation.status === 'settled' &&
-            operation.outcome.effects !== 'unknown' &&
-            operation.outcome.event.tool.readBack !== undefined &&
-            portableHistory.some((message) => message.role === 'tool' &&
-                message.tool_call_id === operation.callId &&
-                message.name === operation.toolId &&
-                message.content === operation.outcome.event.tool.readBack));
+        records.every((operation) => {
+            const readBack = readBackOf(operation);
+            return (operation.status !== 'ready' &&
+                readBack !== undefined &&
+                portableHistory.some((message) => message.role === 'tool' &&
+                    message.tool_call_id === operation.callId &&
+                    message.name === operation.toolId &&
+                    message.content === readBack));
+        });
     if (!identities.includes(key) &&
         !portableSettlements &&
         !(records.length === 0 && identities.includes(identity))) {

package/server/conversation-store.d.ts

@@ -11,6 +11,7 @@
  */
 import { type ProviderCheckpoint, TheoremError, type TurnEvent, type TurnHistoryMessage, z } from '@theoremjs/agents';
 import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import { type StatedTurn } from '../client/transport.ts';
 import { type MemorySessionStoreOptions } from './session-store.ts';
 /** A reply paused on gates: its events so far, and the history it was given. */
 export type PausedReply = {
@@ -23,9 +24,10 @@ export type PausedReply = {
     workedMs: number;
     /** When the reply last paused (epoch ms). */
     endedAt: number;
-    /** The model and effort the reply ran with, for the run that goes on after its gates. */
+    /** The model, effort, and stated turn the reply ran with, for the run that goes on after its gates. */
     model?: string;
     effort?: string;
+    stated?: StatedTurn;
 };
 /** One conversation as the host stores it. */
 export type StoredConversation = {

package/server/conversation-store.js

@@ -12,6 +12,7 @@
 import { labelText, providerCheckpointSchema, TheoremError, turnEventSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
 import { openSecret, sealSecret } from '@theoremjs/agents/kernel';
 import { transcriptBlockSchema } from "../client/transcript-schema.js";
+import { statedTurnSchema } from "../client/transport.js";
 import { memoryStoreLimits } from "./session-store.js";
 const pausedReply = z.object({
     events: z.array(turnEventSchema),
@@ -21,6 +22,7 @@ const pausedReply = z.object({
     endedAt: z.number(),
     model: z.string().optional(),
     effort: z.string().optional(),
+    stated: statedTurnSchema.optional(),
 });
 true;
 const storedConversation = z.object({

package/server/conversation.d.ts

@@ -14,10 +14,10 @@
  *
  * @module
  */
-import { type GateReference, type LabelOverrides, type Profile, type ProviderCheckpoint, TheoremError, type TurnEvent, type TurnHistoryMessage, type TurnInput } from '@theoremjs/agents';
+import { type GateReference, type LabelOverrides, type Profile, type ProviderCheckpoint, TheoremError, type ToolId, type TurnEvent, type TurnHistoryMessage, type TurnInput } from '@theoremjs/agents';
 import { type ClientTurnOptions } from '@theoremjs/agents/host';
 import { type ComposerProfileInterface, streamThoughtsEnabled, type TranscriptBlock, type UserTurnDraft, type UserTurnHistoryMedia } from '@theoremjs/agents/interface';
-import type { ConversationLine, ConversationView, TheoremTurnInput } from '../client/transport.ts';
+import type { ConversationLine, ConversationView, StatedTurn, TheoremTurnInput } from '../client/transport.ts';
 import { type StoredConversation, type TheoremConversationStore } from './conversation-store.ts';
 /** One walked-away call: its id, and the run that settles it (`invokeTool` with the abandoned resume). */
 export type WalkedAwayCall = {
@@ -119,6 +119,9 @@ export type ReplyTurn = {
     providerState?: ProviderCheckpoint;
     model?: string;
     effort?: string;
+    stated?: StatedTurn;
+    /** The tools the reply had when it paused, for a reply that goes on. */
+    promoted?: ToolId[];
 };
 /** What a reply's model run takes from the host. */
 export type ReplyRunner = {
@@ -131,6 +134,8 @@ export type ReplyRunner = {
     compact(history: TurnHistoryMessage[], tokens: number, model: string | undefined): Promise<TurnHistoryMessage[] | undefined>;
     model?: string;
     effort?: string;
+    stated?: StatedTurn;
+    promoted?: ToolId[];
     signal: AbortSignal;
 };
 /** A line of a reply's stream: an event, or the ref of what the store wrote. */

package/server/conversation.js

@@ -17,7 +17,7 @@
 import { attachmentsRefused, labelText, TheoremError, toErrorEvent, } from '@theoremjs/agents';
 import { sanitizeTurnRequestWithEvents, withPublicLabels } from '@theoremjs/agents/guardrails';
 import { forClient } from '@theoremjs/agents/host';
-import { appendAssistantEventsToHistory, appendUserDraftToHistory, applyTurnEventsToSession, emptyInterfaceTurnSession, foldTurnEvents, gatedToolsFromEvents, historyFromTranscriptBlocks, prepareUserTurn, settlesToolCall, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
+import { appendAssistantEventsToHistory, appendUserDraftToHistory, applyTurnEventsToSession, emptyInterfaceTurnSession, foldTurnEvents, gatedToolsFromEvents, historyFromTranscriptBlocks, prepareUserTurn, replyToolIdsFromEvents, settlesToolCall, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
 import { base64ToBytes } from '@theoremjs/agents/kernel';
 import { stampWorked, stoppedReply } from "../client/run-commit.js";
 import { emptyConversation, unknownConversation, } from "./conversation-store.js";
@@ -192,6 +192,7 @@ function pausedOn(conversation, reply, runner) {
         endedAt: Date.now(),
         ...(runner.model ? { model: runner.model } : {}),
         ...(runner.effort ? { effort: runner.effort } : {}),
+        ...(runner.stated ? { stated: runner.stated } : {}),
     };
     return { ...conversation, ...metered(conversation, reply.events), paused };
 }
@@ -234,6 +235,8 @@ async function* runReply(host, opened, reply, runner, input, withMessage) {
             providerState: conversation.providerState,
             model: runner.model,
             effort: runner.effort,
+            ...(runner.stated ? { stated: runner.stated } : {}),
+            ...(runner.promoted ? { promoted: runner.promoted } : {}),
         });
         for await (const event of events) {
             reply.events.push(event);
@@ -485,7 +488,13 @@ export async function* answerReply(args) {
             yield error;
         return;
     }
-    yield* runReply(host, { ...opened, conversation: waiting }, reply, { ...runner, model: runner.model ?? paused.model, effort: runner.effort ?? paused.effort }, {
+    yield* runReply(host, { ...opened, conversation: waiting }, reply, {
+        ...runner,
+        model: runner.model ?? paused.model,
+        effort: runner.effort ?? paused.effort,
+        ...(paused.stated ? { stated: paused.stated } : {}),
+        promoted: replyToolIdsFromEvents(reply.events),
+    }, {
         history: replyHistory(reply),
         ...(waiting.inputTokens === undefined ? {} : { inputTokens: waiting.inputTokens }),
         ...(waiting.historyTokens === undefined ? {} : { historyTokens: waiting.historyTokens }),

package/server/handler.d.ts

@@ -36,6 +36,7 @@ import { type PageToolBroker } from './page-dispatch.ts';
  */
 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 ToolBackgroundService } from '@theoremjs/agents/kernel';
 import { type TheoremConversationStore } from './conversation-store.ts';
 import { type TheoremCredentialStore } from './credential-store.ts';
 export { theoremSession, theoremSessionId } from './session-identity.ts';
@@ -73,6 +74,11 @@ export type TheoremHandlerOptions = {
      * answered, with the `host`, `onStage` and `credentials` it gives for that call's turn.
      */
     prepare?: TurnWiring['prepare'];
+    /**
+     * Let the page say which prompt lines a turn gets (`stated`), for a page the host trusts as it
+     * trusts itself: the studio's. Unset refuses them, so a public page never chooses its own lines.
+     */
+    pageStatesTurn?: boolean;
     /**
      * 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
@@ -112,6 +118,15 @@ export type TheoremHandlerOptions = {
      * answered by then settles as timed out. Unset, it waits until the page answers or the turn stops.
      */
     pageToolTimeoutMs?: number;
+    /**
+     * The service for tools with a `background` setting, by session. It receives each detached call
+     * and its late events. The session keeps each call's state and result. Unset, every tool runs
+     * inline. The value must stay valid after the request ends, until each call settles.
+     */
+    background?: (ctx: {
+        request: Request;
+        sessionId: string;
+    }) => ToolBackgroundService;
     /** Check current resource access before disclosing a saved tool result. This callback must be read-only. */
     authorizeToolReplay?: (context: {
         request: Request;

package/server/handler.js

@@ -370,6 +370,7 @@ async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answe
     yield* invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, sessionId),
+        ...backgroundWiring(ctx, request, sessionId),
         pageExecution: sessionPageDispatch(ctx.sessions, sessionId, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
         name: pending.name,
         callId,
@@ -391,6 +392,12 @@ async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answe
         host: prepared.host,
     });
 }
+/** 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 }) }
+        : {};
+}
 /** A settled call's answer, streamed again. */
 async function* once(event, labels) {
     yield withPublicLabels(event, labels);
@@ -409,6 +416,7 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
         const prepared = await preparedTurn(ctx.options.prepare, {
             profile: ctx.profile.id,
             execution: sessionToolCoordinator(ctx.sessions, session.id),
+            ...backgroundWiring(ctx, request, session.id),
             pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
             input: turn.input,
             ...(turn.conversationId ? { conversationId: turn.conversationId } : {}),
@@ -418,6 +426,8 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
             host,
             ...(turn.model ? { model: turn.model } : {}),
             ...(turn.effort ? { effort: turn.effort } : {}),
+            ...(turn.promoted ? { promoted: turn.promoted } : {}),
+            ...turn.stated,
         }, {
             credentials: sessionCredentials(ctx, session.id),
             ...(onStage ? { onStage } : {}),
@@ -454,6 +464,7 @@ function chatRunner(ctx, request, session, generation) {
         },
         ...(generation.model ? { model: generation.model } : {}),
         ...(generation.effort ? { effort: generation.effort } : {}),
+        ...(generation.stated ? { stated: generation.stated } : {}),
         signal,
     };
 }
@@ -472,6 +483,9 @@ function conversationHost(ctx, session) {
 /** The person's message: a new reply, run against the conversation the host keeps. */
 async function turn(ctx, chat, request, session) {
     const body = await readBody(request, theoremTurnRequestSchema, ctx.options.maxRequestBytes);
+    if (body.stated && !ctx.options.pageStatesTurn) {
+        throw new TheoremError('request', labelText('error.request'));
+    }
     const message = postedMessage(chatInterface(chat), body.input, await ctx.options.context?.(request));
     const runner = chatRunner(ctx, request, session, body);
     const host = conversationHost(ctx, session);
@@ -481,7 +495,12 @@ async function turn(ctx, chat, request, session) {
         // labels-exempt: internal diagnostic; the user reads error.request
         if (body.abandon)
             throw statelessRefusal('walk away from');
-        return eventStream(ctx, request, () => runner.run({ input: message.input, model: body.model, effort: body.effort }));
+        return eventStream(ctx, request, () => runner.run({
+            input: message.input,
+            model: body.model,
+            effort: body.effort,
+            ...(body.stated ? { stated: body.stated } : {}),
+        }));
     }
     const opened = await openConversation(host, body.conversation, {
         kind: 'message',
@@ -577,6 +596,7 @@ async function* callEvents(ctx, request, session, body) {
     const events = invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, session.id),
+        ...backgroundWiring(ctx, request, session.id),
         pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker, ctx.options.pageToolTimeoutMs).execution,
         name: body.name,
         input: body.input,
@@ -615,7 +635,8 @@ async function* replayOperation(ctx, request, operation) {
         tool.type === 'builtin' ||
         !('tools' in ctx.profile) ||
         !ctx.profile.tools?.allow.includes(operation.toolId) ||
-        (ctx.options.authorizeToolReplay &&
+        (operation.status === 'settled' &&
+            ctx.options.authorizeToolReplay &&
             !(await ctx.options.authorizeToolReplay({ request, operation }))))
         throw new TheoremError('blocked', labelText('error.blocked'));
     authorizeToolReplay({
@@ -623,9 +644,9 @@ async function* replayOperation(ctx, request, operation) {
         profile: ctx.profile,
         name: operation.toolId,
         resume: undefined,
-        outcome: operation.outcome,
+        ...(operation.status === 'settled' ? { outcome: operation.outcome } : {}),
     });
-    yield* once(operation.outcome.event, ctx.profile.labels);
+    yield* once(operation.status === 'settled' ? operation.outcome.event : operation.reply.event, ctx.profile.labels);
 }
 /**
  * The user's answer to a paused call. In a kept conversation the reply goes on
@@ -663,7 +684,7 @@ async function settlingOf(ctx, request, session, body) {
         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' &&
+    if ((operation?.status === 'settled' || operation?.status === 'background') &&
         operation.profileId === ctx.profile.id &&
         operation.callId === body.gateId) {
         if (body.input !== undefined &&

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 { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremStartRequestSchema, theoremSteerRequestSchema, theoremStopRequestSchema, theoremTurnRequestSchema, } from '../client/transport.ts';
+export { type StatedTurn, theoremConversationRequestSchema, theoremInvokeRequestSchema, 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';

package/server/session-boundary.d.ts

@@ -8,11 +8,13 @@ export interface SessionBoundaryOptions {
     sessionStore: TheoremSessionStore;
     gateTtlMs?: number;
     operationRetentionMs?: number;
+    /** As `TheoremHandlerOptions.pageStatesTurn`: refuses a live call's `stated` unless set. */
+    pageStatesTurn?: boolean;
     pageToolBroker?: PageToolBroker;
     /** How long the page has to answer a tool call it runs, in milliseconds. Unset, it waits. */
     pageToolTimeoutMs?: number;
 }
-export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs'>;
+export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs' | 'path' | 'conditions'>;
 export interface TheoremSessionBoundary {
     sessionId: string;
     setCookie?: string;

package/server/session-boundary.js

@@ -6,7 +6,7 @@ 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 { DEFAULT_OPERATION_RETENTION_MS } from "./session-store.js";
+import { DEFAULT_OPERATION_RETENTION_MS, detachedReply, } from "./session-store.js";
 import { sessionToolCoordinator } from "./tool-operations.js";
 import { liveSessionOpen } from "./turn-input.js";
 export async function createTheoremSessionBoundary(options) {
@@ -31,11 +31,14 @@ export async function createTheoremSessionBoundary(options) {
         toolExecution: sessionToolCoordinator(store, id),
         async prepareLiveOpen(raw, server) {
             const open = checkRequest(liveOpenMessageSchema, raw, 'live open');
+            if (open.stated && !options.pageStatesTurn) {
+                throw new TheoremError('request', labelText('error.request'));
+            }
             const prepared = liveSessionOpen(open, server);
             const state = await store.read(id);
             const providerState = await requireOwnedCheckpoint(state.providerCheckpoints, prepared.providerState, state.operations);
             if (providerState &&
-                Object.values(state.operations).some((operation) => operation.status !== 'settled')) {
+                Object.values(state.operations).some((operation) => operation.status !== 'settled' && !detachedReply(operation))) {
                 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' } });
             }

package/server/session-store.d.ts

@@ -10,7 +10,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 { AnsweredGate, ToolGate, ToolId, ToolOperationIdentity, ToolOperationOutcome, ToolOperationReply, ToolOperationUncertainty, TurnInput, TurnToolSnapshot } from '@theoremjs/agents/kernel';
 import { type TheoremSessionCapacity } from './session-limits.ts';
 /** A tool call the kernel paused on a gate, as the server saw it. */
 export type PendingToolGate = {
@@ -47,19 +47,30 @@ export type SessionToolOperation = {
     claimToken: string;
     startedAt: number;
     pageGrant?: SessionPageGrant;
+}) | (ToolOperationIdentity & {
+    status: 'background';
+    claimToken: string;
+    reply: ToolOperationReply;
+    startedAt: number;
+    detachedAt: number;
+    pageGrant?: SessionPageGrant;
 }) | (ToolOperationIdentity & {
     status: 'settled';
     pageGrant?: SessionPageGrant;
     outcome: ToolOperationOutcome;
+    reply?: ToolOperationReply;
     settledAt: number;
     retainUntil?: number;
 }) | (ToolOperationIdentity & {
     status: 'uncertain';
     pageGrant?: SessionPageGrant;
+    reply?: ToolOperationReply;
     claimToken: string;
     reason: ToolOperationUncertainty;
     detectedAt: number;
 });
+/** The reply the model read for a call that detached, whatever has happened to the call since. */
+export declare function detachedReply(operation: SessionToolOperation): ToolOperationReply | undefined;
 export declare const DEFAULT_OPERATION_RETENTION_MS: number;
 export type TheoremSessionState = {
     version: 3;

package/server/session-store.js

@@ -8,9 +8,17 @@
  *
  * @module
  */
-import { jsonObjectSchema, jsonValueSchema, labelText, savedToolInvocationSchema, TheoremError, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_PERMISSION, toolOperationOutcomeSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
+import { jsonObjectSchema, jsonValueSchema, labelText, savedToolInvocationSchema, TheoremError, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_PERMISSION, toolOperationOutcomeSchema, toolOperationReplySchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
 import { gateExpired } from '@theoremjs/agents/kernel';
 import { checkedCapacity } from "./session-limits.js";
+/** The reply the model read for a call that detached, whatever has happened to the call since. */
+export function detachedReply(operation) {
+    return operation.status === 'background' ||
+        operation.status === 'settled' ||
+        operation.status === 'uncertain'
+        ? operation.reply
+        : undefined;
+}
 export const DEFAULT_OPERATION_RETENTION_MS = 24 * 60 * 60 * 1000;
 const blobSchema = z.strictObject({
     data: z.string(),
@@ -118,11 +126,21 @@ const operationSchema = z.discriminatedUnion('status', [
         claimToken: z.string().min(1),
         startedAt: z.number().finite().nonnegative(),
     }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('background'),
+        pageGrant: pageGrant.optional(),
+        claimToken: z.string().min(1),
+        reply: toolOperationReplySchema,
+        startedAt: z.number().finite().nonnegative(),
+        detachedAt: z.number().finite().nonnegative(),
+    }),
     z.strictObject({
         ...identityFields,
         status: z.literal('settled'),
         pageGrant: pageGrant.optional(),
         outcome: toolOperationOutcomeSchema,
+        reply: toolOperationReplySchema.optional(),
         settledAt: z.number().finite().nonnegative(),
         retainUntil: z.number().finite().nonnegative().optional(),
     }),
@@ -130,6 +148,7 @@ const operationSchema = z.discriminatedUnion('status', [
         ...identityFields,
         status: z.literal('uncertain'),
         pageGrant: pageGrant.optional(),
+        reply: toolOperationReplySchema.optional(),
         claimToken: z.string().min(1),
         reason: z.enum(['execution_interrupted', 'settlement_write_failed', 'worker_lost']),
         detectedAt: z.number().finite().nonnegative(),

package/server/tool-operations.d.ts

@@ -1,5 +1,5 @@
 import { type ToolExecutionCoordinator } from '@theoremjs/agents';
-import type { TheoremSessionState } from './session-store.ts';
+import { type TheoremSessionState } from './session-store.ts';
 export declare function sessionToolCoordinator(store: {
     readonly capacity?: {
         maxOutcomeBytes: number;

package/server/tool-operations.js

@@ -1,4 +1,5 @@
 import { TheoremError, } from '@theoremjs/agents';
+import { detachedReply, } from "./session-store.js";
 /** 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' } });
@@ -33,7 +34,9 @@ function checkedRecord(state, identity) {
 function checkedClaim(state, claim) {
     const record = checkedRecord(state, claim);
     if (!record ||
-        (record.status !== 'running' && record.status !== 'uncertain') ||
+        (record.status !== 'running' &&
+            record.status !== 'background' &&
+            record.status !== 'uncertain') ||
         record.claimToken !== claim.claimToken)
         unavailable(
         // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
@@ -43,6 +46,8 @@ function checkedClaim(state, claim) {
 function existingResult(record) {
     if (record?.status === 'settled')
         return { kind: 'settled', outcome: record.outcome };
+    if (record?.status === 'background')
+        return { kind: 'background', reply: record.reply };
     if (record?.status === 'running')
         return { kind: 'running' };
     if (record?.status === 'uncertain')
@@ -52,6 +57,7 @@ function existingResult(record) {
 function saveOutcome(state, identity, outcome) {
     const before = state.operations[identity.operationId];
     const pageGrant = before && before.status !== 'ready' ? before.pageGrant : undefined;
+    const reply = before ? detachedReply(before) : undefined;
     const settledAt = Date.now();
     const { operationId, callId, profileId, toolId, invocationHash, invocation } = identity;
     state.operations[identity.operationId] = {
@@ -63,6 +69,7 @@ function saveOutcome(state, identity, outcome) {
         ...(invocation ? { invocation } : {}),
         status: 'settled',
         ...(pageGrant ? { pageGrant } : {}),
+        ...(reply ? { reply } : {}),
         outcome,
         settledAt,
     };
@@ -93,6 +100,23 @@ export function sessionToolCoordinator(store, sessionId) {
                 return { kind: 'acquired', claimToken };
             });
         },
+        detach(claim, reply) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedClaim(state, claim);
+                if (record.status !== 'running')
+                    // labels-exempt: internal diagnostic; the user reads tool.execution_uncertain
+                    unavailable(`Tool operation ${claim.operationId} is ${record.status}, so it cannot detach`);
+                state.operations[claim.operationId] = {
+                    ...claim,
+                    invocation: record.invocation,
+                    ...(record.pageGrant ? { pageGrant: record.pageGrant } : {}),
+                    status: 'background',
+                    reply,
+                    startedAt: record.startedAt,
+                    detachedAt: Date.now(),
+                };
+            });
+        },
         settle(claim, outcome) {
             return store.mutate(sessionId, (state) => {
                 const record = checkedClaim(state, claim);
@@ -116,10 +140,12 @@ export function sessionToolCoordinator(store, sessionId) {
         markUncertain(claim, reason) {
             return store.mutate(sessionId, (state) => {
                 const record = checkedClaim(state, claim);
+                const reply = detachedReply(record);
                 state.operations[claim.operationId] = {
                     ...claim,
                     invocation: record.invocation,
                     ...(record.pageGrant ? { pageGrant: record.pageGrant } : {}),
+                    ...(reply ? { reply } : {}),
                     status: 'uncertain',
                     reason,
                     detectedAt: Date.now(),

package/server/turn-input.d.ts

@@ -7,4 +7,4 @@ export declare function kernelTurnInput(input: TheoremTurnInput, server?: unknow
  * What a live call's first message asks of the session, as `runSession` takes
  * it: the page's context is the client's, and `server` is the host's own.
  */
-export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history'>;
+export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history' | 'path' | 'conditions'>;

package/server/turn-input.js

@@ -22,6 +22,7 @@ export function liveSessionOpen(open, server) {
         ...(open.history ? { history: open.history } : {}),
         ...(open.slots ? { slots: open.slots } : {}),
         ...(context ? { context } : {}),
+        ...open.stated,
         ...(open.resume
             ? { providerState: open.resume.providerState, awayMs: open.resume.awayMs }
             : {}),

package/server/turn-wiring.d.ts

@@ -8,7 +8,7 @@
 import type { NormalizedTurnRequest, StageHandler, TurnRequest, TurnWiring } from '@theoremjs/agents';
 import type { ToolCredentialSource } from '@theoremjs/agents/kernel';
 /** The fields a handler sets on every turn, which `prepare` cannot replace. */
-export type HandlerOwned = Pick<TurnRequest, 'profile' | 'execution' | 'pageExecution' | 'providerState' | 'signal'>;
+export type HandlerOwned = Pick<TurnRequest, 'profile' | 'execution' | 'pageExecution' | 'background' | 'providerState' | 'signal'>;
 /** What the handler adds to a turn of its own: the session's credentials and its steering. */
 export type HandlerTurnParts = {
     credentials: ToolCredentialSource;

package/server/turn-wiring.js

@@ -15,6 +15,7 @@ export async function preparedTurn(prepare, turn, handler) {
         profile: turn.profile,
         ...(turn.execution ? { execution: turn.execution } : {}),
         ...(turn.pageExecution ? { pageExecution: turn.pageExecution } : {}),
+        ...(turn.background ? { background: turn.background } : {}),
         ...(turn.providerState ? { providerState: turn.providerState } : {}),
         ...(turn.signal ? { signal: turn.signal } : {}),
     };