@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,439 @@
+import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { traceJson } from '../../observability/trace-span.js';
+import { guardedCall } from '../provider-runtime.js';
+import { soleModelId } from '../registry/sole-model.js';
+import { isRecord } from '../util/record.js';
+import { tracedCall } from './call-trace.js';
+/** Where the provider takes decision requests, as its preset states. */
+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. What the
+ * provider path threw is its `cause`, and a failure the framework named reads as that failure.
+ */
+export class DecisionError extends TheoremError {
+    code;
+    status;
+    constructor(code, message, status, options) {
+        super(DECISION_ERROR_KINDS[code], message, options);
+        this.code = code;
+        this.status = status;
+    }
+}
+function requireDecisionProfile(registry, id) {
+    const profile = registry.profiles.get(id);
+    if (profile.type !== 'decision') {
+        throw new TheoremError('request', 
+        // labels-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`); // labels-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`); // labels-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`); // labels-exempt: upstream contract error
+    }
+    return out;
+}
+/** A box's four edges, each a fraction of the image, with the low edge before the high one. */
+function box(value, path) {
+    if (!isRecord(value))
+        throw new DecisionError('malformed_response', `${path} is invalid`); // labels-exempt: upstream contract error
+    const edges = {
+        top: finite(value.top, `${path}.top`),
+        bottom: finite(value.bottom, `${path}.bottom`),
+        left: finite(value.left, `${path}.left`),
+        right: finite(value.right, `${path}.right`),
+    };
+    if (edges.left >= edges.right || edges.top >= edges.bottom)
+        throw new DecisionError('malformed_response', `${path} has an edge out of order`); // labels-exempt: upstream contract error
+    return edges;
+}
+/** 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`); // labels-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', 
+        // labels-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', 
+            // labels-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', 
+                // labels-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 if (question.type === 'box') {
+            answers[id] = {
+                type: 'box',
+                box: box(answer.box, `${id}.box`),
+                confidence: finite(answer.confidence, `${id}.confidence`),
+            };
+        }
+        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', 
+        // labels-exempt: developer contract error
+        `Decision question '${id}' must include instructions`);
+    }
+    if ((question.type === 'noul' || question.type === 'box') && 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`); // labels-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', 
+        // labels-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', 
+        // labels-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'); // labels-exempt: developer contract error
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(request.state);
+    }
+    catch {
+        // labels-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', 
+        // labels-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', 
+        // labels-exempt: developer contract error
+        'Decision request must declare at least one question');
+    }
+    for (const [id, question] of Object.entries(request.questions))
+        validateQuestion(id, question);
+    if (request.assets !== undefined)
+        validateAssets(request.assets);
+    for (const [id, question] of Object.entries(request.questions))
+        validateBoxImage(id, question, request.state, request.assets);
+}
+function stateAt(state, path) {
+    let value = state;
+    for (const step of path.split('.')) {
+        if (!isRecord(value) && !Array.isArray(value))
+            return undefined;
+        value = Array.isArray(value) ? value[Number(step)] : value[step];
+    }
+    return value;
+}
+/** A box's image names an image the request holds, itself or through the state field it gives. */
+function validateBoxImage(id, question, state, assets) {
+    if (!isRecord(question) || question.image === undefined)
+        return;
+    const image = question.image;
+    const reference = typeof image === 'string' && !assets?.[image] ? stateAt(state, image) : image;
+    if (question.type !== 'box' || typeof reference !== 'string' || assets?.[reference] === undefined)
+        throw new DecisionError('invalid_request', 
+        // labels-exempt: developer contract error
+        `Decision question '${id}' has an image that is neither a held image nor a state field holding one`);
+}
+/** The question as a provider reads it: a box's image said in its instructions, not as a field. */
+function providerQuestion(question, assets) {
+    if (question.type !== 'box' || question.image === undefined)
+        return question;
+    const { image, instructions } = question;
+    const hint = labelText('decision.box_image', {
+        image: assets?.[image] ? image : `\`${image}\``,
+    });
+    return {
+        type: 'box',
+        instructions: typeof instructions === 'string' ? `${instructions} ${hint}` : [instructions, hint],
+    };
+}
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+/** Only what any provider needs: a known image type and bare, padded base64. The provider holds its own limits. */
+function validateAssets(assets) {
+    if (!isRecord(assets) || Object.keys(assets).length === 0)
+        throw new DecisionError('invalid_request', 'Decision assets must name at least one image'); // labels-exempt: developer contract error
+    for (const [reference, asset] of Object.entries(assets)) {
+        if (!reference.trim() ||
+            !isRecord(asset) ||
+            (asset.mimeType !== 'image/png' && asset.mimeType !== 'image/jpeg') ||
+            typeof asset.data !== 'string' ||
+            asset.data.length % 4 !== 0 ||
+            !BASE64.test(asset.data))
+            throw new DecisionError('invalid_request', 
+            // labels-exempt: developer contract error
+            `Decision asset '${reference}' must be PNG or JPEG bytes as padded base64`);
+    }
+}
+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;
+}
+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),
+        ...(request.assets ? { assets: request.assets } : {}),
+    });
+    if (verdict?.action === 'block') {
+        throw new DecisionError('disclosure_blocked', 'Decision disclosure was blocked'); // labels-exempt: developer contract error
+    }
+}
+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),
+        ...(request.assets
+            ? {
+                // invariant: Image bytes never reach a trace; it keeps each image's type and size.
+                'theorem.decision.assets': traceJson(Object.fromEntries(Object.entries(request.assets).map(([reference, { mimeType, data }]) => [
+                    reference,
+                    { mimeType, bytes: data.length },
+                ]))),
+            }
+            : {}),
+    };
+}
+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 }),
+            }
+            : {}),
+    });
+}
+function decisionProviderError(error) {
+    if (error instanceof DecisionError)
+        return error;
+    const kind = error instanceof TheoremError
+        ? error.kind
+        : error instanceof TypeError
+            ? 'network'
+            : 'bad_response';
+    const codes = {
+        auth: 'authentication',
+        rate_limit: 'rate_limited',
+        network: 'network',
+        unavailable: 'unavailable',
+        timeout: 'timeout',
+        cancelled: 'cancelled',
+        request: 'invalid_request',
+        unsupported: 'invalid_request',
+    };
+    const code = kind === 'auth' && isRecord(error) && error.status === 403
+        ? 'permission'
+        : (codes[kind] ?? 'malformed_response');
+    return new DecisionError(code, 
+    // why: A framework failure's message holds no response body, and says what stopped the decision.
+    error instanceof TheoremError ? error.message : labelText('provider.decision_failed'), isRecord(error) && typeof error.status === 'number' ? error.status : undefined, { cause: error });
+}
+async function decide(registry, profile, [modelId, binding], request, options) {
+    throwIfAborted(request.signal);
+    const provider = registry.providers.require(binding.provider, binding.apiId);
+    await enforceDisclosure(profile, modelId, binding.provider, request);
+    throwIfAborted(request.signal);
+    try {
+        const call = guardedCall(provider, binding, 'decision', options, {
+            ...(request.signal ? { signal: request.signal } : {}),
+            ...(binding.timeoutMs ? { timeoutMs: binding.timeoutMs } : {}),
+        });
+        const result = await call.decide({
+            apiId: binding.apiId,
+            state: request.state,
+            questions: Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
+                id,
+                providerQuestion(question, request.assets),
+            ])),
+            ...(request.assets ? { assets: request.assets } : {}),
+        });
+        if (typeof result.model !== 'string' || !result.model.trim())
+            throw new DecisionError('malformed_response', labelText('provider.decision_model_missing'));
+        return { ...result, answers: validateAnswers(result.answers, request.questions) };
+    }
+    catch (error) {
+        if (request.signal?.aborted)
+            throw new DecisionError('cancelled', labelText('provider.decision_ended'));
+        throw decisionProviderError(error);
+    }
+}
+/**
+ * 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;
+    return await tracedCall({
+        name: `decide ${binding.apiId}`,
+        attributes: decisionSpanAttributes(profile, modelId, binding, request),
+        traceparent: request.traceparent,
+        metadata: request.metadata,
+        writer: {
+            override: options.sink,
+            observability: profile.observability,
+            guardrails: profile.guardrails,
+        },
+    }, async (root) => {
+        const result = await decide(registry, profile, model, request, options);
+        recordResult(root, result);
+        return result;
+    });
+}

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

@@ -0,0 +1,8 @@
+import type { TraceSink } from '../../observability/trace-sink.js';
+import type { ProviderHostOptions } from '../protocols/runtime.js';
+import type { KernelRegistry } from '../registry/kernel-registry.js';
+import type { EmbeddingRequest, EmbeddingResult } from '../types.js';
+export interface RunEmbeddingOptions extends ProviderHostOptions {
+    sink?: TraceSink;
+}
+export declare function runEmbeddingInRegistry(registry: KernelRegistry, request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;

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

@@ -0,0 +1,118 @@
+import { refuseOverlong } from '../../guardrails/detect-at.js';
+import { TheoremError, throwIfAborted } from '../../guardrails/error.js';
+import { protocolOf } from '../protocols/binding.js';
+import { guardedCall } from '../provider-runtime.js';
+import { attachmentsRefused, base64Bytes } from '../registry/attachments.js';
+import { embeddingMediaIssues, embeddingRules } from '../registry/embedding-rules.js';
+import { tracedCall } from './call-trace.js';
+function requireEmbeddingProfile(registry, id) {
+    const profile = registry.profiles.get(id);
+    if (profile.type !== 'embedding')
+        throw new TheoremError('request', `runEmbedding requires profile.type 'embedding' (got '${profile.type}' for ${id})`);
+    return profile;
+}
+function chooseModel(profile, requested) {
+    const modelId = requested ?? profile.defaultModel;
+    if (requested && !profile.allowModelSelect)
+        throw new TheoremError('request', `Profile ${profile.id} does not allow model selection`); // labels-exempt: developer contract error
+    const binding = profile.models[modelId];
+    if (!binding)
+        throw new TheoremError('request', `Unknown model '${modelId}' for ${profile.id}`); // labels-exempt: developer contract error
+    return [modelId, binding];
+}
+const TASKS = ['query', 'document'];
+function checkTask(task) {
+    if (task !== undefined && !TASKS.includes(task))
+        throw new TheoremError('request', `Embedding task must be 'query' or 'document'`); // labels-exempt: developer contract error
+}
+function inputsOf(input) {
+    return Array.isArray(input) ? input : [input];
+}
+/** An input's parts; a bare string is one text part. */
+function partsOf(input) {
+    if (typeof input === 'string')
+        return [{ type: 'text', text: input }];
+    return input && Array.isArray(input.parts) ? input.parts : [];
+}
+/** Text is checked per part; media per input, held to the profile and to what the model takes. */
+function validateInputs(profile, modelId, inputs, model) {
+    const rules = embeddingRules(profile.inputs, model);
+    if (rules.maxInputs !== undefined && inputs.length > rules.maxInputs)
+        throw new TheoremError('request', `Model '${modelId}' of ${profile.id} takes at most ${rules.maxInputs} inputs per request`);
+    const media = [];
+    for (const input of inputs) {
+        const parts = partsOf(input);
+        if (parts.length === 0)
+            throw new TheoremError('request', `Profile ${profile.id} received an empty embedding input`); // labels-exempt: developer contract error
+        const files = [];
+        for (const part of parts) {
+            if (part.type === 'text') {
+                refuseOverlong(part.text, 'embedding input');
+                if (!rules.text)
+                    throw new TheoremError('unsupported', `Profile ${profile.id} does not accept text embedding input`);
+                continue;
+            }
+            files.push(part.type === 'media'
+                ? { mimeType: part.mimeType, sizeBytes: base64Bytes(part.data) }
+                : { mimeType: part.mimeType });
+        }
+        media.push(files);
+    }
+    const issues = embeddingMediaIssues(rules, media);
+    if (issues.length > 0)
+        throw attachmentsRefused(issues);
+}
+function validateResult(result, count) {
+    if (!result.model.trim() || result.embeddings.length !== count)
+        throw new TheoremError('bad_response', 'Embedding provider returned an invalid vector count'); // labels-exempt: upstream contract error
+    const embeddings = result.embeddings.map((vector, index) => {
+        if (vector.index !== index ||
+            vector.dimensions !== vector.values.length ||
+            vector.dimensions === 0)
+            throw new TheoremError('bad_response', 'Embedding provider returned invalid vector metadata'); // labels-exempt: upstream contract error
+        if (vector.values.some((value) => !Number.isFinite(value)))
+            throw new TheoremError('bad_response', 'Embedding provider returned a non-finite vector value');
+        return vector;
+    });
+    return { ...result, embeddings };
+}
+export async function runEmbeddingInRegistry(registry, request, options = {}) {
+    throwIfAborted(request.signal);
+    const profile = requireEmbeddingProfile(registry, request.profile);
+    const [modelId, binding] = chooseModel(profile, request.model);
+    const inputs = inputsOf(request.input);
+    checkTask(request.task);
+    const provider = registry.providers.require(binding.provider, binding.apiId);
+    validateInputs(profile, modelId, inputs, protocolOf(provider, binding).embeddingLimits?.(binding.apiId));
+    const call = guardedCall(provider, binding, 'embedding', options, {
+        ...(request.signal ? { signal: request.signal } : {}),
+    });
+    return await tracedCall({
+        name: `embed ${binding.apiId}`,
+        attributes: {
+            'gen_ai.operation.name': 'embeddings',
+            'gen_ai.provider.name': binding.provider,
+            'gen_ai.agent.name': profile.id,
+            'gen_ai.request.model': binding.apiId,
+            'theorem.model.id': modelId,
+            'theorem.embedding.inputs': inputs.length,
+            ...(request.task ? { 'theorem.embedding.task': request.task } : {}),
+        },
+        traceparent: request.traceparent,
+        metadata: request.metadata,
+        writer: {
+            override: options.sink,
+            observability: profile.observability,
+            guardrails: profile.guardrails,
+        },
+    }, async () => {
+        const result = await call.embed({
+            apiId: binding.apiId,
+            input: request.input,
+            ...(request.task ? { task: request.task } : {}),
+            ...(binding.options ? { options: binding.options } : {}),
+            ...(request.signal ? { signal: request.signal } : {}),
+        });
+        return validateResult(result, inputs.length);
+    });
+}

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,19 @@
+import type { TurnEventOf } from '../turn-events.js';
+import type { Profile, TurnContext } from '../types.js';
+export interface LiveInboundPrepareResult {
+    /** The message to send, wrapped as user data. Absent when a match blocks: it does not reach the model. */
+    text?: string;
+    /** Present when a detector matched. */
+    guardrail?: TurnEventOf<'guardrail'>;
+}
+/** Reads text a live session receives from the user at the `live_user` boundary, wraps what crosses as user data, and returns the guardrail event when something matched. */
+declare function prepareLiveInboundText(profile: Profile, text: string): LiveInboundPrepareResult;
+export interface LiveContextPrepareResult {
+    /** Each package that crossed, in its sender's fence, the host's first. */
+    texts: string[];
+    /** One per package a detector matched in. */
+    guardrails: TurnEventOf<'guardrail'>[];
+}
+/** Reads each sender's context at the `context` boundary, as a turn does. A package a match blocks does not reach the model. */
+declare function prepareLiveContext(profile: Profile, context: TurnContext): LiveContextPrepareResult;
+export { prepareLiveContext, prepareLiveInboundText };

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

@@ -0,0 +1,44 @@
+import { wrapContext, wrapUserData } from '../../guardrails/canary.js';
+import { boundaryReader, detectAt, detectEvent } from '../../guardrails/detect-at.js';
+import { guardrailTurnEvent, projectGuardrailTurnEvent } from '../../guardrails/events.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { sanitizeContext } from '../../guardrails/sanitize.js';
+import { resolveObservabilityPolicy } from '../../observability/resolve-policy.js';
+import { CONTEXT_SENDERS } from '../schema.js';
+// why: Resolves through the shared policy so Live ingress and the turn engine cannot drift on what an unset switch means.
+/** Reads text a live session receives from the user at the `live_user` boundary, wraps what crosses as user data, and returns the guardrail event when something matched. */
+function prepareLiveInboundText(profile, text) {
+    const { detect } = resolveGuardrailPolicy(profile.guardrails);
+    const detected = detectAt(text, 'live_user', detect);
+    const event = detectEvent('live_user', detected);
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    const guardrail = event
+        ? projectGuardrailTurnEvent(guardrailTurnEvent(event), includeMatch)
+        : undefined;
+    return {
+        ...(detected.text === undefined ? {} : { text: wrapUserData(detected.text) }),
+        ...(guardrail ? { guardrail } : {}),
+    };
+}
+/** Reads each sender's context at the `context` boundary, as a turn does. A package a match blocks does not reach the model. */
+function prepareLiveContext(profile, context) {
+    const { detect } = resolveGuardrailPolicy(profile.guardrails);
+    const includeMatch = resolveObservabilityPolicy(profile.observability).include
+        .guardrailMatchPreview;
+    const texts = [];
+    const guardrails = [];
+    for (const sender of [...CONTEXT_SENDERS].reverse()) {
+        if (context[sender] === undefined)
+            continue;
+        const read = sanitizeContext({ [sender]: context[sender] }, () => boundaryReader('context', detect));
+        for (const event of read.events) {
+            guardrails.push(projectGuardrailTurnEvent(guardrailTurnEvent(event), includeMatch));
+        }
+        const text = read.context?.[sender];
+        if (!read.blocked && typeof text === 'string')
+            texts.push(wrapContext(sender, text));
+    }
+    return { texts, guardrails };
+}
+export { prepareLiveContext, prepareLiveInboundText };