@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -1,13 +1,11 @@
-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 { 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 { 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';
+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',
@@ -20,12 +18,15 @@ const DECISION_ERROR_KINDS = {
     malformed_response: 'bad_response',
     disclosure_blocked: 'blocked',
 };
-/** A normalized native-decision failure; response bodies are deliberately omitted. */
+/**
+ * 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) {
-        super(DECISION_ERROR_KINDS[code], message);
+    constructor(code, message, status, options) {
+        super(DECISION_ERROR_KINDS[code], message, options);
         this.code = code;
         this.status = status;
     }
@@ -34,7 +35,7 @@ function requireDecisionProfile(registry, id) {
     const profile = registry.profiles.get(id);
     if (profile.type !== 'decision') {
         throw new TheoremError('request', 
-        // lexicon-exempt: developer contract error
+        // labels-exempt: developer contract error
         `runDecision requires profile.type 'decision' (got '${profile.type}' for ${profile.id})`);
     }
     return profile;
@@ -50,7 +51,7 @@ function decisionModel(profile) {
 }
 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
+        throw new DecisionError('malformed_response', `${path} is outside its valid range`); // labels-exempt: upstream contract error
     }
     return value;
 }
@@ -58,31 +59,45 @@ 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
+        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`); // lexicon-exempt: upstream contract error
+        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`); // lexicon-exempt: upstream contract error
+        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', 
-        // lexicon-exempt: upstream contract error
+        // labels-exempt: upstream contract error
         'Decision provider returned an incomplete answer set');
     }
     const answers = Object.create(null);
@@ -90,14 +105,14 @@ function validateAnswers(raw, questions) {
         const answer = raw[id];
         if (!isRecord(answer) || answer.type !== question.type) {
             throw new DecisionError('malformed_response', 
-            // lexicon-exempt: upstream contract error
+            // 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', 
-                // lexicon-exempt: upstream contract error
+                // labels-exempt: upstream contract error
                 `Decision provider returned an undeclared choice for '${id}'`);
             }
             answers[id] = {
@@ -110,6 +125,13 @@ function validateAnswers(raw, questions) {
         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] = {
@@ -161,22 +183,22 @@ function isJson(value) {
 function validateQuestion(id, question) {
     if (!isRecord(question) || !id.trim() || !isDecisionEntry(question.instructions)) {
         throw new DecisionError('invalid_request', 
-        // lexicon-exempt: developer contract error
+        // labels-exempt: developer contract error
         `Decision question '${id}' must include instructions`);
     }
-    if (question.type === 'noul' && question.criteria === undefined)
+    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`); // lexicon-exempt: developer contract error
+        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', 
-        // lexicon-exempt: developer contract error
+        // labels-exempt: developer contract error
         `Decision ${question.type} '${id}' must declare criteria`);
     }
 }
@@ -185,35 +207,89 @@ export function validateDecisionRequest(request, profile) {
     throwIfAborted(request.signal);
     if (request.model !== undefined) {
         throw new DecisionError('invalid_request', 
-        // lexicon-exempt: developer contract error
+        // 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'); // lexicon-exempt: developer contract error
+        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 {
-        // lexicon-exempt: developer contract error
+        // 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', 
-        // lexicon-exempt: developer contract error
+        // 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', 
-        // lexicon-exempt: developer contract error
+        // 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];
@@ -234,95 +310,18 @@ function isDecisionEntry(value) {
     }
     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),
+        ...(request.assets ? { assets: request.assets } : {}),
     });
     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
+        throw new DecisionError('disclosure_blocked', 'Decision disclosure was blocked'); // labels-exempt: developer 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',
@@ -333,6 +332,15 @@ function decisionSpanAttributes(profile, modelId, binding, request) {
         '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) {
@@ -350,32 +358,58 @@ function recordResult(root, result) {
             : {}),
     });
 }
-async function decide(profile, [modelId, binding], request, options) {
+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);
-    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,
+        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,
-            provider: binding.provider,
-            apiKey,
-            options,
-            signal: controller.signal,
+            state: request.state,
+            questions: Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [
+                id,
+                providerQuestion(question, request.assets),
+            ])),
+            ...(request.assets ? { assets: request.assets } : {}),
         });
-        return await resultFromResponse(response, request.questions, binding, controller.signal, request.signal);
+        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) };
     }
-    finally {
-        if (timeout !== undefined)
-            clearTimeout(timeout);
-        request.signal?.removeEventListener('abort', abort);
+    catch (error) {
+        if (request.signal?.aborted)
+            throw new DecisionError('cancelled', labelText('provider.decision_ended'));
+        throw decisionProviderError(error);
     }
 }
 /**
@@ -387,26 +421,19 @@ export async function runDecisionInRegistry(registry, request, options) {
     validateDecisionRequest(request, profile);
     const model = decisionModel(profile);
     const [modelId, binding] = model;
-    const tree = startTrace(`decide ${binding.apiId}`, {
-        kind: 'CLIENT',
+    return await tracedCall({
+        name: `decide ${binding.apiId}`,
         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' });
+        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;
-    }
-    catch (error) {
-        endThrownSpan(tree.root, error);
-        throw error;
-    }
-    finally {
-        await writeSpans(sink, tree.collect(), policy, request.metadata);
-    }
+    });
 }

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/live-inbound.d.ts

@@ -1,9 +1,19 @@
 import type { TurnEventOf } from '../turn-events.js';
-import type { Profile } from '../types.js';
+import type { Profile, TurnContext } from '../types.js';
 export interface LiveInboundPrepareResult {
-    text: string;
-    /** Present when inbound sanitize redacted spans. */
+    /** 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 { prepareLiveInboundText };
+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 };