theorum 0.1.6 → 0.1.7

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/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));

package/esm/src/providers/openrouter.js

@@ -9,7 +9,7 @@
  */
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 import { jsonSchema, streamText, tool, } from 'ai';
-import { toErrorEvent } from '../guardrails/error.js';
+import { isAbortError, toErrorEvent } from '../guardrails/error.js';
 import { tryStructured } from '../kernel/engine/delta.js';
 import { getTool } from '../kernel/registry/catalog.js';
 import { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';
@@ -499,6 +499,7 @@ function streamTextOptions(req, context) {
         tools: buildTools(req.dynamicTools),
         providerOptions: providerOptionsFor(req),
         includeRawChunks: true,
+        abortSignal: req.signal,
         onError: () => undefined,
     };
 }
@@ -544,6 +545,9 @@ async function* streamOpenRouter(req, config) {
         yield* finalEvents(req, acc);
     }
     catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
         yield* yieldCapturedRawEventsUnchecked(context);
         yield toErrorEvent(err);
     }

package/esm/src/providers/provider.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { TheorumError, toErrorEvent } from '../guardrails/error.js';
+import { isAbortError, TheorumError, toErrorEvent } from '../guardrails/error.js';
 import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
 import { tapFetch } from './google-tap.js';
 import { toInteractionsBody } from './interactions.js';
@@ -121,7 +121,7 @@ async function* streamComplete(req, transport) {
         yield toErrorEvent('missing Gemini vault bucket for Interactions');
         return;
     }
-    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) }, req.geminiBucket, withTap(req, transport));
+    const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)), signal: req.signal }, req.geminiBucket, withTap(req, transport));
     if (res.status !== HTTP_OK) {
         const errorBody = await res.text().catch(() => '');
         yield toErrorEvent(`Gemini HTTP ${String(res.status)}: ${errorBody}`);
@@ -148,6 +148,9 @@ async function* streamGuarded(req, transport) {
         yield* streamComplete(req, transport);
     }
     catch (err) {
+        if (isAbortError(err)) {
+            throw err;
+        }
         yield toErrorEvent(err);
     }
 }

package/esm/src/providers/speech.js

@@ -68,6 +68,7 @@ async function requestSpeech(apiKey, text, req, config) {
         method: 'POST',
         headers: buildHeaders(apiKey, config),
         body: JSON.stringify(buildPayload(req, text, req.speech, config.voice)),
+        signal: req.signal,
     });
 }
 function* yieldSpeechSuccess(rawBytes, text, format) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",