@theoremjs/agents 0.3.4-next.484.g20d8b9d → 0.3.4-next.522.g9e684cd

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

@@ -29,7 +29,7 @@ export { outOfScopeFields, profileTypesForField } from './profile-scope.js';
 export type { DecisionModelBinding, ModelBinding, RuntimeAbilities } from './protocols/binding.js';
 export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './protocols/binding.js';
 export type { ProviderLimits } from './protocols/limits.js';
-export { providerLimitsSchema, resolveProviderLimits } from './protocols/limits.js';
+export { providerLimitsSchema } from './protocols/limits.js';
 export type { EstimatedCost, ModelPrice, PriceTable, Rates } from './protocols/prices.js';
 export { costFromPrices } from './protocols/prices.js';
 export type { Continuation, DecisionCall, EmbeddingCall, EmbeddingMediaKind, EmbeddingModelLimits, ExtensionBodyAt, ExtensionReader, LiveToolResult, ModelProfileType, Protocol, ProtocolContentEvent, ProtocolContext, ProtocolDefinition, ProtocolEvent, ProtocolExtension, ProtocolOperations, ProtocolRequest, ProtocolSession, ProtocolSocket, SendInit, UpstreamFailure, } from './protocols/protocol.js';

package/esm/src/kernel/mod.js

@@ -18,7 +18,7 @@ export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './
 export { unsetValue } from './profile-presence.js';
 export { outOfScopeFields, profileTypesForField } from './profile-scope.js';
 export { checkBinding, commonModelSettingsSchema, decisionModelBindingSchema, keySlotSchema, keySlotsOf, modelBindingSchema, } from './protocols/binding.js';
-export { providerLimitsSchema, resolveProviderLimits } from './protocols/limits.js';
+export { providerLimitsSchema } from './protocols/limits.js';
 export { costFromPrices } from './protocols/prices.js';
 export { carriesTo, defineProtocol, extendProtocol, modelOptions } from './protocols/protocol.js';
 export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from './protocols/provider.js';

package/esm/src/kernel/profile-presence.js

@@ -40,6 +40,18 @@ export const PROFILE_FIELD_PRESENCE = {
     },
     'models.*.allowEffortSelect': { unset: 'Off', value: false },
     'models.*.timeoutMs': { unset: 'No timeout' },
+    'models.*.limits': { unset: 'No limits' },
+    ...Object.fromEntries([
+        'operationTimeoutMs',
+        'connectTimeoutMs',
+        'liveStepTimeoutMs',
+        'maxWireRecordBytes',
+        'maxWireResponseBytes',
+        'maxEventBytes',
+        'maxStepBytes',
+        'maxStepEvents',
+        'maxPendingToolCalls',
+    ].map((field) => [`models.*.limits.${field}`, { unset: 'No limit' }])),
     'models.*.compaction': { unset: 'Off' },
     'models.*.compaction.maxTokens': { required: true },
     'models.*.compaction.compactAt': { required: true },

package/esm/src/kernel/profile-scope.js

@@ -25,10 +25,10 @@ const MODEL_PROFILE_TYPES = [
 const TURN_TYPES = ['text', 'image', 'speech', 'live'];
 /** Types whose `inputs` are turn inputs (text, files, slots) rather than decision state. */
 const TURN_INPUT_TYPES = ['text', 'image'];
-const TURN_INPUT_REASON = 'a decision takes JSON state, not turn text, files, or slots';
+const TURN_INPUT_REASON = 'a decision takes JSON state, and live takes its input through live.ingress';
 /** Types that take slots and context: the turn types, and a call. */
 const SLOT_TYPES = ['text', 'image', 'live'];
-const SLOT_REASON = 'a decision takes JSON state, and speech reads its transcript only';
+const SLOT_REASON = 'a decision takes JSON state, and an embedding call embeds its input alone';
 /** Guardrails a host profile may set keep `host`; the rest guard a model turn. */
 function turnGuardrailTypes(key) {
     return HOST_GUARDRAIL_FIELDS.includes(key)
@@ -79,11 +79,11 @@ export const PROFILE_FIELD_SCOPE = {
     },
     'identity.system': {
         profileTypes: ['text', 'image', 'live'],
-        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+        reason: 'speech has no system channel (the input text is the transcript), a decision is asked only through its questions, and an embedding call embeds its input alone',
     },
     'identity.systemByRole': {
         profileTypes: ['text', 'image', 'live'],
-        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+        reason: 'speech has no system channel (the input text is the transcript), a decision is asked only through its questions, and an embedding call embeds its input alone',
     },
     models: { profileTypes: MODEL_PROFILE_TYPES, reason: 'a host profile runs no model' },
     'models.*.protocol': {
@@ -96,7 +96,7 @@ export const PROFILE_FIELD_SCOPE = {
     },
     'models.*.compaction': {
         profileTypes: ['text', 'image', 'speech'],
-        reason: 'live compacts with live.contextCompression',
+        reason: 'live compacts with live.contextCompression, and decision and embedding calls keep no conversation to compact',
     },
     'profile.defaultModel': {
         profileTypes: [...TURN_TYPES, 'embedding'],
@@ -116,7 +116,7 @@ export const PROFILE_FIELD_SCOPE = {
     live: { profileTypes: ['live'], reason: 'only live profiles open a realtime session' },
     tools: {
         profileTypes: ['text', 'image', 'live', 'host'],
-        reason: 'speech and decision profiles call no tools',
+        reason: 'speech, decision, and embedding profiles call no tools',
     },
     'tools.t1Policy': {
         profileTypes: ['text', 'image'],
@@ -132,7 +132,7 @@ export const PROFILE_FIELD_SCOPE = {
     },
     'inputs.voice': {
         profileTypes: ['text'],
-        reason: 'no image model reads audio, and a decision takes JSON state',
+        reason: 'no image model reads audio, live takes audio through live.ingress, a decision takes JSON state, and an embedding call takes text and files',
     },
     'inputs.text': {
         profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
@@ -176,7 +176,7 @@ export const PROFILE_FIELD_SCOPE = {
     },
     outputs: {
         profileTypes: ['text', 'image', 'speech'],
-        reason: 'live output is the realtime session, and decision and host profiles produce no turn output',
+        reason: 'live output is the realtime session, and decision, embedding, and host profiles produce no turn output',
     },
     'outputs.structured': {
         profileTypes: ['text'],
@@ -205,27 +205,27 @@ export const PROFILE_FIELD_SCOPE = {
     },
     'guardrails.quota': {
         profileTypes: turnGuardrailTypes('quota'),
-        reason: 'quota counts model turns',
+        reason: 'quota counts model turns, and decision, embedding, and host profiles run none',
     },
     'guardrails.detect': {
         profileTypes: turnGuardrailTypes('detect'),
-        reason: 'the decision path runs none of the turn guardrails',
+        reason: 'decision and embedding calls run none of the turn guardrails',
     },
     'guardrails.blockedReply': {
         profileTypes: ['text', 'image', 'live'],
-        reason: 'only a reply can be blocked, and speech, decision, and host profiles write none',
+        reason: 'only a reply can be blocked, and speech, decision, embedding, and host profiles write none',
     },
     'guardrails.network': {
         profileTypes: ['text', 'image', 'live', 'host'],
-        reason: 'speech and decision profiles call no tools',
+        reason: 'speech, decision, and embedding profiles call no tools',
     },
     'guardrails.taint': {
         profileTypes: ['text', 'image', 'live'],
-        reason: 'speech and decision profiles call no tools, and a host profile runs no turn to taint',
+        reason: 'speech, decision, and embedding profiles call no tools, and a host profile runs no turn to taint',
     },
     'guardrails.disclosure': {
         profileTypes: ['decision'],
-        reason: 'disclosure gates state leaving a decision profile for its model',
+        reason: 'only a decision profile sends state to its model, and disclosure gates that state',
     },
 };
 /**

package/esm/src/kernel/protocols/binding.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { type JsonObject } from '../json.js';
 import { type KeySlot } from '../schema.js';
+import { type ProviderLimits } from './limits.js';
 import { type ModelProfileType, type Protocol } from './protocol.js';
 import type { RegisteredProvider } from './provider.js';
 /** A vault slot name. */
@@ -31,9 +32,10 @@ export interface ModelBinding extends z.infer<typeof commonModelSettingsSchema>
     keySlot?: string;
     fallbackKeySlot?: string;
     options?: JsonObject;
+    limits?: ProviderLimits;
 }
 /** A decision profile's model: no generation settings, and a time limit. */
-export interface DecisionModelBinding extends Pick<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'keySlot' | 'fallbackKeySlot' | 'options'> {
+export interface DecisionModelBinding extends Pick<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'keySlot' | 'fallbackKeySlot' | 'options' | 'limits'> {
     timeoutMs?: number;
 }
 export declare const modelBindingSchema: z.ZodType<ModelBinding>;

package/esm/src/kernel/protocols/binding.js

@@ -3,6 +3,7 @@ import { TheoremError } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { jsonObjectSchema } from '../json.js';
 import { KEY_SLOT_NAME } from '../schema.js';
+import { providerLimitsSchema } from './limits.js';
 import { modelOptions } from './protocol.js';
 /** A vault slot name. */
 export const keySlotSchema = z.string().regex(KEY_SLOT_NAME);
@@ -61,6 +62,10 @@ const modelBinding = z.strictObject({
         .optional()
         // labels-exempt: builder field description, read by the studio and docs
         .describe("What this model's protocol takes beyond the shared settings."),
+    limits: providerLimitsSchema
+        .optional()
+        // labels-exempt: builder field description, read by the studio and docs
+        .describe("Theorem's cut-offs for this model's calls; each one left out is no limit."),
 });
 true;
 export const modelBindingSchema = modelBinding;
@@ -72,6 +77,7 @@ const decisionModelBinding = modelBinding
     keySlot: true,
     fallbackKeySlot: true,
     options: true,
+    limits: true,
 })
     .extend({
     timeoutMs: z

package/esm/src/kernel/protocols/limits.d.ts

@@ -1,15 +1,14 @@
 import { z } from 'zod';
-/** The budgets every provider call runs under; a host may tighten or loosen each. */
+/** The budgets a provider call runs under. Each one left out is no limit: the provider's own applies. */
 export interface ProviderLimits {
-    operationTimeoutMs: number;
-    connectTimeoutMs: number;
-    liveStepTimeoutMs: number;
-    maxWireRecordBytes: number;
-    maxWireResponseBytes: number;
-    maxEventBytes: number;
-    maxStepBytes: number;
-    maxStepEvents: number;
-    maxPendingToolCalls: number;
+    operationTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    liveStepTimeoutMs?: number;
+    maxWireRecordBytes?: number;
+    maxWireResponseBytes?: number;
+    maxEventBytes?: number;
+    maxStepBytes?: number;
+    maxStepEvents?: number;
+    maxPendingToolCalls?: number;
 }
 export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
-export declare function resolveProviderLimits(overrides?: Partial<ProviderLimits>): ProviderLimits;

package/esm/src/kernel/protocols/limits.js

@@ -2,27 +2,13 @@ import { z } from 'zod';
 const positiveBudget = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
 const timerBudget = positiveBudget.max(2147483647);
 export const providerLimitsSchema = z.strictObject({
-    operationTimeoutMs: timerBudget,
-    connectTimeoutMs: timerBudget,
-    liveStepTimeoutMs: timerBudget,
-    maxWireRecordBytes: positiveBudget,
-    maxWireResponseBytes: positiveBudget,
-    maxEventBytes: positiveBudget,
-    maxStepBytes: positiveBudget,
-    maxStepEvents: positiveBudget,
-    maxPendingToolCalls: positiveBudget,
+    operationTimeoutMs: timerBudget.optional(),
+    connectTimeoutMs: timerBudget.optional(),
+    liveStepTimeoutMs: timerBudget.optional(),
+    maxWireRecordBytes: positiveBudget.optional(),
+    maxWireResponseBytes: positiveBudget.optional(),
+    maxEventBytes: positiveBudget.optional(),
+    maxStepBytes: positiveBudget.optional(),
+    maxStepEvents: positiveBudget.optional(),
+    maxPendingToolCalls: positiveBudget.optional(),
 });
-export function resolveProviderLimits(overrides = {}) {
-    return Object.freeze(providerLimitsSchema.parse({
-        operationTimeoutMs: 120000,
-        connectTimeoutMs: 30000,
-        liveStepTimeoutMs: 120000,
-        maxWireRecordBytes: 16 * 1024 * 1024,
-        maxWireResponseBytes: 64 * 1024 * 1024,
-        maxEventBytes: 16 * 1024 * 1024,
-        maxStepBytes: 64 * 1024 * 1024,
-        maxStepEvents: 100000,
-        maxPendingToolCalls: 32,
-        ...overrides,
-    }));
-}

package/esm/src/kernel/protocols/runtime.d.ts

@@ -3,7 +3,7 @@ import { type JsonObject } from '../json.js';
 import type { KeyVault } from '../registry/vault.js';
 import type { DecisionResult, KeySlot } from '../types.js';
 import { type DecisionModelBinding, type ModelBinding } from './binding.js';
-import { type ProviderLimits } from './limits.js';
+import type { ProviderLimits } from './limits.js';
 import type { DecisionCall, EmbeddingCall, EmbeddingResult, ModelProfileType, ProtocolOperations } from './protocol.js';
 import type { RegisteredProvider } from './provider.js';
 /** Opens a WebSocket with the headers and subprotocols a sign-in put on it. */
@@ -18,7 +18,8 @@ export type OpenWebSocket = (url: string, init: {
 export declare function plainWebSocket(provider: string): OpenWebSocket;
 /** What a host lends every provider call: its keys, its network, its clock, and its budgets. */
 export interface ProviderHostOptions {
-    limits?: Partial<ProviderLimits>;
+    /** Overrides the model's own `limits`, one field at a time. */
+    limits?: ProviderLimits;
     vault?: KeyVault;
     fetch?: typeof fetch;
     wait?: Wait;

package/esm/src/kernel/protocols/runtime.js

@@ -1,4 +1,4 @@
-import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { describeError, kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
 import { labelText } from '../../guardrails/labels.js';
 import { retryTransient, waitDefault } from '../../providers/shared/retry.js';
 import { readSseChunks } from '../../providers/shared/sse.js';
@@ -7,7 +7,6 @@ import { KEY_FALLBACK_ROW } from '../../providers/types.js';
 import { jsonValueSchema } from '../json.js';
 import { bytesToBase64 } from '../util/base64.js';
 import { bindingServe, keySlotsOf, } from './binding.js';
-import { resolveProviderLimits } from './limits.js';
 import { costFromPrices } from './prices.js';
 /**
  * The runtime's own WebSocket. It takes no headers, so a sign-in that needs them is refused; a host
@@ -249,7 +248,7 @@ function protocolContext(setup, slot, raw, wire = { sent: false }, asked = []) {
         apiId,
         options: setup.binding.options ?? {},
         builtInTools,
-        limits: setup.limits ?? resolveProviderLimits(),
+        limits: setup.limits ?? setup.binding.limits ?? {},
         ...(setup.signal ? { signal: setup.signal } : {}),
         tapUpstream: tap,
         async *send(body, init) {
@@ -375,7 +374,7 @@ function failureEvent(error) {
         type: 'error',
         errorKind: error.kind,
         // invariant: `error` is the person's wording, added from the profile's labels; the upstream text is internal.
-        errorInternal: error.message,
+        errorInternal: describeError(error),
         ...(error.copy ? { errorCopy: error.copy } : {}),
     };
 }

package/esm/src/kernel/provider-budget.d.ts

@@ -11,9 +11,9 @@ export declare class ProviderBudget {
     private stepBytes;
     private stepEvents;
     private calls;
-    private deadline;
+    private deadline?;
     private releaseSignal;
-    constructor(limits: ProviderLimits, caller?: AbortSignal, timeoutMs?: number);
+    constructor(limits: ProviderLimits, caller?: AbortSignal, timeoutMs?: number | undefined);
     resumeOperation(): void;
     /** Milliseconds before the running timer ends the call. */
     timeLeft(): number;

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';
@@ -128,11 +128,14 @@ function diagnosticError(error, clean) {
         return new DOMException(message, error.name);
     if (isAbortError(error))
         return new DOMException(message, 'AbortError');
+    const cause = error instanceof Error && error.cause !== undefined
+        ? { cause: diagnosticError(error.cause, clean) }
+        : {};
     const result = error instanceof TheoremError
-        ? new TheoremError(error.kind, message, { copy: diagnosticCopy(error.copy, clean) })
+        ? new TheoremError(error.kind, message, { copy: diagnosticCopy(error.copy, clean), ...cause })
         : error instanceof TypeError
-            ? new TypeError(message)
-            : new Error(message);
+            ? new TypeError(message, cause)
+            : new Error(message, cause);
     if (isRecord(error) && typeof error.status === 'number')
         Object.assign(result, { status: error.status });
     return result;
@@ -188,7 +191,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

@@ -1,6 +1,6 @@
 import { TOOL_BOUNDARIES } from '../../guardrails/boundaries.js';
 import { detectProblem } from '../../guardrails/detectors.js';
-import { TheoremError } from '../../guardrails/error.js';
+import { errorKind, TheoremError } from '../../guardrails/error.js';
 import { labelText, validateLabelOverrides } from '../../guardrails/labels.js';
 import { BLOCKED_REPLY_ON_BLOCK, } from '../../guardrails/types.js';
 import { resolveObservabilityPolicy } from '../../observability/resolve-policy.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)) {
@@ -332,7 +332,7 @@ function assertObservability(profileId, spec) {
             throw err;
         }
         const message = err instanceof Error ? err.message : String(err);
-        throw new TheoremError('config', `Profile ${profileId}: ${message}`);
+        throw new TheoremError(errorKind(err), `Profile ${profileId}: ${message}`, { cause: err });
     }
 }
 function assertIdentitySystem(input) {

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).'),
@@ -788,6 +798,22 @@ export const EXTRA_FIELDS = {
         ...field("'page'", 'Who answers a call to a function tool. With page, the page the agent is on returns the output, and the tool has no handler.', ['page']),
         unset: 'Its handler',
     },
+    'registerTool.maxResponseBytes': {
+        ...field('number', 'The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with response_too_large.'),
+        unset: 'No limit',
+    },
+    'registerTool.session': {
+        ...field('McpSessionLimits', "How long and how many of an MCP tool's server sessions the kernel keeps."),
+        unset: 'No limits',
+    },
+    'registerTool.session.idleMs': {
+        ...field('number', 'How long a session may sit unused before the next call opens a new one, in milliseconds.'),
+        unset: 'No limit',
+    },
+    'registerTool.session.max': {
+        ...field('number', 'The most sessions the tool keeps open; past it the least recently used is dropped.'),
+        unset: 'No limit',
+    },
     'registerTool.maxCallsPerTurn': {
         ...field('number', 'How many times one turn of the calling agent may run this tool.'),
         unset: 'As many as its steps allow',

package/esm/src/kernel/tools/execute.js

@@ -742,7 +742,9 @@ async function* settleBodyOutcome(args) {
         provisional: { outputRaw: outcome.outputRaw, modelResult: outcome.modelResult },
         sources: tool.sources,
         ...(tool.type !== 'function' && tool.images
-            ? { images: (output) => fetchToolImages(tool.images, output, ctx) }
+            ? {
+                images: (output) => fetchToolImages(tool.images, output, ctx, tool.imageLimits),
+            }
             : {}),
         labels: tool.labels,
         reproject: makeReproject((v) => parseToolOutput(tool.output, v), 

package/esm/src/kernel/tools/image-fetch.d.ts

@@ -1,14 +1,12 @@
 import type { InteractionPart, ToolWarning } from '../turn-events.js';
-import type { ToolContext } from './types.js';
-/** The most pictures one call hands the model. */
-export declare const MAX_TOOL_IMAGES = 4;
+import type { ToolContext, ToolImageLimits } from './types.js';
 /**
  * The pictures a tool's `images(output)` names, fetched through the profile's network policy (every
  * hop, redirects included, no tool credentials) and handed to the model as image parts. A picture
  * that is not an https address, blocked, slow, too big or not an image is left out and reported in
  * one `images_unfetched` warning: the call itself stays whole. `urls` are the ones fetched.
  */
-export declare function fetchToolImages(images: (output: never) => string[], output: unknown, ctx: ToolContext): Promise<{
+export declare function fetchToolImages(images: (output: never) => string[], output: unknown, ctx: ToolContext, limits?: ToolImageLimits): Promise<{
     parts: InteractionPart[];
     urls: string[];
     warning?: ToolWarning;