@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/provider-budget.js

@@ -0,0 +1,262 @@
+import { TheoremError, throwIfAborted } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+function combinedSignal(signals) {
+    const controller = new AbortController();
+    const releases = [];
+    const dispose = () => {
+        for (const release of releases.splice(0))
+            release();
+    };
+    for (const signal of signals) {
+        const abort = () => {
+            controller.abort(signal.reason);
+            dispose();
+        };
+        if (signal.aborted) {
+            abort();
+            break;
+        }
+        signal.addEventListener('abort', abort, { once: true });
+        releases.push(() => signal.removeEventListener('abort', abort));
+    }
+    return { signal: controller.signal, dispose };
+}
+export class ProviderBudget {
+    limits;
+    controller = new AbortController();
+    signal;
+    timer;
+    timerDeadline;
+    wireBytes = 0;
+    stepBytes = 0;
+    stepEvents = 0;
+    calls = new Set();
+    deadline;
+    releaseSignal;
+    constructor(limits, caller, timeoutMs = limits.operationTimeoutMs) {
+        this.limits = limits;
+        const effective = combinedSignal(caller ? [caller, this.controller.signal] : [this.controller.signal]);
+        this.signal = effective.signal;
+        this.releaseSignal = effective.dispose;
+        this.startTimer(timeoutMs);
+        this.deadline = performance.now() + timeoutMs;
+    }
+    resumeOperation() {
+        const remaining = this.deadline - performance.now();
+        if (remaining <= 0) {
+            this.controller.abort(new TheoremError('timeout', labelText('error.timeout')));
+            throwIfAborted(this.signal);
+        }
+        this.startTimer(remaining);
+    }
+    /** Milliseconds before the running timer ends the call. */
+    timeLeft() {
+        return (this.timerDeadline ?? this.deadline) - performance.now();
+    }
+    startTimer(ms) {
+        this.stopTimer();
+        this.timerDeadline = performance.now() + ms;
+        this.timer = setTimeout(() => this.controller.abort(new TheoremError('timeout', labelText('error.timeout'))), ms);
+    }
+    stopTimer() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.timerDeadline = undefined;
+    }
+    close() {
+        this.controller.abort();
+        this.dispose();
+    }
+    dispose() {
+        this.stopTimer();
+        this.releaseSignal();
+    }
+    startLiveStep() {
+        if (this.timer === undefined)
+            this.startTimer(this.limits.liveStepTimeoutMs);
+    }
+    fail() {
+        const error = new TheoremError('bad_response', labelText('provider.budget_exhausted'), {
+            copy: { key: 'provider.budget_exhausted' },
+        });
+        this.controller.abort(error);
+        throw error;
+    }
+    checkDeadline() {
+        if (this.timerDeadline !== undefined && performance.now() >= this.timerDeadline) {
+            this.controller.abort(new TheoremError('timeout', labelText('error.timeout')));
+        }
+        throwIfAborted(this.signal);
+    }
+    value(value) {
+        this.checkDeadline();
+        const bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+        this.checkDeadline();
+        this.stepBytes += bytes;
+        this.stepEvents++;
+        if (bytes > this.limits.maxEventBytes ||
+            this.stepBytes > this.limits.maxStepBytes ||
+            this.stepEvents > this.limits.maxStepEvents)
+            this.fail();
+    }
+    event(event) {
+        this.value(event);
+        if (event.type === 'tool_call')
+            this.calls.add(event.call.callId);
+        if (event.type === 'tool_cancel')
+            this.calls.delete(event.callId);
+        if (this.calls.size > this.limits.maxPendingToolCalls)
+            this.fail();
+    }
+    resetStep() {
+        this.stepBytes = 0;
+        this.stepEvents = 0;
+        this.calls.clear();
+        this.wireBytes = 0;
+        this.stopTimer();
+    }
+    socket(open) {
+        return async (url, init) => {
+            throwIfAborted(this.signal);
+            const ws = await open(url, init);
+            if (this.signal.aborted) {
+                ws.close();
+                throwIfAborted(this.signal);
+            }
+            const abort = () => ws.close();
+            this.signal.addEventListener('abort', abort, { once: true });
+            ws.addEventListener('close', () => this.signal.removeEventListener('abort', abort), {
+                once: true,
+            });
+            ws.addEventListener('message', (event) => {
+                const data = event.data;
+                const bytes = typeof data === 'string'
+                    ? new TextEncoder().encode(data).byteLength
+                    : data instanceof Blob
+                        ? data.size
+                        : data instanceof ArrayBuffer || ArrayBuffer.isView(data)
+                            ? data.byteLength
+                            : 0;
+                if (bytes <= this.limits.maxWireRecordBytes)
+                    return;
+                event.stopImmediatePropagation();
+                try {
+                    this.fail();
+                }
+                catch {
+                    ws.close(1009, 'response limit');
+                }
+            });
+            return ws;
+        };
+    }
+    fetch(upstream) {
+        return async (input, init) => {
+            const supplied = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+            const effective = combinedSignal(supplied ? [this.signal, supplied] : [this.signal]);
+            const signal = effective.signal;
+            throwIfAborted(signal);
+            const response = await upstream(input, { ...init, signal }).catch((error) => {
+                effective.dispose();
+                throw error;
+            });
+            throwIfAborted(signal);
+            if (!response.body) {
+                effective.dispose();
+                return response;
+            }
+            const reader = response.body.getReader();
+            let responseBytes = 0;
+            const record = response.headers.get('content-type')?.includes('text/event-stream')
+                ? new SseRecordBudget(this)
+                : undefined;
+            const abort = () => {
+                void reader.cancel(signal.reason).catch(() => undefined);
+            };
+            signal.addEventListener('abort', abort, { once: true });
+            const body = new ReadableStream({
+                pull: async (controller) => {
+                    try {
+                        throwIfAborted(signal);
+                        const next = await reader.read();
+                        throwIfAborted(signal);
+                        if (next.done) {
+                            controller.close();
+                            signal.removeEventListener('abort', abort);
+                            effective.dispose();
+                            reader.releaseLock();
+                            return;
+                        }
+                        responseBytes += next.value.byteLength;
+                        this.wireBytes += next.value.byteLength;
+                        if (responseBytes > this.limits.maxWireResponseBytes ||
+                            this.wireBytes > this.limits.maxWireResponseBytes)
+                            this.fail();
+                        record?.accept(next.value);
+                        controller.enqueue(next.value);
+                    }
+                    catch (error) {
+                        controller.error(error);
+                        signal.removeEventListener('abort', abort);
+                        effective.dispose();
+                        void reader.cancel(error).catch(() => undefined);
+                    }
+                },
+                cancel: (reason) => {
+                    signal.removeEventListener('abort', abort);
+                    effective.dispose();
+                    return reader.cancel(reason);
+                },
+            });
+            return new Response(body, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        };
+    }
+}
+class SseRecordBudget {
+    budget;
+    recordBytes = 0;
+    lineBytes = 0;
+    previousCR = false;
+    emptyCR = false;
+    constructor(budget) {
+        this.budget = budget;
+    }
+    accept(chunk) {
+        for (const byte of chunk) {
+            if (this.emptyCR && byte !== 10) {
+                this.recordBytes = 0;
+                this.emptyCR = false;
+            }
+            this.recordBytes++;
+            if (this.recordBytes > this.budget.limits.maxWireRecordBytes)
+                this.budget.fail();
+            if (this.emptyCR) {
+                this.recordBytes = 0;
+                this.emptyCR = false;
+                this.previousCR = false;
+                continue;
+            }
+            if (byte === 10 && this.previousCR) {
+                this.previousCR = false;
+                continue;
+            }
+            if (byte === 10 || byte === 13) {
+                if (this.lineBytes === 0) {
+                    if (byte === 13)
+                        this.emptyCR = true;
+                    else
+                        this.recordBytes = 0;
+                }
+                this.lineBytes = 0;
+            }
+            else
+                this.lineBytes++;
+            this.previousCR = byte === 13;
+        }
+    }
+}

package/esm/src/kernel/provider-dispatch.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderHostOptions } from './protocols/runtime.js';
+import type { KernelRegistry } from './registry/kernel-registry.js';
+import type { TurnModel, TurnRequest } from './types.js';
+export interface RegistryTurnModel extends TurnModel {
+    forProfile(profileId: string, modelId?: string, request?: TurnRequest): RegistryTurnModel;
+}
+export declare function resolveRegisteredTurnModel(registry: KernelRegistry, profileId: string, modelId: string | undefined, options: ProviderHostOptions, request?: TurnRequest): RegistryTurnModel;
+/**
+ * A host's provider options as the model of the agents its call runs. It
+ * completes nothing itself: a host's own call and a live session run no turn.
+ */
+export declare function hostAgentModel(registry: KernelRegistry, options: ProviderHostOptions): RegistryTurnModel;
+export declare function nestedTurnModel(provider: TurnModel, profileId: string, modelId?: string, request?: TurnRequest): TurnModel;

package/esm/src/kernel/provider-dispatch.js

@@ -0,0 +1,36 @@
+import { TheoremError } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+import { assertHistoryKept, registeredTurnModel } from './provider-runtime.js';
+export function resolveRegisteredTurnModel(registry, profileId, modelId, options, request) {
+    const profile = registry.profiles.get(profileId);
+    if (profile.type === 'host')
+        return hostAgentModel(registry, options);
+    if (profile.type === 'decision' || profile.type === 'live' || profile.type === 'embedding')
+        throw new TheoremError('unsupported', labelText('provider.turn_profile'));
+    const binding = profile.models[modelId ?? profile.defaultModel];
+    if (!binding)
+        throw new TheoremError('config', labelText('provider.model_binding_missing'));
+    assertHistoryKept(profile.providerContinuation, request?.providerState, request?.input?.history);
+    const turn = registeredTurnModel(registry.providers.require(binding.provider, binding.apiId), structuredClone(binding), profile.type, options, request?.providerState, profile.providerContinuation, request?.input?.history);
+    return {
+        complete: turn.complete,
+        forProfile: (id, model, req) => resolveRegisteredTurnModel(registry, id, model, options, req),
+    };
+}
+/**
+ * A host's provider options as the model of the agents its call runs. It
+ * completes nothing itself: a host's own call and a live session run no turn.
+ */
+export function hostAgentModel(registry, options) {
+    return {
+        complete() {
+            throw new TheoremError('unsupported', labelText('provider.host_model'));
+        },
+        forProfile: (id, model, req) => resolveRegisteredTurnModel(registry, id, model, options, req),
+    };
+}
+export function nestedTurnModel(provider, profileId, modelId, request) {
+    return 'forProfile' in provider && typeof provider.forProfile === 'function'
+        ? provider.forProfile(profileId, modelId, request)
+        : provider;
+}

package/esm/src/kernel/provider-live.d.ts

@@ -0,0 +1,7 @@
+import type { LiveConnection } from '../providers/types.js';
+import type { ProviderCheckpoint, ProviderContinuationPolicy } from './checkpoint.js';
+import { type ModelBinding } from './protocols/binding.js';
+import type { RegisteredProvider } from './protocols/provider.js';
+import type { ProviderHostOptions } from './protocols/runtime.js';
+import type { ModelRequest } from './types.js';
+export declare function openRegisteredLiveSession(provider: RegisteredProvider, binding: ModelBinding, request: ModelRequest, host: ProviderHostOptions, initial?: ProviderCheckpoint, policy?: ProviderContinuationPolicy): Promise<LiveConnection>;

package/esm/src/kernel/provider-live.js

@@ -0,0 +1,189 @@
+import { TheoremError } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+import { protocolOf } from './protocols/binding.js';
+import { checkpointProviderState, guardedCall, kernelCall, protocolRequest, restoreProviderState, withProviderAbort, } from './provider-runtime.js';
+async function liveTerminalBatch(provider, binding, keySlot, request, event, failed, pending, boundary) {
+    const success = !failed &&
+        !event.interrupted &&
+        (event.stop.kind === 'completed' || event.stop.kind === 'tool');
+    const checkpoint = success
+        ? await checkpointProviderState(provider, binding, keySlot, event.state, request.history ?? [])
+        : undefined;
+    return {
+        type: 'batch',
+        row: {},
+        turnPhase: success ? (event.stop.kind === 'tool' ? 'streaming' : 'complete') : 'abort',
+        events: [
+            ...(success ? pending : []),
+            ...boundary,
+            ...(checkpoint ? [{ type: 'provider_checkpoint', providerState: checkpoint }] : []),
+            ...(event.stop.kind === 'tool'
+                ? []
+                : [
+                    {
+                        type: 'done',
+                        stop: event.stop,
+                        interrupted: event.interrupted,
+                        providerState: checkpoint,
+                    },
+                ]),
+        ],
+    };
+}
+function liveClosedItem(closed) {
+    return {
+        type: 'closed',
+        code: closed?.code ?? 1000,
+        reason: closed?.reason ?? 'provider-closed',
+        ...(closed?.error
+            ? {
+                error: closed.error instanceof TheoremError
+                    ? closed.error
+                    : new TheoremError('unavailable', labelText('provider.session_closed')),
+            }
+            : {}),
+        ...(closed?.warning ? { goAway: closed.warning } : {}),
+    };
+}
+function rememberLiveCall(call, callNames, history) {
+    if (callNames.has(call.callId) ||
+        history?.some((message) => message.role === 'tool' && message.tool_call_id === call.callId))
+        throw new TheoremError('bad_response', labelText('provider.settled_call'));
+    callNames.set(call.callId, call.name);
+}
+function streamingBatch(events) {
+    return { type: 'batch', row: {}, turnPhase: 'streaming', events };
+}
+/** A call the model made, for the step; a step's signed reasoning rides on its first call, as in a turn. */
+function queuedCall(call, pending, reasoning) {
+    const tool = kernelCall(call);
+    const first = !pending.some((item) => item.type === 'tool');
+    return {
+        type: 'tool',
+        tool: first && reasoning.length ? { ...tool, reasoning: reasoning.splice(0) } : tool,
+    };
+}
+/** The batch saying the model cancelled one of its calls. */
+function cancelBatch(callId, callNames) {
+    const name = callNames.get(callId);
+    if (!name)
+        throw new TheoremError('bad_response', labelText('provider.tool_cancel_missing'));
+    return streamingBatch([
+        { type: 'tool', tool: { callId, name, at: Date.now(), phase: 'cancel' } },
+    ]);
+}
+export async function openRegisteredLiveSession(provider, binding, request, host, initial, policy = {}) {
+    const restored = await restoreProviderState(provider, binding, initial, request.history ?? [], policy);
+    const call = guardedCall(provider, binding, 'live', host, { ...request, liveConnection: true });
+    const session = await call.openSession(protocolRequest(request, protocolOf(provider, binding), restored));
+    let sends = Promise.resolve();
+    const send = (fn) => {
+        sends = sends.then(() => withProviderAbort(fn, request.signal));
+    };
+    return {
+        setup: {},
+        flush: () => sends,
+        sendInput(part) {
+            if (part.type === 'text')
+                send(() => session.sendText(part.text));
+            else if (part.type === 'audio' && 'data' in part)
+                send(() => session.sendAudio(part));
+            else if (part.type === 'video' && 'data' in part)
+                send(() => session.sendVideo(part));
+            else
+                throw new TheoremError('unsupported', labelText('provider.live_input'));
+        },
+        sendContext(text) {
+            send(() => session.sendContext({ server: text }));
+        },
+        sendToolResponse(callId, name, output, parts) {
+            send(() => session.sendToolResult({
+                callId,
+                name,
+                text: typeof output === 'string' ? output : JSON.stringify(output),
+                ...(parts?.length ? { parts } : {}),
+            }));
+        },
+        close(_code, reason) {
+            sends = sends.then(() => session.close(reason), () => session.close(reason));
+        },
+        async *batches() {
+            if (restored.warning)
+                yield streamingBatch([{ type: 'provider_warning', warning: restored.warning }]);
+            const callNames = new Map();
+            let pending = [];
+            let boundary = [];
+            let reasoning = [];
+            let failed = false;
+            const iterator = session.events()[Symbol.asyncIterator]();
+            try {
+                while (true) {
+                    const next = await withProviderAbort(() => iterator.next(), request.signal);
+                    if (next.done)
+                        break;
+                    const raw = next.value;
+                    await withProviderAbort(() => sends, request.signal);
+                    const event = raw;
+                    if (event.type === 'raw')
+                        continue;
+                    if (event.type === 'reasoning') {
+                        const { type: _type, ...part } = event;
+                        reasoning.push(part);
+                        continue;
+                    }
+                    if (event.type === 'session' && event.session.kind === 'turn_complete') {
+                        boundary.push(event);
+                        continue;
+                    }
+                    if (event.type === 'session' &&
+                        boundary.length &&
+                        !pending.length &&
+                        (event.session.kind === 'working' || event.session.kind === 'idle')) {
+                        yield streamingBatch([...boundary, event]);
+                        boundary = [];
+                        continue;
+                    }
+                    if (event.type === 'tool_call') {
+                        rememberLiveCall(event.call, callNames, request.history);
+                        pending.push(queuedCall(event.call, pending, reasoning));
+                        continue;
+                    }
+                    if (event.type === 'tool_cancel') {
+                        const cancelled = cancelBatch(event.callId, callNames);
+                        pending = pending.filter((item) => item.type !== 'tool' || item.tool.callId !== event.callId);
+                        yield cancelled;
+                        continue;
+                    }
+                    if (event.type === 'error')
+                        failed = true;
+                    if (event.type === 'done') {
+                        if (event.stop.kind === 'generation_complete') {
+                            yield streamingBatch([{ type: 'done', stop: event.stop }]);
+                            continue;
+                        }
+                        yield await liveTerminalBatch(provider, binding, call.keySlot(), request, event, failed, pending, boundary);
+                        pending = [];
+                        boundary = [];
+                        reasoning = [];
+                        failed = false;
+                    }
+                    else
+                        yield streamingBatch([event]);
+                }
+            }
+            finally {
+                const returned = iterator.return?.();
+                if (returned)
+                    void returned.catch(() => { });
+            }
+            if (pending.length || boundary.length)
+                yield {
+                    type: 'batch',
+                    row: {},
+                    turnPhase: 'abort',
+                    events: [{ type: 'done', stop: { kind: 'stream_incomplete' } }],
+                };
+            yield liveClosedItem(session.closeInfo?.());
+        },
+    };
+}

package/esm/src/kernel/provider-runtime.d.ts

@@ -0,0 +1,57 @@
+import { type ProviderCheckpoint, type ProviderContinuationPolicy, type ProviderWarning } from './checkpoint.js';
+import { type DecisionModelBinding, type ModelBinding } from './protocols/binding.js';
+import { type DecisionCall, type EmbeddingCall, type EmbeddingResult, type ModelProfileType, type Protocol, type ProtocolEvent, type ProtocolRequest, type ProtocolSession } from './protocols/protocol.js';
+import type { RegisteredProvider } from './protocols/provider.js';
+import { type ProviderHostOptions } from './protocols/runtime.js';
+import { type ToolCallRequest } from './turn-events.js';
+import type { DecisionResult, KeySlot, ModelRequest, TurnHistoryMessage, TurnModel } from './types.js';
+export declare function withProviderAbort<T>(operation: () => T | Promise<T>, signal?: AbortSignal): Promise<T>;
+/** One binding's calls with the kernel's guards: its budget, its key redaction, and event checks. */
+export interface GuardedCall {
+    complete(request: ProtocolRequest): AsyncIterable<ProtocolEvent>;
+    openSession(request: ProtocolRequest): Promise<ProtocolSession>;
+    decide(request: DecisionCall): Promise<DecisionResult>;
+    embed(request: EmbeddingCall): Promise<EmbeddingResult>;
+    /** The slot the last attempt signed with: the fallback's after a quota refusal. */
+    keySlot(): KeySlot | undefined;
+}
+/**
+ * One binding's call as the kernel runs it: the protocol runtime's keys, retries, and ids, inside
+ * the host's budgets, with every key it signs with kept out of errors and traces.
+ */
+export declare function guardedCall(provider: RegisteredProvider, binding: ModelBinding | DecisionModelBinding, profileType: ModelProfileType, host: ProviderHostOptions, req: {
+    signal?: AbortSignal;
+    tapUpstream?: (row: Record<string, unknown>) => void;
+    liveConnection?: boolean;
+    /** The call's own deadline, in place of the limits' operation timeout. */
+    timeoutMs?: number;
+}): GuardedCall;
+/** `history: 'stateless'`: every request stands alone, so one that carries a conversation is refused. */
+export declare function assertHistoryKept(policy: ProviderContinuationPolicy | undefined, checkpoint: ProviderCheckpoint | undefined, history: readonly TurnHistoryMessage[] | undefined): void;
+/**
+ * The protocol's saved state when the checkpoint was written for this exact call, or a warning
+ * that it was not and the conversation goes from the transcript.
+ */
+export declare function restoreProviderState(provider: RegisteredProvider, binding: ModelBinding, raw: ProviderCheckpoint | undefined, history: readonly TurnHistoryMessage[], policy?: ProviderContinuationPolicy): Promise<{
+    state?: unknown;
+    covered?: number;
+    wireCallIds?: Record<string, string>;
+    warning?: ProviderWarning;
+}>;
+/** Saves a protocol's state with what it was written for, or nothing when it kept none. */
+export declare function checkpointProviderState(provider: RegisteredProvider, binding: ModelBinding, keySlot: KeySlot | undefined, state: unknown, history: readonly TurnHistoryMessage[], wireCallIds?: Record<string, string>): Promise<ProviderCheckpoint | undefined>;
+/** The engine's request as the protocol gets it, with its saved state when reused. */
+export declare function protocolRequest(request: ModelRequest, protocol: Protocol, restored: {
+    state?: unknown;
+    covered?: number;
+    wireCallIds?: Record<string, string>;
+}): ProtocolRequest;
+/** A call the kernel hands on: its Theorem id, never the wire's. */
+export declare function kernelCall(call: Extract<ProtocolEvent, {
+    type: 'tool_call';
+}>['call']): ToolCallRequest;
+/**
+ * A profile's model as the engine calls it: each step one guarded protocol call, with the
+ * protocol's saved state reused while it still fits and rebuilt, with a warning, when it does not.
+ */
+export declare function registeredTurnModel(provider: RegisteredProvider, binding: ModelBinding, profileType: ModelProfileType, host: ProviderHostOptions, initial?: ProviderCheckpoint, policy?: ProviderContinuationPolicy, hostHistory?: readonly TurnHistoryMessage[]): TurnModel;