@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -3,21 +3,27 @@ import { defaultKernelScope as scope } from './scope.js';
 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();
 }
@@ -25,6 +31,7 @@ function resetTools() {
 function registerProfile(profile) {
     scope.profiles.register(profile);
 }
+/** Define, validate, and register several profiles in the default scope. */
 function registerProfiles(profiles) {
     scope.profiles.registerMany(profiles);
 }
@@ -32,15 +39,19 @@ function registerProfiles(profiles) {
 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);
 }
@@ -48,25 +59,63 @@ function registerStructured(id, spec) {
 function getStructured(id) {
     return scope.schemas.get(id);
 }
-function runTurn(req, provider, sinkOverride) {
-    return scope.runTurn(req, provider, sinkOverride);
+/** 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);
 }
-function compactHistory(req, provider, sinkOverride) {
-    return scope.compactHistory(req, provider, 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);
 }
-export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, };
+/** 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

@@ -1,9 +1,10 @@
 import type { CompactionFailure, CompactionMeter, CompactionResult, CompactionSpec, Profile, TurnHistoryMessage, TurnInput, TurnTokens } from '../types.js';
-import { type MediaTokenFamily } from './token-estimate.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`. */
@@ -17,19 +18,19 @@ export interface CompactionTokens {
 /** 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'>>;
+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 loads the history tokenizer.
+ * 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;
-    family: MediaTokenFamily | undefined;
 }): 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>;
@@ -41,7 +42,7 @@ export declare function shouldCompact(resolved: CompactionTokens, spec: Compacti
  *   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>;
+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

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

@@ -1,11 +1,11 @@
-import { lexiconText } from '../../guardrails/lexicon.js';
+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';
 }
-// An exchange starts at each `user` message; system messages before the first one belong to none.
+// 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++) {
@@ -16,24 +16,24 @@ function findExchangeBoundaries(history) {
     return boundaries;
 }
 /** Prefers host-supplied `input.historyTokens`; otherwise estimates `input.history`. */
-export async function resolveHistoryTokens(input, family) {
+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, family);
+    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 loads the history tokenizer.
+ * 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, args.family)) };
+        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 };
@@ -43,6 +43,7 @@ export async function resolveCompactionTokens(args) {
         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;
 }
@@ -68,7 +69,7 @@ export async function shouldCompact(resolved, spec) {
  *   walking backwards from the most recent (token estimator; unknown media is
  *   not counted).
  */
-export async function splitForCompaction(history, spec, family) {
+export async function splitForCompaction(history, spec) {
     if (history.length === 0) {
         return { toCompact: [], toRetain: [] };
     }
@@ -93,7 +94,7 @@ export async function splitForCompaction(history, spec, family) {
             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;
+            const exchangeTokens = estimator.messages(exchangeMessages).tokens;
             if (accumulated + exchangeTokens > budget) {
                 break;
             }
@@ -121,7 +122,7 @@ function textPart(text) {
  * provider needs the tools declared to read them.
  */
 export function compactorHistory(toCompact, compactor) {
-    const lexicon = compactor.lexicon;
+    const labels = compactor.labels;
     const toolNames = new Map();
     let droppedMedia = 0;
     const readable = (parts) => (parts ?? []).filter((part) => {
@@ -141,13 +142,13 @@ export function compactorHistory(toCompact, compactor) {
             history.push({
                 role: 'assistant',
                 parts: [
-                    textPart(lexiconText('compaction.tool_result', { tool: tool ?? '', result }, lexicon)),
+                    textPart(labelText('compaction.tool_result', { tool: tool ?? '', result }, labels)),
                     ...parts,
                 ],
             });
             continue;
         }
-        const calls = (message.tool_calls ?? []).map((call) => textPart(lexiconText('compaction.tool_call', { tool: call.function.name, arguments: call.function.arguments }, lexicon)));
+        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;

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

@@ -1,7 +1,9 @@
 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, KeyVault } from '../types.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";
@@ -14,17 +16,17 @@ declare const DECISION_ERROR_KINDS: {
     readonly malformed_response: "bad_response";
     readonly disclosure_blocked: "blocked";
 };
-/** A normalized native-decision failure; response bodies are deliberately omitted. */
+/**
+ * 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);
+    constructor(code: keyof typeof DECISION_ERROR_KINDS, message: string, status?: number | undefined, options?: ErrorOptions);
 }
-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;
+/** 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;
 }