@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -0,0 +1,524 @@
+import { z } from 'zod';
+import { isAbortError, TheoremError, throwIfAborted, } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+import { historyHash, providerCheckpointSchema, } from './checkpoint.js';
+import { historyToolCalls } from './interaction-parts.js';
+import { jsonObjectSchema, jsonValueSchema } from './json.js';
+import { keySlotsOf, protocolOf, } from './protocols/binding.js';
+import { resolveProviderLimits } from './protocols/limits.js';
+import { carriesTo, } from './protocols/protocol.js';
+import { callProtocol, plainWebSocket } from './protocols/runtime.js';
+import { ProviderBudget } from './provider-budget.js';
+import { reasoningPartSchema, turnEventSchema, turnStopSchema, } from './turn-events.js';
+import { isRecord } from './util/record.js';
+const toolCallSchema = z.strictObject({
+    name: z.string().min(1),
+    callId: z.string().min(1),
+    wireCallId: z.string().min(1).optional(),
+    arguments: z.record(z.string(), jsonValueSchema),
+    stepId: z.string().min(1).optional(),
+    stepCallCount: z.number().int().min(1).optional(),
+});
+const reasoningEventSchema = reasoningPartSchema.extend({ type: z.literal('reasoning') });
+const contentTypes = new Set([
+    'text',
+    'thought',
+    'structured',
+    'media',
+    'grounding',
+    'citation',
+    'evidence',
+    'tokens',
+    'session',
+    'tool_draft',
+    'error',
+    'custom',
+]);
+function providerStop(raw) {
+    const stop = turnStopSchema.parse(raw);
+    if (stop.kind === 'gate')
+        throw new TheoremError('bad_response', labelText('provider.kernel_gate'));
+    return stop;
+}
+/** Checks one event a protocol streamed has the shape its type promises. */
+function validateProtocolEvent(raw) {
+    if (!isRecord(raw) || typeof raw.type !== 'string')
+        throw new TheoremError('bad_response', labelText('provider.event_invalid'));
+    if (contentTypes.has(raw.type))
+        return turnEventSchema.parse(raw);
+    switch (raw.type) {
+        case 'tool_call':
+            return { type: 'tool_call', call: toolCallSchema.parse(raw.call) };
+        case 'tool_cancel':
+            return { type: 'tool_cancel', callId: z.string().min(1).parse(raw.callId) };
+        case 'reasoning':
+            return reasoningEventSchema.parse(raw);
+        case 'raw':
+            return { type: 'raw', row: jsonObjectSchema.parse(raw.row) };
+        case 'done':
+            return {
+                type: 'done',
+                stop: providerStop(raw.stop),
+                interrupted: z.boolean().optional().parse(raw.interrupted),
+                state: raw.state,
+            };
+        case 'response':
+            if (!isRecord(raw.response))
+                throw new TheoremError('bad_response', labelText('provider.response_identity'));
+            return {
+                type: 'response',
+                response: z
+                    .strictObject({ id: z.string().optional(), model: z.string().optional() })
+                    .parse(raw.response),
+            };
+        default:
+            throw new TheoremError('bad_response', labelText('provider.event_type', { type: raw.type }));
+    }
+}
+export async function withProviderAbort(operation, signal) {
+    throwIfAborted(signal);
+    if (!signal)
+        return await operation();
+    let abort = () => { };
+    const stopped = new Promise((_resolve, reject) => {
+        abort = () => {
+            try {
+                throwIfAborted(signal);
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+    try {
+        return await Promise.race([
+            Promise.resolve().then(() => {
+                throwIfAborted(signal);
+                return operation();
+            }),
+            stopped,
+        ]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+    }
+}
+function diagnosticCopy(copy, clean) {
+    if (!copy)
+        return undefined;
+    const line = (value) => ({
+        ...value,
+        ...(value.params
+            ? {
+                params: Object.fromEntries(Object.entries(value.params).map(([key, parameter]) => [
+                    key,
+                    typeof parameter === 'string' ? clean(parameter) : parameter,
+                ])),
+            }
+            : {}),
+    });
+    return 'key' in copy ? line(copy) : copy.map(line);
+}
+function diagnosticError(error, clean) {
+    const message = clean(error instanceof Error ? error.message : String(error));
+    if (error instanceof DOMException)
+        return new DOMException(message, error.name);
+    if (isAbortError(error))
+        return new DOMException(message, 'AbortError');
+    const result = error instanceof TheoremError
+        ? new TheoremError(error.kind, message, { copy: diagnosticCopy(error.copy, clean) })
+        : error instanceof TypeError
+            ? new TypeError(message)
+            : new Error(message);
+    if (isRecord(error) && typeof error.status === 'number')
+        Object.assign(result, { status: error.status });
+    return result;
+}
+async function safeProviderCall(operation, clean) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw diagnosticError(error, clean);
+    }
+}
+async function* guardedEvents(events, clean, budget, live = false) {
+    if (!live)
+        budget.resumeOperation();
+    let iterator;
+    try {
+        iterator = events()[Symbol.asyncIterator]();
+        for (;;) {
+            const current = iterator;
+            const next = await withProviderAbort(() => current.next(), budget.signal);
+            if (next.done)
+                break;
+            const event = validateProtocolEvent(next.value);
+            if (live && (event.type !== 'session' || event.session.kind === 'working'))
+                budget.startLiveStep();
+            budget.event(event);
+            if (event.type === 'error')
+                yield {
+                    ...event,
+                    ...(event.errorCopy ? { errorCopy: diagnosticCopy(event.errorCopy, clean) } : {}),
+                    ...(event.errorInternal ? { errorInternal: clean(event.errorInternal) } : {}),
+                    ...(event.error ? { error: clean(event.error) } : {}),
+                };
+            else
+                yield event;
+            if (live && event.type === 'done')
+                budget.resetStep();
+        }
+    }
+    catch (error) {
+        throw diagnosticError(error, clean);
+    }
+    finally {
+        budget.close();
+        if (iterator?.return)
+            void Promise.resolve(iterator.return()).catch(() => undefined);
+    }
+}
+const SECRET_FIELD = /^(?:authorization|proxy-authorization|cookie|set-cookie|api[_-]?key|x-goog-api-key|secret|token|access[_-]?token|refresh[_-]?token|password)$/i;
+/**
+ * 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 function guardedCall(provider, binding, profileType, host, req) {
+    const limits = resolveProviderLimits(host.limits);
+    const budget = new ProviderBudget(limits, req.signal, req.timeoutMs ?? (req.liveConnection ? limits.connectTimeoutMs : limits.operationTimeoutMs));
+    const secrets = new Set();
+    const remember = (value) => {
+        if (typeof value === 'string')
+            secrets.add(value);
+        else if (value && typeof value === 'object')
+            for (const item of Object.values(value))
+                remember(item);
+    };
+    const scrub = (value) => {
+        if (typeof value === 'string') {
+            let clean = value;
+            for (const secret of secrets) {
+                if (secret && (secret.length >= 4 || clean === secret))
+                    clean = clean.split(secret).join('[redacted]');
+            }
+            return clean;
+        }
+        if (Array.isArray(value))
+            return value.map(scrub);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                String(scrub(key)),
+                SECRET_FIELD.test(key) && typeof item === 'string' ? '[redacted]' : scrub(item),
+            ]));
+        return value;
+    };
+    const clean = (text) => String(scrub(text));
+    let slot = keySlotsOf(provider, binding).keySlot;
+    const call = callProtocol({
+        provider,
+        binding,
+        profileType,
+        limits,
+        signal: budget.signal,
+        fetch: budget.fetch(host.fetch ?? globalThis.fetch),
+        openWebSocket: budget.socket(host.openWebSocket ?? plainWebSocket(provider.id)),
+        ...(host.vault ? { vault: host.vault } : {}),
+        ...(host.wait ? { wait: host.wait } : {}),
+        timeLeft: () => budget.timeLeft(),
+        ...(req.tapUpstream
+            ? {
+                tapUpstream: (row) => req.tapUpstream?.(jsonObjectSchema.parse(scrub(row))),
+            }
+            : {}),
+        onKey(used, key) {
+            slot = used;
+            remember(key);
+        },
+    });
+    budget.stopTimer();
+    /** One request with one answer, inside the budget and its abort. */
+    const once = async (run) => {
+        try {
+            budget.resumeOperation();
+            const result = await withProviderAbort(() => safeProviderCall(run, clean), budget.signal);
+            budget.value(result);
+            return result;
+        }
+        finally {
+            budget.close();
+        }
+    };
+    return {
+        keySlot: () => slot,
+        complete: (request) => guardedEvents(() => call.complete({ ...request, signal: budget.signal }), clean, budget),
+        decide: (request) => once(() => call.decide({ ...request, signal: budget.signal })),
+        embed: (request) => once(() => call.embed({ ...request, signal: budget.signal })),
+        async openSession(request) {
+            budget.resumeOperation();
+            const session = await withProviderAbort(() => safeProviderCall(() => call.openSession({ ...request, signal: budget.signal }), clean), budget.signal)
+                .catch((error) => {
+                budget.close();
+                throw error;
+            })
+                .finally(() => budget.stopTimer());
+            return {
+                events: () => guardedEvents(() => session.events(), clean, budget, true),
+                closeInfo: () => {
+                    const closed = session.closeInfo?.();
+                    return (closed && {
+                        ...closed,
+                        ...(closed.error ? { error: diagnosticError(closed.error, clean) } : {}),
+                    });
+                },
+                sendText: (text) => {
+                    budget.startLiveStep();
+                    return safeProviderCall(() => session.sendText(text), clean);
+                },
+                sendAudio: (media) => safeProviderCall(() => session.sendAudio(media), clean),
+                sendVideo: (media) => safeProviderCall(() => session.sendVideo(media), clean),
+                sendContext: (context) => safeProviderCall(() => session.sendContext(context), clean),
+                sendToolResult: (result) => {
+                    budget.startLiveStep();
+                    return safeProviderCall(() => session.sendToolResult(result), clean);
+                },
+                close: (reason) => {
+                    budget.stopTimer();
+                    return safeProviderCall(() => session.close(reason), clean).finally(() => budget.dispose());
+                },
+            };
+        },
+    };
+}
+/** What saved state was written for besides the model: the connection and the keyed options. */
+function compatibilityKey(provider, binding, protocol) {
+    const options = binding.options ?? {};
+    const keyed = [...(protocol.continuation?.keyOptions ?? [])]
+        .sort()
+        .map((name) => [name, options[name] ?? null]);
+    return JSON.stringify({ connection: provider.connection ?? null, options: keyed });
+}
+/** `history: 'stateless'`: every request stands alone, so one that carries a conversation is refused. */
+export function assertHistoryKept(policy, checkpoint, history) {
+    if (policy?.history === 'stateless' && (checkpoint || history?.length))
+        throw new TheoremError('request', labelText('provider.stateless_history'));
+}
+/**
+ * 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 async function restoreProviderState(provider, binding, raw, history, policy = {}) {
+    if (!raw)
+        return {};
+    const checkpoint = providerCheckpointSchema.parse(raw);
+    const protocol = protocolOf(provider, binding);
+    const contract = protocol.continuation;
+    let reason;
+    if (checkpoint.protocol !== protocol.id || checkpoint.provider !== provider.id)
+        reason = 'provider_changed';
+    else if (checkpoint.apiId !== binding.apiId)
+        reason = 'model_changed';
+    else if (!contract || checkpoint.version !== contract.version)
+        reason = 'version_changed';
+    else if (checkpoint.compatibilityKey !== compatibilityKey(provider, binding, protocol))
+        reason = 'connection_changed';
+    else if (checkpoint.keySlot !== keySlotsOf(provider, binding).keySlot)
+        reason = 'key_changed';
+    else if (policy.history === 'provider'
+        ? history.length > 0
+        : checkpoint.coveredHistoryLength > history.length ||
+            checkpoint.coveredHistoryHash !==
+                (await historyHash(history.slice(0, checkpoint.coveredHistoryLength))))
+        reason = 'history_changed';
+    if (reason)
+        return { warning: { code: 'provider_state_rebuilt', reason } };
+    return {
+        state: contract?.schema.parse(checkpoint.data),
+        covered: policy.history === 'provider' ? 0 : checkpoint.coveredHistoryLength,
+        ...(checkpoint.wireCallIds ? { wireCallIds: checkpoint.wireCallIds } : {}),
+    };
+}
+/** Saves a protocol's state with what it was written for, or nothing when it kept none. */
+export async function checkpointProviderState(provider, binding, keySlot, state, history, wireCallIds = {}) {
+    if (state === undefined)
+        return undefined;
+    const protocol = protocolOf(provider, binding);
+    const contract = protocol.continuation;
+    if (!contract)
+        throw new TheoremError('bad_response', labelText('provider.continuation_contract'));
+    return {
+        protocol: protocol.id,
+        provider: provider.id,
+        version: contract.version,
+        apiId: binding.apiId,
+        ...(keySlot ? { keySlot } : {}),
+        compatibilityKey: compatibilityKey(provider, binding, protocol),
+        coveredHistoryLength: history.length,
+        coveredHistoryHash: await historyHash(history),
+        data: jsonValueSchema.parse(contract.schema.parse(state)),
+        ...(Object.keys(wireCallIds).length ? { wireCallIds } : {}),
+    };
+}
+/** Each message's reasoning, kept only where the target protocol can read it back. */
+function carriedHistory(history, protocol) {
+    return history?.map((message) => {
+        if (!message.reasoning)
+            return message;
+        const { reasoning, ...rest } = message;
+        const carried = reasoning.filter((part) => carriesTo(part.origin.protocol, protocol));
+        return carried.length ? { ...rest, reasoning: carried } : rest;
+    });
+}
+/** History with each call the saved state holds under the wire's own id, as the wire knows it. */
+function wireHistory(history, wireCallIds) {
+    if (!history || !wireCallIds)
+        return history;
+    const wire = (id) => wireCallIds[id] ?? id;
+    return history.map((message) => ({
+        ...message,
+        ...(message.tool_calls
+            ? { tool_calls: message.tool_calls.map((call) => ({ ...call, id: wire(call.id) })) }
+            : {}),
+        ...(message.tool_call_id ? { tool_call_id: wire(message.tool_call_id) } : {}),
+    }));
+}
+/** The engine's request as the protocol gets it, with its saved state when reused. */
+export function protocolRequest(request, protocol, restored) {
+    const { providerState: _checkpoint, tapUpstream: _tap, history, ...portable } = request;
+    const carried = wireHistory(carriedHistory(history, protocol), restored.wireCallIds);
+    return {
+        ...portable,
+        ...(carried ? { history: carried } : {}),
+        ...(restored.state !== undefined
+            ? { state: restored.state, stateHistoryLength: restored.covered }
+            : {}),
+    };
+}
+/** A call the kernel hands on: its Theorem id, never the wire's. */
+export function kernelCall(call) {
+    const { wireCallId: _wire, ...rest } = call;
+    return rest;
+}
+async function* consumeModelStep(events, signal) {
+    const wireCallIds = {};
+    let terminal;
+    let failed = false;
+    const pending = [];
+    const reasoning = [];
+    let text = '';
+    const outputs = [];
+    const flushText = () => {
+        if (text)
+            outputs.push({ role: 'assistant', content: text });
+        text = '';
+    };
+    const iterator = events[Symbol.asyncIterator]();
+    let exhausted = false;
+    try {
+        for (;;) {
+            const next = await withProviderAbort(() => iterator.next(), signal);
+            if (next.done) {
+                exhausted = true;
+                break;
+            }
+            throwIfAborted(signal);
+            const event = next.value;
+            if (terminal)
+                throw new TheoremError('bad_response', labelText('provider.events_after_completion'));
+            switch (event.type) {
+                case 'raw':
+                    continue;
+                case 'text':
+                    text += event.text;
+                    break;
+                case 'structured':
+                    flushText();
+                    outputs.push({ role: 'assistant', content: JSON.stringify(event.structured) });
+                    break;
+                case 'reasoning': {
+                    const { type: _type, ...part } = event;
+                    reasoning.push(part);
+                    break;
+                }
+                case 'tool_call':
+                    if (pending.some((call) => call.callId === event.call.callId))
+                        throw new TheoremError('bad_response', labelText('provider.duplicate_call'));
+                    flushText();
+                    if (event.call.wireCallId)
+                        wireCallIds[event.call.callId] = event.call.wireCallId;
+                    pending.push(kernelCall(event.call));
+                    continue;
+                case 'tool_cancel':
+                    throw new TheoremError('bad_response', labelText('provider.tool_cancel_live'));
+                case 'error':
+                    failed = true;
+                    break;
+                case 'done':
+                    terminal = event;
+                    continue;
+            }
+            yield event;
+        }
+    }
+    finally {
+        if (!exhausted && iterator.return)
+            void Promise.resolve(iterator.return()).catch(() => undefined);
+    }
+    flushText();
+    return { terminal, failed, pending, reasoning, outputs, wireCallIds };
+}
+/**
+ * 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 function registeredTurnModel(provider, binding, profileType, host, initial, policy = {}, hostHistory = []) {
+    const protocol = protocolOf(provider, binding);
+    let active = initial;
+    return {
+        async *complete(req) {
+            // invariant: Only the checkpoint the host handed in follows the profile's history holder,
+            // judged against the history the host passed. A checkpoint from an earlier step of this
+            // turn always covers this turn's own history.
+            const providerHeld = active === initial && policy.history === 'provider';
+            const restored = await restoreProviderState(provider, binding, active, providerHeld ? hostHistory : (req.history ?? []), providerHeld ? policy : {});
+            if (restored.warning) {
+                active = undefined;
+                yield { type: 'provider_warning', warning: restored.warning };
+            }
+            const call = guardedCall(provider, binding, profileType, host, req);
+            const { terminal, failed, pending, reasoning, outputs, wireCallIds } = yield* consumeModelStep(call.complete(protocolRequest(req, protocol, restored)), req.signal);
+            throwIfAborted(req.signal);
+            if (!terminal) {
+                yield { type: 'done', stop: { kind: failed ? 'provider_error' : 'stream_incomplete' } };
+                return;
+            }
+            if (failed ||
+                terminal.interrupted ||
+                (terminal.stop.kind !== 'tool' && terminal.stop.kind !== 'completed')) {
+                yield { type: 'done', stop: terminal.stop };
+                return;
+            }
+            if (pending.length)
+                outputs.push(historyToolCalls(pending.map((entry, index) => (index === 0 ? { ...entry, reasoning } : entry))));
+            const history = [...(req.history ?? [])];
+            if (req.input.length)
+                history.push(req.input.every((part) => part.type === 'text')
+                    ? {
+                        role: 'user',
+                        content: req.input.map((part) => (part.type === 'text' ? part.text : '')).join(''),
+                    }
+                    : { role: 'user', parts: req.input });
+            const checkpoint = await checkpointProviderState(provider, binding, call.keySlot(), terminal.state, [
+                ...history,
+                ...(pending.length ? outputs.filter((message) => message.tool_calls) : outputs),
+            ], { ...restored.wireCallIds, ...wireCallIds });
+            active = checkpoint;
+            for (const entry of pending)
+                yield { type: 'tool', tool: entry };
+            yield { type: 'done', stop: terminal.stop, providerState: checkpoint };
+        },
+    };
+}

package/esm/src/kernel/registry/attachments.d.ts

@@ -1,10 +1,13 @@
+import type { BoundaryReader } from '../../guardrails/detect-at.js';
 import { type ErrorCopy, TheoremError } from '../../guardrails/error.js';
-import { type LexiconOverrides } from '../../guardrails/lexicon.js';
+import { type LabelOverrides } from '../../guardrails/labels.js';
 import type { AttachmentValidationIssue, MediaLimits, MimeInputs, Profile, TurnBlob, TurnMediaRef } from '../types.js';
+/** The media limits an inputs spec sets, or `undefined` unless it sets `maxFiles`, `maxBytes`, and `maxTurnBytes`. */
 declare function resolveMediaLimits(inputs: MimeInputs): MediaLimits | undefined;
 /** A MIME-specific cap, then its category wildcard, then the global cap. */
 declare function maxBytesForMime(mimeType: string, limits: MediaLimits): number;
 declare function isTurnMediaRef(item: TurnBlob | TurnMediaRef): item is TurnMediaRef;
+/** The profile's media limits; throws when it takes no media. */
 declare function requireMediaLimits(profile: Profile): MediaLimits;
 /** CSV formula injection: formula-like cells get an apostrophe before they reach a model. */
 declare function sanitizeCsvText(text: string): string;
@@ -22,14 +25,22 @@ export interface AttachmentRules {
 }
 /** The one attachment check: the kernel throws on it at ingress and the headless interface runs it before a send. */
 declare function attachmentIssues(rules: AttachmentRules, files: AttachmentFacts[], clips: AttachmentFacts[]): AttachmentValidationIssue[];
+/** The user-facing wording key and params for an attachment issue. */
 declare function attachmentIssueCopy(issue: AttachmentValidationIssue): ErrorCopy;
-declare function attachmentIssueText(issue: AttachmentValidationIssue, lexicon?: LexiconOverrides): string;
+/** The user-facing text for an attachment issue. */
+declare function attachmentIssueText(issue: AttachmentValidationIssue, labels?: LabelOverrides): string;
+/** The error for a turn whose attachments were refused. */
 declare function attachmentsRefused(issues: readonly AttachmentValidationIssue[]): TheoremError;
+/** The decoded size of inline base64 data; throws when it is not base64. */
+declare function base64Bytes(data: string): number;
 /** Provider references are checked for MIME and count; byte limits apply to inline blobs only. */
 declare function assertTurnAttachments(profile: Profile, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined): void;
 /** Provider file references pass through unsanitized: the kernel has no bytes to scan. */
-declare function sanitizeTurnBlobs(profile: Profile, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined): {
+declare function sanitizeTurnBlobs(profile: Profile, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined, at: {
+    attachment: BoundaryReader;
+    voice: BoundaryReader;
+}): {
     attachments?: Array<TurnBlob | TurnMediaRef>;
     voice?: TurnBlob[];
 };
-export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };
+export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };