theorum 0.1.6 → 0.1.9

package/docs/AGENT_PROFILE_CONTRACT.md

@@ -181,6 +181,7 @@ export interface Profile {
 
 ### Per-turn Interactions state
 - `TurnRequest.input`: Optional turn input object. If omitted, Theorum normalizes it to an empty input and still runs the profile/provider turn.
+- `TurnRequest.signal`: Optional `AbortSignal`. When aborted, THEORUM stops the turn and cancels in-flight provider HTTP (Gemini fetch, OpenRouter `abortSignal`, speech fetch). Traces mark `cancelled: true`.
 - `TurnRequest.previousInteractionId`: Optional Google Interactions server-side conversation pointer. Theorum passes it through as `previous_interaction_id` for profiles using `geminiInteractions`.
 - `TurnRequest.store`: Optional Google Interactions storage override. If omitted, Theorum does not send `store`; provider/project policy remains the authority. If supplied, Theorum serializes the explicit boolean.
 

package/esm/mod.d.ts

@@ -37,7 +37,7 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { describeError, publicError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export { describeError, isAbortError, publicError, TheorumError, throwIfAborted, toErrorEvent, } from './src/guardrails/error.js';
 export type { QuotaSlotStatus } from './src/guardrails/quota.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';

package/esm/mod.js

@@ -37,7 +37,7 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { describeError, publicError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+export { describeError, isAbortError, publicError, TheorumError, throwIfAborted, toErrorEvent, } from './src/guardrails/error.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
 export { runTurn } from './src/kernel/engine/runner.js';

package/esm/src/guardrails/error.d.ts

@@ -28,6 +28,12 @@ declare const PUBLIC_FILE_SIZE = "That file is too large.";
 declare const PUBLIC_FILE_COUNT = "Too many files for one message.";
 /** Safe copy for unsupported generated image dimensions. */
 declare const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+/** Safe copy when the host aborts a turn. */
+declare const PUBLIC_CANCELLED = "Cancelled.";
+/** True when `err` is an abort (DOMException or Error named AbortError). */
+declare function isAbortError(err: unknown): boolean;
+/** Throw if `signal` is already aborted. */
+declare function throwIfAborted(signal?: AbortSignal): void;
 /** Convert an unknown thrown value or internal message to user-safe text. */
 declare function publicError(err: unknown): string;
 /** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
@@ -42,4 +48,4 @@ declare function toErrorEvent(err: unknown): {
     error: string;
     errorInternal: string;
 };
-export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };
+export { describeError, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, toErrorEvent, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -31,10 +31,33 @@ const PUBLIC_FILE_SIZE = 'That file is too large.';
 const PUBLIC_FILE_COUNT = 'Too many files for one message.';
 /** Safe copy for unsupported generated image dimensions. */
 const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+/** Safe copy when the host aborts a turn. */
+const PUBLIC_CANCELLED = 'Cancelled.';
+/** True when `err` is an abort (DOMException or Error named AbortError). */
+function isAbortError(err) {
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    const name = err.name;
+    return name === 'AbortError';
+}
+/** Throw if `signal` is already aborted. */
+function throwIfAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    const { reason } = signal;
+    if (isAbortError(reason)) {
+        throw reason;
+    }
+    throw new DOMException('The operation was aborted.', 'AbortError');
+}
 const EXACT = {
     [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
     'empty Gemini stream': PUBLIC_UNAVAILABLE,
     'canary leaked': PUBLIC_CANARY,
+    'The operation was aborted.': PUBLIC_CANCELLED,
+    'This operation was aborted': PUBLIC_CANCELLED,
     'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
     'expected JSON object': 'Something was wrong with that request.',
     'user input cannot be placed in the system block': PUBLIC_GENERIC,
@@ -98,8 +121,12 @@ const ALREADY_PUBLIC = new Set([
     PUBLIC_FILE_SIZE,
     PUBLIC_FILE_COUNT,
     PUBLIC_IMAGE_SIZE,
+    PUBLIC_CANCELLED,
 ]);
 function publicText(text) {
+    if (/aborted/i.test(text)) {
+        return PUBLIC_CANCELLED;
+    }
     if (ALREADY_PUBLIC.has(text)) {
         return text;
     }
@@ -116,6 +143,9 @@ function publicText(text) {
 }
 /** Convert an unknown thrown value or internal message to user-safe text. */
 function publicError(err) {
+    if (isAbortError(err)) {
+        return PUBLIC_CANCELLED;
+    }
     if (typeof err === 'string') {
         return publicText(err);
     }
@@ -146,4 +176,4 @@ function toErrorEvent(err) {
         errorInternal: describeError(err),
     };
 }
-export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };
+export { describeError, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, toErrorEvent, UPSTREAM_FAILED, };

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

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { describeError, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export type { QuotaSlotStatus } from './quota.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';

package/esm/src/guardrails/mod.js

@@ -8,7 +8,7 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { describeError, isAbortError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_CANCELLED, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, throwIfAborted, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';

package/esm/src/kernel/engine/runner/gates.js

@@ -1,4 +1,4 @@
-import { TheorumError, toErrorEvent } from '../../../guardrails/error.js';
+import { TheorumError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { resolveTurn } from '../../registry/resolve.js';
 import { getStructured } from '../../registry/schemas.js';
@@ -191,6 +191,7 @@ async function* runAttemptsWithValidation(safe, profile, generation, system, pro
         currentReq: safe,
     };
     while (flow.currentAttempt <= maxRetries) {
+        throwIfAborted(safe.signal);
         const step = yield* executeSingleAttemptCycle({
             flow,
             state,

package/esm/src/kernel/engine/runner/mod.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { throwIfAborted } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { noopSink, writeTrace } from '../../../observability/trace.js';
 import { buildRecord } from '../../../observability/trace-record.js';
@@ -47,6 +48,7 @@ async function* runTurn(req, provider, sink = noopSink()) {
     let generation;
     try {
         const safe = sanitizeTurnRequest(req);
+        throwIfAborted(safe.signal);
         const { profile, generation: gen } = resolveTurn(safe);
         generation = gen;
         const { model: resolvedModel, geminiBucket, canary: turnCanary } = gen;

package/esm/src/kernel/engine/runner/steps.js

@@ -1,3 +1,4 @@
+import { throwIfAborted } from '../../../guardrails/error.js';
 import { recordStepEvent } from './state.js';
 import { yieldProviderEvents } from './stream.js';
 import { executeDynamicDeclaration, findDynamicDeclaration, formatToolFinding, isActionableDynamicDeclaration, } from './tools.js';
@@ -11,7 +12,7 @@ async function* executeAutonomousStep(args, state, buffer = {
     holdLate: false,
     holdUserVisible: false,
 }) {
-    const { profile, generation, system, provider, gemini } = args;
+    const { profile, generation, system, provider, gemini, signal } = args;
     const genForStep = { ...generation, history: state.currentHistory };
     const pendingTools = [];
     let latestStructured;
@@ -21,6 +22,7 @@ async function* executeAutonomousStep(args, state, buffer = {
         system,
         provider,
         gemini,
+        signal,
     })) {
         if (event.type === 'structured') {
             latestStructured = event.structured;
@@ -107,9 +109,10 @@ async function* executeAttempt(args) {
     const holdUserVisible = Boolean(profile.guardrails.egress?.enforce);
     const holdLate = Boolean(profile.outputs.validation) || holdUserVisible;
     while (!isStepLimitReached(stepInAttempt, generation.maxSteps)) {
+        throwIfAborted(args.safe.signal);
         stepInAttempt++;
         state.stepCount++;
-        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini }, state, { holdLate, holdUserVisible });
+        const stepResult = yield* executeAutonomousStep({ profile, generation, system, provider, gemini, signal: args.safe.signal }, state, { holdLate, holdUserVisible });
         if (stepResult.latestStructured !== undefined) {
             latestStructured = stepResult.latestStructured;
         }

package/esm/src/kernel/engine/runner/stream.d.ts

@@ -7,5 +7,6 @@ declare function yieldProviderEvents(args: {
     system: string;
     provider: ModelProvider;
     gemini: Record<string, unknown>[];
+    signal?: AbortSignal;
 }): AsyncGenerator<TurnEvent>;
 export { shouldSkipStreamEvent, systemFromProfile, yieldProviderEvents };

package/esm/src/kernel/engine/runner/stream.js

@@ -1,4 +1,4 @@
-import { publicError, toErrorEvent } from '../../../guardrails/error.js';
+import { publicError, throwIfAborted, toErrorEvent } from '../../../guardrails/error.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
 import { eventHasCanary, redactCanary } from '../boundary.js';
 import { dispatchModelTool } from './tools.js';
@@ -51,14 +51,17 @@ function* processNormalEvent(event, profile, generation) {
     }
 }
 async function* yieldProviderEvents(args) {
-    const { profile, generation, system, provider, gemini } = args;
+    const { profile, generation, system, provider, gemini, signal } = args;
     const { canary } = generation;
+    throwIfAborted(signal);
     for await (const event of provider.complete({
         ...providerCompleteRequest(generation, system),
+        signal,
         tapGemini: (row) => {
             gemini.push(row);
         },
     })) {
+        throwIfAborted(signal);
         if (canary && eventHasCanary(event, canary)) {
             yield redactCanary(event, canary);
             yield toErrorEvent('canary leaked');

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

@@ -387,6 +387,11 @@ export interface TurnRequest {
     dynamicToolLoader?: DynamicToolLoader;
     /** Host-owned metadata preserved for traces; the kernel does not interpret it. */
     metadata?: Record<string, unknown>;
+    /**
+     * Optional abort signal. When aborted, THEORUM stops the turn and cancels
+     * in-flight provider HTTP where the adapter supports it.
+     */
+    signal?: AbortSignal;
     input?: TurnInput;
     toolInvoke?: {
         name: CustomToolId;
@@ -521,6 +526,8 @@ export interface ProviderCompleteRequest extends ProviderGenerationConfig {
     geminiBucket?: GeminiBucket;
     /** Scrubbed SSE / HTTP rows for traces. */
     tapGemini?: (row: Record<string, unknown>) => void;
+    /** Host abort signal — adapters should pass this into fetch / SDK calls. */
+    signal?: AbortSignal;
 }
 /** Minimal adapter contract every model provider must implement. */
 export interface ModelProvider {

package/esm/src/observability/trace-record.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { publicError } from '../guardrails/error.js';
+import { isAbortError, publicError } from '../guardrails/error.js';
 import { sanitizeText, sanitizeTurnRequest } from '../guardrails/sanitize.js';
 import { OMIT_CANARY } from '../kernel/engine/boundary.js';
 import { sha256 } from '../kernel/engine/hash.js';
@@ -109,14 +109,15 @@ async function buildRecord(args) {
     const lastErr = [...snapped].reverse().find((row) => row.type === 'error');
     const done = completedInteraction(gemini);
     const status = done?.status;
-    const ok = !(thrown || lastErr) && status !== 'cancelled';
+    const aborted = isAbortError(thrown);
+    const ok = !(thrown || lastErr) && status !== 'cancelled' && !aborted;
     const record = {
         v: TRACE_VERSION,
         id: crypto.randomUUID(),
         ts: started,
         ms: Date.now() - started,
         streamed: true,
-        cancelled: status === 'cancelled',
+        cancelled: status === 'cancelled' || aborted,
         previousInteractionId: safe.previousInteractionId ?? null,
         store: safe.store ?? null,
         profile: safe.profile,

package/esm/src/providers/create-provider.d.ts

@@ -22,8 +22,15 @@ export interface CreateProviderOptions {
         voice?: string;
     };
 }
+declare function isSpeechRole(profile: Profile): boolean;
 /**
  * Create a `ModelProvider` for a profile.
  * One call: protocol/provider (and speech role) pick the transport.
  */
 export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    isSpeechRole: typeof isSpeechRole;
+    createProvider: typeof createProvider;
+};
+export {};

package/esm/src/providers/create-provider.js

@@ -36,3 +36,5 @@ export function createProvider(profile, options = {}) {
     }
     throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
 }
+/** @internal Exported for direct unit testing only. */
+export const _internals = { isSpeechRole, createProvider };

package/esm/src/providers/gemini-tape.d.ts

@@ -1,2 +1,16 @@
+declare function isImageBlob(rec: Record<string, unknown>): boolean;
+declare function scrubEntry(rec: Record<string, unknown>, key: string, nested: unknown): Promise<[string, unknown]>;
+declare function scrubRecord(rec: Record<string, unknown>): Promise<Record<string, unknown>>;
+declare function scrubGemini(value: unknown): Promise<unknown>;
+declare function redactCanaryInTree(value: unknown, canary: string): unknown;
 declare function tapeGemini(value: unknown, canary: string): Promise<unknown>;
 export { tapeGemini };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    isImageBlob: typeof isImageBlob;
+    scrubEntry: typeof scrubEntry;
+    scrubRecord: typeof scrubRecord;
+    scrubGemini: typeof scrubGemini;
+    redactCanaryInTree: typeof redactCanaryInTree;
+    tapeGemini: typeof tapeGemini;
+};

package/esm/src/providers/gemini-tape.js

@@ -44,3 +44,12 @@ async function tapeGemini(value, canary) {
     return redactCanaryInTree(await scrubGemini(value), canary);
 }
 export { tapeGemini };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    isImageBlob,
+    scrubEntry,
+    scrubRecord,
+    scrubGemini,
+    redactCanaryInTree,
+    tapeGemini,
+};

package/esm/src/providers/google-tap.d.ts

@@ -1,3 +1,13 @@
 import type { ProviderCompleteRequest } from '../kernel/types.js';
+declare function tapeHeaderValue(key: string, value: string): string;
+declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
+declare function throwRow(err: unknown): Record<string, unknown>;
 declare function tapFetch(tap: ProviderCompleteRequest['tapGemini'], send?: typeof fetch): typeof fetch;
 export { tapFetch };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    tapeHeaderValue: typeof tapeHeaderValue;
+    tapeHeaders: typeof tapeHeaders;
+    throwRow: typeof throwRow;
+    tapFetch: typeof tapFetch;
+};

package/esm/src/providers/google-tap.js

@@ -46,3 +46,5 @@ function tapFetch(tap, send = fetch) {
     };
 }
 export { tapFetch };
+/** @internal Exported for direct unit testing only. */
+export const _internals = { tapeHeaderValue, tapeHeaders, throwRow, tapFetch };

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

@@ -1,5 +1,41 @@
-import type { ProviderCompleteRequest } from '../kernel/types.js';
+import type { InteractionPart, ProviderCompleteRequest } from '../kernel/types.js';
 declare function camelToSnake(key: string): string;
+declare function toGoogleValue(value: unknown): unknown;
+declare function wirePart(part: InteractionPart): Record<string, string>;
+declare function userInputStep(parts: InteractionPart[]): {
+    type: string;
+    content: Record<string, string>[];
+};
+declare function historyStep(msg: import('../kernel/types.js').TurnHistoryMessage): {
+    type: string;
+    content: Record<string, string>[];
+};
+declare function systemHoldsUserInput(system: string, parts: InteractionPart[]): boolean;
+declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+declare function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+declare function attachSpeechConfig(req: ProviderCompleteRequest, generationConfig: Record<string, unknown>): void;
+declare function inputStepsFromRequest(req: ProviderCompleteRequest): {
+    type: string;
+    content: Record<string, string>[];
+}[];
+declare function applyOptionalRequestFields(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+declare function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
 /** Interactions REST body for one complete() call (Google snake_case keys). */
 declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
 export { camelToSnake, toInteractionsBody };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    camelToSnake: typeof camelToSnake;
+    toGoogleValue: typeof toGoogleValue;
+    wirePart: typeof wirePart;
+    userInputStep: typeof userInputStep;
+    historyStep: typeof historyStep;
+    systemHoldsUserInput: typeof systemHoldsUserInput;
+    jsonResponseFormat: typeof jsonResponseFormat;
+    attachResponseFormat: typeof attachResponseFormat;
+    attachSpeechConfig: typeof attachSpeechConfig;
+    inputStepsFromRequest: typeof inputStepsFromRequest;
+    applyOptionalRequestFields: typeof applyOptionalRequestFields;
+    baseInteractionsBody: typeof baseInteractionsBody;
+    toInteractionsBody: typeof toInteractionsBody;
+};

package/esm/src/providers/interactions.js

@@ -151,3 +151,19 @@ function toInteractionsBody(req) {
     return toGoogleValue(camel);
 }
 export { camelToSnake, toInteractionsBody };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    camelToSnake,
+    toGoogleValue,
+    wirePart,
+    userInputStep,
+    historyStep,
+    systemHoldsUserInput,
+    jsonResponseFormat,
+    attachResponseFormat,
+    attachSpeechConfig,
+    inputStepsFromRequest,
+    applyOptionalRequestFields,
+    baseInteractionsBody,
+    toInteractionsBody,
+};

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

@@ -13,7 +13,26 @@ interface GeminiTransport {
     wait?: (ms: number) => Promise<void>;
     fetch?: typeof fetch;
 }
+declare function waitDefault(ms: number): Promise<void>;
+declare function isQuota(err: unknown): boolean;
+declare function isTransientHttp(status: number): boolean;
+declare function isTransientThrown(err: unknown): boolean;
+declare function requireKey(vault: GeminiVault, bucket: GeminiBucket): string;
+declare function backoffMs(attempt: number): number;
+declare function canOverflow(bucket: GeminiBucket, vault: GeminiVault, primary: string): string | undefined;
 declare function withGeminiKey<T>(bucket: GeminiBucket, run: (apiKey: string) => Promise<T>, transport: GeminiTransport): Promise<T>;
+declare function withApiKey(init: RequestInit, apiKey: string): RequestInit;
 declare function fetchGemini(url: string, init: RequestInit, bucket: GeminiBucket, transport: GeminiTransport): Promise<Response>;
 export type { GeminiTransport, GeminiVault };
 export { fetchGemini, withGeminiKey };
+/** @internal Exported for direct unit testing only. */
+export declare const _internals: {
+    waitDefault: typeof waitDefault;
+    isQuota: typeof isQuota;
+    isTransientHttp: typeof isTransientHttp;
+    isTransientThrown: typeof isTransientThrown;
+    requireKey: typeof requireKey;
+    backoffMs: typeof backoffMs;
+    canOverflow: typeof canOverflow;
+    withApiKey: typeof withApiKey;
+};

package/esm/src/providers/keys.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
+import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -39,6 +39,9 @@ function isTransientHttp(status) {
         status === HTTP_GATEWAY_TIMEOUT);
 }
 function isTransientThrown(err) {
+    if (isAbortError(err)) {
+        return false;
+    }
     return TRANSIENT_THROWN_RE.test(String(err));
 }
 function requireKey(vault, bucket) {
@@ -56,7 +59,9 @@ async function runWithBackoff(apiKey, run, wait, attempt) {
         return await run(apiKey);
     }
     catch (err) {
-        if (!(isQuota(err) || isTransientThrown(err)) || attempt === LAST_ATTEMPT) {
+        if (isAbortError(err) ||
+            !(isQuota(err) || isTransientThrown(err)) ||
+            attempt === LAST_ATTEMPT) {
             throw err;
         }
         await wait(backoffMs(attempt));
@@ -103,11 +108,16 @@ async function fetchWithBackoff(args) {
         if (!isTransientHttp(last.status) || args.attempt === LAST_ATTEMPT) {
             return last;
         }
+        if (args.init.signal?.aborted) {
+            throw args.init.signal.reason instanceof Error
+                ? args.init.signal.reason
+                : new DOMException('The operation was aborted.', 'AbortError');
+        }
         await wait(backoffMs(args.attempt));
         return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
     }
     catch (err) {
-        if (!isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
+        if (isAbortError(err) || !isTransientThrown(err) || args.attempt === LAST_ATTEMPT) {
             throw err;
         }
         await wait(backoffMs(args.attempt));
@@ -127,3 +137,14 @@ async function fetchGemini(url, init, bucket, transport) {
     return last;
 }
 export { fetchGemini, withGeminiKey };
+/** @internal Exported for direct unit testing only. */
+export const _internals = {
+    waitDefault,
+    isQuota,
+    isTransientHttp,
+    isTransientThrown,
+    requireKey,
+    backoffMs,
+    canOverflow,
+    withApiKey,
+};

package/esm/src/providers/openrouter-payload.d.ts

@@ -28,5 +28,12 @@ interface OpenRouterWireIds {
 declare function resolveOpenRouterModel(modelId: ModelId | string, customMap?: Record<string, string>, wire?: OpenRouterWireIds): string;
 /** Convert a provider-neutral request into an OpenRouter chat completion payload. */
 declare function toOpenRouterPayload(req: ProviderCompleteRequest, config: OpenRouterConfig): Record<string, unknown>;
-export type { OpenRouterConfig, OpenRouterWireIds };
-export { resolveOpenRouterModel, toOpenRouterPayload };
+interface ResolvedPlugins {
+    plugins: Array<{
+        id: string;
+    }>;
+    webSearch: boolean;
+}
+declare function resolveOpenRouterPlugins(builtins: readonly string[]): ResolvedPlugins;
+export type { OpenRouterConfig, OpenRouterWireIds, ResolvedPlugins };
+export { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload };

package/esm/src/providers/openrouter-payload.js

@@ -167,13 +167,29 @@ function toOpenRouterPayload(req, config) {
     if (tools.length > 0) {
         payload.tools = tools;
     }
-    const plugins = req.builtins
-        .map((id) => getTool(id)?.openRouterPlugin)
-        .filter((id) => Boolean(id))
-        .map((id) => ({ id }));
-    if (plugins.length > 0) {
-        payload.plugins = plugins;
+    const resolved = resolveOpenRouterPlugins(req.builtins);
+    if (resolved.webSearch) {
+        payload.web_search_options = {};
+    }
+    if (resolved.plugins.length > 0) {
+        payload.plugins = resolved.plugins;
     }
     return payload;
 }
-export { resolveOpenRouterModel, toOpenRouterPayload };
+function resolveOpenRouterPlugins(builtins) {
+    let webSearch = false;
+    const plugins = [];
+    for (const id of builtins) {
+        const pluginId = getTool(id)?.openRouterPlugin;
+        if (!pluginId)
+            continue;
+        if (pluginId === 'web') {
+            webSearch = true;
+        }
+        else {
+            plugins.push({ id: pluginId });
+        }
+    }
+    return { plugins, webSearch };
+}
+export { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload };