@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,72 @@
+import { defaultKernelScope as scope } from './scope.js';
+/** Register or replace a tool in the default scope. */
+function registerTool(def) {
+    return scope.tools.register(def);
+}
+function registerTools(defs) {
+    return scope.tools.registerMany(defs);
+}
+function getTool(name) {
+    return scope.tools.get(name);
+}
+function requireTool(name) {
+    return scope.tools.require(name);
+}
+function hasTool(name) {
+    return scope.tools.has(name);
+}
+function listTools() {
+    return scope.tools.list();
+}
+function resetTools() {
+    scope.tools.reset();
+}
+/** Define, validate, and register a profile in the default scope. */
+function registerProfile(profile) {
+    scope.profiles.register(profile);
+}
+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);
+}
+function hasProfile(id) {
+    return scope.profiles.has(id);
+}
+function listProfiles() {
+    return scope.profiles.list();
+}
+function clearProfiles() {
+    scope.profiles.clear();
+}
+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);
+}
+function runTurn(req, provider, sinkOverride) {
+    return scope.runTurn(req, provider, sinkOverride);
+}
+function runSession(req, options, sinkOverride) {
+    return scope.runSession(req, options, sinkOverride);
+}
+function compactHistory(req, provider, sinkOverride) {
+    return scope.compactHistory(req, provider, sinkOverride);
+}
+function invokeTool(request, sinkOverride) {
+    return scope.invokeTool(request, sinkOverride);
+}
+function resolveTurn(req) {
+    return scope.resolveTurn(req);
+}
+function projectProfile(id) {
+    return scope.projectProfile(id);
+}
+function runDecision(request, options) {
+    return scope.runDecision(request, options);
+}
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, };

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

@@ -0,0 +1,70 @@
+import type { CompactionFailure, CompactionMeter, CompactionResult, CompactionSpec, Profile, TurnHistoryMessage, TurnInput, TurnTokens } from '../types.js';
+import { type MediaTokenFamily } from './token-estimate.js';
+export interface CompactionSplit {
+    toCompact: TurnHistoryMessage[];
+    toRetain: TurnHistoryMessage[];
+}
+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, family: MediaTokenFamily | 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 loads the history tokenizer.
+ */
+export declare function resolveCompactionTokens(args: {
+    spec: CompactionSpec;
+    input?: TurnInput;
+    /** Tokens of this turn's last model call, when one completed. */
+    prompt?: TurnTokens;
+    family: MediaTokenFamily | undefined;
+}): Promise<CompactionTokens | undefined>;
+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, family: MediaTokenFamily | undefined): 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,202 @@
+import { lexiconText } from '../../guardrails/lexicon.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';
+}
+// 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, family) {
+    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, family);
+}
+/**
+ * `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 loads the history tokenizer.
+ */
+export async function resolveCompactionTokens(args) {
+    const meter = compactionMeter(args.spec);
+    if (meter === 'history') {
+        return { meter, ...(await resolveHistoryTokens(args.input, args.family)) };
+    }
+    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 };
+}
+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, family) {
+    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 = (await estimator.messages(exchangeMessages, family)).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 lexicon = compactor.lexicon;
+    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(lexiconText('compaction.tool_result', { tool: tool ?? '', result }, lexicon)),
+                    ...parts,
+                ],
+            });
+            continue;
+        }
+        const calls = (message.tool_calls ?? []).map((call) => textPart(lexiconText('compaction.tool_call', { tool: call.function.name, arguments: call.function.arguments }, lexicon)));
+        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,41 @@
+import { TheoremError } from '../../guardrails/error.js';
+import type { TraceSink } from '../../observability/trace-sink.js';
+import type { KernelRegistry } from '../registry/kernel-registry.js';
+import type { DecisionProfile, DecisionRequest, DecisionResult, KeyVault } from '../types.js';
+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. */
+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);
+}
+export interface RunDecisionOptions {
+    /** The host's keys by slot; the profile's `key` (or its model's) names the slot. */
+    vault?: KeyVault;
+    fetch?: typeof globalThis.fetch;
+    endpoint?: string;
+    /** 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 {};