@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,412 @@
+import { kindOfHttpStatus, TheoremError, throwIfAborted, } from '../../guardrails/error.js';
+import { resolveTraceWriter } from '../../observability/policy.js';
+import { writeSpans } from '../../observability/trace.js';
+import { startTrace, traceJson } from '../../observability/trace-span.js';
+import { decisionUsage } from '../../providers/decision/usage.js';
+import { soleModelId } from '../registry/sole-model.js';
+import { isRecord } from '../util/record.js';
+import { endThrownSpan } from './turn-trace.js';
+const TYPESAFE_SYSTEM_ONE_URL = 'https://api.typesafe.ai/v1/systemone';
+const OPENROUTER_DECISIONS_URL = 'https://openrouter.ai/api/alpha/decisions';
+const DECISION_ERROR_KINDS = {
+    invalid_request: 'request',
+    authentication: 'auth',
+    permission: 'auth',
+    rate_limited: 'rate_limit',
+    unavailable: 'unavailable',
+    network: 'network',
+    timeout: 'timeout',
+    cancelled: 'cancelled',
+    malformed_response: 'bad_response',
+    disclosure_blocked: 'blocked',
+};
+/** A normalized native-decision failure; response bodies are deliberately omitted. */
+export class DecisionError extends TheoremError {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(DECISION_ERROR_KINDS[code], message);
+        this.code = code;
+        this.status = status;
+    }
+}
+function requireDecisionProfile(registry, id) {
+    const profile = registry.profiles.get(id);
+    if (profile.type !== 'decision') {
+        throw new TheoremError('request', 
+        // lexicon-exempt: developer contract error
+        `runDecision requires profile.type 'decision' (got '${profile.type}' for ${profile.id})`);
+    }
+    return profile;
+}
+/** The profile's one model; registration guarantees exactly one. */
+function decisionModel(profile) {
+    const modelId = soleModelId(profile.models);
+    const binding = modelId ? profile.models[modelId] : undefined;
+    if (!modelId || !binding) {
+        throw new TheoremError('config', `Profile ${profile.id}: type 'decision' must declare exactly one model`);
+    }
+    return [modelId, binding];
+}
+function finite(value, path, min = 0, max = 1) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+        throw new DecisionError('malformed_response', `${path} is outside its valid range`); // lexicon-exempt: upstream contract error
+    }
+    return value;
+}
+function distribution(value, labels, path) {
+    if (!isRecord(value) ||
+        Object.keys(value).length !== labels.length ||
+        labels.some((key) => !Object.hasOwn(value, key))) {
+        throw new DecisionError('malformed_response', `${path} does not match declared labels`); // lexicon-exempt: upstream contract error
+    }
+    const out = Object.create(null);
+    for (const label of labels)
+        out[label] = finite(value[label], `${path}.${label}`);
+    const total = Object.values(out).reduce((sum, item) => sum + item, 0);
+    if (Math.abs(total - 1) > 0.001) {
+        throw new DecisionError('malformed_response', `${path} must sum to one`); // lexicon-exempt: upstream contract error
+    }
+    return out;
+}
+/** A score's legend: text for every declared level. */
+function legend(value, labels, path) {
+    if (!isRecord(value) ||
+        Object.keys(value).length !== labels.length ||
+        labels.some((label) => !Object.hasOwn(value, label)) ||
+        Object.values(value).some((text) => typeof text !== 'string' || !text.trim())) {
+        throw new DecisionError('malformed_response', `${path} is invalid`); // lexicon-exempt: upstream contract error
+    }
+    return value;
+}
+function validateAnswers(raw, questions) {
+    if (!isRecord(raw) || Object.keys(raw).length !== Object.keys(questions).length) {
+        throw new DecisionError('malformed_response', 
+        // lexicon-exempt: upstream contract error
+        'Decision provider returned an incomplete answer set');
+    }
+    const answers = Object.create(null);
+    for (const [id, question] of Object.entries(questions)) {
+        const answer = raw[id];
+        if (!isRecord(answer) || answer.type !== question.type) {
+            throw new DecisionError('malformed_response', 
+            // lexicon-exempt: upstream contract error
+            `Decision provider returned an invalid answer for '${id}'`);
+        }
+        if (question.type === 'choice') {
+            const labels = Object.keys(question.criteria);
+            if (typeof answer.choice !== 'string' || !labels.includes(answer.choice)) {
+                throw new DecisionError('malformed_response', 
+                // lexicon-exempt: upstream contract error
+                `Decision provider returned an undeclared choice for '${id}'`);
+            }
+            answers[id] = {
+                type: 'choice',
+                choice: answer.choice,
+                confidence: finite(answer.confidence, `${id}.confidence`),
+                probabilities: distribution(answer.probabilities, labels, `${id}.probabilities`),
+            };
+        }
+        else if (question.type === 'noul') {
+            answers[id] = { type: 'noul', noul: finite(answer.noul, `${id}.noul`) };
+        }
+        else {
+            const labels = question.criteria.map((_, index) => String(index));
+            answers[id] = {
+                type: 'score',
+                score: finite(answer.score, `${id}.score`, 0, Math.max(0, labels.length - 1)),
+                confidence: finite(answer.confidence, `${id}.confidence`),
+                legend: legend(answer.legend, labels, `${id}.legend`),
+                probabilities: distribution(answer.probabilities, labels, `${id}.probabilities`),
+            };
+        }
+    }
+    return answers;
+}
+function isJson(value) {
+    const ancestors = new Set();
+    const pending = [{ value }];
+    while (pending.length) {
+        const next = pending.pop();
+        if (!next)
+            break;
+        const item = next.value;
+        if (next.exit) {
+            ancestors.delete(item);
+            continue;
+        }
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            continue;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                return false;
+            continue;
+        }
+        if (typeof item !== 'object' || ancestors.has(item))
+            return false;
+        if (!Array.isArray(item) &&
+            Object.getPrototypeOf(item) !== Object.prototype &&
+            Object.getPrototypeOf(item) !== null)
+            return false;
+        if (Object.getOwnPropertySymbols(item).length)
+            return false;
+        ancestors.add(item);
+        pending.push({ value: item, exit: true });
+        const entries = Array.isArray(item) ? Array.from(item) : Object.values(item);
+        for (const entry of entries)
+            pending.push({ value: entry });
+    }
+    return true;
+}
+function validateQuestion(id, question) {
+    if (!isRecord(question) || !id.trim() || !isDecisionEntry(question.instructions)) {
+        throw new DecisionError('invalid_request', 
+        // lexicon-exempt: developer contract error
+        `Decision question '${id}' must include instructions`);
+    }
+    if (question.type === 'noul' && question.criteria === undefined)
+        return;
+    if (typeof question.type !== 'string' ||
+        !['choice', 'noul', 'score'].includes(question.type) ||
+        (question.type === 'score' ? !Array.isArray(question.criteria) : !isRecord(question.criteria))) {
+        throw new DecisionError('invalid_request', `Decision question '${id}' has invalid criteria`); // lexicon-exempt: developer contract error
+    }
+    const criteria = Array.isArray(question.criteria)
+        ? question.criteria
+        : Object.values(question.criteria);
+    if (!criteria.length || !criteria.every(isDecisionEntry)) {
+        throw new DecisionError('invalid_request', 
+        // lexicon-exempt: developer contract error
+        `Decision ${question.type} '${id}' must declare criteria`);
+    }
+}
+/** Check a decision before a host spends quota or dispatches it. Does not apply model-specific policy. */
+export function validateDecisionRequest(request, profile) {
+    throwIfAborted(request.signal);
+    if (request.model !== undefined) {
+        throw new DecisionError('invalid_request', 
+        // lexicon-exempt: developer contract error
+        'Decision requests do not select a model; the profile runs its one model');
+    }
+    if (request.state === null || !isJson(request.state)) {
+        throw new DecisionError('invalid_request', 'Decision state must be non-null JSON'); // lexicon-exempt: developer contract error
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(request.state);
+    }
+    catch {
+        // lexicon-exempt: developer contract error
+        throw new DecisionError('invalid_request', 'Decision state cannot be serialized as JSON');
+    }
+    const bytes = new TextEncoder().encode(serialized).byteLength;
+    if (profile.inputs.maxStateBytes !== undefined && bytes > profile.inputs.maxStateBytes) {
+        throw new DecisionError('invalid_request', 
+        // lexicon-exempt: developer contract error
+        `Decision state exceeds ${profile.inputs.maxStateBytes} bytes`);
+    }
+    if (!isRecord(request.questions) ||
+        !isJson(request.questions) ||
+        Object.keys(request.questions).length === 0) {
+        throw new DecisionError('invalid_request', 
+        // lexicon-exempt: developer contract error
+        'Decision request must declare at least one question');
+    }
+    for (const [id, question] of Object.entries(request.questions))
+        validateQuestion(id, question);
+}
+function isDecisionEntry(value) {
+    const pending = [value];
+    while (pending.length) {
+        const item = pending.pop();
+        if (typeof item === 'string') {
+            if (!item.trim())
+                return false;
+            continue;
+        }
+        if (!isRecord(item) && !Array.isArray(item))
+            return false;
+        const entries = Object.values(item);
+        if (!entries.length)
+            return false;
+        for (const entry of entries)
+            pending.push(entry);
+    }
+    return true;
+}
+function errorForStatus(status) {
+    if (status === 400 || status === 409 || status === 413 || status === 422)
+        return new DecisionError('invalid_request', 'Provider rejected the decision request', status); // lexicon-exempt: upstream contract error
+    if (status === 401)
+        return new DecisionError('authentication', 'Decision provider authentication failed', status); // lexicon-exempt: upstream contract error
+    if (status === 402 || status === 403)
+        return new DecisionError('permission', 'Decision provider refused the request', status); // lexicon-exempt: upstream contract error
+    if (status === 429)
+        return new DecisionError('rate_limited', 'Decision provider rate limited the request', status); // lexicon-exempt: upstream contract error
+    if (kindOfHttpStatus(status) === 'timeout')
+        return new DecisionError('timeout', 'Decision provider request timed out', status); // lexicon-exempt: upstream contract error
+    return new DecisionError('unavailable', 'Decision provider is unavailable', status); // lexicon-exempt: upstream contract error
+}
+async function enforceDisclosure(profile, model, provider, request) {
+    const verdict = await profile.guardrails?.disclosure?.enforce(request.state, {
+        destination: provider,
+        profileId: profile.id,
+        model,
+        questionIds: Object.keys(request.questions),
+    });
+    if (verdict?.action === 'block') {
+        throw new DecisionError('disclosure_blocked', 'Decision disclosure was blocked'); // lexicon-exempt: developer contract error
+    }
+}
+function requireApiKey(profile, binding, options) {
+    const keySlot = binding.key ?? profile.key;
+    const apiKey = keySlot ? options.vault?.[keySlot]?.trim() : undefined;
+    if (!apiKey)
+        throw new DecisionError('authentication', `the vault has no key in slot '${keySlot}'`); // lexicon-exempt: developer contract error
+    return apiKey;
+}
+async function sendDecisionRequest(args) {
+    try {
+        const response = await (args.options.fetch ?? globalThis.fetch)(args.options.endpoint ??
+            (args.provider === 'openrouter' ? OPENROUTER_DECISIONS_URL : TYPESAFE_SYSTEM_ONE_URL), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${args.apiKey}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify({
+                model: args.apiId,
+                state: args.request.state,
+                questions: args.request.questions,
+            }),
+            signal: args.signal,
+        });
+        if (!response.ok)
+            throw errorForStatus(response.status);
+        return response;
+    }
+    catch (error) {
+        if (error instanceof DecisionError)
+            throw error;
+        if (args.request.signal?.aborted)
+            throw new DecisionError('cancelled', 'Decision request was cancelled'); // lexicon-exempt: developer contract error
+        if (args.signal.aborted)
+            throw new DecisionError('timeout', 'Decision request timed out'); // lexicon-exempt: developer contract error
+        throw new DecisionError('network', 'Decision provider network request failed'); // lexicon-exempt: upstream contract error
+    }
+}
+async function resultFromResponse(response, questions, binding, signal, requestSignal) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        if (requestSignal?.aborted)
+            throw new DecisionError('cancelled', 'Decision request was cancelled'); // lexicon-exempt: developer contract error
+        if (signal.aborted)
+            throw new DecisionError('timeout', 'Decision request timed out'); // lexicon-exempt: developer contract error
+        if (!(error instanceof SyntaxError))
+            throw new DecisionError('network', 'Decision response body could not be read'); // lexicon-exempt: upstream contract error
+        throw new DecisionError('malformed_response', 'Decision provider returned non-JSON output'); // lexicon-exempt: upstream contract error
+    }
+    if (!isRecord(body) ||
+        typeof body.model !== 'string' ||
+        !body.model.trim() ||
+        !isRecord(body.answers)) {
+        throw new DecisionError('malformed_response', 'Decision response has an invalid shape'); // lexicon-exempt: upstream contract error
+    }
+    const usage = decisionUsage(body.usage, binding, body.model);
+    return {
+        model: body.model,
+        answers: validateAnswers(body.answers, questions),
+        ...(usage ? { usage } : {}),
+    };
+}
+function decisionSpanAttributes(profile, modelId, binding, request) {
+    return {
+        'gen_ai.operation.name': 'decide',
+        'gen_ai.provider.name': binding.provider,
+        'gen_ai.agent.name': profile.id,
+        'gen_ai.request.model': binding.apiId,
+        'theorem.model.id': modelId,
+        'theorem.decision.contract': profile.decision.contract,
+        'theorem.decision.state': traceJson(request.state),
+        'theorem.decision.questions': traceJson(request.questions),
+    };
+}
+function recordResult(root, result) {
+    root.set({
+        'gen_ai.response.model': result.model,
+        'theorem.decision.answers': traceJson(result.answers),
+        ...(result.usage
+            ? {
+                'gen_ai.usage.input_tokens': result.usage.inputTokens,
+                'gen_ai.usage.output_tokens': result.usage.outputTokens,
+                ...(result.usage.costUsd === undefined
+                    ? {}
+                    : { 'theorem.usage.cost_usd': result.usage.costUsd }),
+            }
+            : {}),
+    });
+}
+async function decide(profile, [modelId, binding], request, options) {
+    throwIfAborted(request.signal);
+    await enforceDisclosure(profile, modelId, binding.provider, request);
+    throwIfAborted(request.signal);
+    const apiKey = requireApiKey(profile, binding, options);
+    const controller = new AbortController();
+    const timeout = binding.timeoutMs
+        ? setTimeout(() => controller.abort(), binding.timeoutMs)
+        : undefined;
+    const abort = () => controller.abort();
+    request.signal?.addEventListener('abort', abort, { once: true });
+    try {
+        const response = await sendDecisionRequest({
+            request,
+            apiId: binding.apiId,
+            provider: binding.provider,
+            apiKey,
+            options,
+            signal: controller.signal,
+        });
+        return await resultFromResponse(response, request.questions, binding, controller.signal, request.signal);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+        request.signal?.removeEventListener('abort', abort);
+    }
+}
+/**
+ * Exactly one decision request, traced however it ends. An ambiguous POST is never retried,
+ * and a trace write failure never changes the decision's outcome.
+ */
+export async function runDecisionInRegistry(registry, request, options) {
+    const profile = requireDecisionProfile(registry, request.profile);
+    validateDecisionRequest(request, profile);
+    const model = decisionModel(profile);
+    const [modelId, binding] = model;
+    const tree = startTrace(`decide ${binding.apiId}`, {
+        kind: 'CLIENT',
+        attributes: decisionSpanAttributes(profile, modelId, binding, request),
+        ...(request.traceparent ? { traceparent: request.traceparent } : {}),
+    });
+    const { sink, policy } = resolveTraceWriter({
+        override: options.sink,
+        observability: profile.observability,
+    });
+    try {
+        const result = await decide(profile, model, request, options);
+        recordResult(tree.root, result);
+        tree.root.end({ code: 'OK' });
+        return result;
+    }
+    catch (error) {
+        endThrownSpan(tree.root, error);
+        throw error;
+    }
+    finally {
+        await writeSpans(sink, tree.collect(), policy, request.metadata);
+    }
+}

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

@@ -0,0 +1,6 @@
+export declare function sha256(text: string): Promise<string>;
+/** Hashes the decoded bytes, so the hash names the media whatever encoding carried it; `undefined` when not base64. */
+export declare function sha256Base64(base64: string): Promise<{
+    hash: string;
+    bytes: number;
+} | undefined>;

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

@@ -0,0 +1,22 @@
+import { base64ToBytes } from '../util/base64.js';
+const HEX_PAD = 2;
+const HEX_RADIX = 16;
+function hexSha256(bytes) {
+    return [...bytes].map((b) => b.toString(HEX_RADIX).padStart(HEX_PAD, '0')).join('');
+}
+export async function sha256(text) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return hexSha256(new Uint8Array(buf));
+}
+/** Hashes the decoded bytes, so the hash names the media whatever encoding carried it; `undefined` when not base64. */
+export async function sha256Base64(base64) {
+    let raw;
+    try {
+        raw = base64ToBytes(base64);
+    }
+    catch {
+        return undefined;
+    }
+    const buf = await crypto.subtle.digest('SHA-256', raw);
+    return { hash: hexSha256(new Uint8Array(buf)), bytes: raw.byteLength };
+}

package/esm/src/kernel/engine/live-inbound.d.ts

@@ -0,0 +1,9 @@
+import type { TurnEventOf } from '../turn-events.js';
+import type { Profile } from '../types.js';
+export interface LiveInboundPrepareResult {
+    text: string;
+    /** Present when inbound sanitize redacted spans. */
+    guardrail?: TurnEventOf<'guardrail'>;
+}
+declare function prepareLiveInboundText(profile: Profile, text: string): LiveInboundPrepareResult;
+export { prepareLiveInboundText };

package/esm/src/kernel/engine/live-inbound.js

@@ -0,0 +1,19 @@
+import { wrapUserData } from '../../guardrails/canary.js';
+import { guardrailFromHits, projectGuardrailTurnEvent } from '../../guardrails/events.js';
+import { detectionForTrust, resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { detectText } from '../../guardrails/sanitize.js';
+import { resolveObservabilityPolicy } from '../../observability/resolve-policy.js';
+// Resolves through the shared policy so Live ingress and the turn engine cannot drift on what an unset switch means.
+function prepareLiveInboundText(profile, text) {
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const detected = detectText(text, detectionForTrust(policy, 'untrusted'));
+    const raw = guardrailFromHits('live_inbound', 'untrusted', detected.hits, 'redact');
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    const guardrail = raw ? projectGuardrailTurnEvent(raw, includeMatch) : undefined;
+    return {
+        text: wrapUserData(detected.text),
+        ...(guardrail ? { guardrail } : {}),
+    };
+}
+export { prepareLiveInboundText };

package/esm/src/kernel/engine/live-ingress.d.ts

@@ -0,0 +1,9 @@
+import type { LiveIngressSpec, Profile } from '../types.js';
+export type LiveIngressChannel = keyof LiveIngressSpec;
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export declare function liveIngressChannelDefault(channel: LiveIngressChannel): boolean;
+export declare function liveIngressEnabledFromSpec(ingress: LiveIngressSpec | undefined, channel: LiveIngressChannel): boolean;
+export declare function liveIngressEnabled(profile: Profile, channel: LiveIngressChannel): boolean;
+export declare function hasAnyLiveIngress(profile: Profile): boolean;
+export declare function assertLiveIngressConfigured(profile: Profile): void;
+export declare function assertLiveIngress(profile: Profile, channel: LiveIngressChannel): void;

package/esm/src/kernel/engine/live-ingress.js

@@ -0,0 +1,37 @@
+import { TheoremError } from '../../guardrails/error.js';
+const LIVE_INGRESS_CHANNELS = ['audio', 'video', 'text'];
+function assertLiveProfile(profile) {
+    if (profile.type !== 'live') {
+        throw new TheoremError('request', `Profile '${profile.id}' is not type 'live'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return profile;
+}
+/** Default when `live.ingress.<channel>` is omitted — mic and camera on, typed text off. */
+export function liveIngressChannelDefault(channel) {
+    return channel !== 'text';
+}
+export function liveIngressEnabledFromSpec(ingress, channel) {
+    const value = ingress?.[channel];
+    if (value === undefined)
+        return liveIngressChannelDefault(channel);
+    return value;
+}
+export function liveIngressEnabled(profile, channel) {
+    const live = assertLiveProfile(profile);
+    return liveIngressEnabledFromSpec(live.live.ingress, channel);
+}
+export function hasAnyLiveIngress(profile) {
+    const live = assertLiveProfile(profile);
+    return LIVE_INGRESS_CHANNELS.some((channel) => liveIngressEnabledFromSpec(live.live.ingress, channel));
+}
+export function assertLiveIngressConfigured(profile) {
+    const live = assertLiveProfile(profile);
+    if (hasAnyLiveIngress(live))
+        return;
+    throw new TheoremError('config', `Profile '${live.id}': at least one live.ingress channel (audio, video, text) must be enabled`);
+}
+export function assertLiveIngress(profile, channel) {
+    if (liveIngressEnabled(profile, channel))
+        return;
+    throw new TheoremError('request', `Profile '${profile.id}' live.ingress.${channel} is disabled — cannot send on this channel`);
+}

package/esm/src/kernel/engine/media-probe/audio.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Identified by the bytes, not the declared MIME type. Decoded means what a decoder outputs: declared
+ * encoder delay and padding are dropped (Opus pre-skip, `CodecDelay`, `DiscardPadding`, LAME, the MP4
+ * edit list's leading skip); ADTS declares no delay, so its priming samples count. `undefined` when
+ * the duration cannot be read exactly.
+ */
+export declare function audioSeconds(bytes: Uint8Array): number | undefined;