theorum 0.1.11 → 0.1.13

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

@@ -79,6 +79,38 @@ function defineProfile(input) {
         guardrails: buildDefaultGuardrails(input.guardrails),
     };
 }
+function assertCompactionSpec(profileId, modelId, spec) {
+    const tag = `Profile ${profileId} model ${modelId} compaction`;
+    assertCompactionBudget(tag, spec);
+    assertCompactionRetain(tag, spec);
+    if (spec.meter != null && spec.meter !== 'history' && spec.meter !== 'input') {
+        throw new TheorumError(`${tag}: meter must be 'history' or 'input'`);
+    }
+    if (!profiles.has(spec.profile)) {
+        throw new TheorumError(`${tag}: compaction profile '${spec.profile}' must be registered before '${profileId}'`);
+    }
+}
+function assertCompactionBudget(tag, spec) {
+    if (spec.maxTokens <= 0) {
+        throw new TheorumError(`${tag}: maxTokens must be > 0`);
+    }
+    if (spec.compactAt <= 0 || spec.compactAt >= 1) {
+        throw new TheorumError(`${tag}: compactAt must be in (0, 1)`);
+    }
+}
+function assertCompactionRetain(tag, spec) {
+    if (spec.previousExchanges < 0) {
+        throw new TheorumError(`${tag}: previousExchanges must be >= 0`);
+    }
+    if (spec.previousExchanges > 0 && spec.previousExchanges < 1) {
+        if (spec.previousExchanges >= spec.compactAt) {
+            throw new TheorumError(`${tag}: previousExchanges as fraction (${spec.previousExchanges}) must be < compactAt (${spec.compactAt})`);
+        }
+    }
+    if (spec.previousExchanges >= 1 && !Number.isInteger(spec.previousExchanges)) {
+        throw new TheorumError(`${tag}: previousExchanges >= 1 must be an integer`);
+    }
+}
 /** Register one host-owned profile in the process-local registry. */
 function registerProfile(profileInput) {
     const profile = defineProfile(profileInput);
@@ -89,6 +121,11 @@ function registerProfile(profileInput) {
             throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
         }
     }
+    for (const [modelId, spec] of Object.entries(profile.model.config)) {
+        if (spec.compaction) {
+            assertCompactionSpec(profile.id, modelId, spec.compaction);
+        }
+    }
     profiles.set(profile.id, profile);
 }
 /** Register several host-owned profiles in order. */

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

@@ -0,0 +1,75 @@
+/**
+ * Normalized turn stop reasons and resume policy.
+ *
+ * Providers map Interactions `status` / OpenRouter `finish_reason` into `TurnStop`.
+ * Hosts classify client SSE drops via `turnStopFromClientStreamEnd`.
+ *
+ * @module
+ */
+/** Why a turn ended (provider-neutral). */
+export type TurnStopKind = 'completed' | 'length' | 'tool' | 'filtered' | 'provider_error' | 'cancelled' | 'stream_incomplete';
+/** Normalized stop attached to terminal `done` events and host continue requests. */
+export interface TurnStop {
+    kind: TurnStopKind;
+    /** Raw provider / native reason for diagnostics. */
+    native?: string;
+}
+/**
+ * Fixed continue instruction for resumeable stops.
+ * Hosts should not invent per-app continue prompts.
+ */
+export declare const CONTINUE_INSTRUCTION = "Continue and finish the incomplete output from the previous turn. Do not restart from scratch; preserve what was already generated and complete it.";
+/**
+ * Default kinds for one silent auto-continue (hosts wait briefly, then resume once).
+ * User `cancelled` is never included.
+ */
+export declare const DEFAULT_AUTO_CONTINUE: readonly TurnStopKind[];
+/** Pause before the one-shot auto-continue so a flaky tunnel can settle. */
+export declare const AUTO_CONTINUE_DELAY_MS = 1500;
+/** Profile resume policy under `outputs.resume`. */
+export interface ProfileResumeSpec {
+    /**
+     * Kinds eligible for a Continue / continueFrom turn.
+     * Defaults to length, stream_incomplete, provider_error.
+     */
+    allowContinue?: TurnStopKind[];
+    /**
+     * Kinds the host may auto-continue once without a CTA.
+     * Kernel does not loop; hosts call continueFrom at most once.
+     */
+    autoContinue?: TurnStopKind[];
+}
+/** Partial state passed when continuing a resumeable stop. */
+export interface TurnContinueFrom {
+    stop: TurnStop;
+    partialText?: string;
+    /** Serialized artifact / code preview from the interrupted turn. */
+    partialArtifact?: string;
+}
+/** True when this stop may be continued (profile allow list or default). */
+export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly TurnStopKind[]): boolean;
+/** True when the host aborted (user Stop). */
+export declare function isUserCancelledStop(stop: TurnStop | undefined): boolean;
+/** True when profile policy allows one silent auto-continue for this stop. */
+export declare function shouldAutoContinue(stop: TurnStop | undefined, autoContinue?: readonly TurnStopKind[] | undefined): boolean;
+/** OpenRouter normalized `finish_reason` (+ optional `native_finish_reason`). */
+export declare function turnStopFromOpenRouter(finishReason: string | null | undefined, nativeFinishReason?: string | null): TurnStop;
+/** Gemini Interactions terminal `status`. */
+export declare function turnStopFromInteractionStatus(status: string | null | undefined): TurnStop;
+/**
+ * Client SSE ended without a clean terminal event.
+ * User Stop → cancelled; otherwise stream_incomplete (tunnel drop, etc.).
+ * Returns null when `sawTerminal` so hosts keep the provider stop.
+ */
+export declare function turnStopFromClientStreamEnd(opts: {
+    abortedByUser: boolean;
+    sawTerminal: boolean;
+    hadPartial?: boolean;
+}): TurnStop | null;
+/** Error hosts throw when classifying an incomplete / non-success stop. */
+export declare class GenerationStopError extends Error {
+    readonly name = "GenerationStopError";
+    readonly stop: TurnStop;
+    constructor(stop: TurnStop, message?: string);
+}
+export declare function isGenerationStopError(err: unknown): err is GenerationStopError;

package/esm/src/kernel/stop.js

@@ -0,0 +1,120 @@
+/**
+ * Normalized turn stop reasons and resume policy.
+ *
+ * Providers map Interactions `status` / OpenRouter `finish_reason` into `TurnStop`.
+ * Hosts classify client SSE drops via `turnStopFromClientStreamEnd`.
+ *
+ * @module
+ */
+/**
+ * Fixed continue instruction for resumeable stops.
+ * Hosts should not invent per-app continue prompts.
+ */
+export const CONTINUE_INSTRUCTION = 'Continue and finish the incomplete output from the previous turn. Do not restart from scratch; preserve what was already generated and complete it.';
+/** Default kinds hosts may offer Continue for. */
+const DEFAULT_ALLOW_CONTINUE = [
+    'length',
+    'stream_incomplete',
+    'provider_error',
+];
+/**
+ * Default kinds for one silent auto-continue (hosts wait briefly, then resume once).
+ * User `cancelled` is never included.
+ */
+export const DEFAULT_AUTO_CONTINUE = ['length', 'stream_incomplete'];
+/** Pause before the one-shot auto-continue so a flaky tunnel can settle. */
+export const AUTO_CONTINUE_DELAY_MS = 1_500;
+const RESUMEABLE_DEFAULT = new Set(DEFAULT_ALLOW_CONTINUE);
+/** True when this stop may be continued (profile allow list or default). */
+export function isResumeableStop(stop, allowContinue) {
+    if (!stop)
+        return false;
+    const allow = allowContinue?.length ? new Set(allowContinue) : RESUMEABLE_DEFAULT;
+    return allow.has(stop.kind);
+}
+/** True when the host aborted (user Stop). */
+export function isUserCancelledStop(stop) {
+    return stop?.kind === 'cancelled';
+}
+/** True when profile policy allows one silent auto-continue for this stop. */
+export function shouldAutoContinue(stop, autoContinue = DEFAULT_AUTO_CONTINUE) {
+    if (!stop)
+        return false;
+    const list = autoContinue ?? DEFAULT_AUTO_CONTINUE;
+    if (list.length === 0)
+        return false;
+    return list.includes(stop.kind) && isResumeableStop(stop);
+}
+/** OpenRouter normalized `finish_reason` (+ optional `native_finish_reason`). */
+export function turnStopFromOpenRouter(finishReason, nativeFinishReason) {
+    const native = nativeFinishReason?.trim() || finishReason?.trim() || undefined;
+    const effective = (nativeFinishReason || finishReason || '').toLowerCase();
+    if (!effective)
+        return { kind: 'stream_incomplete', native };
+    if (effective === 'network_error' || effective.includes('network')) {
+        return { kind: 'provider_error', native };
+    }
+    return openRouterFinishKind((finishReason || '').toLowerCase(), effective, native);
+}
+function openRouterFinishKind(finish, effective, native) {
+    if (finish === 'stop') {
+        return /error|fail/.test(effective)
+            ? { kind: 'provider_error', native }
+            : { kind: 'completed', native };
+    }
+    if (finish === 'length')
+        return { kind: 'length', native };
+    if (finish === 'tool_calls' || finish === 'tool-calls')
+        return { kind: 'tool', native };
+    if (finish === 'content_filter' || finish === 'content-filter') {
+        return { kind: 'filtered', native };
+    }
+    return { kind: 'provider_error', native };
+}
+/** Gemini Interactions terminal `status`. */
+export function turnStopFromInteractionStatus(status) {
+    const s = (status || '').toLowerCase();
+    const native = status || undefined;
+    switch (s) {
+        case 'completed':
+            return { kind: 'completed', native };
+        case 'incomplete':
+        case 'budget_exceeded':
+            return { kind: 'length', native };
+        case 'requires_action':
+            return { kind: 'tool', native };
+        case 'cancelled':
+            return { kind: 'cancelled', native };
+        case 'failed':
+            return { kind: 'provider_error', native };
+        case 'in_progress':
+        case 'queued':
+            return { kind: 'stream_incomplete', native };
+        default:
+            return { kind: 'stream_incomplete', native };
+    }
+}
+/**
+ * Client SSE ended without a clean terminal event.
+ * User Stop → cancelled; otherwise stream_incomplete (tunnel drop, etc.).
+ * Returns null when `sawTerminal` so hosts keep the provider stop.
+ */
+export function turnStopFromClientStreamEnd(opts) {
+    if (opts.sawTerminal)
+        return null;
+    if (opts.abortedByUser)
+        return { kind: 'cancelled' };
+    return { kind: 'stream_incomplete' };
+}
+/** Error hosts throw when classifying an incomplete / non-success stop. */
+export class GenerationStopError extends Error {
+    name = 'GenerationStopError';
+    stop;
+    constructor(stop, message) {
+        super(message || `Generation stopped: ${stop.kind}`);
+        this.stop = stop;
+    }
+}
+export function isGenerationStopError(err) {
+    return err instanceof GenerationStopError;
+}

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

@@ -84,6 +84,82 @@ export interface ModelSpec {
      * (and builtin routing). Host-owned — e.g. pin image models to `paid`.
      */
     key?: GeminiBucket;
+    /** Optional compaction policy for this model's context window. */
+    compaction?: CompactionSpec;
+}
+/**
+ * What the compaction threshold meters.
+ *
+ * - `'history'` (default) — conversational history only (`TurnInput.historyTokens`
+ *   or a local estimate of `history`). Excludes system, tool schemas, and this
+ *   turn's attachments.
+ * - `'input'` — full-prompt provider input tokens (`TurnInput.inputTokens` for
+ *   `timing: 'before'`, this turn's `tokens.input` for `timing: 'after'`).
+ */
+export type CompactionMeter = 'history' | 'input';
+/**
+ * Context supplied to a custom compaction trigger.
+ *
+ * Includes the resolved token count and the spec values so the trigger can
+ * incorporate the token-based threshold as a fallback alongside other signals
+ * (e.g. available system RAM).
+ */
+export interface CompactionTriggerContext {
+    /** Resolved token count for the configured meter. */
+    tokens: number;
+    /** `CompactionSpec.maxTokens` — the token ceiling for this profile. */
+    maxTokens: number;
+    /** `CompactionSpec.compactAt` — the fraction at which the default check fires. */
+    compactAt: number;
+    /** Which meter produced `tokens`. */
+    meter: CompactionMeter;
+}
+/**
+ * Compaction policy for a model.
+ *
+ * `previousExchanges` accepts three value ranges:
+ * - `≥ 1` (integer) — keep that many recent exchanges (user message + all
+ *   messages until the next user message).
+ * - `(0, 1)` — fraction of `maxTokens`; the retained tail's estimated history
+ *   tokens must fit within this budget.
+ * - `0` — compact everything; no tail is retained.
+ */
+export interface CompactionSpec {
+    /**
+     * Token budget compared by the trigger (`compactAt * maxTokens`).
+     * Meaning depends on `meter`: history budget vs full-prompt input budget.
+     */
+    maxTokens: number;
+    /** Fraction of `maxTokens` at which compaction fires. Must be in (0, 1). */
+    compactAt: number;
+    /**
+     * How many recent exchanges to preserve verbatim.
+     * `≥ 1` = exchange count, `(0, 1)` = fraction of `maxTokens`, `0` = compact all.
+     */
+    previousExchanges: number;
+    /** Profile id of the compaction agent. Must be registered before the owning profile. */
+    profile: ProfileId;
+    /**
+     * When compaction runs relative to the primary turn.
+     * - `'before'`: kernel compacts synchronously before the turn; user pays latency on this turn.
+     * - `'after'`: kernel signals in the `done` event; host runs compaction asynchronously.
+     */
+    timing: 'before' | 'after';
+    /**
+     * Threshold meter. Defaults to `'history'`.
+     * Use `'input'` when the host prefers provider full-prompt usage (after
+     * subtracting a known baseline in `maxTokens` / `compactAt`).
+     */
+    meter?: CompactionMeter;
+    /**
+     * Optional custom trigger. When present, replaces the default token-threshold
+     * check (`tokens > compactAt * maxTokens`). The trigger receives full context
+     * so it can incorporate the token-based logic as a fallback alongside other
+     * signals such as available system RAM.
+     *
+     * Both sync and async returns are accepted.
+     */
+    trigger?: (ctx: CompactionTriggerContext) => boolean | Promise<boolean>;
 }
 /** Static metadata for harness, preset, and host-registered tools. */
 export interface ToolCatalogEntry {
@@ -176,6 +252,8 @@ export interface ProfileStreamingSpec {
     streamThoughts?: boolean;
     gateMedia?: boolean;
 }
+export type { ProfileResumeSpec, TurnContinueFrom, TurnStop, TurnStopKind, } from './stop.js';
+import type { ProfileResumeSpec, TurnContinueFrom, TurnStop } from './stop.js';
 /** Context passed to a host-owned outbound disclosure guard. */
 export interface EgressContext {
     text: string;
@@ -214,7 +292,7 @@ export interface ProfileGuardrailsSpec {
 /** Model, provider, thinking, and step bounds for a profile. */
 export interface ProfileModelSpec {
     protocol: 'geminiInteractions' | 'openAi';
-    provider: 'google' | 'openrouter';
+    provider: 'google' | 'openrouter' | 'local';
     /** Ids this profile may select. Each id must exist in `config`. */
     allow: ModelId[];
     /** Host-owned wire config keyed by the same ids used in `allow` / `select`. */
@@ -249,6 +327,8 @@ export interface ProfileOutputsSpec {
     speech?: ProfileSpeechSpec;
     validation?: ProfileValidationSpec;
     streaming?: ProfileStreamingSpec;
+    /** Resume / Continue policy for non-user stops. */
+    resume?: ProfileResumeSpec;
 }
 /** Complete host-owned agent contract consumed by the kernel. */
 export interface Profile {
@@ -359,6 +439,17 @@ export interface TurnInput {
     voice?: TurnBlob[];
     history?: TurnHistoryMessage[];
     repair?: TurnRepairRequest;
+    /**
+     * Optional host-supplied history token count for `meter: 'history'`.
+     * When set, overrides the local history estimate. Not full-prompt API tokens.
+     */
+    historyTokens?: number;
+    /**
+     * Optional host-supplied full-prompt input token count for `meter: 'input'`
+     * with `timing: 'before'` (typically the previous turn's `tokens.input`).
+     * Ignored when `meter` is `'history'`.
+     */
+    inputTokens?: number;
 }
 /** Host request after kernel ingress normalization. */
 export type NormalizedTurnRequest = TurnRequest & {
@@ -392,11 +483,18 @@ export interface TurnRequest {
      * in-flight provider HTTP where the adapter supports it.
      */
     signal?: AbortSignal;
+    /**
+     * Continue a prior resumeable stop. Kernel appends CONTINUE_INSTRUCTION to
+     * the system prompt; hosts should also pass partial artifact via input/history.
+     */
+    continueFrom?: TurnContinueFrom;
     input?: TurnInput;
     toolInvoke?: {
         name: CustomToolId;
         arguments: Record<string, unknown>;
     };
+    /** Provider for the compaction profile when `timing: 'before'`. Falls back to the turn provider. */
+    compactionProvider?: ModelProvider;
 }
 /** Safe profile projection suitable for UI or host inspection. */
 export interface ProjectedProfile {
@@ -485,6 +583,20 @@ export interface ProviderEvidenceEvent {
     annotations?: unknown[];
     sources?: GroundingSource[];
 }
+/** Compaction signal emitted in the `done` event when `timing: 'after'`. */
+export interface CompactionSignal {
+    needed: boolean;
+    /** Which meter produced `tokens`. */
+    meter: CompactionMeter;
+    /** Token count used for the compaction decision. */
+    tokens: number;
+    /**
+     * Provider-reported full-prompt input tokens from this turn, when known.
+     * Always observability; also the decision value when `meter: 'input'`.
+     */
+    promptTokens?: number;
+    history: TurnHistoryMessage[];
+}
 /** Public event yielded by providers and by `runTurn`. */
 export interface TurnEvent {
     type: TurnEventType;
@@ -508,6 +620,10 @@ export interface TurnEvent {
     error?: string;
     /** Raw diagnostic detail for traces/logs; never surface to end users. */
     errorInternal?: string;
+    /** Compaction signal for `timing: 'after'` profiles. Present only on `done` events. */
+    compaction?: CompactionSignal;
+    /** Why the turn ended. Present on terminal `done` events when known. */
+    stop?: TurnStop;
 }
 /** Provider-neutral request object sent from the kernel to a model adapter. */
 export interface ProviderCompleteRequest extends ProviderGenerationConfig {

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

@@ -4,10 +4,15 @@
  * Routes from `profile.model.protocol` / `provider` (and whether the profile is
  * a speech role). Adapters under this folder are internal implementation.
  *
+ * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
+ * `openrouter` chat provider actually runs `complete` — not when this module
+ * is imported, and not for Google or local paths.
+ *
  * @module
  */
 import type { ModelProvider, Profile } from '../kernel/types.js';
 import type { GeminiTransport } from './keys.js';
+import { type LocalProviderConfig } from './local.js';
 import type { OpenRouterConfig } from './openrouter-payload.js';
 /** Credentials supplied by the host when creating a provider. */
 export interface CreateProviderOptions {
@@ -21,6 +26,8 @@ export interface CreateProviderOptions {
     openRouter?: OpenRouterConfig & {
         voice?: string;
     };
+    /** Local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
+    local?: LocalProviderConfig;
 }
 /**
  * Create a `ModelProvider` for a profile.

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

@@ -4,16 +4,33 @@
  * Routes from `profile.model.protocol` / `provider` (and whether the profile is
  * a speech role). Adapters under this folder are internal implementation.
  *
+ * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
+ * `openrouter` chat provider actually runs `complete` — not when this module
+ * is imported, and not for Google or local paths.
+ *
  * @module
  */
 import { TheorumError } from '../guardrails/error.js';
-import { createOpenRouterProvider } from './openrouter.js';
+import { exposeForTests } from './expose-for-tests.js';
+import { createLocalProvider } from './local.js';
 import { createInteractionsProvider } from './provider.js';
 import { createSpeechProvider } from './speech.js';
-import { exposeForTests } from './expose-for-tests.js';
 function isSpeechRole(profile) {
     return profile.outputs.speech !== undefined;
 }
+/**
+ * Defer loading `@openrouter/ai-sdk-provider` / `ai` until the first `complete`.
+ * Keeps Google and local hosts free of the Vercel SDK graph.
+ */
+function lazyOpenRouterChat(config) {
+    let pending;
+    return {
+        async *complete(req) {
+            pending ??= import('./openrouter.js').then((m) => m.createOpenRouterProvider(config));
+            yield* (await pending).complete(req);
+        },
+    };
+}
 /**
  * Create a `ModelProvider` for a profile.
  * One call: protocol/provider (and speech role) pick the transport.
@@ -33,8 +50,11 @@ export function createProvider(profile, options = {}) {
         if (isSpeechRole(profile)) {
             return createSpeechProvider(options.openRouter);
         }
-        return createOpenRouterProvider(options.openRouter);
+        return lazyOpenRouterChat(options.openRouter);
+    }
+    if (protocol === 'openAi' && provider === 'local') {
+        return createLocalProvider(options.local);
     }
     throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
 }
-exposeForTests('create-provider', { isSpeechRole, createProvider });
+exposeForTests('create-provider', { isSpeechRole, createProvider, lazyOpenRouterChat });

package/esm/src/providers/expose-for-tests.js

@@ -16,6 +16,10 @@ export function exposeForTests(bucket, api) {
     if (!enabled)
         return;
     const g = dntShim.dntGlobalThis;
-    const root = (g.__theorumTestInternals ??= {});
+    let root = g.__theorumTestInternals;
+    if (!root) {
+        root = {};
+        g.__theorumTestInternals = root;
+    }
     root[bucket] = api;
 }

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

@@ -0,0 +1,29 @@
+/**
+ * Local provider adapter for OpenAI-compatible endpoints (Ollama, llama.cpp,
+ * vLLM, LM Studio, etc.).
+ *
+ * Streams SSE from `/v1/chat/completions`, accumulates tool calls, and yields
+ * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
+ *
+ * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
+ * environment variables (see docs/SECRETS.md).
+ *
+ * @module
+ */
+import type { ModelProvider } from '../kernel/types.js';
+/** Default OpenAI-compat base when the host omits `baseUrl` (Ollama's default port). */
+export declare const DEFAULT_LOCAL_BASE_URL = "http://127.0.0.1:11434";
+/** Host-supplied config for the local provider. */
+export interface LocalProviderConfig {
+    /**
+     * Base URL of the OpenAI-compat server (no trailing slash).
+     * Defaults to `http://127.0.0.1:11434`. Hosts that honor `OLLAMA_HOST` should
+     * resolve it themselves and pass the result here.
+     */
+    baseUrl?: string;
+    /** Custom fetch implementation for testing or proxying. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Create a `ModelProvider` for a local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
+declare function createLocalProvider(config?: LocalProviderConfig): ModelProvider;
+export { createLocalProvider };