@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { type JsonValue } from './json.js';
+import type { TurnHistoryMessage } from './turn-events.js';
+/**
+ * A protocol's saved continuation, and what it was saved for. It is used only when the next call
+ * goes to the same protocol, provider registration, connection, model, key slot, and keyed options.
+ */
+export interface ProviderCheckpoint {
+    protocol: string;
+    provider: string;
+    /** The protocol's `continuation.version` the data was written under. */
+    version: number;
+    apiId: string;
+    /** The slot whose key the saved state belongs to. */
+    keySlot?: string;
+    /** Hash of the provider's connection and the options the protocol keys its state on. */
+    compatibilityKey: string;
+    coveredHistoryLength: number;
+    coveredHistoryHash: string;
+    data: JsonValue;
+    /** The wire's own id for each Theorem call id the saved state holds, sent back in its place. */
+    wireCallIds?: Record<string, string>;
+}
+export declare const providerCheckpointSchema: z.ZodType<ProviderCheckpoint>;
+/** Why a saved continuation was dropped and the conversation sent from the transcript. */
+export type ProviderStateRebuilt = 'provider_changed' | 'model_changed' | 'connection_changed' | 'key_changed' | 'history_changed' | 'version_changed';
+export interface ProviderWarning {
+    code: 'provider_state_rebuilt';
+    reason: ProviderStateRebuilt;
+}
+export declare const providerWarningSchema: z.ZodType<ProviderWarning>;
+export interface ProviderContinuationPolicy {
+    /**
+     * Who holds the conversation a checkpoint continues. `'host'` (unset) passes the covered
+     * history back with the checkpoint. `'provider'` passes the checkpoint alone: the provider's
+     * stored conversation is the history, and a turn that goes elsewhere needs the host's history.
+     * `'stateless'` keeps no conversation: a request that carries history or a checkpoint is refused,
+     * and completion carries no checkpoint.
+     */
+    history?: 'host' | 'stateless' | 'provider';
+}
+export declare const providerContinuationSchema: z.ZodType<ProviderContinuationPolicy>;
+export declare function historyHash(history: readonly TurnHistoryMessage[]): Promise<string>;

package/esm/src/kernel/checkpoint.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { jsonValueSchema } from './json.js';
+export const providerCheckpointSchema = z.strictObject({
+    protocol: z.string().min(1),
+    provider: z.string().min(1),
+    version: z.number().int().positive(),
+    apiId: z.string().min(1),
+    keySlot: z.string().min(1).optional(),
+    compatibilityKey: z.string(),
+    coveredHistoryLength: z.number().int().nonnegative(),
+    coveredHistoryHash: z.string(),
+    data: jsonValueSchema,
+    wireCallIds: z.record(z.string().min(1), z.string().min(1)).optional(),
+});
+export const providerWarningSchema = z.strictObject({
+    code: z.literal('provider_state_rebuilt'),
+    reason: z.enum([
+        'provider_changed',
+        'model_changed',
+        'connection_changed',
+        'key_changed',
+        'history_changed',
+        'version_changed',
+    ]),
+});
+export const providerContinuationSchema = z.strictObject({
+    history: z.enum(['host', 'stateless', 'provider']).optional(),
+});
+export async function historyHash(history) {
+    const stable = (value) => {
+        if (Array.isArray(value))
+            return value.map(stable);
+        if (value && typeof value === 'object') {
+            const ordered = {};
+            for (const key of Object.keys(value).sort())
+                ordered[key] = stable(value[key]);
+            return ordered;
+        }
+        return value;
+    };
+    const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(stable(history.map((message) => {
+        const canonicalText = (text) => message.role === 'user'
+            ? (text.match(/^<user_data>\n([\s\S]*)\n<\/user_data>$/)?.[1] ?? text)
+            : text;
+        const parts = [
+            ...(message.content === undefined
+                ? []
+                : [{ type: 'text', text: canonicalText(message.content) }]),
+            ...(message.parts ?? []).map((part) => part.type === 'text' ? { ...part, text: canonicalText(part.text) } : part),
+        ];
+        const { content: _content, parts: _parts, ...rest } = message;
+        return { ...rest, ...(parts.length ? { parts } : {}) };
+    })))));
+    let hex = '';
+    for (const byte of new Uint8Array(hash))
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}

package/esm/src/kernel/default-scope.d.ts

@@ -0,0 +1,72 @@
+import type { TraceSink } from '../observability/trace-sink.js';
+import type { RunDecisionOptions } from './engine/decision.js';
+import type { RunEmbeddingOptions } from './engine/embedding.js';
+import type { RunSessionOptions } from './engine/session/mod.js';
+import type { Protocol } from './protocols/protocol.js';
+import type { Provider, RegisteredProvider, Registration } from './protocols/provider.js';
+import type { ProviderHostOptions } from './protocols/runtime.js';
+import type { ProfileDefinition } from './registry/profiles.js';
+import { defaultKernelScope as scope } from './scope.js';
+import type { ToolCallResult, ToolStepCallResult } from './tools/run.js';
+import type { InvokeToolRequest, InvokeToolStepRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
+import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
+/** Register or replace a tool in the default scope. */
+declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
+/** Register or replace several tools in the default scope. */
+declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
+/** The default scope's tool `name`, or `undefined`. */
+declare function getTool(name: string): RegisteredTool | undefined;
+/** The default scope's tool `name`; throws when there is none. */
+declare function requireTool(name: string): RegisteredTool;
+/** True when the default scope has a tool `name`. */
+declare function hasTool(name: string): boolean;
+/** Every tool in the default scope. */
+declare function listTools(): RegisteredTool[];
+/** Remove every tool from the default scope. */
+declare function resetTools(): void;
+/** Define, validate, and register a profile in the default scope. */
+declare function registerProfile(profile: Profile | ProfileDefinition): void;
+/** Define, validate, and register several profiles in the default scope. */
+declare function registerProfiles(profiles: Array<Profile | ProfileDefinition>): void;
+/** The default scope's profile `id`; throws when there is none. */
+declare function getProfile(id: string): Profile;
+/** True when the default scope has a profile `id`. */
+declare function hasProfile(id: string): boolean;
+/** Every profile in the default scope. */
+declare function listProfiles(): Profile[];
+/** Remove every profile from the default scope. */
+declare function clearProfiles(): void;
+/** Register a structured-output schema in the default scope under `id`. */
+declare function registerStructured(id: string, spec: StructuredSpec): void;
+/** The default scope's schema `id`; throws when there is none. */
+declare function getStructured(id: string): StructuredSpec;
+/** Run one turn of a profile in the default scope, streaming its events. */
+declare function runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Open a live session for a live profile in the default scope. */
+declare function runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
+/** Compact a conversation history with the model, or `undefined` when there is nothing to compact. */
+declare function compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
+/** Run a held tool call in the default scope, streaming the events of the turn it resumes. */
+declare function invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
+declare function invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
+/** Run one tool call in the default scope to its end: how it settled, with every event it emitted. */
+declare function runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
+/** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
+declare function runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
+/** Resolve a turn request in the default scope: its profile, model, and generation settings. */
+declare function resolveTurn(req: TurnRequest): ReturnType<typeof scope.resolveTurn>;
+/** Each model of profile `id` in the default scope that cannot run a plain turn on its provider, and why. */
+/** The profile `id` projected for a client, with server-only fields removed. */
+declare function projectProfile(id: string): ProjectedProfile;
+/** Answer a decision request with the profile's model in the default scope. */
+declare function runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
+/** Create vectors for one or more inputs in the default scope. */
+declare function runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
+/** Registers a provider in the default scope, with this project's connection and key slots. */
+export declare function registerProvider<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
+export declare function getProvider(id: string): RegisteredProvider | undefined;
+export declare function listProviders(): RegisteredProvider[];
+/** Every protocol the default scope's providers serve. */
+export declare function listProtocols(): Protocol[];

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

@@ -0,0 +1,121 @@
+import { defaultKernelScope as scope } from './scope.js';
+/** Register or replace a tool in the default scope. */
+function registerTool(def) {
+    return scope.tools.register(def);
+}
+/** Register or replace several tools in the default scope. */
+function registerTools(defs) {
+    return scope.tools.registerMany(defs);
+}
+/** The default scope's tool `name`, or `undefined`. */
+function getTool(name) {
+    return scope.tools.get(name);
+}
+/** The default scope's tool `name`; throws when there is none. */
+function requireTool(name) {
+    return scope.tools.require(name);
+}
+/** True when the default scope has a tool `name`. */
+function hasTool(name) {
+    return scope.tools.has(name);
+}
+/** Every tool in the default scope. */
+function listTools() {
+    return scope.tools.list();
+}
+/** Remove every tool from the default scope. */
+function resetTools() {
+    scope.tools.reset();
+}
+/** Define, validate, and register a profile in the default scope. */
+function registerProfile(profile) {
+    scope.profiles.register(profile);
+}
+/** Define, validate, and register several profiles in the default scope. */
+function registerProfiles(profiles) {
+    scope.profiles.registerMany(profiles);
+}
+/** The default scope's profile `id`; throws when there is none. */
+function getProfile(id) {
+    return scope.profiles.get(id);
+}
+/** True when the default scope has a profile `id`. */
+function hasProfile(id) {
+    return scope.profiles.has(id);
+}
+/** Every profile in the default scope. */
+function listProfiles() {
+    return scope.profiles.list();
+}
+/** Remove every profile from the default scope. */
+function clearProfiles() {
+    scope.profiles.clear();
+}
+/** Register a structured-output schema in the default scope under `id`. */
+function registerStructured(id, spec) {
+    scope.schemas.register(id, spec);
+}
+/** The default scope's schema `id`; throws when there is none. */
+function getStructured(id) {
+    return scope.schemas.get(id);
+}
+/** Run one turn of a profile in the default scope, streaming its events. */
+function runTurn(req, options = {}, sinkOverride) {
+    return scope.runTurn(req, options, sinkOverride);
+}
+/** Open a live session for a live profile in the default scope. */
+function runSession(req, options, sinkOverride) {
+    return scope.runSession(req, options, sinkOverride);
+}
+/** Compact a conversation history with the model, or `undefined` when there is nothing to compact. */
+function compactHistory(req, options = {}, sinkOverride) {
+    return scope.compactHistory(req, options, sinkOverride);
+}
+/** Run a held tool call in the default scope, streaming the events of the turn it resumes. */
+function invokeTool(request, sinkOverride) {
+    return scope.invokeTool(request, sinkOverride);
+}
+/** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
+function invokeToolStep(request, sinkOverride) {
+    return scope.invokeToolStep(request, sinkOverride);
+}
+/** Run one tool call in the default scope to its end: how it settled, with every event it emitted. */
+function runTool(request, sinkOverride) {
+    return scope.runTool(request, sinkOverride);
+}
+/** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
+function runToolStep(request, sinkOverride) {
+    return scope.runToolStep(request, sinkOverride);
+}
+/** Resolve a turn request in the default scope: its profile, model, and generation settings. */
+function resolveTurn(req) {
+    return scope.resolveTurn(req);
+}
+/** Each model of profile `id` in the default scope that cannot run a plain turn on its provider, and why. */
+/** The profile `id` projected for a client, with server-only fields removed. */
+function projectProfile(id) {
+    return scope.projectProfile(id);
+}
+/** Answer a decision request with the profile's model in the default scope. */
+function runDecision(request, options) {
+    return scope.runDecision(request, options);
+}
+/** Create vectors for one or more inputs in the default scope. */
+function runEmbedding(request, options = {}) {
+    return scope.runEmbedding(request, options);
+}
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
+/** Registers a provider in the default scope, with this project's connection and key slots. */
+export function registerProvider(provider, registration) {
+    return scope.providers.register(provider, registration);
+}
+export function getProvider(id) {
+    return scope.providers.get(id);
+}
+export function listProviders() {
+    return scope.providers.list();
+}
+/** Every protocol the default scope's providers serve. */
+export function listProtocols() {
+    return scope.providers.protocols();
+}

package/esm/src/kernel/engine/call-trace.d.ts

@@ -0,0 +1,19 @@
+import { resolveTraceWriter } from '../../observability/policy.js';
+import { type SpanHandle, type SpanOptions } from '../../observability/trace-span.js';
+interface TracedCall {
+    /** The root span's name, such as `decide <apiId>`. */
+    name: string;
+    attributes: SpanOptions['attributes'];
+    traceparent?: string;
+    /** Host metadata kept on the record. */
+    metadata?: Record<string, unknown>;
+    /** Where the record goes and how it is cleaned: the profile's settings, or the caller's sink. */
+    writer: Parameters<typeof resolveTraceWriter>[0];
+}
+/**
+ * One request that isn't a turn, under a root span: ended OK when `run` returns, with the
+ * exception when it throws, and written either way. A failed write never changes the outcome.
+ */
+declare function tracedCall<T>({ name, attributes, traceparent, metadata, writer }: TracedCall, run: (root: SpanHandle) => Promise<T>): Promise<T>;
+export type { TracedCall };
+export { tracedCall };

package/esm/src/kernel/engine/call-trace.js

@@ -0,0 +1,29 @@
+import { resolveTraceWriter } from '../../observability/policy.js';
+import { writeSpans } from '../../observability/trace.js';
+import { startTrace } from '../../observability/trace-span.js';
+import { endThrownSpan } from './turn-trace.js';
+/**
+ * One request that isn't a turn, under a root span: ended OK when `run` returns, with the
+ * exception when it throws, and written either way. A failed write never changes the outcome.
+ */
+async function tracedCall({ name, attributes, traceparent, metadata, writer }, run) {
+    const tree = startTrace(name, {
+        kind: 'CLIENT',
+        attributes,
+        ...(traceparent ? { traceparent } : {}),
+    });
+    const { sink, policy } = resolveTraceWriter(writer);
+    try {
+        const result = await run(tree.root);
+        tree.root.end({ code: 'OK' });
+        return result;
+    }
+    catch (error) {
+        endThrownSpan(tree.root, error);
+        throw error;
+    }
+    finally {
+        await writeSpans(sink, tree.collect(), policy, metadata);
+    }
+}
+export { tracedCall };

package/esm/src/kernel/engine/compaction.d.ts

@@ -0,0 +1,71 @@
+import type { CompactionFailure, CompactionMeter, CompactionResult, CompactionSpec, Profile, TurnHistoryMessage, TurnInput, TurnTokens } from '../types.js';
+/** A history divided into the messages to compact and the messages to keep. */
+export interface CompactionSplit {
+    toCompact: TurnHistoryMessage[];
+    toRetain: TurnHistoryMessage[];
+}
+/** The count a compaction trigger sees: the tokens, the meter they were counted by and the media parts left out. */
+export interface CompactionTokens {
+    meter: CompactionMeter;
+    /** Token count compared to `compactAt * maxTokens`. */
+    tokens: number;
+    /**
+     * Media parts left out of `tokens` because no verified rule counts them for this model.
+     * Always 0 for host-supplied and provider-reported counts.
+     */
+    unknownMedia: number;
+}
+/** Effective meter; defaults to `'history'`. */
+export declare function compactionMeter(spec: CompactionSpec): CompactionMeter;
+/** Prefers host-supplied `input.historyTokens`; otherwise estimates `input.history`. */
+export declare function resolveHistoryTokens(input: TurnInput | undefined): Promise<Omit<CompactionTokens, 'meter'>>;
+/**
+ * `meter: 'input'` prefers this turn's last model call (`timing: 'after'`), else the host's
+ * `input.inputTokens` from the previous turn (`timing: 'before'`); `undefined` (do not fire) when
+ * neither is positive. It never estimates history.
+ */
+export declare function resolveCompactionTokens(args: {
+    spec: CompactionSpec;
+    input?: TurnInput;
+    /** Tokens of this turn's last model call, when one completed. */
+    prompt?: TurnTokens;
+}): Promise<CompactionTokens | undefined>;
+/** True when the tokens exceed `compactAt` times `maxTokens`. */
+export declare function compactionNeeded(tokens: number, spec: CompactionSpec): boolean;
+/** `spec.trigger`, when set, decides alone; otherwise the token threshold does. */
+export declare function shouldCompact(resolved: CompactionTokens, spec: CompactionSpec): Promise<boolean>;
+/**
+ * `previousExchanges` semantics:
+ * - `0` — compact everything, retain nothing.
+ * - `≥ 1` (integer) — retain the last N exchanges.
+ * - `(0, 1)` — retain exchanges that fit within this fraction of `maxTokens`,
+ *   walking backwards from the most recent (token estimator; unknown media is
+ *   not counted).
+ */
+export declare function splitForCompaction(history: TurnHistoryMessage[], spec: CompactionSpec): Promise<CompactionSplit>;
+/**
+ * `toCompact` as the compactor reads it: media its profile does not accept is
+ * left out, and tool calls and results become the assistant's text, so no
+ * provider needs the tools declared to read them.
+ */
+export declare function compactorHistory(toCompact: readonly TurnHistoryMessage[], compactor: Profile): {
+    history: TurnHistoryMessage[];
+    droppedMedia: number;
+};
+/** What the compactor returned: a summary, or why there is none. */
+export type CompactorRun = {
+    summary: string;
+    droppedMedia: number;
+    tokens?: TurnTokens;
+} | {
+    failure: CompactionFailure;
+    droppedMedia: number;
+    tokens?: TurnTokens;
+};
+/**
+ * The history after one compaction. A failed compactor never leaves a hollow
+ * summary: under `maxTokens` the history stays whole for the next turn to try
+ * again; over it, `toCompact` is dropped (keeping any earlier summary) so the
+ * turn still fits.
+ */
+export declare function compactionResult(split: CompactionSplit, run: CompactorRun, tokens: number, spec: CompactionSpec): CompactionResult;

package/esm/src/kernel/engine/compaction.js

@@ -0,0 +1,203 @@
+import { labelText } from '../../guardrails/labels.js';
+import { mediaChannelForMime } from '../registry/catalog.js';
+import { loadTokenEstimator } from './token-estimate.js';
+/** Effective meter; defaults to `'history'`. */
+export function compactionMeter(spec) {
+    return spec.meter ?? 'history';
+}
+// why: An exchange starts at each `user` message; system messages before the first one belong to none.
+function findExchangeBoundaries(history) {
+    const boundaries = [];
+    for (let i = 0; i < history.length; i++) {
+        if (history[i].role === 'user') {
+            boundaries.push(i);
+        }
+    }
+    return boundaries;
+}
+/** Prefers host-supplied `input.historyTokens`; otherwise estimates `input.history`. */
+export async function resolveHistoryTokens(input) {
+    if (input?.historyTokens != null) {
+        return { tokens: input.historyTokens, unknownMedia: 0 };
+    }
+    const history = input?.history ?? [];
+    if (history.length === 0)
+        return { tokens: 0, unknownMedia: 0 };
+    return await (await loadTokenEstimator()).messages(history);
+}
+/**
+ * `meter: 'input'` prefers this turn's last model call (`timing: 'after'`), else the host's
+ * `input.inputTokens` from the previous turn (`timing: 'before'`); `undefined` (do not fire) when
+ * neither is positive. It never estimates history.
+ */
+export async function resolveCompactionTokens(args) {
+    const meter = compactionMeter(args.spec);
+    if (meter === 'history') {
+        return { meter, ...(await resolveHistoryTokens(args.input)) };
+    }
+    if (args.prompt && args.prompt.input > 0) {
+        return { meter, tokens: args.prompt.input, unknownMedia: args.prompt.unknownMedia?.input ?? 0 };
+    }
+    const fromHost = args.input?.inputTokens;
+    if (fromHost == null || fromHost <= 0)
+        return undefined;
+    return { meter, tokens: fromHost, unknownMedia: 0 };
+}
+/** True when the tokens exceed `compactAt` times `maxTokens`. */
+export function compactionNeeded(tokens, spec) {
+    return tokens > spec.compactAt * spec.maxTokens;
+}
+/** `spec.trigger`, when set, decides alone; otherwise the token threshold does. */
+export async function shouldCompact(resolved, spec) {
+    if (spec.trigger) {
+        const ctx = {
+            tokens: resolved.tokens,
+            maxTokens: spec.maxTokens,
+            compactAt: spec.compactAt,
+            meter: resolved.meter,
+            unknownMedia: resolved.unknownMedia,
+        };
+        return await spec.trigger(ctx);
+    }
+    return compactionNeeded(resolved.tokens, spec);
+}
+/**
+ * `previousExchanges` semantics:
+ * - `0` — compact everything, retain nothing.
+ * - `≥ 1` (integer) — retain the last N exchanges.
+ * - `(0, 1)` — retain exchanges that fit within this fraction of `maxTokens`,
+ *   walking backwards from the most recent (token estimator; unknown media is
+ *   not counted).
+ */
+export async function splitForCompaction(history, spec) {
+    if (history.length === 0) {
+        return { toCompact: [], toRetain: [] };
+    }
+    if (spec.previousExchanges === 0) {
+        return { toCompact: [...history], toRetain: [] };
+    }
+    const boundaries = findExchangeBoundaries(history);
+    if (boundaries.length === 0) {
+        return { toCompact: [...history], toRetain: [] };
+    }
+    let cutIndex;
+    if (spec.previousExchanges >= 1) {
+        const keep = Math.min(spec.previousExchanges, boundaries.length);
+        cutIndex = boundaries[boundaries.length - keep];
+    }
+    else {
+        const budget = spec.previousExchanges * spec.maxTokens;
+        const estimator = await loadTokenEstimator();
+        let accumulated = 0;
+        cutIndex = history.length;
+        for (let i = boundaries.length - 1; i >= 0; i--) {
+            const exchangeStart = boundaries[i];
+            const exchangeEnd = i < boundaries.length - 1 ? boundaries[i + 1] : history.length;
+            const exchangeMessages = history.slice(exchangeStart, exchangeEnd);
+            const exchangeTokens = estimator.messages(exchangeMessages).tokens;
+            if (accumulated + exchangeTokens > budget) {
+                break;
+            }
+            accumulated += exchangeTokens;
+            cutIndex = exchangeStart;
+        }
+    }
+    if (cutIndex <= 0) {
+        return { toCompact: [], toRetain: [...history] };
+    }
+    return {
+        toCompact: history.slice(0, cutIndex),
+        toRetain: history.slice(cutIndex),
+    };
+}
+function isCompactionSummary(message) {
+    return message.metadata?.compactionSummary === true;
+}
+function textPart(text) {
+    return { type: 'text', text };
+}
+/**
+ * `toCompact` as the compactor reads it: media its profile does not accept is
+ * left out, and tool calls and results become the assistant's text, so no
+ * provider needs the tools declared to read them.
+ */
+export function compactorHistory(toCompact, compactor) {
+    const labels = compactor.labels;
+    const toolNames = new Map();
+    let droppedMedia = 0;
+    const readable = (parts) => (parts ?? []).filter((part) => {
+        if (part.type === 'text' || mediaChannelForMime(compactor, part.mimeType))
+            return true;
+        droppedMedia += 1;
+        return false;
+    });
+    const history = [];
+    for (const message of toCompact) {
+        for (const call of message.tool_calls ?? [])
+            toolNames.set(call.id, call.function.name);
+        const parts = readable(message.parts);
+        if (message.role === 'tool') {
+            const tool = message.name ?? (message.tool_call_id ? toolNames.get(message.tool_call_id) : undefined);
+            const result = message.content ?? '';
+            history.push({
+                role: 'assistant',
+                parts: [
+                    textPart(labelText('compaction.tool_result', { tool: tool ?? '', result }, labels)),
+                    ...parts,
+                ],
+            });
+            continue;
+        }
+        const calls = (message.tool_calls ?? []).map((call) => textPart(labelText('compaction.tool_call', { tool: call.function.name, arguments: call.function.arguments }, labels)));
+        const all = [...parts, ...calls];
+        if (!message.content && all.length === 0)
+            continue;
+        history.push({
+            role: message.role,
+            ...(message.content ? { content: message.content } : {}),
+            ...(all.length > 0 ? { parts: all } : {}),
+            ...(message.name ? { name: message.name } : {}),
+        });
+    }
+    return { history, droppedMedia };
+}
+/**
+ * The history after one compaction. A failed compactor never leaves a hollow
+ * summary: under `maxTokens` the history stays whole for the next turn to try
+ * again; over it, `toCompact` is dropped (keeping any earlier summary) so the
+ * turn still fits.
+ */
+export function compactionResult(split, run, tokens, spec) {
+    const shared = {
+        toCompact: split.toCompact,
+        droppedMedia: run.droppedMedia,
+        ...(run.tokens ? { tokens: run.tokens } : {}),
+    };
+    if ('summary' in run) {
+        const summary = {
+            role: 'assistant',
+            content: run.summary,
+            metadata: { compactionSummary: true },
+        };
+        return {
+            ...shared,
+            outcome: 'compacted',
+            summary: run.summary,
+            history: [summary, ...split.toRetain],
+        };
+    }
+    if (tokens > spec.maxTokens) {
+        return {
+            ...shared,
+            outcome: 'dropped',
+            failure: run.failure,
+            history: [...split.toCompact.filter(isCompactionSummary), ...split.toRetain],
+        };
+    }
+    return {
+        ...shared,
+        outcome: 'deferred',
+        failure: run.failure,
+        history: [...split.toCompact, ...split.toRetain],
+    };
+}

package/esm/src/kernel/engine/decision.d.ts

@@ -0,0 +1,43 @@
+import { TheoremError } from '../../guardrails/error.js';
+import type { TraceSink } from '../../observability/trace-sink.js';
+import type { ProviderHostOptions } from '../protocols/runtime.js';
+import type { KernelRegistry } from '../registry/kernel-registry.js';
+import type { DecisionProfile, DecisionRequest, DecisionResult } from '../types.js';
+/** Where the provider takes decision requests, as its preset states. */
+declare const DECISION_ERROR_KINDS: {
+    readonly invalid_request: "request";
+    readonly authentication: "auth";
+    readonly permission: "auth";
+    readonly rate_limited: "rate_limit";
+    readonly unavailable: "unavailable";
+    readonly network: "network";
+    readonly timeout: "timeout";
+    readonly cancelled: "cancelled";
+    readonly malformed_response: "bad_response";
+    readonly disclosure_blocked: "blocked";
+};
+/**
+ * A normalized native-decision failure; response bodies are deliberately omitted. What the
+ * provider path threw is its `cause`, and a failure the framework named reads as that failure.
+ */
+export declare class DecisionError extends TheoremError {
+    readonly code: keyof typeof DECISION_ERROR_KINDS;
+    readonly status?: number | undefined;
+    constructor(code: keyof typeof DECISION_ERROR_KINDS, message: string, status?: number | undefined, options?: ErrorOptions);
+}
+/** Options for running a decision: the key vault, transport utilities, and a trace sink that replaces the profile's. */
+export interface RunDecisionOptions extends ProviderHostOptions {
+    /** Replaces the profile's `observability.writeTo`; an explicit sink always records, unsampled. */
+    sink?: TraceSink;
+}
+/** Check a decision before a host spends quota or dispatches it. Does not apply model-specific policy. */
+export declare function validateDecisionRequest(request: Omit<DecisionRequest, 'state' | 'questions'> & {
+    state: unknown;
+    questions: unknown;
+}, profile: DecisionProfile): asserts request is DecisionRequest;
+/**
+ * Exactly one decision request, traced however it ends. An ambiguous POST is never retried,
+ * and a trace write failure never changes the decision's outcome.
+ */
+export declare function runDecisionInRegistry(registry: KernelRegistry, request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
+export {};