@theoremjs/web 0.3.4-next.693.g4ab1526 → 0.3.4-next.711.g78e504a

package/README.md

@@ -418,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.
 
@@ -450,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/transcript-schema.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.693.g4ab1526",
+  "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.693.g4ab1526"
+    "@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.d.ts

@@ -14,7 +14,7 @@
  *
  * @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, StatedTurn, TheoremTurnInput } from '../client/transport.ts';
@@ -120,6 +120,8 @@ export type ReplyTurn = {
     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 = {
@@ -133,6 +135,7 @@ export type ReplyRunner = {
     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";
@@ -236,6 +236,7 @@ async function* runReply(host, opened, reply, runner, input, withMessage) {
             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);
@@ -492,6 +493,7 @@ export async function* answerReply(args) {
         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 }),

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';
@@ -117,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,7 @@ 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),
@@ -587,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,
@@ -625,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({
@@ -633,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
@@ -673,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/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) {
@@ -38,7 +38,7 @@ export async function createTheoremSessionBoundary(options) {
             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-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 } : {}),
     };