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

package/esm/src/kernel/tools/image-fetch.js

@@ -1,17 +1,9 @@
 import { fetchGuarded } from '../../guardrails/network.js';
 import { bytesToBase64 } from '../util/base64.js';
 import { toolNetworkPolicy } from './events.js';
-/** The most pictures one call hands the model. */
-export const MAX_TOOL_IMAGES = 4;
-/** The largest picture fetched; a larger one is left out, not cut. */
-const MAX_TOOL_IMAGE_BYTES = 5 * 1024 * 1024;
-/** The most one call hands the model in all, so pictures cannot crowd a request past a provider's limit. */
-const MAX_TOOL_IMAGES_TOTAL_BYTES = 10 * 1024 * 1024;
-/** How long each picture may take, so a slow host cannot hold the call. */
-const IMAGE_FETCH_TIMEOUT_MS = 15_000;
 const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
-/** The body, read up to `maxBytes`; `undefined` when it runs past. */
-async function readCappedBytes(response, maxBytes) {
+/** The body, read up to `maxBytes` when set; `undefined` when it runs past. */
+async function readCappedBytes(response, maxBytes = Number.POSITIVE_INFINITY) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
         await response.body?.cancel().catch(() => { });
@@ -41,9 +33,15 @@ async function readCappedBytes(response, maxBytes) {
     }
     return bytes;
 }
-async function fetchOne(url, ctx) {
-    const timeout = AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS);
-    const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+/** The call's signal, joined by the picture's own timeout when the tool sets one. */
+function fetchSignal(ctx, timeoutMs) {
+    if (timeoutMs === undefined)
+        return ctx.signal;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+}
+async function fetchOne(url, ctx, limits) {
+    const signal = fetchSignal(ctx, limits.timeoutMs);
     const response = await fetchGuarded(url, { method: 'GET', headers: { Accept: 'image/*' }, signal }, {
         policy: toolNetworkPolicy(ctx),
         followRedirects: true,
@@ -56,9 +54,9 @@ async function fetchOne(url, ctx) {
         await response.body?.cancel().catch(() => { });
         throw new Error(`not a png, jpeg, gif or webp image (${mimeType || 'no type'})`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
-    const bytes = await readCappedBytes(response, MAX_TOOL_IMAGE_BYTES);
+    const bytes = await readCappedBytes(response, limits.bytes);
     if (!bytes)
-        throw new Error(`larger than ${MAX_TOOL_IMAGE_BYTES} bytes`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`larger than ${limits.bytes} bytes`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     return { type: 'image', mimeType, data: bytesToBase64(bytes) };
 }
 /** `url` when it is an absolute https address; otherwise the reason it is not. */
@@ -80,7 +78,7 @@ function httpsAddress(url) {
  * 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 async function fetchToolImages(images, output, ctx) {
+export async function fetchToolImages(images, output, ctx, limits = {}) {
     const reasons = [];
     const named = [];
     try {
@@ -100,8 +98,9 @@ export async function fetchToolImages(images, output, ctx) {
             warning: unfetched([`the images hook threw: ${String(err)}`]), // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         };
     }
-    const wanted = named.slice(0, MAX_TOOL_IMAGES);
-    const settled = await Promise.allSettled(wanted.map((url) => fetchOne(url, ctx)));
+    const wanted = named.slice(0, limits.count);
+    const settled = await Promise.allSettled(wanted.map((url) => fetchOne(url, ctx, limits)));
+    const totalBytes = limits.totalBytes ?? Number.POSITIVE_INFINITY;
     const parts = [];
     const urls = [];
     let total = 0;
@@ -113,8 +112,8 @@ export async function fetchToolImages(images, output, ctx) {
             return;
         }
         const size = 'data' in result.value ? result.value.data.length : 0;
-        if (total + size > MAX_TOOL_IMAGES_TOTAL_BYTES) {
-            reasons.push(`${new URL(url).hostname}: past the ${MAX_TOOL_IMAGES_TOTAL_BYTES} byte total`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        if (total + size > totalBytes) {
+            reasons.push(`${new URL(url).hostname}: past the ${totalBytes} byte total`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             return;
         }
         total += size;

package/esm/src/kernel/tools/mcp-sessions.d.ts

@@ -2,14 +2,19 @@
  * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
  * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
  */
+import type { McpSessionLimits } from './types.js';
 export type McpSession = {
     id: string;
     protocolVersion: string;
 };
+/** The tool a session is used for, and that tool's own `session` limits. */
+export interface McpSessionUse extends McpSessionLimits {
+    tool: string;
+}
 export interface McpSessionCache {
-    get(key: string): McpSession | undefined;
+    get(key: string, use: McpSessionUse): McpSession | undefined;
     /** Parallel callers for one key share a single `open`. */
-    open(key: string, open: () => Promise<McpSession>): Promise<McpSession>;
+    open(key: string, use: McpSessionUse, open: () => Promise<McpSession>): Promise<McpSession>;
     /** Only drops the session if it's still `id`, so a late expiry can't evict a newer one. */
     drop(key: string, id: string): void;
     clear(): void;

package/esm/src/kernel/tools/mcp-sessions.js

@@ -2,38 +2,47 @@
  * Sessions for MCP servers that refuse a call without one. A session is a cache, not state: it
  * lives in memory on one tool registry, is never persisted, and losing it costs one reopen.
  */
-const MAX_SESSIONS = 256;
-const IDLE_MS = 30 * 60 * 1000;
 // why: The spec allows visible ASCII only; the cap keeps a server from bloating every later request.
 const SESSION_ID = /^[\x21-\x7E]{1,256}$/;
 export function createMcpSessionCache(now = Date.now) {
     const sessions = new Map();
     const pending = new Map();
+    /** Drops the tool's least recently used sessions past its `max`. */
+    const trim = ({ tool, max }) => {
+        if (max === undefined)
+            return;
+        let held = [...sessions.values()].filter((entry) => entry.tool === tool).length;
+        for (const [key, entry] of sessions) {
+            if (held <= max)
+                break;
+            if (entry.tool !== tool)
+                continue;
+            sessions.delete(key);
+            held--;
+        }
+    };
     return {
-        get(key) {
+        get(key, use) {
             const entry = sessions.get(key);
             if (!entry)
                 return undefined;
             sessions.delete(key);
-            if (now() - entry.usedAt > IDLE_MS)
+            if (use.idleMs !== undefined && now() - entry.usedAt > use.idleMs)
                 return undefined;
             // why: Re-inserting keeps the map in least-recently-used order for eviction.
-            sessions.set(key, { ...entry, usedAt: now() });
+            sessions.set(key, { ...entry, usedAt: now(), tool: use.tool });
+            trim(use);
             return { id: entry.id, protocolVersion: entry.protocolVersion };
         },
-        open(key, open) {
+        open(key, use, open) {
             const inFlight = pending.get(key);
             if (inFlight)
                 return inFlight;
             const opening = open()
                 .then((session) => {
                 sessions.delete(key);
-                sessions.set(key, { ...session, usedAt: now() });
-                for (const oldest of sessions.keys()) {
-                    if (sessions.size <= MAX_SESSIONS)
-                        break;
-                    sessions.delete(oldest);
-                }
+                sessions.set(key, { ...session, usedAt: now(), tool: use.tool });
+                trim(use);
                 return session;
             })
                 .finally(() => pending.delete(key));

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

@@ -63,17 +63,38 @@ function assertTimeout(name, timeoutMs) {
         return;
     throw new TheoremError('config', `Tool "${name}" timeoutMs needs a finite number of ms above 0`);
 }
+/** A count or size limit is a whole number above 0. */
+function assertWhole(name, field, value) {
+    if (value === undefined || (Number.isInteger(value) && value > 0))
+        return;
+    throw new TheoremError('config', `Tool "${name}" ${field} needs a whole number above 0`);
+}
+/** What a remote tool may set on how much it reads: its body, and the pictures it names. */
+function assertReadLimits(def) {
+    assertWhole(def.name, 'maxResponseBytes', def.maxResponseBytes);
+    const images = def.imageLimits;
+    if (!images)
+        return;
+    assertWhole(def.name, 'imageLimits.count', images.count);
+    assertWhole(def.name, 'imageLimits.bytes', images.bytes);
+    assertWhole(def.name, 'imageLimits.totalBytes', images.totalBytes);
+    assertTimeout(def.name, images.timeoutMs);
+}
 function normalizeHttp(def) {
     assertFixedEndpointOrigin(def.endpoint);
     assertAuthService(def.name, def.auth);
     assertQueryParam(def.name, def.auth, def.mapping?.queryParams);
     assertLimit(def.name, def.limit);
     assertTimeout(def.name, def.timeoutMs);
+    assertReadLimits(def);
     return { ...def, type: 'http', ...schemasFromZod(def) };
 }
 function normalizeMcp(def) {
     assertAuthService(def.name, def.auth);
     assertQueryParam(def.name, def.auth);
+    assertReadLimits(def);
+    assertWhole(def.name, 'session.idleMs', def.session?.idleMs);
+    assertWhole(def.name, 'session.max', def.session?.max);
     return { ...def, type: 'mcp', ...schemasFromZod(def) };
 }
 function normalizeFunction(def) {

package/esm/src/kernel/tools/remote.d.ts

@@ -96,8 +96,6 @@ export declare function refusedCredentialOutcome(tool: {
     name: string;
     auth?: ToolAuthConfig;
 }, refusal: CredentialRefusal | undefined, carried: boolean, ctx: ToolContext, base: ToolCallBase): Generator<TurnEvent, ToolBodyOutcome | undefined>;
-/** The most of a tool's response body the kernel reads; past it the call fails instead of exhausting the host's memory. */
-export declare const MAX_TOOL_RESPONSE_BYTES: number;
 /** Every string in `value` with the credential replaced. */
 export declare function omitSecret(value: unknown, secret: string): unknown;
 /** A failure's message and details with the credential replaced. */

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

@@ -391,12 +391,10 @@ function* thrownOutcome(err, checks) {
     return failureOutcome({ code: 'network_error', kind: 'network', message: messageOf(err) }, false);
 }
 const OMIT_CREDENTIAL = '[omitted - credential]';
-/** The most of a tool's response body the kernel reads; past it the call fails instead of exhausting the host's memory. */
-export const MAX_TOOL_RESPONSE_BYTES = 4 * 1024 * 1024;
 /** The most of an error or unparseable body quoted back in a failure message. */
 const MAX_QUOTED_BODY_CHARS = 2000;
-/** A body's text as it arrives, up to `maxBytes`; returns `false` when it runs past, with the rest left unread. */
-async function* cappedPieces(response, maxBytes) {
+/** A body's text as it arrives, up to `maxBytes` when set; returns `false` when it runs past, with the rest left unread. */
+async function* cappedPieces(response, maxBytes = Number.POSITIVE_INFINITY) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
         await response.body?.cancel().catch(() => { });
@@ -427,8 +425,8 @@ async function* cappedPieces(response, maxBytes) {
         yield rest;
     return true;
 }
-/** A body, read up to `maxBytes`; `undefined` when it runs past, with the rest left unread. */
-async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
+/** A body, read up to `maxBytes` when set; `undefined` when it runs past, with the rest left unread. */
+async function readCappedText(response, maxBytes) {
     const pieces = cappedPieces(response, maxBytes);
     let text = '';
     for (;;) {
@@ -443,8 +441,8 @@ async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
  * shows: the last `secret.length - 1` characters wait for the next piece, so one split across
  * pieces is whole when it is replaced. Drafts that ran before the body ran past its cap stay sent.
  */
-async function* readCappedTextShowing(response, shown, secret) {
-    const pieces = cappedPieces(response, MAX_TOOL_RESPONSE_BYTES);
+async function* readCappedTextShowing(response, shown, secret, maxBytes) {
+    const pieces = cappedPieces(response, maxBytes);
     const hold = secret ? secret.length - 1 : 0;
     let text = '';
     let pending = '';
@@ -471,12 +469,12 @@ async function* readCappedTextShowing(response, shown, secret) {
 function quotedBody(text) {
     return text.length > MAX_QUOTED_BODY_CHARS ? `${text.slice(0, MAX_QUOTED_BODY_CHARS)}…` : text;
 }
-/** The failure for a body past MAX_TOOL_RESPONSE_BYTES. */
-function tooLargeFailure(host) {
+/** The failure for a body past the tool's `maxResponseBytes`. */
+function tooLargeFailure(host, maxBytes) {
     return {
         code: 'response_too_large',
         kind: 'bad_response',
-        message: `Response from ${host} is larger than ${MAX_TOOL_RESPONSE_BYTES} bytes`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message: `Response from ${host} is larger than ${maxBytes} bytes`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     };
 }
 /** The text with the credential replaced. */
@@ -568,10 +566,10 @@ function isDraftable(response) {
     return type === '' || type.startsWith('text/') || /[/+]json\b/.test(type);
 }
 /** An HTTP tool's body; a successful text body shows as drafts while it arrives, any other reads whole. */
-async function* readHttpBody(response, shown, secret) {
+async function* readHttpBody(response, shown, secret, maxBytes) {
     if (!shown || !isDraftable(response))
-        return await readCappedText(response);
-    return yield* readCappedTextShowing(response, shown, secret);
+        return await readCappedText(response, maxBytes);
+    return yield* readCappedTextShowing(response, shown, secret, maxBytes);
 }
 async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret }, ctx, base, span, shown) {
     const checks = requestChecks(span);
@@ -597,9 +595,10 @@ async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret },
             resolveHost: ctx.resolveHost,
             onCheck: checks.onCheck,
         }));
-        const text = yield* readHttpBody(response, shown, secret);
-        if (text === undefined)
-            return failureOutcome(tooLargeFailure(targetUrl.hostname), false);
+        const text = yield* readHttpBody(response, shown, secret, tool.maxResponseBytes);
+        if (text === undefined) {
+            return failureOutcome(tooLargeFailure(targetUrl.hostname, tool.maxResponseBytes), false);
+        }
         if (!response.ok) {
             const refused = yield* refusedCredentialOutcome(tool, credentialRefusal(response), secret !== undefined, ctx, base);
             if (refused)
@@ -747,9 +746,10 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
         resolveHost: transport.resolveHost,
         onCheck: transport.onCheck,
     });
-    const text = await readCappedText(response);
+    const text = await readCappedText(response, transport.maxResponseBytes);
     if (text === undefined) {
-        return { kind: 'failure', failure: tooLargeFailure(new URL(transport.url).hostname) };
+        const host = new URL(transport.url).hostname;
+        return { kind: 'failure', failure: tooLargeFailure(host, transport.maxResponseBytes) };
     }
     if (!response.ok) {
         const sessionSent = SESSION_HEADER in transport.originBoundHeaders;
@@ -854,9 +854,10 @@ async function openMcpSession(transport) {
             clientInfo: { name: 'theorem', version: '1' },
         },
     }, { 'Mcp-Method': 'initialize' });
-    const text = await readCappedText(response);
+    const text = await readCappedText(response, transport.maxResponseBytes);
     if (text === undefined) {
-        throw new McpSessionFailure(tooLargeFailure(new URL(transport.url).hostname));
+        const host = new URL(transport.url).hostname;
+        throw new McpSessionFailure(tooLargeFailure(host, transport.maxResponseBytes));
     }
     if (!response.ok) {
         throw sessionFailure(`mcp_session_http_${response.status}`, `MCP server refused to open a session: HTTP ${response.status}: ${quotedBody(text)}`);
@@ -886,7 +887,7 @@ async function negotiateInSession(transport, rpcId, mcpToolName, input, sessions
     for (let attempt = 0; attempt < 2; attempt++) {
         if (!session) {
             try {
-                session = await sessions.cache.open(sessions.key, () => openMcpSession(transport));
+                session = await sessions.cache.open(sessions.key, sessions.use, () => openMcpSession(transport));
             }
             catch (err) {
                 if (err instanceof McpSessionFailure)
@@ -1090,13 +1091,16 @@ async function* sendMcpRequest(tool, url, input, { authHeaders, secret }, ctx, b
             resolveHost: ctx.resolveHost,
             signal: ctx.signal,
             onCheck: checks.onCheck,
+            ...(tool.maxResponseBytes === undefined ? {} : { maxResponseBytes: tool.maxResponseBytes }),
         };
         const key = await mcpSessionKey(url.href, transport.originBoundHeaders);
-        const cached = sessions.get(key);
+        const use = { tool: tool.name, ...tool.session };
+        const cached = sessions.get(key, use);
         const first = cached
             ? await negotiateInSession(transport, base.callId, tool.mcpToolName, input, {
                 cache: sessions,
                 key,
+                use,
                 cached,
             })
             : await negotiateMcpRpc(transport, base.callId, tool.mcpToolName, input);
@@ -1104,6 +1108,7 @@ async function* sendMcpRequest(tool, url, input, { authHeaders, secret }, ctx, b
             ? await negotiateInSession(transport, base.callId, tool.mcpToolName, input, {
                 cache: sessions,
                 key,
+                use,
             })
             : first;
         const refused = yield* refusedCredentialOutcome(tool, negotiated.refusal, secret !== undefined, ctx, base);

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

@@ -163,12 +163,25 @@ export interface ToolOutputHooks<TOut = unknown> {
 /** For a tool whose result names pictures by address; function tools return the bytes themselves as `parts`. */
 export interface ToolImageHooks<TOut = unknown> {
     /**
-     * The https addresses of pictures in `output` the model should see, at most `MAX_TOOL_IMAGES`
-     * of them. After the result passes the output guard, the kernel fetches each one through the
-     * profile's network policy, without the tool's credentials, and hands the model the image as a
-     * part; one it cannot fetch is an `images_unfetched` warning, never a failed call.
+     * The https addresses of pictures in `output` the model should see. After the result passes the
+     * output guard, the kernel fetches each one through the profile's network policy, without the
+     * tool's credentials, and hands the model the image as a part; one it cannot fetch is an
+     * `images_unfetched` warning, never a failed call.
      */
     images?: (output: TOut) => string[];
+    /** How many of those pictures the kernel fetches, how large, and how slowly. Left out, there is no limit. */
+    imageLimits?: ToolImageLimits;
+}
+/** Each limit left out is no limit. A picture past one is left out, not cut. */
+export interface ToolImageLimits {
+    /** The most pictures one call hands the model; the first ones named are kept. */
+    count?: number;
+    /** The largest picture fetched. */
+    bytes?: number;
+    /** The most one call hands the model in all. */
+    totalBytes?: number;
+    /** How long each picture may take. */
+    timeoutMs?: number;
 }
 export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
     type: 'function';
@@ -226,6 +239,8 @@ export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, To
     };
     /** The service's own limit for one key; the kernel keeps this tool's requests within it. */
     limit?: HttpToolLimit;
+    /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
+    maxResponseBytes?: number;
     /**
      * How long the service may take to answer, its body read included. Past it the call
      * fails `timeout` and frees its place in the limit. Left out, a call waits as long as
@@ -246,6 +261,17 @@ export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, Too
     mcpToolName: string;
     headers?: Record<string, string>;
     auth?: ToolAuthConfig;
+    /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
+    maxResponseBytes?: number;
+    /** How long and how many of this tool's server sessions the kernel keeps. Left out, there is no limit. */
+    session?: McpSessionLimits;
+}
+/** The sessions an MCP tool keeps: each field left out is no limit. */
+export interface McpSessionLimits {
+    /** How long a session may sit unused before the next call opens a new one, in milliseconds. */
+    idleMs?: number;
+    /** The most sessions the tool keeps open; past it the least recently used is dropped. */
+    max?: number;
 }
 /**
  * What an agent tool call carries: the text, and whatever else the called

package/esm/src/kernel/turn-events.d.ts

@@ -520,6 +520,8 @@ export interface CompactionFailure {
     stop?: TurnStopKind;
     /** The error it reported, when it reported one. */
     error?: ErrorKind;
+    /** Why it failed, for the builder only: `forClient` strips it for a visitor. */
+    errorInternal?: string;
     /** It completed without a summary. */
     empty?: true;
     /** Nothing in `toCompact` was left for it to read, so it did not run. */

package/esm/src/kernel/turn-events.js

@@ -333,6 +333,7 @@ true;
 const compactionFailure = z.object({
     stop: z.enum(TURN_STOP_KINDS).optional(),
     error: errorKindSchema.optional(),
+    errorInternal: z.string().optional(),
     empty: z.literal(true).optional(),
     unreadable: z.literal(true).optional(),
 });

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/observability/trace-catalog.js

@@ -718,6 +718,7 @@ const TRACE_EVENTS = {
             dropped_media: attr('messages', 'Media left out', 'number', 'Media the compactor does not take, left out of what it read.'),
             failure_stop: attr('agent', 'Compactor stop', 'text', 'How the failed compactor stopped.', STOP_KINDS),
             failure_error: attr('agent', 'Compactor error', 'text', 'The error the compactor failed with.', ERROR_KIND_OPTIONS),
+            failure_reason: attr('agent', 'Compactor reason', 'content', 'Why the compactor failed, in its own words.'),
             failure_empty: attr('agent', 'Empty summary', 'boolean', 'The compactor replied with nothing.'),
             failure_unreadable: attr('agent', 'Nothing to read', 'boolean', 'Everything to compact was media the compactor does not take, so it did not run.'),
             summary: attr('messages', 'Summary', 'content', 'The summary that replaced them.'),

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