@theoremjs/web 0.3.4-next.715.geef22fd → 0.3.4-next.721.g7ff150a

package/README.md

@@ -131,8 +131,13 @@ const boundary = await createTheoremSessionBoundary({
 });
 const open = parseLiveOpenMessage(firstFrame);
 const session = await runSession(
-  { profile, ...await boundary.prepareLiveOpen(open, hostContext) },
-  { vault: hostKeyVault, execution: boundary.toolExecution, pageExecution: boundary.pageExecution },
+  {
+    profile,
+    ...await boundary.prepareLiveOpen(open, hostContext),
+    execution: boundary.toolExecution,
+    pageExecution: boundary.pageExecution,
+  },
+  { vault: hostKeyVault },
 );
 for await (const event of session.events()) {
   if ((event.type === 'done' || event.type === 'provider_checkpoint') && event.providerState) {
@@ -447,11 +452,11 @@ These claims do not provide exactly-once effects at the destination. Use the ope
 Concurrent pending attempts can reach preparation before one claims the body.
 Permission checks and pre-body hooks must be read-only or independently idempotent. The kernel cannot prove hook purity.
 A live session does not restore a dispatched call after an unexpected failure. It retains an uncertain call on that connection.
-To retain execution claims across connections, supply a durable coordinator through `RunSessionOptions.execution`.
+To retain execution claims across connections, supply a durable coordinator as `execution` on `SessionRequest`.
 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`.
+`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. 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. 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`.
 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/live/live-page-tool.d.ts

@@ -19,6 +19,10 @@ export type LiveCallOptions = {
     slots?: Record<string, string>;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
+    /** The model picked for the call, read as the call starts, when the profile allows it. */
+    model?: string;
+    /** That model's effort, read as the call starts, when the binding allows it. */
+    effort?: string;
     /**
      * 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

@@ -26,6 +26,10 @@ export interface LiveClientOptions {
     slots?: Record<string, string>;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
+    /** The model picked for the call, when the profile allows it. */
+    model?: string;
+    /** That model's effort, when the binding allows it. */
+    effort?: string;
     /** What the page tells the agent as the call opens; `setContext` replaces it during the call. */
     context?: unknown;
     relayUrl?: string;

package/client/live-client.js

@@ -228,12 +228,14 @@ 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, stated, openMessage: host } = this.options;
+        const { slots, stated, model, effort, openMessage: host } = this.options;
         return {
             type: 'open',
             ...(this.history.length ? { history: structuredClone(this.history) } : {}),
             ...(slots ? { slots } : {}),
             ...(stated ? { stated } : {}),
+            ...(model ? { model } : {}),
+            ...(effort ? { effort } : {}),
             ...(this.context === undefined ? {} : { context: this.context }),
             ...(this.providerState
                 ? {

package/client/live-messages.d.ts

@@ -22,6 +22,10 @@ export type LiveOpenMessage = {
     context?: unknown;
     /** Which prompt lines the call gets, for a host that lets its page choose (`pageStatesTurn`). */
     stated?: StatedTurn;
+    /** The model picked for the call, when the profile allows it. */
+    model?: string;
+    /** That model's effort, when the binding allows it. */
+    effort?: string;
     /** 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

@@ -15,6 +15,8 @@ const liveOpenMessage = z.object({
     slots: z.record(z.string(), z.string()).optional(),
     context: z.unknown().optional(),
     stated: statedTurnSchema.optional(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
     resume: z
         .object({ providerState: providerCheckpointSchema, awayMs: z.number().nonnegative() })
         .optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.715.geef22fd",
+  "version": "0.3.4-next.721.g7ff150a",
   "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.715.geef22fd"
+    "@theoremjs/agents": "^0.3.4-next.721.g7ff150a"
   }
 }

package/server/handler.js

@@ -42,7 +42,7 @@ 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 { answerReply, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, requiredOperationId, rewindConversation, statelessRefusal, waitingCalls, } from "./conversation.js";
-import { unknownConversation } from "./conversation-store.js";
+import { unknownConversation, } from "./conversation-store.js";
 import { createMemoryCredentialStore, } from "./credential-store.js";
 import { sessionStateStore, } from "./session-authority.js";
 import { theoremSession } from "./session-identity.js";
@@ -519,7 +519,57 @@ async function conversation(ctx, request, session) {
     if (!host)
         throw statelessRefusal('read');
     const opened = await openConversation(host, body.conversation, { kind: 'read' });
-    return jsonResponse(200, conversationView(host, opened.conversation));
+    return jsonResponse(200, await currentView(ctx, session, host, opened.conversation));
+}
+/**
+ * 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) {
+    const view = conversationView(host, conversation);
+    if (!view.transcript.some(isDetachedBlock))
+        return view;
+    const { operations } = await ctx.sessions.read(session.id);
+    return {
+        ...view,
+        transcript: view.transcript.map((block) => isDetachedBlock(block) ? lateBlock(block, operations, host, ctx.profile) : block),
+    };
+}
+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) {
+    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;
+    if (operation?.status === 'settled') {
+        const settled = host.forReader(operation.outcome.event);
+        if (settled.type !== 'tool')
+            return block;
+        const { tool: state } = settled;
+        if (!('phase' in state) || (state.phase !== 'complete' && state.phase !== 'error'))
+            return block;
+        return { ...block, tool: { ...tool, state, endedAt: operation.settledAt } };
+    }
+    const message = labelText('tool.execution_uncertain', {}, profile.labels);
+    const failure = {
+        code: operation?.status === 'uncertain' ? operation.reason : 'outcome_not_retained',
+        kind: 'internal',
+        message,
+    };
+    const { name, callId } = tool;
+    const at = operation?.status === 'uncertain' ? operation.detectedAt : (tool.state?.at ?? Date.now());
+    return {
+        ...block,
+        tool: {
+            ...tool,
+            state: { name, callId, at, phase: 'error', failure, readBack: message },
+            endedAt: at,
+        },
+    };
 }
 /** The conversation cut after one block; a reply that waits on gates is walked away from first. */
 async function rewind(ctx, request, session) {
@@ -542,7 +592,7 @@ async function rewind(ctx, request, session) {
         throw new TheoremError('internal', labelText('error.internal'));
     const rewound = {
         conversation: next.ref,
-        view: conversationView(host, next.conversation),
+        view: await currentView(ctx, session, host, next.conversation),
     };
     return jsonResponse(200, rewound);
 }

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' | 'path' | 'conditions'>;
+export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history' | 'path' | 'conditions' | 'model' | 'effort'>;

package/server/turn-input.js

@@ -23,6 +23,8 @@ export function liveSessionOpen(open, server) {
         ...(open.slots ? { slots: open.slots } : {}),
         ...(context ? { context } : {}),
         ...open.stated,
+        ...(open.model ? { model: open.model } : {}),
+        ...(open.effort ? { effort: open.effort } : {}),
         ...(open.resume
             ? { providerState: open.resume.providerState, awayMs: open.resume.awayMs }
             : {}),