@theoremjs/agents 0.3.4-next.482.g7e608f2 → 0.3.4-next.508.geda6db0

package/esm/src/kernel/provider-budget.js

@@ -21,6 +21,9 @@ function combinedSignal(signals) {
     }
     return { signal: controller.signal, dispose };
 }
+function over(value, limit) {
+    return limit !== undefined && value > limit;
+}
 export class ProviderBudget {
     limits;
     controller = new AbortController();
@@ -38,10 +41,14 @@ export class ProviderBudget {
         const effective = combinedSignal(caller ? [caller, this.controller.signal] : [this.controller.signal]);
         this.signal = effective.signal;
         this.releaseSignal = effective.dispose;
+        if (timeoutMs === undefined)
+            return;
         this.startTimer(timeoutMs);
         this.deadline = performance.now() + timeoutMs;
     }
     resumeOperation() {
+        if (this.deadline === undefined)
+            return;
         const remaining = this.deadline - performance.now();
         if (remaining <= 0) {
             this.controller.abort(new TheoremError('timeout', labelText('error.timeout')));
@@ -51,7 +58,8 @@ export class ProviderBudget {
     }
     /** Milliseconds before the running timer ends the call. */
     timeLeft() {
-        return (this.timerDeadline ?? this.deadline) - performance.now();
+        const end = this.timerDeadline ?? this.deadline;
+        return end === undefined ? Number.POSITIVE_INFINITY : end - performance.now();
     }
     startTimer(ms) {
         this.stopTimer();
@@ -73,8 +81,9 @@ export class ProviderBudget {
         this.releaseSignal();
     }
     startLiveStep() {
-        if (this.timer === undefined)
-            this.startTimer(this.limits.liveStepTimeoutMs);
+        const ms = this.limits.liveStepTimeoutMs;
+        if (this.timer === undefined && ms !== undefined)
+            this.startTimer(ms);
     }
     fail() {
         const error = new TheoremError('bad_response', labelText('provider.budget_exhausted'), {
@@ -95,9 +104,9 @@ export class ProviderBudget {
         this.checkDeadline();
         this.stepBytes += bytes;
         this.stepEvents++;
-        if (bytes > this.limits.maxEventBytes ||
-            this.stepBytes > this.limits.maxStepBytes ||
-            this.stepEvents > this.limits.maxStepEvents)
+        if (over(bytes, this.limits.maxEventBytes) ||
+            over(this.stepBytes, this.limits.maxStepBytes) ||
+            over(this.stepEvents, this.limits.maxStepEvents))
             this.fail();
     }
     event(event) {
@@ -106,7 +115,7 @@ export class ProviderBudget {
             this.calls.add(event.call.callId);
         if (event.type === 'tool_cancel')
             this.calls.delete(event.callId);
-        if (this.calls.size > this.limits.maxPendingToolCalls)
+        if (over(this.calls.size, this.limits.maxPendingToolCalls))
             this.fail();
     }
     resetStep() {
@@ -138,7 +147,7 @@ export class ProviderBudget {
                         : data instanceof ArrayBuffer || ArrayBuffer.isView(data)
                             ? data.byteLength
                             : 0;
-                if (bytes <= this.limits.maxWireRecordBytes)
+                if (!over(bytes, this.limits.maxWireRecordBytes))
                     return;
                 event.stopImmediatePropagation();
                 try {
@@ -168,7 +177,8 @@ export class ProviderBudget {
             }
             const reader = response.body.getReader();
             let responseBytes = 0;
-            const record = response.headers.get('content-type')?.includes('text/event-stream')
+            const record = this.limits.maxWireRecordBytes !== undefined &&
+                response.headers.get('content-type')?.includes('text/event-stream')
                 ? new SseRecordBudget(this)
                 : undefined;
             const abort = () => {
@@ -190,8 +200,8 @@ export class ProviderBudget {
                         }
                         responseBytes += next.value.byteLength;
                         this.wireBytes += next.value.byteLength;
-                        if (responseBytes > this.limits.maxWireResponseBytes ||
-                            this.wireBytes > this.limits.maxWireResponseBytes)
+                        if (over(responseBytes, this.limits.maxWireResponseBytes) ||
+                            over(this.wireBytes, this.limits.maxWireResponseBytes))
                             this.fail();
                         record?.accept(next.value);
                         controller.enqueue(next.value);
@@ -233,7 +243,7 @@ class SseRecordBudget {
                 this.emptyCR = false;
             }
             this.recordBytes++;
-            if (this.recordBytes > this.budget.limits.maxWireRecordBytes)
+            if (over(this.recordBytes, this.budget.limits.maxWireRecordBytes))
                 this.budget.fail();
             if (this.emptyCR) {
                 this.recordBytes = 0;

package/esm/src/kernel/provider-runtime.js

@@ -5,7 +5,7 @@ import { historyHash, providerCheckpointSchema, } from './checkpoint.js';
 import { stepReplyMessages } from './interaction-parts.js';
 import { jsonObjectSchema, jsonValueSchema } from './json.js';
 import { keySlotsOf, protocolOf, } from './protocols/binding.js';
-import { resolveProviderLimits } from './protocols/limits.js';
+import { providerLimitsSchema } from './protocols/limits.js';
 import { carriesTo, } from './protocols/protocol.js';
 import { callProtocol, plainWebSocket } from './protocols/runtime.js';
 import { ProviderBudget } from './provider-budget.js';
@@ -188,7 +188,7 @@ const SECRET_FIELD = /^(?:authorization|proxy-authorization|cookie|set-cookie|ap
  * the host's budgets, with every key it signs with kept out of errors and traces.
  */
 export function guardedCall(provider, binding, profileType, host, req) {
-    const limits = resolveProviderLimits(host.limits);
+    const limits = Object.freeze(providerLimitsSchema.parse({ ...binding.limits, ...host.limits }));
     const budget = new ProviderBudget(limits, req.signal, req.timeoutMs ?? (req.liveConnection ? limits.connectTimeoutMs : limits.operationTimeoutMs));
     const secrets = new Set();
     const remember = (value) => {

package/esm/src/kernel/registry/profiles.js

@@ -50,7 +50,7 @@ function validateDecisionBinding(profileId, modelId, binding) {
     if ('retry' in binding) {
         throw new TheoremError('config', 
         // labels-exempt: developer contract / internal diagnostic
-        `Profile ${profileId} model '${modelId}': decision retry configuration is unsupported; POSTs are never retried`);
+        `Profile ${profileId} model '${modelId}': a decision binding takes no retry; a decision retries only a transient failure, by the kernel's rule`);
     }
     if (binding.timeoutMs !== undefined &&
         (!Number.isFinite(binding.timeoutMs) || binding.timeoutMs <= 0)) {

package/esm/src/kernel/registry/resolve.js

@@ -4,6 +4,7 @@ import { TheoremError } from '../../guardrails/error.js';
 import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
 import { replyIsJudged } from '../../guardrails/progressive-yield.js';
 import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
+import { ANSWER_TOOL } from '../answer-tool.js';
 import { DEFAULT_MAX_STEPS } from '../profile-presence.js';
 import { profileTurnResumption } from '../stop.js';
 import { projectTools } from '../tools/project.js';
@@ -171,6 +172,9 @@ function resolveTurnInRegistry(registry, req, model) {
     const builtins = toolSnapshot.builtins;
     const structuredId = resolveStructured(profile, input.slots);
     assertOutputMode(profile, structuredId);
+    if (structuredId && toolSnapshot.wire.some((tool) => tool.name === ANSWER_TOOL)) {
+        throw new TheoremError('config', `Profile ${profile.id}: a structured turn answers through '${ANSWER_TOOL}', so no tool of its own may take that name`);
+    }
     assertSpeechRole(profile, safe);
     const builtInArgs = resolveBuiltInArgs(profile, picked, binding, safe.builtInArgs);
     const transport = resolveTransport(profile, binding);

package/esm/src/kernel/registry/schemas.js

@@ -5,7 +5,7 @@ function createSchemaRegistry() {
     return {
         register(id, spec) {
             if ('enforced' in spec) {
-                throw new TheoremError('config', `registerStructured '${id}': enforced was removed; every structured schema is sent to the model as its response format`);
+                throw new TheoremError('config', `registerStructured '${id}': enforced was removed; every structured schema is sent to the model, as its response format or as its answer tool's input`);
             }
             if (!spec.jsonSchema ||
                 typeof spec.jsonSchema !== 'object' ||

package/esm/src/kernel/schema.js

@@ -520,6 +520,16 @@ export const PROFILE_FIELDS = withScopeAndPresence({
     'providerContinuation.history': field("'host' | 'stateless' | 'provider'", 'Who holds the conversation a checkpoint continues: the host passes history back, the provider keeps it and the checkpoint travels alone, or the profile is stateless and every request stands alone.', ['host', 'stateless', 'provider']),
     'models.*.apiId': field('string', "The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name this model has in the profile is its key in models."),
     'models.*.timeoutMs': field('number', 'How long a decision waits for its provider, in milliseconds. Omit for no timeout.'),
+    'models.*.limits': field('ProviderLimits', "The points at which Theorem stops this model's calls. Each one left out is no limit, so the provider's own limits apply. A runTurn limits value overrides each field it sets."),
+    'models.*.limits.operationTimeoutMs': field('number', 'How long one call may take, in milliseconds, retries included.'),
+    'models.*.limits.connectTimeoutMs': field('number', 'How long a live session may take to open, in milliseconds.'),
+    'models.*.limits.liveStepTimeoutMs': field('number', 'How long a live session may wait for the model to answer, in milliseconds.'),
+    'models.*.limits.maxWireRecordBytes': field('number', 'The most bytes in one record the provider sends: a stream event or a socket message.'),
+    'models.*.limits.maxWireResponseBytes': field('number', 'The most bytes the provider sends for one step.'),
+    'models.*.limits.maxEventBytes': field('number', 'The most bytes in one event of a step.'),
+    'models.*.limits.maxStepBytes': field('number', 'The most bytes in all the events of one step.'),
+    'models.*.limits.maxStepEvents': field('number', 'The most events in one step.'),
+    'models.*.limits.maxPendingToolCalls': field('number', 'The most tool calls one step may ask for.'),
     decision: field('{ contract: DecisionContractId }', 'Names the host decision this profile makes.'),
     'decision.contract': field('string', 'Your name for this decision, on its traces. Not sent to the model. Not checked against the questions.'),
     'models.*.efforts': field('Record<string, ThinkingLevel>', 'Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a level its model does not take. Speech ignores them, and so may an image profile without includeText.'),
@@ -762,12 +772,12 @@ export const EXTRA_FIELDS = {
         noul: 'One number, which may weigh named criteria.',
         box: 'Where something is in an image: its top, bottom, left and right edges, with a confidence.',
     }),
-    'decision.questions.instructions': field('DecisionEntry', "What to ask about the state. Name a state field in backticks, such as `photo`, and one of the decision's images by its reference, such as <ginger>. A box looks in its In image, else in the image of the first field it names."),
+    'decision.questions.instructions': field('DecisionEntry', "What to ask about the state. Name a state field in backticks, such as `photo`, and one of the decision's images by its reference, such as <ginger>. A box names what to find and the image it is in, such as the ginger in `photo`."),
     'decision.questions.image': {
         ...field('string', "The image a box is in: one of the decision's images, such as <ghs02>, or a state field its instructions name, such as `photo`. The model is told it in the instructions."),
         unset: 'The image the instructions name',
     },
-    'decision.images': field('Record<string, DecisionAsset>', 'Pictures sent with every decision, beside the state. A question names one by its reference, such as <ghs02>. A PNG or JPEG.'),
+    'decision.images': field('Record<string, DecisionAsset>', "Pictures a decision can send. Write one's reference, such as <ghs02>, in the state or a question, and the model reads the picture there; a picture nothing references is not sent. A PNG or JPEG."),
     'decision.images.name': field('string', 'The reference a question writes, without its angle brackets: ghs02 is written <ghs02>. Lowercase letters, digits and _.'),
     'registerTool.name': field('string', "The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model calls a custom tool by."),
     'registerTool.description': field('string', 'Tells the model what the tool does (custom tools only).'),

package/esm/src/kernel/types.d.ts

@@ -458,8 +458,10 @@ export interface DecisionRequest {
     state: Exclude<DecisionJson, null>;
     questions: Record<string, DecisionQuestion>;
     /**
-     * Images by reference. Write a reference as a string where its image belongs, in `state`, in a
-     * question's instructions, or in its criteria; the provider puts the image there.
+     * Images by reference. Write a reference in a string where its image belongs, in `state`, in a
+     * question's instructions, or in its criteria, as the whole string or inside it; the model reads
+     * the image in its place, once for each use. Keys are never read. Only the images some string
+     * references are sent, so pick references that cannot occur in your text by accident.
      */
     assets?: Record<string, DecisionAsset>;
     signal?: AbortSignal;

package/esm/src/observability/spans.js

@@ -47,15 +47,14 @@ function mergeSpans(spans) {
     return out;
 }
 function applySpans(text, spans) {
-    let out = text;
-    const merged = mergeSpans(spans);
-    for (let i = merged.length - 1; i >= 0; i -= 1) {
-        const span = merged[i];
-        if (span) {
-            out = out.slice(0, span.start) + tokenFor(span.kind) + out.slice(span.end);
-        }
+    const pieces = [];
+    let at = 0;
+    for (const span of mergeSpans(spans)) {
+        pieces.push(text.slice(at, span.start), tokenFor(span.kind));
+        at = span.end;
     }
-    return out;
+    pieces.push(text.slice(at));
+    return pieces.join('');
 }
 function spansFromPatterns(text, patterns, kind) {
     const spans = [];

package/esm/src/providers/embedding-limits.js

@@ -1,7 +1,7 @@
-import { geminiEmbedding } from './gemini/embedding-protocol.js';
-import { ollamaEmbedding } from './local/embedding-protocol.js';
-import { openRouterEmbedding } from './openrouter/embedding-protocol.js';
-const SHIPPED = [geminiEmbedding, openRouterEmbedding, ollamaEmbedding];
+import { geminiEmbeddings } from './gemini/embeddings-protocol.js';
+import { ollamaEmbeddings } from './local/embeddings-protocol.js';
+import { openRouterEmbeddings } from './openrouter/embeddings-protocol.js';
+const SHIPPED = [geminiEmbeddings, openRouterEmbeddings, ollamaEmbeddings];
 /**
  * What a binding's embedding model takes, read from its protocol: one Theorem ships, or one of
  * `protocols`. Undefined when neither has it, and the kernel then holds requests to the profile alone.

package/esm/src/providers/gemini/{embedding-protocol.d.ts → embeddings-protocol.d.ts}

@@ -1,8 +1,8 @@
 import type { Protocol } from '../../kernel/protocols/protocol.js';
-/** What a `geminiEmbedding` binding sets in `options`. */
-export interface GeminiEmbeddingOptions {
+/** What a `geminiEmbeddings` binding sets in `options`. */
+export interface GeminiEmbeddingsOptions {
     /** For `gemini-embedding-001`; Gemini Embedding 2 refuses it and reads the request's `task` from the text. */
     taskType?: 'RETRIEVAL_QUERY' | 'RETRIEVAL_DOCUMENT' | 'SEMANTIC_SIMILARITY' | 'CLASSIFICATION' | 'CLUSTERING' | 'QUESTION_ANSWERING' | 'FACT_VERIFICATION' | 'CODE_RETRIEVAL_QUERY';
     outputDimensionality?: 768 | 1536 | 3072;
 }
-export declare const geminiEmbedding: Protocol<GeminiEmbeddingOptions>;
+export declare const geminiEmbeddings: Protocol<GeminiEmbeddingsOptions>;

package/esm/src/providers/gemini/{embedding-protocol.js → embeddings-protocol.js}

@@ -76,8 +76,8 @@ function requestBody(input, parsed, shape) {
         body.outputDimensionality = parsed.outputDimensionality;
     return body;
 }
-export const geminiEmbedding = defineProtocol({
-    id: 'geminiEmbedding',
+export const geminiEmbeddings = defineProtocol({
+    id: 'geminiEmbeddings',
     name: 'Gemini Embeddings',
     description: "Google's embedding API for text and supported media.",
     endpoints: { embedding: '/models/{apiId}:embedContent' },
@@ -88,7 +88,7 @@ export const geminiEmbedding = defineProtocol({
     create(context) {
         return {
             async embed(request) {
-                const parsed = modelOptions(geminiEmbedding, context.apiId, request.options);
+                const parsed = modelOptions(geminiEmbeddings, context.apiId, request.options);
                 const taskField = TASK_FIELD_MODELS.test(context.apiId);
                 const shape = { taskField, ...(request.task ? { task: request.task } : {}) };
                 const inputs = Array.isArray(request.input) ? request.input : [request.input];

package/esm/src/providers/gemini/live-protocol.js

@@ -20,8 +20,11 @@ function socketTrouble(frame, during) {
 /** Waits for `setupComplete`; a refusal here comes before any event, so the kernel can try the other key. */
 async function setupComplete(frames, context) {
     let timer;
+    const limit = context.limits.connectTimeoutMs;
     const late = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new TheoremError('timeout', `Gemini Live setup timed out after ${context.limits.connectTimeoutMs}ms`)), context.limits.connectTimeoutMs);
+        if (limit === undefined)
+            return;
+        timer = setTimeout(() => reject(new TheoremError('timeout', `Gemini Live setup timed out after ${limit}ms`)), limit);
     });
     try {
         for (;;) {

package/esm/src/providers/gemini/provider.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { labelText } from '../../guardrails/labels.js';
 import { defineProvider, endpointUrlSchema, header, query, } from '../../kernel/protocols/provider.js';
-import { geminiEmbedding } from './embedding-protocol.js';
+import { geminiEmbeddings } from './embeddings-protocol.js';
 import { geminiInteractions } from './interactions-protocol.js';
 import { geminiLive } from './live-protocol.js';
 import { geminiPrices } from './prices.js';
@@ -31,7 +31,7 @@ export const geminiProvider = defineProvider({
         const liveOrigin = `${host.protocol === 'http:' ? 'ws:' : 'wss:'}//${host.host}`;
         return [
             { protocol: geminiInteractions, baseUrl: `${origin}/v1beta` },
-            { protocol: geminiEmbedding, baseUrl: `${origin}/v1beta` },
+            { protocol: geminiEmbeddings, baseUrl: `${origin}/v1beta` },
             // probed 2026-09-23: Live's WebSocket takes the key only in the URL's query.
             { protocol: geminiLive, baseUrl: `${liveOrigin}/ws`, authorize: query('key') },
         ];

package/esm/src/providers/local/embeddings-protocol.d.ts

@@ -0,0 +1,7 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What an `ollamaEmbeddings` binding sets in `options`. */
+export interface OllamaEmbeddingsOptions {
+    truncate?: boolean;
+    dimensions?: number;
+}
+export declare const ollamaEmbeddings: Protocol<OllamaEmbeddingsOptions>;

package/esm/src/providers/local/{embedding-protocol.js → embeddings-protocol.js}

@@ -23,8 +23,8 @@ function strings(input) {
         return item.parts[0].text;
     });
 }
-export const ollamaEmbedding = defineProtocol({
-    id: 'ollamaEmbedding',
+export const ollamaEmbeddings = defineProtocol({
+    id: 'ollamaEmbeddings',
     name: 'Ollama Embeddings',
     description: 'Ollama’s local embedding endpoint.',
     endpoints: { embedding: '/api/embed' },

package/esm/src/providers/local/provider.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
 import { openAi } from '../open-ai/protocol.js';
-import { ollamaEmbedding } from './embedding-protocol.js';
+import { ollamaEmbeddings } from './embeddings-protocol.js';
 /** A server on your machine or network that speaks OpenAI's chat API: Ollama, llama.cpp, vLLM, LM Studio. */
 export const localProvider = defineProvider({
     id: 'local',
@@ -16,7 +16,7 @@ export const localProvider = defineProvider({
     serves: (at) => [
         { protocol: openAi, baseUrl: at.baseUrl },
         {
-            protocol: ollamaEmbedding,
+            protocol: ollamaEmbeddings,
             baseUrl: at.baseUrl,
             url: ({ path }) => {
                 const base = new URL(at.baseUrl);

package/esm/src/providers/mod.d.ts

@@ -17,15 +17,15 @@ export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, head
 export type { OpenWebSocket, ProviderHostOptions } from '../kernel/protocols/runtime.js';
 export type { CredentialContext, CredentialResolver, KeyCredential, KeyVault, } from '../kernel/registry/vault.js';
 export { embeddingModelLimits } from './embedding-limits.js';
-export { geminiEmbedding } from './gemini/embedding-protocol.js';
+export { geminiEmbeddings } from './gemini/embeddings-protocol.js';
 export { geminiInteractions } from './gemini/interactions-protocol.js';
 export { geminiLive } from './gemini/live-protocol.js';
 export { geminiProvider } from './gemini/provider.js';
-export { ollamaEmbedding } from './local/embedding-protocol.js';
+export { ollamaEmbeddings } from './local/embeddings-protocol.js';
 export { localProvider } from './local/provider.js';
 export { openAi } from './open-ai/protocol.js';
 export { openRouterDecisions } from './openrouter/decisions-protocol.js';
-export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+export { openRouterEmbeddings } from './openrouter/embeddings-protocol.js';
 export { openRouterImages } from './openrouter/images-protocol.js';
 export { openRouterOpenAi } from './openrouter/protocol.js';
 export { openRouterProvider } from './openrouter/provider.js';

package/esm/src/providers/mod.js

@@ -8,15 +8,15 @@ export { jsonObjectSchema, jsonValueSchema } from '../kernel/json.js';
 export { carriesTo, defineProtocol, extendProtocol, modelOptions, } from '../kernel/protocols/protocol.js';
 export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from '../kernel/protocols/provider.js';
 export { embeddingModelLimits } from './embedding-limits.js';
-export { geminiEmbedding } from './gemini/embedding-protocol.js';
+export { geminiEmbeddings } from './gemini/embeddings-protocol.js';
 export { geminiInteractions } from './gemini/interactions-protocol.js';
 export { geminiLive } from './gemini/live-protocol.js';
 export { geminiProvider } from './gemini/provider.js';
-export { ollamaEmbedding } from './local/embedding-protocol.js';
+export { ollamaEmbeddings } from './local/embeddings-protocol.js';
 export { localProvider } from './local/provider.js';
 export { openAi } from './open-ai/protocol.js';
 export { openRouterDecisions } from './openrouter/decisions-protocol.js';
-export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+export { openRouterEmbeddings } from './openrouter/embeddings-protocol.js';
 export { openRouterImages } from './openrouter/images-protocol.js';
 export { openRouterOpenAi } from './openrouter/protocol.js';
 export { openRouterProvider } from './openrouter/provider.js';

package/esm/src/providers/openrouter/decisions-protocol.d.ts

@@ -1,4 +1,6 @@
 import { type Protocol } from '../../kernel/protocols/mod.js';
-import { type SystemOneOptions } from '../system-one/protocol.js';
-/** OpenRouter's decision API: System One's questions and answers, at OpenRouter's own endpoint. */
-export declare const openRouterDecisions: Protocol<SystemOneOptions>;
+/**
+ * OpenRouter's decision API: questions about a state, answered in one call. It takes no options:
+ * images and box questions need no opt-in, and a request with an image runs in long context.
+ */
+export declare const openRouterDecisions: Protocol<Record<string, never>>;

package/esm/src/providers/openrouter/decisions-protocol.js

@@ -1,9 +1,60 @@
-import { extendProtocol } from '../../kernel/protocols/mod.js';
-import { systemOne } from '../system-one/protocol.js';
-/** OpenRouter's decision API: System One's questions and answers, at OpenRouter's own endpoint. */
-export const openRouterDecisions = extendProtocol(systemOne, {
+import { z } from 'zod';
+import { splitReferences } from '../../kernel/engine/decision-references.js';
+import { jsonObjectSchema } from '../../kernel/json.js';
+import { defineProtocol } from '../../kernel/protocols/mod.js';
+import { decisionAnswered } from '../system-one/protocol.js';
+/**
+ * OpenRouter's decision API: questions about a state, answered in one call. It takes no options:
+ * images and box questions need no opt-in, and a request with an image runs in long context.
+ */
+export const openRouterDecisions = defineProtocol({
     id: 'openRouterDecisions',
     name: 'OpenRouter Decisions',
     description: "OpenRouter's decision API: questions about a state, answered in one call.", // labels-exempt: builder field description, read by the studio and docs
     endpoints: { decision: '/alpha/decisions' },
+    options: z.strictObject({}),
+    create(context) {
+        return {
+            decide(request) {
+                const assets = request.assets ?? {};
+                const body = jsonObjectSchema.parse({
+                    model: context.apiId,
+                    state: withImages(request.state, assets),
+                    questions: Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
+                        id,
+                        {
+                            ...question,
+                            instructions: withImages(question.instructions, assets),
+                            ...('criteria' in question && question.criteria !== undefined
+                                ? { criteria: withImages(question.criteria, assets) }
+                                : {}),
+                        },
+                    ])),
+                });
+                return decisionAnswered('openRouterDecisions', context.send(body, { stream: false }));
+            },
+        };
+    },
 });
+/**
+ * Each reference becomes its image, where the reference was, as TypeSafe reads references. A string
+ * that is one reference becomes the image part; a longer one becomes its text and images in order.
+ * why: OpenRouter ignores an `assets` map; it reads image parts in place.
+ */
+function withImages(value, assets) {
+    if (typeof value === 'string') {
+        const pieces = splitReferences(value, assets);
+        if (pieces.every((piece) => typeof piece === 'string'))
+            return value;
+        const parts = pieces.map((piece) => typeof piece === 'string' ? piece : imagePart(piece.asset));
+        return parts.length === 1 ? parts[0] : parts;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => withImages(item, assets));
+    if (value !== null && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, withImages(item, assets)]));
+    return value;
+}
+function imagePart({ mimeType, data }) {
+    return { type: 'image_url', image_url: { url: `data:${mimeType};base64,${data}` } };
+}

package/esm/src/providers/openrouter/embeddings-protocol.d.ts

@@ -0,0 +1,6 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What an `openRouterEmbeddings` binding sets in `options`. */
+export interface OpenRouterEmbeddingsOptions {
+    encodingFormat?: 'float' | 'base64';
+}
+export declare const openRouterEmbeddings: Protocol<OpenRouterEmbeddingsOptions>;

package/esm/src/providers/openrouter/{embedding-protocol.js → embeddings-protocol.js}

@@ -38,8 +38,8 @@ function embeddingValues(value) {
     }
     return Array.from(new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Float32Array.BYTES_PER_ELEMENT));
 }
-export const openRouterEmbedding = defineProtocol({
-    id: 'openRouterEmbedding',
+export const openRouterEmbeddings = defineProtocol({
+    id: 'openRouterEmbeddings',
     name: 'OpenRouter Embeddings',
     description: 'OpenRouter embedding models, including supported multimodal models.',
     endpoints: { embedding: '/embeddings' },

package/esm/src/providers/openrouter/provider.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
 import { openRouterDecisions } from './decisions-protocol.js';
-import { openRouterEmbedding } from './embedding-protocol.js';
+import { openRouterEmbeddings } from './embeddings-protocol.js';
 import { openRouterImages } from './images-protocol.js';
 import { openRouterOpenAi } from './protocol.js';
 const connection = z.strictObject({
@@ -42,7 +42,7 @@ export const openRouterProvider = defineProvider({
         const decisionUrl = at.decisionUrl ?? 'https://openrouter.ai/api/alpha/decisions';
         return [
             { protocol: openRouterOpenAi, baseUrl, headers },
-            { protocol: openRouterEmbedding, baseUrl, headers },
+            { protocol: openRouterEmbeddings, baseUrl, headers },
             { protocol: openRouterImages, baseUrl, headers },
             { protocol: openRouterDecisions, baseUrl: decisionUrl, url: () => decisionUrl, headers },
         ];

package/esm/src/providers/system-one/protocol.d.ts

@@ -1,4 +1,6 @@
+import { type JsonObject } from '../../kernel/json.js';
 import { type Protocol } from '../../kernel/protocols/mod.js';
+import type { DecisionResult } from '../../kernel/types.js';
 /** What a System One binding may set. Both are TypeSafe's opt-in "danger zone" headers. */
 export interface SystemOneOptions {
     images?: boolean;
@@ -6,3 +8,5 @@ export interface SystemOneOptions {
 }
 /** TypeSafe's decision API: questions about a state, answered in one call. */
 export declare const systemOne: Protocol<SystemOneOptions>;
+/** The first decision reply, read into the kernel's result. Shared by every decision API that answers as System One does. */
+export declare function decisionAnswered(protocol: string, rows: AsyncIterable<JsonObject>): Promise<DecisionResult>;

package/esm/src/providers/system-one/protocol.js

@@ -56,34 +56,35 @@ export const systemOne = defineProtocol({
                         ? { assets: assetsOnWire(request.assets) }
                         : {}),
                 });
-                for await (const row of context.send(body, { stream: false, headers })) {
-                    const parsed = reply.safeParse(row);
-                    if (!parsed.success)
-                        throw new TheoremError('bad_response', labelText('protocol.reply_shape', {
-                            protocol: 'systemOne',
-                            issues: z.prettifyError(parsed.error),
-                        }));
-                    const { model, answers, usage } = parsed.data;
-                    // invariant: The kernel validates every answer against its question before exposing it.
-                    return {
-                        model,
-                        answers: answers,
-                        ...(usage
-                            ? {
-                                usage: {
-                                    inputTokens: usage.input_tokens,
-                                    outputTokens: usage.output_tokens,
-                                    ...(usage.cost === undefined ? {} : { costUsd: usage.cost }),
-                                },
-                            }
-                            : {}),
-                    };
-                }
-                throw new TheoremError('bad_response', labelText('provider.decision_failed'));
+                return await decisionAnswered('systemOne', context.send(body, { stream: false, headers }));
             },
         };
     },
 });
+/** The first decision reply, read into the kernel's result. Shared by every decision API that answers as System One does. */
+export async function decisionAnswered(protocol, rows) {
+    for await (const row of rows) {
+        const parsed = reply.safeParse(row);
+        if (!parsed.success)
+            throw new TheoremError('bad_response', labelText('protocol.reply_shape', { protocol, issues: z.prettifyError(parsed.error) }));
+        const { model, answers, usage } = parsed.data;
+        // invariant: The kernel validates every answer against its question before exposing it.
+        return {
+            model,
+            answers: answers,
+            ...(usage
+                ? {
+                    usage: {
+                        inputTokens: usage.input_tokens,
+                        outputTokens: usage.output_tokens,
+                        ...(usage.cost === undefined ? {} : { costUsd: usage.cost }),
+                    },
+                }
+                : {}),
+        };
+    }
+    throw new TheoremError('bad_response', labelText('provider.decision_failed'));
+}
 const FORMATS = { 'image/png': 'png', 'image/jpeg': 'jpeg' };
 function assetsOnWire(assets) {
     return Object.fromEntries(Object.entries(assets).map(([reference, { mimeType, data }]) => [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.482.g7e608f2",
+  "version": "0.3.4-next.508.geda6db0",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",

package/esm/src/providers/local/embedding-protocol.d.ts

@@ -1,7 +0,0 @@
-import { type Protocol } from '../../kernel/protocols/mod.js';
-/** What an `ollamaEmbedding` binding sets in `options`. */
-export interface OllamaEmbeddingOptions {
-    truncate?: boolean;
-    dimensions?: number;
-}
-export declare const ollamaEmbedding: Protocol<OllamaEmbeddingOptions>;

package/esm/src/providers/openrouter/embedding-protocol.d.ts

@@ -1,6 +0,0 @@
-import { type Protocol } from '../../kernel/protocols/mod.js';
-/** What an `openRouterEmbedding` binding sets in `options`. */
-export interface OpenRouterEmbeddingOptions {
-    encodingFormat?: 'float' | 'base64';
-}
-export declare const openRouterEmbedding: Protocol<OpenRouterEmbeddingOptions>;