@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/protocols/binding.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { jsonObjectSchema } from '../json.js';
+import { KEY_SLOT_NAME } from '../schema.js';
+import { modelOptions } from './protocol.js';
+/** A vault slot name. */
+export const keySlotSchema = z.string().regex(KEY_SLOT_NAME);
+export const commonModelSettingsSchema = z.strictObject({
+    maxOutputTokens: z.number().int().positive().optional(),
+    temperature: z.number().finite().nonnegative().optional(),
+    efforts: z
+        .record(z.string().min(1), z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']))
+        .optional(),
+    defaultEffort: z.string().min(1).optional(),
+    allowEffortSelect: z.boolean().optional(),
+    summaries: z.boolean().optional(),
+    builtInTools: z.array(z.string().min(1)).optional(),
+    compaction: z
+        .custom((value) => typeof value === 'object' && value !== null && !Array.isArray(value))
+        .optional(),
+});
+const shared = commonModelSettingsSchema.shape;
+const modelBinding = z.strictObject({
+    // labels-exempt: builder field description, read by the studio and docs
+    protocol: z.string().min(1).describe('The API shape this model is spoken to in.'),
+    provider: z.string().min(1).describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its registration supplies the endpoint and authentication.'),
+    // labels-exempt: builder field description, read by the studio and docs
+    apiId: z.string().min(1).describe('The id the provider knows the model by.'),
+    maxOutputTokens: shared.maxOutputTokens.describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'The most tokens the model may write in one step.'),
+    // labels-exempt: builder field description, read by the studio and docs
+    temperature: shared.temperature.describe("How varied the model's answers are."),
+    efforts: shared.efforts.describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'Effort names a turn may pick, each mapped to a thinking level.'),
+    // labels-exempt: builder field description, read by the studio and docs
+    defaultEffort: shared.defaultEffort.describe('The effort used when a turn picks none.'),
+    // labels-exempt: builder field description, read by the studio and docs
+    allowEffortSelect: shared.allowEffortSelect.describe('Whether a turn may pick an effort.'),
+    // labels-exempt: builder field description, read by the studio and docs
+    summaries: shared.summaries.describe('Whether the model sends summaries of its thinking.'),
+    builtInTools: shared.builtInTools.describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'Tools the provider runs itself, by the ids it knows them by.'),
+    compaction: shared.compaction.describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'How the conversation is shortened when it grows too long.'),
+    keySlot: keySlotSchema
+        .optional()
+        // labels-exempt: builder field description, read by the studio and docs
+        .describe("The slot this model's key is read from, in place of the provider's."),
+    fallbackKeySlot: keySlotSchema
+        .optional()
+        // labels-exempt: builder field description, read by the studio and docs
+        .describe('The slot tried once when the first key is out of quota.'),
+    options: jsonObjectSchema
+        .optional()
+        // labels-exempt: builder field description, read by the studio and docs
+        .describe("What this model's protocol takes beyond the shared settings."),
+});
+true;
+export const modelBindingSchema = modelBinding;
+const decisionModelBinding = modelBinding
+    .pick({
+    protocol: true,
+    provider: true,
+    apiId: true,
+    keySlot: true,
+    fallbackKeySlot: true,
+    options: true,
+})
+    .extend({
+    timeoutMs: z
+        .number()
+        .positive()
+        .optional()
+        // labels-exempt: builder field description, read by the studio and docs
+        .describe('How long a decision may take before it fails.'),
+});
+true;
+export const decisionModelBindingSchema = decisionModelBinding;
+/** The slots a model reads its key from: the ones it names, else its provider's. */
+export function keySlotsOf(provider, binding) {
+    const keySlot = binding.keySlot ?? provider.keySlot;
+    const fallbackKeySlot = binding.fallbackKeySlot ?? provider.fallbackKeySlot;
+    return {
+        ...(keySlot === undefined ? {} : { keySlot }),
+        ...(fallbackKeySlot === undefined ? {} : { fallbackKeySlot }),
+    };
+}
+/** The provider's serve of the protocol a binding speaks. */
+export function bindingServe(provider, binding) {
+    const serve = provider.serves.find((entry) => entry.protocol.id === binding.protocol);
+    if (!serve)
+        throw new TheoremError('config', labelText('protocol.not_served', { provider: provider.id, protocol: binding.protocol }));
+    return serve;
+}
+/** The protocol a binding speaks on its provider. */
+export function protocolOf(provider, binding) {
+    return bindingServe(provider, binding).protocol;
+}
+/**
+ * The one place a binding meets its provider, once, at registration, for fit only. Returns the
+ * binding with its options parsed; changes nothing in place.
+ */
+export function checkBinding(provider, binding, profileType, runtime = { webSocketHeaders: true }) {
+    const serve = bindingServe(provider, binding);
+    const { protocol } = serve;
+    if (protocol.endpoints[profileType] === undefined)
+        throw new TheoremError('unsupported', labelText('protocol.profile_type', { protocol: protocol.id, profileType }));
+    const options = jsonObjectSchema.parse(modelOptions(protocol, binding.apiId, binding.options));
+    const slots = keySlotsOf(provider, binding);
+    if (slots.keySlot !== undefined && slots.keySlot === slots.fallbackKeySlot)
+        throw new TheoremError('config', labelText('provider.model_fallback_slot'));
+    if ((binding.keySlot || binding.fallbackKeySlot) && !provider.definition.key)
+        throw new TheoremError('config', labelText('protocol.no_key', { provider: provider.id }));
+    const authorize = serve.authorize ?? provider.definition.authorize;
+    if (profileType === 'live' && authorize?.webSocketHeaders && !runtime.webSocketHeaders)
+        throw new TheoremError('unsupported', labelText('protocol.ws_headers', { provider: provider.id }));
+    return { ...binding, options: options };
+}

package/esm/src/kernel/protocols/limits.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/** The budgets every provider call runs under; a host may tighten or loosen each. */
+export interface ProviderLimits {
+    operationTimeoutMs: number;
+    connectTimeoutMs: number;
+    liveStepTimeoutMs: number;
+    maxWireRecordBytes: number;
+    maxWireResponseBytes: number;
+    maxEventBytes: number;
+    maxStepBytes: number;
+    maxStepEvents: number;
+    maxPendingToolCalls: number;
+}
+export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
+export declare function resolveProviderLimits(overrides?: Partial<ProviderLimits>): ProviderLimits;

package/esm/src/kernel/protocols/limits.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+const positiveBudget = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const timerBudget = positiveBudget.max(2147483647);
+export const providerLimitsSchema = z.strictObject({
+    operationTimeoutMs: timerBudget,
+    connectTimeoutMs: timerBudget,
+    liveStepTimeoutMs: timerBudget,
+    maxWireRecordBytes: positiveBudget,
+    maxWireResponseBytes: positiveBudget,
+    maxEventBytes: positiveBudget,
+    maxStepBytes: positiveBudget,
+    maxStepEvents: positiveBudget,
+    maxPendingToolCalls: positiveBudget,
+});
+export function resolveProviderLimits(overrides = {}) {
+    return Object.freeze(providerLimitsSchema.parse({
+        operationTimeoutMs: 120000,
+        connectTimeoutMs: 30000,
+        liveStepTimeoutMs: 120000,
+        maxWireRecordBytes: 16 * 1024 * 1024,
+        maxWireResponseBytes: 64 * 1024 * 1024,
+        maxEventBytes: 16 * 1024 * 1024,
+        maxStepBytes: 64 * 1024 * 1024,
+        maxStepEvents: 100000,
+        maxPendingToolCalls: 32,
+        ...overrides,
+    }));
+}

package/esm/src/kernel/protocols/mod.d.ts

@@ -0,0 +1,5 @@
+export * from './binding.js';
+export * from './prices.js';
+export * from './protocol.js';
+export * from './provider.js';
+export { type CallSetup, callProtocol } from './runtime.js';

package/esm/src/kernel/protocols/mod.js

@@ -0,0 +1,5 @@
+export * from './binding.js';
+export * from './prices.js';
+export * from './protocol.js';
+export * from './provider.js';
+export { callProtocol } from './runtime.js';

package/esm/src/kernel/protocols/prices.d.ts

@@ -0,0 +1,36 @@
+import type { TurnCost, TurnTokens } from '../turn-events.js';
+/** US dollars per million tokens. Thinking tokens are billed as output. */
+export interface Rates {
+    input: number;
+    output: number;
+    cachedInput?: number;
+    /**
+     * Rates for one modality's share of a side, keyed as `TurnTokens.byModality` keys it (`audio`,
+     * `image`, …). A share with no rate here is billed at the side's own rate.
+     */
+    byModality?: {
+        input?: Readonly<Record<string, number>>;
+        output?: Readonly<Record<string, number>>;
+    };
+}
+/** One model's rates, and the higher ones a prompt above `longContext.above` input tokens is billed at. */
+export interface ModelPrice extends Rates {
+    longContext?: Rates & {
+        above: number;
+    };
+}
+/**
+ * A provider's prices, kept only where its API reports no cost. `models` is keyed by `apiId`; a
+ * key ending in `*` covers every id that starts with what comes before it. `checked` is the date
+ * the table was last checked against the provider's price page.
+ */
+export interface PriceTable {
+    checked: string;
+    models: Readonly<Record<string, ModelPrice>>;
+}
+/** A cost Theorem worked out from a price table, not one the API reported. */
+export type EstimatedCost = TurnCost & {
+    estimated: true;
+};
+/** The cost of one call from its tokens, or nothing for a model the table doesn't price. */
+export declare function costFromPrices(table: PriceTable, apiId: string, tokens: TurnTokens): EstimatedCost | undefined;

package/esm/src/kernel/protocols/prices.js

@@ -0,0 +1,37 @@
+const PER = 1_000_000;
+function priceFor(table, apiId) {
+    const exact = table.models[apiId];
+    if (exact)
+        return exact;
+    let best;
+    for (const [key, price] of Object.entries(table.models))
+        if (key.endsWith('*') &&
+            apiId.startsWith(key.slice(0, -1)) &&
+            key.length - 1 > (best?.prefix.length ?? -1))
+            best = { prefix: key.slice(0, -1), price };
+    return best?.price;
+}
+/** Bills each priced modality's share at its rate, and the rest of the side at `rate`. */
+function sideUsd(count, rate, modalityRates, shares) {
+    let rest = count;
+    let usd = 0;
+    for (const [modality, modalityRate] of Object.entries(modalityRates ?? {})) {
+        const share = Math.min(shares?.[modality] ?? 0, rest);
+        usd += share * modalityRate;
+        rest -= share;
+    }
+    return usd + rest * rate;
+}
+/** The cost of one call from its tokens, or nothing for a model the table doesn't price. */
+export function costFromPrices(table, apiId, tokens) {
+    const price = priceFor(table, apiId);
+    if (!price)
+        return undefined;
+    const rates = price.longContext && tokens.input > price.longContext.above ? price.longContext : price;
+    const cached = Math.min(tokens.cached ?? 0, tokens.input);
+    const usd = (cached * (rates.cachedInput ?? rates.input) +
+        sideUsd(tokens.input - cached, rates.input, rates.byModality?.input, tokens.byModality?.input) +
+        sideUsd(tokens.output, rates.output, rates.byModality?.output, tokens.byModality?.output)) /
+        PER;
+    return { usd, estimated: true };
+}

package/esm/src/kernel/protocols/protocol.d.ts

@@ -0,0 +1,253 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import type { JsonObject, JsonValue } from '../json.js';
+import type { ReasoningOrigin, ToolCallRequest } from '../turn-events.js';
+import type { DecisionRequest, DecisionResult, EmbeddingInput, EmbeddingResult, EmbeddingTask, InteractionPart, ModelRequest, TurnContext, TurnEvent, TurnHistoryMessage, TurnResponse, TurnStop } from '../types.js';
+import type { ProviderLimits } from './limits.js';
+/** The kinds of profile a protocol can serve, each at its own endpoint: every type but `host`. */
+declare const MODEL_PROFILE_TYPES: readonly ["text", "image", "speech", "live", "decision", "embedding"];
+export type ModelProfileType = (typeof MODEL_PROFILE_TYPES)[number];
+/** The turn events a protocol yields as they are. */
+export type ProtocolContentEvent = Extract<TurnEvent, {
+    type: 'text' | 'thought' | 'structured' | 'media' | 'grounding' | 'citation' | 'evidence' | 'tokens' | 'session' | 'tool_draft' | 'error';
+}>;
+/**
+ * What a protocol streams back: the model's events, reasoning it must get back word for word,
+ * content with no common shape, and (opted in) the wire rows themselves. A protocol writes
+ * `custom.kind` in its own terms; the kernel sets reasoning's origin and mints call ids.
+ */
+export type ProtocolEvent<S = unknown> = ProtocolContentEvent | {
+    type: 'tool_call';
+    call: ToolCallRequest & {
+        wireCallId?: string;
+    };
+} | {
+    type: 'tool_cancel';
+    callId: string;
+} | {
+    type: 'response';
+    response: TurnResponse;
+} | {
+    type: 'done';
+    stop: TurnStop;
+    interrupted?: boolean;
+    state?: S;
+} | {
+    type: 'reasoning';
+    text?: string;
+    data: JsonValue;
+    origin?: ReasoningOrigin;
+} | {
+    type: 'custom';
+    kind: string;
+    data: JsonObject;
+} | {
+    type: 'raw';
+    row: JsonObject;
+};
+/**
+ * One turn as a protocol gets it: the kernel's request without what only the kernel uses (the
+ * checkpoint, the upstream tap), and the protocol's own saved state, if it is reused.
+ */
+export type ProtocolRequest<S = unknown> = Omit<ModelRequest, 'providerState' | 'tapUpstream'> & {
+    state?: S;
+    /** How much of `history` the reused state already holds. */
+    stateHistoryLength?: number;
+};
+export type DecisionCall = Pick<DecisionRequest, 'state' | 'questions' | 'assets'> & {
+    apiId: string;
+    signal?: AbortSignal;
+};
+/** One embedding request after profile resolution, before provider serialization. */
+export type EmbeddingCall = {
+    apiId: string;
+    input: EmbeddingInput | readonly EmbeddingInput[];
+    task?: EmbeddingTask;
+    options?: JsonObject;
+    signal?: AbortSignal;
+};
+export type { EmbeddingResult };
+/** A tool's result, sent back into a live session. */
+export interface LiveToolResult {
+    callId: string;
+    name: string;
+    text: string;
+    parts?: InteractionPart[];
+}
+/** A live session, as a protocol hands it back. */
+export interface ProtocolSession<S = unknown> {
+    closeInfo?(): {
+        code: number;
+        reason: string;
+        error?: Error;
+        warning?: {
+            timeLeftMs?: number;
+            closedAfterMs: number;
+        };
+    } | undefined;
+    events(): AsyncIterable<ProtocolEvent<S>>;
+    sendText(text: string): Promise<void>;
+    sendAudio(media: {
+        data: string;
+        mimeType: string;
+    }): Promise<void>;
+    sendVideo(media: {
+        data: string;
+        mimeType: string;
+    }): Promise<void>;
+    sendContext(context: TurnContext): Promise<void>;
+    sendToolResult(result: LiveToolResult): Promise<void>;
+    close(reason?: string): Promise<void>;
+}
+/** One open WebSocket: frames out and in are JSON objects. */
+export interface ProtocolSocket {
+    /** `input` is what the frame gives the model to read, for the trace; setup and control frames give none. */
+    send(frame: JsonObject, input?: readonly TurnHistoryMessage[]): void;
+    frames(): AsyncIterable<JsonObject>;
+    close(code?: number, reason?: string): void;
+}
+export interface SendInit {
+    stream: boolean;
+    /** In place of the profile type's endpoint, for a call the shape makes elsewhere. */
+    path?: string;
+    headers?: Record<string, string>;
+    /** The builtin ids this request wrote. Any other id the request asked for is refused. */
+    wroteTools?: readonly string[];
+}
+/** What the kernel hands a protocol for one call. It never holds a key, a slot, or a base URL. */
+export interface ProtocolContext<O = unknown> {
+    profileType: ModelProfileType;
+    apiId: string;
+    options: O;
+    /** The binding's `builtInTools`, for the protocol to write. */
+    builtInTools: readonly string[];
+    limits: ProviderLimits;
+    signal?: AbortSignal;
+    /** Posts to this profile type's endpoint on the provider and yields the reply's rows. */
+    send(body: JsonObject, init: SendInit): AsyncIterable<JsonObject>;
+    /** Opens this profile type's WebSocket on the provider and sends `setup` as the first frame. */
+    connect(setup: JsonObject, init?: {
+        wroteTools?: readonly string[];
+    }): Promise<ProtocolSocket>;
+    tapUpstream(row: JsonObject): void;
+}
+export interface ProtocolOperations<S = unknown> {
+    complete?(request: ProtocolRequest<S>): AsyncIterable<ProtocolEvent<S>>;
+    openSession?(request: ProtocolRequest<S>): Promise<ProtocolSession<S>>;
+    decide?(request: DecisionCall): Promise<DecisionResult>;
+    embed?(request: EmbeddingCall): Promise<EmbeddingResult>;
+}
+/** An upstream answer that was not a success, for the protocol to type. */
+export interface UpstreamFailure {
+    status: number;
+    body: JsonValue;
+    headers: Headers;
+}
+export interface Continuation<S> {
+    version: number;
+    schema: z.ZodType<S>;
+    /** Options that change what saved state means; a checkpoint is reused only when they match. */
+    keyOptions?: readonly string[];
+}
+/** One kind of media an embedding model takes: its MIME types, and how many one input may hold when the provider caps it. */
+export interface EmbeddingMediaKind {
+    accept: readonly string[];
+    maxPerInput?: number;
+}
+/** What one embedding model takes, as its provider documents it. */
+export interface EmbeddingModelLimits {
+    /** Inputs one request may carry, when the provider caps them. */
+    maxInputs?: number;
+    /** The media it embeds; empty for a model that embeds text only. */
+    media: readonly EmbeddingMediaKind[];
+}
+export interface ProtocolDefinition<O = unknown, S = unknown> {
+    /** What bindings write, e.g. `'openAi'`. */
+    id: string;
+    /** What people read, e.g. `'OpenAI Chat Completions'`. */
+    name: string;
+    /** One sentence, for the studio and docs. */
+    description: string;
+    /** The path each profile type uses. A type with no entry is not served. */
+    endpoints: Partial<Record<ModelProfileType, string>>;
+    /** Every field a binding may set, each described. */
+    options: z.ZodType<O>;
+    continuation?: Continuation<S>;
+    /** The `data` of the reasoning parts it writes. */
+    reasoning?: z.ZodType<JsonValue>;
+    /** Content it emits that has no common shape, by kind. */
+    custom?: Readonly<Record<string, z.ZodType<JsonObject>>>;
+    /**
+     * Turns the reply's framing into rows. Absent: SSE for a stream, one JSON row otherwise, and a
+     * body that is not JSON as one `{ eventType: 'http_body', mime_type, data }` row, base64.
+     */
+    framing?(response: Response, stream: boolean): AsyncIterable<JsonObject>;
+    /** Types a failed answer. Absent: the kind follows the HTTP status. */
+    error?(failure: UpstreamFailure): TheoremError;
+    /** What the named embedding model takes. Absent: the kernel holds requests to the profile alone. */
+    embeddingLimits?(apiId: string): EmbeddingModelLimits;
+    /** The options the named model refuses, though the protocol takes them for others. Absent: none. */
+    refusedOptions?(apiId: string): readonly string[];
+    create(context: ProtocolContext<O>): ProtocolOperations<S>;
+}
+/** A defined protocol. `lineage` is its id, then its base's, back to the first. */
+export interface Protocol<O = unknown, S = unknown> extends Readonly<Omit<ProtocolDefinition<O, S>, 'create'>> {
+    readonly base?: Protocol;
+    readonly lineage: readonly string[];
+    create(context: ProtocolContext<O>): ProtocolOperations<S>;
+}
+/**
+ * `options` as model `apiId` takes them on `protocol`: the protocol's schema, less any option that
+ * model refuses. Throws a `config` error naming what does not fit.
+ */
+export declare function modelOptions<O>(protocol: Pick<Protocol<O>, 'id' | 'options' | 'refusedOptions'>, apiId: string, options: unknown): O;
+/** Defines a protocol: the code that speaks one API shape, and everything on its wire. */
+export declare function defineProtocol<O, S = unknown>(definition: ProtocolDefinition<O, S>): Protocol<O, S>;
+/** What an extension's `body` sees. */
+export interface ExtensionBodyAt<E> {
+    profileType: ModelProfileType;
+    apiId: string;
+    options: E;
+    /** The binding's built-in tool ids. */
+    builtInTools: readonly string[];
+    /** The request's headers, to add to. */
+    headers: Headers;
+    /** The turn being sent; absent for a decision and a live session's later frames. */
+    request?: ProtocolRequest<unknown>;
+}
+/** What an extension's reader keeps for one call: it sees each reply row before the base. */
+export interface ExtensionReader<S = unknown> {
+    row(row: JsonObject): {
+        events?: ProtocolEvent<S>[];
+        consumed?: boolean;
+    };
+    finish?(): {
+        events?: ProtocolEvent<S>[];
+    };
+}
+export interface ProtocolExtension<E = unknown, S = unknown> extends Pick<ProtocolDefinition<E, S>, 'id' | 'name' | 'description' | 'reasoning' | 'custom' | 'framing' | 'error' | 'embeddingLimits' | 'refusedOptions'> {
+    /** What it adds to the base's options. A field the base already has is refused. */
+    options?: z.ZodObject & z.ZodType<E>;
+    /** Its own paths, where they differ from the base's. */
+    endpoints?: Partial<Record<ModelProfileType, string>>;
+    /** What it adds to the base's request (or a WebSocket's first frame), and the tools it wrote. */
+    body?(body: JsonObject, at: ExtensionBodyAt<E>): {
+        body: JsonObject;
+        wroteTools?: readonly string[];
+    };
+    /** One per call: reads each reply row before the base. */
+    read?(at: {
+        profileType: ModelProfileType;
+        apiId: string;
+        options: E;
+        request?: ProtocolRequest<unknown>;
+    }): ExtensionReader<S>;
+}
+/**
+ * A new protocol built on a base it nearly matches. It has its own id, so what it sends has one
+ * answer: its definition. Its options are the base's plus its own; its endpoints, framing, and error
+ * typing are the base's unless it gives its own.
+ */
+export declare function extendProtocol<O, S, E = JsonObject>(base: Protocol<O, S>, extension: ProtocolExtension<E, S>): Protocol<O & E, S>;
+/** Whether something `writer` wrote may go back to `target`: the writer is in its lineage. */
+export declare function carriesTo(writer: string, target: Pick<Protocol, 'lineage'>): boolean;