@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -0,0 +1,253 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+/** The kinds of profile a protocol can serve, each at its own endpoint: every type but `host`. */
+const MODEL_PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+    'embedding',
+];
+const definitionShape = z.object({
+    id: z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    endpoints: z.partialRecord(z.enum(MODEL_PROFILE_TYPES), z.string().min(1)),
+});
+function refuse(id, issues) {
+    return new TheoremError('config', labelText('protocol.definition', { id, issues }));
+}
+function checkShape(definition) {
+    const parsed = definitionShape.safeParse(definition);
+    if (!parsed.success)
+        throw refuse(String(definition.id), z.prettifyError(parsed.error));
+}
+function own(protocol, kind, schema, value) {
+    if (!schema)
+        throw new TheoremError('internal', labelText('protocol.part_schema', { protocol: protocol.id, kind }));
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new TheoremError('bad_response', labelText('protocol.part_invalid', { protocol: protocol.id, kind }), {
+            cause: parsed.error,
+        });
+    return parsed.data;
+}
+/**
+ * Marks an event a protocol wrote as its own: reasoning gets its origin, a custom kind its
+ * protocol prefix. Each is checked against the writer's schema.
+ */
+function stamp(writer, event) {
+    if (event.type === 'reasoning')
+        return {
+            ...event,
+            data: own(writer, 'reasoning', writer.reasoning, event.data),
+            origin: { protocol: writer.id },
+        };
+    if (event.type === 'custom')
+        return {
+            type: 'custom',
+            kind: `${writer.id}.${event.kind}`,
+            data: own(writer, event.kind, writer.custom?.[event.kind], event.data),
+        };
+    return event;
+}
+async function* stamped(writer, events) {
+    for await (const event of events)
+        yield stamp(writer, event);
+}
+function stampOperations(writer, operations) {
+    const { complete, openSession } = operations;
+    return {
+        ...operations,
+        ...(complete
+            ? { complete: (request) => stamped(writer, complete.call(operations, request)) }
+            : {}),
+        ...(openSession
+            ? {
+                async openSession(request) {
+                    const session = await openSession.call(operations, request);
+                    return { ...session, events: () => stamped(writer, session.events()) };
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * `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 function modelOptions(protocol, apiId, options) {
+    const given = options ?? {};
+    const parsed = protocol.options.safeParse(given);
+    const refused = (protocol.refusedOptions?.(apiId) ?? []).filter((key) => typeof given === 'object' && given !== null && key in given);
+    if (parsed.success && refused.length === 0)
+        return parsed.data;
+    const issues = parsed.success
+        ? refused.map((key) => `✖ ${apiId} takes no ${key}`).join('\n') // labels-exempt: builder config error
+        : z.prettifyError(parsed.error);
+    throw new TheoremError('config', labelText('protocol.options', { apiId, protocol: protocol.id, issues }));
+}
+/** Defines a protocol: the code that speaks one API shape, and everything on its wire. */
+export function defineProtocol(definition) {
+    checkShape(definition);
+    if (typeof definition.create !== 'function' ||
+        typeof definition.options?.safeParse !== 'function')
+        // labels-exempt: builder diagnostic
+        throw refuse(definition.id, 'create and options are required');
+    return Object.freeze({
+        ...definition,
+        lineage: Object.freeze([definition.id]),
+        create: (context) => stampOperations(definition, definition.create(context)),
+    });
+}
+function shapeOf(schema) {
+    return schema instanceof z.ZodObject ? schema.shape : undefined;
+}
+function pick(value, keys) {
+    const source = (value ?? {});
+    const out = {};
+    for (const key of keys)
+        if (key in source)
+            out[key] = source[key];
+    return out;
+}
+function mergeOptions(base, extension) {
+    const baseShape = shapeOf(base.options);
+    const addedShape = extension.options ? shapeOf(extension.options) : {};
+    if (extension.options && !baseShape)
+        throw new TheoremError('config', labelText('protocol.base_options', { protocol: extension.id, base: base.id }));
+    for (const option of Object.keys(addedShape ?? {}))
+        if (baseShape && option in baseShape)
+            throw new TheoremError('config', labelText('protocol.option_clash', { protocol: extension.id, option, base: base.id }));
+    return {
+        schema: (baseShape
+            ? z.strictObject({ ...baseShape, ...addedShape })
+            : base.options),
+        baseKeys: baseShape ? Object.keys(baseShape) : undefined,
+        addedKeys: Object.keys(addedShape ?? {}),
+    };
+}
+/** One call through the extension: its body goes on what the base sends, its reader sees each row first. */
+function extendedCall(base, extension, keys, context, request) {
+    const at = {
+        profileType: context.profileType,
+        apiId: context.apiId,
+        options: pick(context.options, keys.addedKeys),
+    };
+    const pending = [];
+    const reader = extension.read?.({
+        ...at,
+        ...(request ? { request: request } : {}),
+    });
+    const take = (events) => {
+        for (const event of events ?? [])
+            pending.push(stamp(extension, event));
+    };
+    const rewrite = (body, headers, wrote = []) => {
+        if (!extension.body)
+            return { body, wroteTools: wrote };
+        const out = extension.body(body, {
+            ...at,
+            builtInTools: context.builtInTools,
+            headers,
+            ...(request ? { request: request } : {}),
+        });
+        return { body: out.body, wroteTools: [...wrote, ...(out.wroteTools ?? [])] };
+    };
+    async function* read(rows) {
+        for await (const row of rows) {
+            const seen = reader?.row(row);
+            take(seen?.events);
+            if (!seen?.consumed)
+                yield row;
+        }
+    }
+    const inner = {
+        ...context,
+        options: (keys.baseKeys ? pick(context.options, keys.baseKeys) : context.options),
+        send(body, init) {
+            const headers = new Headers(init.headers);
+            const out = rewrite(body, headers, init.wroteTools);
+            return read(context.send(out.body, {
+                ...init,
+                headers: Object.fromEntries(headers),
+                wroteTools: out.wroteTools,
+            }));
+        },
+        async connect(setup, init) {
+            const out = rewrite(setup, new Headers(), init?.wroteTools);
+            const socket = await context.connect(out.body, { wroteTools: out.wroteTools });
+            return { ...socket, frames: () => read(socket.frames()) };
+        },
+    };
+    async function* drained(events) {
+        for await (const event of events) {
+            yield* pending.splice(0);
+            if (event.type === 'done')
+                take(reader?.finish?.().events);
+            yield* pending.splice(0);
+            yield event;
+        }
+        yield* pending.splice(0);
+    }
+    return { operations: base.create(inner), drained };
+}
+/** The operations the base offers, each run as a fresh extended call. */
+function extendedOperations(call) {
+    // invariant: Each call gets its own reader and pending events; the first only says which operations the base has.
+    const offered = call().operations;
+    const operations = {};
+    if (offered.complete)
+        operations.complete = (request) => {
+            const { operations, drained } = call(request);
+            return drained(operations.complete(request));
+        };
+    if (offered.openSession)
+        operations.openSession = async (request) => {
+            const { operations, drained } = call(request);
+            const session = await operations.openSession(request);
+            return { ...session, events: () => drained(session.events()) };
+        };
+    if (offered.decide)
+        operations.decide = (request) => call().operations.decide(request);
+    if (offered.embed)
+        operations.embed = (request) => call().operations.embed(request);
+    return operations;
+}
+/** The extension's own value for a field, else the base's; absent when neither has one. */
+function either(key, extension, base) {
+    const value = extension[key] ?? base[key];
+    return value ? { [key]: value } : {};
+}
+/**
+ * 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 function extendProtocol(base, extension) {
+    checkShape({ ...extension, endpoints: extension.endpoints ?? {} });
+    const keys = mergeOptions(base, extension);
+    return Object.freeze({
+        id: extension.id,
+        name: extension.name,
+        description: extension.description,
+        endpoints: { ...base.endpoints, ...extension.endpoints },
+        options: keys.schema,
+        ...(base.continuation ? { continuation: base.continuation } : {}),
+        ...(extension.reasoning ? { reasoning: extension.reasoning } : {}),
+        ...(extension.custom ? { custom: extension.custom } : {}),
+        ...either('framing', extension, base),
+        ...either('error', extension, base),
+        ...either('embeddingLimits', extension, base),
+        ...either('refusedOptions', extension, base),
+        base: base,
+        lineage: Object.freeze([extension.id, ...base.lineage]),
+        create: (context) => extendedOperations((request) => extendedCall(base, extension, keys, context, request)),
+    });
+}
+/** Whether something `writer` wrote may go back to `target`: the writer is in its lineage. */
+export function carriesTo(writer, target) {
+    return target.lineage.includes(writer);
+}

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

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import type { KeySlot } from '../types.js';
+import { type DecisionModelBinding, type ModelBinding } from './binding.js';
+import type { PriceTable } from './prices.js';
+import { type Protocol } from './protocol.js';
+/** One outgoing call or socket, for a sign-in to put its key on. `body` is final, for signing. */
+export interface Outgoing {
+    transport: 'http' | 'ws';
+    url: URL;
+    headers: Headers;
+    /** WebSocket subprotocols, where some APIs sign in. */
+    protocols: string[];
+    readonly body?: string;
+}
+/** Signs outgoing calls for one key. `invalidate` drops a minted token after an `auth` refusal. */
+export interface Signer {
+    sign(outgoing: Outgoing): void | Promise<void>;
+    invalidate?(): void;
+}
+/**
+ * How a key is put on a request. Made once per registration and key, so a minted token is reused
+ * until it expires. `webSocketHeaders` says it needs headers on a WebSocket, which a browser can't send.
+ */
+export interface Authorize<K = unknown> {
+    (key: K): Signer;
+    readonly webSocketHeaders?: boolean;
+}
+/** A service's address in a connection: HTTP(S), with no credentials in it. Keys go in the vault. */
+export declare const endpointUrlSchema: z.ZodString;
+/** `Authorization: Bearer <key>`. */
+export declare function bearer(): Authorize<string>;
+/** The key in a header of its own, e.g. `x-goog-api-key`, or `api-key` for Azure. */
+export declare function header(name: string): Authorize<string>;
+/** The key in the URL's query, e.g. `key` for Gemini Live's WebSocket. */
+export declare function query(name: string): Authorize<string>;
+/** One protocol a provider serves, and where. `K` is the provider's key. */
+export interface Serve<K = unknown> {
+    protocol: Protocol;
+    baseUrl: string;
+    /** Places the URL when the protocol's path isn't enough, e.g. the model in the path. */
+    url?(at: {
+        path: string;
+        apiId: string;
+        stream: boolean;
+    }): string;
+    /** In place of the provider's sign-in, for this protocol only. */
+    authorize?: Authorize<K>;
+    headers?: Readonly<Record<string, string>>;
+}
+/** A provider: where a service is and how to sign in to it. Data plus one sign-in function. */
+export interface ProviderDefinition<C = unknown, K = unknown> {
+    /** The default id; a registration may rename it. */
+    id: string;
+    name: string;
+    description: string;
+    /** OpenTelemetry `gen_ai.provider.name`; else the id. */
+    traceName?: string;
+    /** What a builder sets when registering it, each field described. */
+    connection?: z.ZodType<C>;
+    /** Absent: no key. Optional: a key may be given. An object for e.g. a service account. */
+    key?: z.ZodType<K | undefined>;
+    authorize?: Authorize<K>;
+    /** Only where the API reports no cost. */
+    prices?: PriceTable;
+    serves(connection: C): Serve<K>[];
+}
+/** A provider as defined; register it to use it. */
+export type Provider<C = unknown, K = unknown> = Readonly<ProviderDefinition<C, K>>;
+/** Defines a provider. Nothing in it can change a request or read a reply. */
+export declare function defineProvider<C = undefined, K = undefined>(definition: ProviderDefinition<C, K>): Provider<C, K>;
+/** What a builder sets when registering a provider. */
+export interface Registration<C> {
+    /** In place of the provider's id, e.g. two `local` servers. */
+    id?: string;
+    connection?: C;
+    keySlot?: KeySlot;
+    fallbackKeySlot?: KeySlot;
+}
+export type ModelSettings<O> = Omit<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'options'> & {
+    options?: O;
+};
+export type DecisionModelSettings<O> = Omit<DecisionModelBinding, 'protocol' | 'provider' | 'apiId' | 'options'> & {
+    options?: O;
+};
+/** A provider registered in a scope, with its connection and slots. */
+export interface RegisteredProvider {
+    readonly id: string;
+    readonly definition: Provider;
+    readonly connection: unknown;
+    readonly keySlot?: KeySlot;
+    readonly fallbackKeySlot?: KeySlot;
+    readonly serves: readonly Serve[];
+    /** A binding for this provider, its options checked against the protocol's schema. */
+    model<O>(protocol: Protocol<O> | string, apiId: string, settings?: ModelSettings<O>): ModelBinding;
+    decisionModel<O>(protocol: Protocol<O> | string, apiId: string, settings?: DecisionModelSettings<O>): DecisionModelBinding;
+}
+export interface ProviderRegistry {
+    /** Refuses an id already registered. */
+    register<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
+    /** Registers in place of the provider with the same id, for a tool that edits a project. */
+    replace<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
+    get(id: string): RegisteredProvider | undefined;
+    require(id: string, apiId: string): RegisteredProvider;
+    list(): RegisteredProvider[];
+    /** Every protocol the registered providers serve, with the protocols they extend. */
+    protocols(): Protocol[];
+}
+export declare function createProviderRegistry(): ProviderRegistry;

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

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { jsonValueSchema } from '../json.js';
+import { decisionModelBindingSchema, keySlotSchema, modelBindingSchema, } from './binding.js';
+import { modelOptions } from './protocol.js';
+function authorizer(sign, webSocketHeaders) {
+    return Object.assign((key) => ({ sign: (outgoing) => sign(key, outgoing) }), {
+        webSocketHeaders,
+    });
+}
+/** A service's address in a connection: HTTP(S), with no credentials in it. Keys go in the vault. */
+export const endpointUrlSchema = z
+    .string()
+    .url()
+    .refine((value) => {
+    // why: what is not a URL is refused by the check above, in its own words.
+    if (!URL.canParse(value))
+        return true;
+    const url = new URL(value);
+    return (['http:', 'https:'].includes(url.protocol) &&
+        !url.username &&
+        !url.password &&
+        ![...url.searchParams.keys()].some((key) => /key|auth|secret|token|password/i.test(key)));
+}, labelText('protocol.endpoint_url'));
+/** `Authorization: Bearer <key>`. */
+export function bearer() {
+    return authorizer((key, outgoing) => outgoing.headers.set('Authorization', `Bearer ${key}`), true);
+}
+/** The key in a header of its own, e.g. `x-goog-api-key`, or `api-key` for Azure. */
+export function header(name) {
+    return authorizer((key, outgoing) => outgoing.headers.set(name, key), true);
+}
+/** The key in the URL's query, e.g. `key` for Gemini Live's WebSocket. */
+export function query(name) {
+    return authorizer((key, outgoing) => outgoing.url.searchParams.set(name, key), false);
+}
+const providerShape = z.object({
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    traceName: z.string().min(1).optional(),
+});
+/** Defines a provider. Nothing in it can change a request or read a reply. */
+export function defineProvider(definition) {
+    const parsed = providerShape.safeParse(definition);
+    if (!parsed.success || typeof definition.serves !== 'function')
+        throw new TheoremError('config', labelText('protocol.definition', {
+            id: String(definition.id),
+            // labels-exempt: builder diagnostic
+            issues: parsed.success ? 'serves is required' : z.prettifyError(parsed.error),
+        }));
+    return Object.freeze({ ...definition });
+}
+function served(provider, protocol) {
+    const serve = provider.serves.find((entry) => entry.protocol.id === protocol);
+    if (!serve)
+        throw new TheoremError('config', labelText('protocol.not_served', { provider: provider.id, protocol }));
+    return serve;
+}
+export function createProviderRegistry() {
+    const providers = new Map();
+    const protocols = new Map();
+    const claim = (protocol) => {
+        const lineage = [];
+        for (let at = protocol; at; at = at.base) {
+            const held = protocols.get(at.id);
+            if (held && held !== at)
+                throw new TheoremError('config', labelText('protocol.id_clash', { protocol: at.id }));
+            lineage.push(at);
+        }
+        return lineage;
+    };
+    const add = (provider, registration, replacing) => {
+        const id = registration.id ?? provider.id;
+        if (!replacing && providers.has(id))
+            throw new TheoremError('config', labelText('protocol.provider_id_clash', { provider: id }));
+        const parsed = provider.connection
+            ? provider.connection.safeParse(registration.connection)
+            : { success: true, data: undefined };
+        if (!parsed.success)
+            throw new TheoremError('config', labelText('protocol.connection', { provider: id, issues: z.prettifyError(parsed.error) }));
+        if (parsed.data !== undefined)
+            jsonValueSchema.parse(parsed.data);
+        if (registration.keySlot !== undefined)
+            keySlotSchema.parse(registration.keySlot);
+        if (registration.fallbackKeySlot !== undefined)
+            keySlotSchema.parse(registration.fallbackKeySlot);
+        if (registration.keySlot && registration.keySlot === registration.fallbackKeySlot)
+            throw new TheoremError('config', labelText('provider.fallback_slot'));
+        if ((registration.keySlot || registration.fallbackKeySlot) && !provider.key)
+            throw new TheoremError('config', labelText('protocol.no_key', { provider: id }));
+        const serves = Object.freeze(provider.serves(parsed.data).map((serve) => Object.freeze({ ...serve })));
+        const claimed = serves.flatMap((serve) => claim(serve.protocol));
+        const optionsOf = (protocol, apiId, options) => {
+            const { protocol: spoken } = served({ id, serves }, typeof protocol === 'string' ? protocol : protocol.id);
+            return { protocol: spoken.id, options: modelOptions(spoken, apiId, options) };
+        };
+        const registered = Object.freeze({
+            id,
+            definition: provider,
+            connection: parsed.data,
+            ...(registration.keySlot ? { keySlot: registration.keySlot } : {}),
+            ...(registration.fallbackKeySlot ? { fallbackKeySlot: registration.fallbackKeySlot } : {}),
+            serves,
+            model(protocol, apiId, settings = {}) {
+                const { options, ...rest } = settings;
+                return modelBindingSchema.parse({
+                    ...rest,
+                    provider: id,
+                    apiId,
+                    ...optionsOf(protocol, apiId, options),
+                });
+            },
+            decisionModel(protocol, apiId, settings = {}) {
+                const { options, ...rest } = settings;
+                return decisionModelBindingSchema.parse({
+                    ...rest,
+                    provider: id,
+                    apiId,
+                    ...optionsOf(protocol, apiId, options),
+                });
+            },
+        });
+        for (const protocol of claimed)
+            protocols.set(protocol.id, protocol);
+        providers.set(id, registered);
+        return registered;
+    };
+    return {
+        register: (provider, registration = {}) => add(provider, registration, false),
+        replace: (provider, registration = {}) => add(provider, registration, true),
+        get: (id) => providers.get(id),
+        require(id, apiId) {
+            const provider = providers.get(id);
+            if (!provider)
+                throw new TheoremError('config', labelText('protocol.provider_missing', { provider: id, apiId }));
+            return provider;
+        },
+        list: () => [...providers.values()],
+        protocols: () => [...protocols.values()],
+    };
+}

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

@@ -0,0 +1,55 @@
+import { type Wait } from '../../providers/shared/retry.js';
+import { type JsonObject } from '../json.js';
+import type { KeyVault } from '../registry/vault.js';
+import type { DecisionResult, KeySlot } from '../types.js';
+import { type DecisionModelBinding, type ModelBinding } from './binding.js';
+import { type ProviderLimits } from './limits.js';
+import type { DecisionCall, EmbeddingCall, EmbeddingResult, ModelProfileType, ProtocolOperations } from './protocol.js';
+import type { RegisteredProvider } from './provider.js';
+/** Opens a WebSocket with the headers and subprotocols a sign-in put on it. */
+export type OpenWebSocket = (url: string, init: {
+    headers: Headers;
+    protocols: string[];
+}) => Promise<WebSocket>;
+/**
+ * The runtime's own WebSocket. It takes no headers, so a sign-in that needs them is refused; a host
+ * that can send them passes `openWebSocket`.
+ */
+export declare function plainWebSocket(provider: string): OpenWebSocket;
+/** What a host lends every provider call: its keys, its network, its clock, and its budgets. */
+export interface ProviderHostOptions {
+    limits?: Partial<ProviderLimits>;
+    vault?: KeyVault;
+    fetch?: typeof fetch;
+    wait?: Wait;
+    openWebSocket?: OpenWebSocket;
+}
+/** One call's setup: a checked binding on its registered provider, and the host's means. */
+export interface CallSetup {
+    provider: RegisteredProvider;
+    binding: ModelBinding | DecisionModelBinding;
+    profileType: ModelProfileType;
+    vault?: KeyVault;
+    fetch?: typeof fetch;
+    wait?: Wait;
+    /** Milliseconds the call has left; a retry never waits past it, so the real cause is reported. */
+    timeLeft?(): number;
+    openWebSocket?: OpenWebSocket;
+    limits?: ProviderLimits;
+    signal?: AbortSignal;
+    tapUpstream?(row: JsonObject): void;
+    /** Hands the wire rows to the stream as `raw` events, for looking around. */
+    rawRows?: boolean;
+    /** Told the slot and key each attempt signs with, so the caller can redact it and key its state. */
+    onKey?(slot: KeySlot | undefined, key: unknown): void;
+}
+/**
+ * One binding's call, as the kernel runs it: the protocol's operations with the kernel's retries,
+ * ids, origins, and prices around them.
+ */
+/** What the kernel runs for one binding. */
+export type ProtocolCall = Required<Omit<ProtocolOperations, 'decide'>> & {
+    decide(request: DecisionCall): Promise<DecisionResult>;
+    embed(request: EmbeddingCall): Promise<EmbeddingResult>;
+};
+export declare function callProtocol(setup: CallSetup): ProtocolCall;