@theoremjs/web 0.3.4-next.544.gb5ef325 → 0.3.4-next.550.gf20b9cd

package/README.md

@@ -236,6 +236,7 @@ const transport = withPageToolDispatch(
 | `provider` | Host options, including the credential vault. A function can return these options per request, for example for tenant-specific credentials. |
 | `session` | Returns the session id of the caller, for example `${userId}:${conversationId}`. Return `undefined` to refuse the request with a 401. Default: a random id in an HttpOnly, SameSite=Lax cookie that lasts 30 days. |
 | `host` | App data for the tool handlers (`ctx.host`), such as the signed-in user. |
+| `prepare` | Your app's own turn, from the one the handler builds (`TurnWiring.prepare` from `@theoremjs/agents`). Set what your app sets per turn, such as `system`, `credentials`, `onStage` and `onAgentCall`; read your app data as `turn.host`. The handler keeps its profile, its tool execution and its abort. Your `onStage` runs before the handler's steering, and your `credentials` are read before the session's. |
 | `pageToolBroker` | Delivers results to active page dispatches. Default: bounded process memory. |
 | `conversationStore` | Where the conversation is kept. Required, except for a stateless profile, which must not have one. See [Keep the conversation](#keep-the-conversation). |
 | `sessionStore`, `steerInbox` | Where open gates are kept, and where steers and stops reach a running turn. Default: process memory, which reaches only turns this process runs. On more than one instance, give a shared `SteerInbox`. |

package/client/chat.d.ts

@@ -59,9 +59,17 @@ export type ChatOptions = {
  * (`sent`), reached the model (`delivered`), answered (`read`).
  */
 export type MessageDelivery = 'sending' | 'sent' | 'delivered' | 'read';
+/** One declared slot as the composer shows it (group label + choices with optional blurbs). */
+export type ChatSlotDecl = {
+    label?: string;
+    choices: readonly {
+        value: string;
+        description?: string;
+    }[];
+};
 /** The slots the profile declares, and the value of each: the page's, else the picked one, else the first allowed. */
 export type ChatSlots = {
-    declared: Record<string, string[]>;
+    declared: Record<string, ChatSlotDecl>;
     values: Record<string, string>;
 };
 /** Everything a chat shows. A new object on each change, the same one between changes. */

package/client/chat.js

@@ -48,8 +48,9 @@ function withTurnError(blocks, error) {
 function slotsOf(iface, fixed, picked) {
     const declared = iface?.inputs.slots ?? {};
     const values = { ...fixed };
-    for (const [name, allowed] of Object.entries(declared)) {
-        const value = fixed?.[name] ?? picked[name] ?? allowed[0];
+    for (const [name, decl] of Object.entries(declared)) {
+        const first = decl.choices[0]?.value;
+        const value = fixed?.[name] ?? picked[name] ?? first;
         if (value !== undefined)
             values[name] = value;
     }

package/client/decision-transport.d.ts

@@ -5,6 +5,7 @@
  * @module
  */
 import { type DecisionAsset, type DecisionJson, type DecisionProfile, type DecisionQuestion, type DecisionResult, type TraceRecord } from '@theoremjs/agents';
+import type { JsonSchema } from './schema-fields.ts';
 import type { TraceFeed } from './trace-feed.ts';
 import { type HttpOptions } from './transport.ts';
 /** One question as the page sees it: its answer type and the names of its options or levels. Instructions stay on the host. */
@@ -24,13 +25,27 @@ export type DecisionInterface = {
     };
     contract: string;
     maxStateBytes?: number;
+    /** The questions every decision asks. Empty when the host builds them for each decision. */
     questions: DecisionQuestionView[];
+    /**
+     * Set when the host builds the questions for each decision, from its state and, when `input`
+     * is set, from what the page fills in by that JSON Schema. Each result names the questions it answers.
+     */
+    build?: {
+        input?: JsonSchema;
+    };
     /** The host's own images, by the reference its questions write, sent with every decision. */
     images?: Record<string, DecisionAsset>;
     observability?: {
         record: boolean;
     };
 };
+/** A decision's result: the answers and, when the host built its questions for it, those questions. */
+export type DecisionReplyResult = DecisionResult & {
+    questions?: DecisionQuestionView[];
+};
+/** Questions as the page sees them: their answer types and labels, never their instructions. */
+export declare function questionViews(questions: Record<string, DecisionQuestion>): DecisionQuestionView[];
 /** The page's view of a decision profile, the questions its host asks, and the host's own images. */
 export declare function decisionInterface(profile: Pick<DecisionProfile, 'identity' | 'decision' | 'inputs' | 'observability'>, questions: Record<string, DecisionQuestion>, images?: Record<string, DecisionAsset>): DecisionInterface;
 /**
@@ -40,13 +55,13 @@ export declare function decisionInterface(profile: Pick<DecisionProfile, 'identi
 export declare function decisionAssets(host: Record<string, DecisionAsset> | undefined, page: Record<string, DecisionAsset> | undefined): Record<string, DecisionAsset> | undefined;
 /** A decision's reply: the answers, and the trace records a host that delivers them sent back. */
 export type DecisionReply = {
-    result: DecisionResult;
+    result: DecisionReplyResult;
     traces?: TraceRecord[];
 };
 export interface DecisionTransport {
     describe(signal?: AbortSignal): Promise<DecisionInterface>;
-    /** `assets` are the images the state names, by reference. */
-    decide(state: Exclude<DecisionJson, null>, signal?: AbortSignal, assets?: Record<string, DecisionAsset>): Promise<DecisionReply>;
+    /** `assets` are the images the state names, by reference; `input` is what the host's question builder takes. */
+    decide(state: Exclude<DecisionJson, null>, signal?: AbortSignal, assets?: Record<string, DecisionAsset>, input?: unknown): Promise<DecisionReply>;
     /** Where the host's trace records land, for the inspector. */
     traces?: TraceFeed;
 }

package/client/decision-transport.js

@@ -14,6 +14,19 @@ function entryLabel(entry, fallback) {
     const entries = Array.isArray(entry) ? entry : Object.keys(entry);
     return entries.length ? entryLabel(entries[0], fallback) : fallback;
 }
+/** Questions as the page sees them: their answer types and labels, never their instructions. */
+export function questionViews(questions) {
+    return Object.entries(questions).map(([id, question]) => ({
+        id,
+        type: question.type,
+        labels: question.type === 'choice'
+            ? Object.keys(question.criteria)
+            : question.type === 'score'
+                ? question.criteria.map((entry, level) => entryLabel(entry, String(level)))
+                : [],
+        ...(question.type === 'box' && question.image !== undefined ? { image: question.image } : {}),
+    }));
+}
 /** The page's view of a decision profile, the questions its host asks, and the host's own images. */
 export function decisionInterface(profile, questions, images) {
     return {
@@ -23,16 +36,7 @@ export function decisionInterface(profile, questions, images) {
         ...(profile.inputs.maxStateBytes === undefined
             ? {}
             : { maxStateBytes: profile.inputs.maxStateBytes }),
-        questions: Object.entries(questions).map(([id, question]) => ({
-            id,
-            type: question.type,
-            labels: question.type === 'choice'
-                ? Object.keys(question.criteria)
-                : question.type === 'score'
-                    ? question.criteria.map((entry, level) => entryLabel(entry, String(level)))
-                    : [],
-            ...(question.type === 'box' && question.image !== undefined ? { image: question.image } : {}),
-        })),
+        questions: questionViews(questions),
         ...(images && Object.keys(images).length > 0 ? { images } : {}),
         ...(profile.observability
             ? { observability: { record: resolveObservabilityPolicy(profile.observability).record } }
@@ -75,9 +79,16 @@ const answerSchema = z.discriminatedUnion('type', [
         probabilities,
     }),
 ]);
+const questionViewSchema = z.object({
+    id: z.string(),
+    type: z.enum(['choice', 'noul', 'score', 'box']),
+    labels: z.array(z.string()),
+    image: z.string().optional(),
+});
 const replySchema = z.object({
     result: z.object({
         model: z.string().min(1),
+        questions: z.array(questionViewSchema).optional(),
         answers: z.record(z.string(), answerSchema),
         usage: z
             .object({
@@ -132,12 +143,8 @@ const describedSchema = z.object({
         identity: z.object({ handle: z.string() }),
         contract: z.string(),
         maxStateBytes: z.number().optional(),
-        questions: z.array(z.object({
-            id: z.string(),
-            type: z.enum(['choice', 'noul', 'score', 'box']),
-            labels: z.array(z.string()),
-            image: z.string().optional(),
-        })),
+        questions: z.array(questionViewSchema),
+        build: z.object({ input: z.record(z.string(), z.unknown()).optional() }).optional(),
         images: z
             .record(z.string(), z.object({ mimeType: z.enum(['image/png', 'image/jpeg']), data: z.string() }))
             .optional(),
@@ -151,6 +158,6 @@ export function createDecisionTransport(options = {}) {
         async describe(signal) {
             return checkWire(describedSchema, await fetchJson(base, { signal }, options), 'the decision description').interface;
         },
-        decide: (state, signal, assets) => postDecision(`${base}/decide`, { state, ...(assets ? { assets } : {}) }, signal, options),
+        decide: (state, signal, assets, input) => postDecision(`${base}/decide`, { state, ...(assets ? { assets } : {}), ...(input === undefined ? {} : { input }) }, signal, options),
     };
 }

package/client/index.d.ts

@@ -1,9 +1,9 @@
 export { float32Rms, float32RmsToLevel, INPUT_LEVEL_GAIN, timeDomainBytesToLevel, } from './audio-level.ts';
-export { type ChatController, type ChatOptions, type ChatSlots, type ChatState, type ChatUpdate, createChatController, type MessageDelivery, type SentTurn, } from './chat.ts';
+export { type ChatController, type ChatOptions, type ChatSlotDecl, type ChatSlots, type ChatState, type ChatUpdate, createChatController, type MessageDelivery, type SentTurn, } from './chat.ts';
 export { type ComposerDrawerKind, type ComposerDrawerSummary, composerDrawerSummary, } from './composer-drawer.ts';
 export { type ComposerHint, isStashShortcut, resolveComposerHint, STASH_SHORTCUT, } from './composer-hints.ts';
 export { type ComposerActionState, composerActionState, composerHasPayload, } from './composer-primary.ts';
-export { createDecisionTransport, type DecisionInterface, type DecisionQuestionView, type DecisionReply, type DecisionTransport, decisionAssets, decisionInterface, failedTraces, postDecision, readDecisionReply, withFailedTraces, } from './decision-transport.ts';
+export { createDecisionTransport, type DecisionInterface, type DecisionQuestionView, type DecisionReply, type DecisionReplyResult, type DecisionTransport, decisionAssets, decisionInterface, failedTraces, postDecision, questionViews, readDecisionReply, withFailedTraces, } from './decision-transport.ts';
 export { type ComposerDraftFields, composerFieldsFromDraft } from './decode-composer-draft.ts';
 export { addUsage, checkEmbeddingInputs, checkInputs, cosineSimilarity, type EmbeddingFields, type EmbeddingInputCheck, type EmbeddingMatch, type EmbeddingMediaPart, type EmbeddingSplit, embeddingBatches, fieldsInput, inputFields, MAX_BATCH_INPUTS, rankMatches, readEmbeddingInput, readEmbeddingInputs, readsAsText, splitText, } from './embedding-input.ts';
 export { type EmbeddingSpace, layoutSpace, layoutSpaceSoon, outlierThreshold, placeQuery, type SpaceCluster, type SpaceDocument, type SpaceLink, type SpacePoint, } from './embedding-space.ts';
@@ -32,6 +32,6 @@ export { DOT_FLOATS, FRAME_SLOT, queryGeometry, SEGMENT_FLOATS, type SpaceGeomet
 export { hasLead, layoutResult, type ResultChart, type ResultFigure, type ResultImage, type ResultLayout, type ResultMedia, returnedMedia, timeFormats, } from './tool-result.ts';
 export type { AnsweringGate, ToolDecisionAction, ToolGateResolution, } from './tool-resume.ts';
 export { continueGatedToolInvocation, type PersonGateResolution } from './tool-resume.ts';
-export { createTraceFeed, type TraceFeed } from './trace-feed.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 { buildInvokeRequest, buildTurnRequest, foldAssistantTurn, issuedOperationId, type RunScope, type WalkAway, } from './turn-client.ts';

package/client/index.js

@@ -3,7 +3,7 @@ export { createChatController, } from "./chat.js";
 export { composerDrawerSummary, } from "./composer-drawer.js";
 export { isStashShortcut, resolveComposerHint, STASH_SHORTCUT, } from "./composer-hints.js";
 export { composerActionState, composerHasPayload, } from "./composer-primary.js";
-export { createDecisionTransport, decisionAssets, decisionInterface, failedTraces, postDecision, readDecisionReply, withFailedTraces, } from "./decision-transport.js";
+export { createDecisionTransport, decisionAssets, decisionInterface, failedTraces, postDecision, questionViews, readDecisionReply, withFailedTraces, } from "./decision-transport.js";
 export { composerFieldsFromDraft } from "./decode-composer-draft.js";
 export { addUsage, checkEmbeddingInputs, checkInputs, cosineSimilarity, embeddingBatches, fieldsInput, inputFields, MAX_BATCH_INPUTS, rankMatches, readEmbeddingInput, readEmbeddingInputs, readsAsText, splitText, } from "./embedding-input.js";
 export { layoutSpace, layoutSpaceSoon, outlierThreshold, placeQuery, } from "./embedding-space.js";
@@ -26,6 +26,6 @@ export { citationsFromBlock, } from "./source-citations.js";
 export { DOT_FLOATS, FRAME_SLOT, queryGeometry, SEGMENT_FLOATS, spaceGeometry, } from "./space-geometry.js";
 export { hasLead, layoutResult, returnedMedia, timeFormats, } from "./tool-result.js";
 export { continueGatedToolInvocation } from "./tool-resume.js";
-export { createTraceFeed } from "./trace-feed.js";
+export { createTraceFeed, recordedFeed } from "./trace-feed.js";
 export { CHAT_LINES, createHttpTransport, fetchConversation, fetchRewound, fetchStarted, hostError, isTheoremStreamError, postJson, postNdjson, readNdjsonStream, TheoremStreamError, } from "./transport.js";
 export { buildInvokeRequest, buildTurnRequest, foldAssistantTurn, issuedOperationId, } from "./turn-client.js";

package/client/source-citations.js

@@ -5,7 +5,7 @@
 const GROUNDING_REDIRECT_HOST = 'vertexaisearch.cloud.google.com';
 /** A citation's sources, in the order they were cited. */
 export function citationsFromBlock(block) {
-    return block.sources.map((source, i) => citationFromSource(source, `c-${String(i)}`));
+    return block.sources.map((source, i) => citationFromSource(source, `${block.id}-c-${String(i)}`));
 }
 function citationFromSource(source, key) {
     const url = webUrl(source.uri);

package/client/trace-feed.d.ts

@@ -11,3 +11,5 @@ export interface TraceFeed {
     subscribe(listener: () => void): () => void;
 }
 export declare function createTraceFeed(): TraceFeed;
+/** A feed already holding `records` — a recording opened for View Trace. */
+export declare function recordedFeed(records: readonly TraceRecord[]): TraceFeed;

package/client/trace-feed.js

@@ -16,3 +16,10 @@ export function createTraceFeed() {
         },
     };
 }
+/** A feed already holding `records` — a recording opened for View Trace. */
+export function recordedFeed(records) {
+    const feed = createTraceFeed();
+    for (const record of records)
+        feed.push(record);
+    return feed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.544.gb5ef325",
+  "version": "0.3.4-next.550.gf20b9cd",
   "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.544.gb5ef325"
+    "@theoremjs/agents": "^0.3.4-next.550.gf20b9cd"
   }
 }

package/server/decision-handler.d.ts

@@ -4,19 +4,35 @@
  * - `GET  <base>`        → `{ interface }` the profile's handle, contract, and questions
  * - `POST <base>/decide` → `{ result }` the answers for the posted `{ state }`
  *
- * The host owns the questions: the browser sends only the state and the images it names,
- * so a visitor can't spend the host's key asking questions of their own.
+ * The host owns the questions: the browser sends only the state, the images it names and,
+ * when the host builds its questions for each decision, the input its builder takes. A
+ * visitor can't spend the host's key asking questions of their own.
  *
  * @module
  */
-import { type DecisionAsset, type DecisionProfile, type DecisionQuestion, type KeyVault, type TraceSink } from '@theoremjs/agents';
+import { type DecisionAsset, type DecisionJson, type DecisionProfile, type DecisionQuestion, type KeyVault, type TraceSink, z } from '@theoremjs/agents';
 import type { ClientTurnOptions } from '@theoremjs/agents/host';
-import type { DecisionProfileDefinition } from '@theoremjs/agents/kernel';
-export type TheoremDecisionHandlerOptions = {
+import { type DecisionProfileDefinition } from '@theoremjs/agents/kernel';
+/**
+ * Questions built for each decision: from its state and, when `input` is set, from what the page
+ * fills in beside it. The handler checks the input against `input` before `build` sees it.
+ */
+export type DecisionQuestionsBuilder<Input = undefined> = {
+    /** What the page fills in for each decision, beyond the state. */
+    input?: z.ZodType<Input>;
+    /** The questions one decision asks, by id. */
+    build(call: {
+        state: Exclude<DecisionJson, null>;
+        input: Input;
+    }): Record<string, DecisionQuestion> | Promise<Record<string, DecisionQuestion>>;
+};
+/** Whether `questions` are built for each decision, not fixed. */
+export declare function isQuestionsBuilder(questions: unknown): questions is DecisionQuestionsBuilder<unknown>;
+export type TheoremDecisionHandlerOptions<Input = unknown> = {
     /** Decision profile to serve. Registered with the kernel when the handler is created. */
     profile: DecisionProfile | DecisionProfileDefinition;
-    /** The questions every decision asks, by id. */
-    questions: Record<string, DecisionQuestion>;
+    /** The questions every decision asks, by id, or a builder that makes them for each decision. */
+    questions: Record<string, DecisionQuestion> | DecisionQuestionsBuilder<Input>;
     /**
      * Images every decision sends, by the reference its questions write, such as `<ghs02>`. The page
      * sees them, to draw a box on one; a page image with one of their names is refused.
@@ -39,4 +55,4 @@ export type TheoremDecisionHandlerOptions = {
         request: Request;
     }) => void;
 };
-export declare function createTheoremDecisionHandler(options: TheoremDecisionHandlerOptions): (request: Request) => Promise<Response>;
+export declare function createTheoremDecisionHandler<Input = unknown>(options: TheoremDecisionHandlerOptions<Input>): (request: Request) => Promise<Response>;

package/server/decision-handler.js

@@ -4,18 +4,27 @@
  * - `GET  <base>`        → `{ interface }` the profile's handle, contract, and questions
  * - `POST <base>/decide` → `{ result }` the answers for the posted `{ state }`
  *
- * The host owns the questions: the browser sends only the state and the images it names,
- * so a visitor can't spend the host's key asking questions of their own.
+ * The host owns the questions: the browser sends only the state, the images it names and,
+ * when the host builds its questions for each decision, the input its builder takes. A
+ * visitor can't spend the host's key asking questions of their own.
  *
  * @module
  */
-import { defineProfile, registerProfile, runDecision, z, } from '@theoremjs/agents';
-import { decisionAssets, decisionInterface } from "../client/decision-transport.js";
+import { defineProfile, registerProfile, runDecision, TheoremError, z, } from '@theoremjs/agents';
+import { jsonSchemaFromZod } from '@theoremjs/agents/kernel';
+import { decisionAssets, decisionInterface, questionViews } from "../client/decision-transport.js";
 import { readBody } from "./handler.js";
 import { singleActionHandler } from "./single-action.js";
+/** Whether `questions` are built for each decision, not fixed. */
+export function isQuestionsBuilder(questions) {
+    return (typeof questions === 'object' &&
+        questions !== null &&
+        typeof questions.build === 'function');
+}
 const decideBodySchema = z.object({
     state: z.unknown(),
     assets: z.record(z.string(), z.object({ mimeType: z.string(), data: z.string() })).optional(),
+    input: z.unknown().optional(),
 });
 export function createTheoremDecisionHandler(options) {
     const profile = defineProfile(options.profile);
@@ -24,23 +33,51 @@ export function createTheoremDecisionHandler(options) {
         throw new Error(`createTheoremDecisionHandler serves type 'decision'; got type '${profile.type}'.`);
     }
     registerProfile(profile);
+    const { questions } = options;
+    const builder = isQuestionsBuilder(questions)
+        ? questions
+        : undefined;
+    const fixed = builder ? {} : questions;
     return singleActionHandler({
         action: 'decide',
-        iface: decisionInterface(profile, options.questions, options.images),
+        iface: builder
+            ? {
+                ...decisionInterface(profile, {}, options.images),
+                build: builder.input ? { input: jsonSchemaFromZod(builder.input, 'input') } : {},
+            }
+            : decisionInterface(profile, fixed, options.images),
         labels: profile.labels,
         clientEvents: options.clientEvents,
         onError: options.onError,
     }, async (request) => {
         const body = await readBody(request, decideBodySchema);
-        return runDecision({
+        if (builder && (body.state === null || body.state === undefined))
+            // labels-exempt: internal diagnostic; the user reads error.request
+            throw new TheoremError('request', 'a decision needs a state');
+        // why: The kernel checks the state is JSON within the profile's size; a builder is never handed null.
+        const state = body.state;
+        const asked = builder
+            ? await builder.build({ state, input: builtInput(builder, body.input) })
+            : fixed;
+        const result = await runDecision({
             profile: profile.id,
-            // why: The kernel checks the state is non-null JSON within the profile's size.
-            state: body.state,
+            state,
             // why: The kernel checks each image's type and bytes before any request leaves.
             assets: decisionAssets(options.images, body.assets),
-            questions: options.questions,
+            questions: asked,
             signal: request.signal,
             metadata: options.metadata?.(request),
         }, { vault: options.vault, fetch: options.fetch, sink: options.sink });
+        return builder ? { ...result, questions: questionViews(asked) } : result;
     });
 }
+/** The page's input, checked against the builder's: refused as a bad request when it does not fit. */
+function builtInput(builder, input) {
+    if (!builder.input)
+        return undefined;
+    const parsed = builder.input.safeParse(input);
+    if (!parsed.success)
+        // labels-exempt: internal diagnostic; the user reads error.request
+        throw new TheoremError('request', `the questions' input does not fit: ${parsed.error.message}`);
+    return parsed.data;
+}

package/server/handler.d.ts

@@ -32,7 +32,7 @@ import { type PageToolBroker } from './page-dispatch.ts';
  *
  * @module
  */
-import { type Profile, type ProfileDefinition, type ProviderHostOptions, type ToolGate, type z } from '@theoremjs/agents';
+import { type Profile, type ProfileDefinition, type ProviderHostOptions, type ToolGate, type TurnWiring, type z } from '@theoremjs/agents';
 import { type ClientTurnOptions } from '@theoremjs/agents/host';
 import { type TheoremConversationStore } from './conversation-store.ts';
 import { type TheoremCredentialStore } from './credential-store.ts';
@@ -64,6 +64,14 @@ export type TheoremHandlerOptions = {
      * request and is read as untrusted; this one is the host's.
      */
     context?: (request: Request) => unknown;
+    /**
+     * The application's own turn, from the one the handler builds: `TurnWiring.prepare`, the
+     * value the application's other call sites use too. The handler keeps its profile, its tool
+     * execution and its abort. The application's `onStage` runs before the handler's steering, and
+     * its `credentials` are read before the session's. A call held at a gate runs on, once
+     * answered, with the `onStage` and `credentials` it gives for that call's turn.
+     */
+    prepare?: TurnWiring['prepare'];
     /**
      * Resolve the caller's session id — e.g. `${userId}:${conversationId}` from your
      * auth. Return `undefined` to refuse the request (401). Default: an opaque id
@@ -134,7 +142,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'> & {
+export type TheoremHostHandlerOptions = Omit<TheoremHandlerOptions, 'profile' | 'provider' | 'steerInbox' | 'conversationStore' | 'prepare'> & {
     /** Host profile to serve. Registered with the kernel when the handler is created. */
     profile: Extract<Profile, {
         type: 'host';

package/server/handler.js

@@ -52,6 +52,7 @@ import { resolveSessionLimits } from "./session-limits.js";
 import { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, } from "./session-store.js";
 import { createMemorySteerInbox, steerStage, steerUnitOf, stopOnRequest, } from "./steer-inbox.js";
 import { sameAcceptedAnswer, sessionToolCoordinator } from "./tool-operations.js";
+import { preparedTurn } from "./turn-wiring.js";
 const NDJSON_HEADERS = {
     'content-type': 'application/x-ndjson; charset=utf-8',
     'cache-control': 'no-store',
@@ -359,6 +360,8 @@ async function* settleAnswered(ctx, request, session, answered) {
 }
 async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
     const host = await ctx.options.host?.(request);
+    // why: The held call goes on with what the application set for its turn: its stage handler and credentials.
+    const { credentials, onStage } = await preparedTurn(ctx.options.prepare, { profile: ctx.profile.id, input: pending.turnInput ?? {}, host, signal: request.signal }, { credentials: sessionCredentials(ctx, sessionId) });
     yield* invokeTool({
         profile: ctx.profile.id,
         execution: sessionToolCoordinator(ctx.sessions, sessionId),
@@ -373,7 +376,8 @@ async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answe
             ? { page: answer.page ?? { unanswered: true } }
             : {}),
         sessionPermissions: answer.sessionPermissions,
-        credentials: sessionCredentials(ctx, sessionId),
+        credentials,
+        ...(onStage ? { onStage } : {}),
         turnInput: pending.turnInput,
         snapshot: pending.snapshot,
         promoted: pending.promoted,
@@ -396,20 +400,22 @@ async function* chatTurn(ctx, request, session, turn, key, stop) {
         stopOnRequest(ctx.inbox, key, stop);
     }
     try {
-        const events = runTurn({
+        const prepared = await preparedTurn(ctx.options.prepare, {
             profile: ctx.profile.id,
             execution: sessionToolCoordinator(ctx.sessions, session.id),
             pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).execution,
             input: turn.input,
             ...(turn.providerState ? { providerState: turn.providerState } : {}),
             sessionPermissions: state.permissions,
-            credentials: sessionCredentials(ctx, session.id),
             signal: AbortSignal.any([request.signal, stop.signal]),
             host,
             ...(turn.model ? { model: turn.model } : {}),
             ...(turn.effort ? { effort: turn.effort } : {}),
+        }, {
+            credentials: sessionCredentials(ctx, session.id),
             ...(key ? { onStage: steerStage(ctx.inbox, key) } : {}),
-        }, provider);
+        });
+        const events = runTurn(prepared, provider);
         yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
             profileId: ctx.profile.id,
             turnInput: turn.input,

package/server/mod.d.ts

@@ -11,7 +11,7 @@ export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremRe
 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';
-export { createTheoremDecisionHandler, type TheoremDecisionHandlerOptions, } from './decision-handler.ts';
+export { createTheoremDecisionHandler, type DecisionQuestionsBuilder, isQuestionsBuilder, type TheoremDecisionHandlerOptions, } from './decision-handler.ts';
 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';

package/server/mod.js

@@ -10,7 +10,7 @@ export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremRe
 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";
-export { createTheoremDecisionHandler, } from "./decision-handler.js";
+export { createTheoremDecisionHandler, isQuestionsBuilder, } from "./decision-handler.js";
 export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, } from "./embedding-handler.js";
 export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSession, theoremSessionId, } from "./handler.js";
 export { createTheoremMcpHandler } from "./mcp-handler.js";

package/server/turn-wiring.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The application's turn wiring (`TurnWiring.prepare`) laid over the turn the handler builds.
+ * The handler keeps the fields it owns; the application's stage handler and credentials go
+ * first, and the handler's own run when the application's have nothing.
+ *
+ * @module
+ */
+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'>;
+/** What the handler adds to a turn of its own: the session's credentials and its steering. */
+export type HandlerTurnParts = {
+    credentials: ToolCredentialSource;
+    onStage?: StageHandler;
+};
+/**
+ * The turn to run: `turn` through the application's `prepare`, with the handler's own fields
+ * kept, and its credentials and steering after the application's.
+ */
+export declare function preparedTurn(prepare: TurnWiring['prepare'], turn: NormalizedTurnRequest & HandlerOwned, handler: HandlerTurnParts): Promise<TurnRequest>;
+/**
+ * The application's stage handler, then the handler's own when the application's asks for
+ * nothing. What the second one would have done waits for the next stage that allows it.
+ */
+export declare function stagesInOrder(app: StageHandler | undefined, own: StageHandler | undefined): StageHandler | undefined;
+/**
+ * The application's credentials, then the session's. A credential is saved where the slot
+ * already lives: a refreshed token back to the application, a sign-in at a gate to the session.
+ */
+export declare function credentialsInOrder(app: ToolCredentialSource | undefined, session: ToolCredentialSource): ToolCredentialSource;

package/server/turn-wiring.js

@@ -0,0 +1,54 @@
+/**
+ * The application's turn wiring (`TurnWiring.prepare`) laid over the turn the handler builds.
+ * The handler keeps the fields it owns; the application's stage handler and credentials go
+ * first, and the handler's own run when the application's have nothing.
+ *
+ * @module
+ */
+/**
+ * The turn to run: `turn` through the application's `prepare`, with the handler's own fields
+ * kept, and its credentials and steering after the application's.
+ */
+export async function preparedTurn(prepare, turn, handler) {
+    const app = prepare ? await prepare(turn) : turn;
+    const owned = {
+        profile: turn.profile,
+        ...(turn.execution ? { execution: turn.execution } : {}),
+        ...(turn.pageExecution ? { pageExecution: turn.pageExecution } : {}),
+        ...(turn.providerState ? { providerState: turn.providerState } : {}),
+        ...(turn.signal ? { signal: turn.signal } : {}),
+    };
+    const onStage = stagesInOrder(app.onStage, handler.onStage);
+    return {
+        ...app,
+        ...owned,
+        credentials: credentialsInOrder(app.credentials, handler.credentials),
+        ...(onStage ? { onStage } : {}),
+    };
+}
+/**
+ * The application's stage handler, then the handler's own when the application's asks for
+ * nothing. What the second one would have done waits for the next stage that allows it.
+ */
+export function stagesInOrder(app, own) {
+    if (!app || !own)
+        return app ?? own;
+    return async (ctx) => (await app(ctx)) ?? (await own(ctx));
+}
+/**
+ * The application's credentials, then the session's. A credential is saved where the slot
+ * already lives: a refreshed token back to the application, a sign-in at a gate to the session.
+ */
+export function credentialsInOrder(app, session) {
+    if (!app)
+        return session;
+    // why: Called as a method: an application's source may keep its secrets on `this`.
+    const secrets = app.clientSecret ? app : session;
+    return {
+        get: async (slot) => (await app.get(slot)) ?? (await session.get(slot)),
+        set: async (slot, credential) => (await app.get(slot)) ? await app.set(slot, credential) : await session.set(slot, credential),
+        ...(secrets.clientSecret
+            ? { clientSecret: async (clientId) => await secrets.clientSecret?.(clientId) }
+            : {}),
+    };
+}