@theoremjs/web 0.3.4-next.548.gbb156b2 → 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/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

@@ -3,7 +3,7 @@ export { type ChatController, type ChatOptions, type ChatSlotDecl, type ChatSlot
 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';

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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.3.4-next.548.gbb156b2",
+  "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.548.gbb156b2"
+    "@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) }
+            : {}),
+    };
+}