@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/registry/provider-request.d.ts

@@ -0,0 +1,6 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { BuiltInArgs, BuiltinToolId, ModelRequest, ProviderBuiltin, ResolvedGeneration } from '../types.js';
+declare function providerBuiltins(tools: ToolRegistry, ids: readonly BuiltinToolId[], args?: BuiltInArgs): ProviderBuiltin[];
+/** Shared by execution and tracing. */
+declare function providerCompleteRequest(tools: ToolRegistry, generation: ResolvedGeneration, system: string): ModelRequest;
+export { providerBuiltins, providerCompleteRequest };

package/esm/src/kernel/registry/provider-request.js

@@ -0,0 +1,34 @@
+import { TheoremError } from '../../guardrails/error.js';
+function providerBuiltins(tools, ids, args = {}) {
+    return ids.map((id) => {
+        const tool = tools.get(id);
+        if (tool?.type !== 'builtin') {
+            throw new TheoremError('config', `Builtin '${id}' is not registered`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        const given = args[id];
+        return given ? { id, args: given } : { id };
+    });
+}
+/** Shared by execution and tracing. */
+function providerCompleteRequest(tools, generation, system) {
+    return {
+        model: generation.model,
+        apiId: generation.apiId,
+        stream: generation.stream,
+        thinking: generation.thinking,
+        summaries: generation.summaries,
+        maxOutputTokens: generation.maxOutputTokens,
+        temperature: generation.temperature,
+        builtins: providerBuiltins(tools, generation.builtins, generation.builtInArgs),
+        sessionId: generation.sessionId,
+        system,
+        input: generation.input,
+        history: generation.history,
+        wireTools: generation.tools.wire,
+        structured: generation.structured,
+        image: generation.image,
+        speech: generation.speech,
+        live: generation.live,
+    };
+}
+export { providerBuiltins, providerCompleteRequest };

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

@@ -0,0 +1,17 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { ModelId, ModelProfile, Profile, ProjectedProfile, ResolvedGeneration, TurnRequest } from '../types.js';
+import type { KernelRegistry } from './kernel-registry.js';
+declare function isModelProfile(profile: Profile): profile is ModelProfile;
+/** Returns the profile when it runs a model; throws a request error naming `door` for a host or decision profile. */
+declare function requireModelProfile(profile: Profile, door: string): ModelProfile;
+/** A request is honored only when selection is allowed; registration guarantees the default. */
+declare function pickModel(profile: ModelProfile, requested?: string): ModelId;
+/** `model` names the binding to resolve, past the profile's own selection rule. */
+declare function resolveTurnInRegistry(registry: KernelRegistry, req: TurnRequest, model?: ModelId): {
+    profile: ModelProfile;
+    generation: ResolvedGeneration;
+};
+/** Projects a profile into the plain object a host reads: its id, type, handle, models, inputs, outputs, and the tools it can use. Throws for a host or decision profile. */
+declare function projectProfileObject(tools: ToolRegistry, input: Profile): ProjectedProfile;
+declare function projectProfileInRegistry(registry: KernelRegistry, id: Profile['id']): ProjectedProfile;
+export { isModelProfile, pickModel, projectProfileInRegistry, projectProfileObject, requireModelProfile, resolveTurnInRegistry, };

package/esm/src/kernel/registry/resolve.js

@@ -0,0 +1,238 @@
+import { mintCanary } from '../../guardrails/canary.js';
+import { detects } from '../../guardrails/detectors.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
+import { replyIsJudged } from '../../guardrails/progressive-yield.js';
+import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
+import { DEFAULT_MAX_STEPS } from '../profile-presence.js';
+import { profileTurnResumption } from '../stop.js';
+import { projectTools } from '../tools/project.js';
+import { resolveTurnTools } from '../tools/resolve.js';
+import { profileInputs, requireModelBinding } from './catalog.js';
+import { assertOutputMode, assertSpeechRole, assertTurnContext, assertTurnSlots, resolveImageFormat, resolveInputParts, resolveSpeech, } from './ingress.js';
+import { resolveTurnSystemPrompt } from './system-prompt.js';
+function isModelProfile(profile) {
+    return profile.type !== 'host' && profile.type !== 'decision' && profile.type !== 'embedding';
+}
+/** Returns the profile when it runs a model; throws a request error naming `door` for a host or decision profile. */
+function requireModelProfile(profile, door) {
+    if (isModelProfile(profile))
+        return profile;
+    if (profile.type === 'host') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'host' never runs a model — ${door} is not supported; execute tools with invokeTool`);
+    }
+    if (profile.type === 'embedding') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'embedding' runs through runEmbedding — ${door} is not supported`);
+    }
+    throw new TheoremError('request', `Profile ${profile.id}: type 'decision' runs through runDecision — ${door} is not supported`);
+}
+/** A request is honored only when selection is allowed; registration guarantees the default. */
+function pickModel(profile, requested) {
+    if (requested) {
+        if (!profile.allowModelSelect) {
+            throw new TheoremError('request', `Profile ${profile.id} does not allow model selection`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (!profile.models[requested]) {
+            throw new TheoremError('request', `Unknown model '${requested}' for ${profile.id}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        return requested;
+    }
+    return profile.defaultModel;
+}
+function resolveEffort(profile, binding, modelId, requested) {
+    const efforts = binding.efforts;
+    if (!efforts || Object.keys(efforts).length === 0) {
+        if (requested) {
+            throw new TheoremError('request', `Profile ${profile.id} model '${modelId}' has no selectable efforts`);
+        }
+        return undefined;
+    }
+    const keys = Object.keys(efforts);
+    if (requested) {
+        if (!binding.allowEffortSelect) {
+            throw new TheoremError('request', `Profile ${profile.id} model '${modelId}' does not allow effort selection`);
+        }
+        const level = efforts[requested];
+        if (!level) {
+            throw new TheoremError('request', `Unknown effort '${requested}' for ${profile.id} model '${modelId}'`);
+        }
+        return level;
+    }
+    // why: Registration requires a default whenever more than one effort is declared.
+    return efforts[binding.defaultEffort ?? keys[0]];
+}
+function resolveSummaries(binding) {
+    if (binding.summaries === true) {
+        return 'auto';
+    }
+    if (binding.summaries === false) {
+        return 'none';
+    }
+    return undefined;
+}
+function resolveStructured(profile, slots) {
+    if (profile.type === 'live') {
+        return null;
+    }
+    const structured = profile.outputs?.structured;
+    if (!structured) {
+        return null;
+    }
+    if (typeof structured === 'string') {
+        return structured;
+    }
+    const value = slots?.[structured.by];
+    if (value) {
+        const mapped = structured.map[value];
+        if (mapped) {
+            return mapped;
+        }
+    }
+    return structured.fallback;
+}
+function resolveStreamFlag(profile) {
+    if (profile.type === 'live') {
+        return true;
+    }
+    return profile.outputs?.streaming?.mode !== 'buffered';
+}
+function resolveTransport(profile, _binding) {
+    return profile.type === 'live' ? 'live' : 'turn';
+}
+function assertTurnResumption(profile, req) {
+    if (!req.continueFrom) {
+        return;
+    }
+    if (profile.type === 'live') {
+        throw new TheoremError('request', `Profile ${profile.id}: type 'live' uses live.sessionResumption, not turnBehaviour.resumption/continueFrom`);
+    }
+    const policy = profileTurnResumption(profile);
+    const max = policy?.maxContinues;
+    if (max === undefined) {
+        return;
+    }
+    const attempt = req.continuation;
+    if (attempt === undefined) {
+        throw new TheoremError('request', `Profile ${profile.id}: continueFrom requires TurnRequest.continuation when turnBehaviour.resumption.maxContinues is set`);
+    }
+    if (attempt < 1) {
+        throw new TheoremError('request', `Profile ${profile.id}: continuation must be >= 1`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (attempt > max) {
+        throw new TheoremError('request', `Profile ${profile.id}: continuation ${attempt} exceeds turnBehaviour.resumption.maxContinues (${max})`);
+    }
+}
+/**
+ * A guarded Live profile (a detector reading `live_reply`) always transcribes its own speech: the outbound gate can only check audio
+ * through its transcript.
+ */
+function resolveLiveSpec(live, guardrails) {
+    if (!replyIsJudged(resolveGuardrailPolicy(guardrails), ['live_reply'])) {
+        return live;
+    }
+    return { ...live, transcription: { ...live?.transcription, output: true } };
+}
+/**
+ * A canary for the turn while `canary_leak` reads somewhere, else none. Speech
+ * has no system prompt to plant one in.
+ */
+function plantedCanary(profile) {
+    const { detect } = resolveGuardrailPolicy(profile.guardrails);
+    return profile.type !== 'speech' && detects(detect, 'canary_leak') ? mintCanary() : '';
+}
+/**
+ * The request's `builtInArgs`. Args must name a tool the chosen model lists; the protocol that
+ * writes the tool parses them.
+ */
+function resolveBuiltInArgs(profile, model, binding, args) {
+    if (!args) {
+        return undefined;
+    }
+    const resolved = {};
+    for (const [id, value] of Object.entries(args)) {
+        if (!binding.builtInTools?.includes(id)) {
+            throw new TheoremError('request', `Profile ${profile.id}: builtInArgs names '${id}', which model '${model}' does not list in builtInTools`);
+        }
+        resolved[id] = value;
+    }
+    return resolved;
+}
+/** `model` names the binding to resolve, past the profile's own selection rule. */
+function resolveTurnInRegistry(registry, req, model) {
+    const profile = requireModelProfile(registry.profiles.get(req.profile), 'resolveTurn');
+    assertTurnSlots(profile, req);
+    assertTurnContext(profile, req);
+    const safe = sanitizeTurnRequest(req, profile);
+    const input = safe.input ?? {};
+    assertTurnResumption(profile, safe);
+    const picked = model ?? pickModel(profile, safe.model);
+    const binding = requireModelBinding(profile, picked);
+    const toolSnapshot = resolveTurnTools(registry.tools, profile, safe, picked);
+    const builtins = toolSnapshot.builtins;
+    const structuredId = resolveStructured(profile, input.slots);
+    assertOutputMode(profile, structuredId);
+    assertSpeechRole(profile, safe);
+    const builtInArgs = resolveBuiltInArgs(profile, picked, binding, safe.builtInArgs);
+    const transport = resolveTransport(profile, binding);
+    return {
+        profile,
+        generation: {
+            model: picked,
+            apiId: binding.apiId,
+            transport,
+            stream: resolveStreamFlag(profile),
+            thinking: resolveEffort(profile, binding, picked, safe.effort),
+            summaries: resolveSummaries(binding),
+            maxOutputTokens: binding.maxOutputTokens,
+            temperature: binding.temperature,
+            builtins,
+            builtInArgs,
+            sessionId: safe.sessionId,
+            tools: toolSnapshot,
+            sessionPermissions: safe.sessionPermissions,
+            execution: safe.execution,
+            pageExecution: safe.pageExecution,
+            history: input.history,
+            maxSteps: profile.maxSteps ?? DEFAULT_MAX_STEPS,
+            structured: structuredId
+                ? { id: structuredId, jsonSchema: registry.schemas.get(structuredId).jsonSchema }
+                : null,
+            image: resolveImageFormat(profile),
+            speech: resolveSpeech(profile, safe),
+            live: profile.type === 'live' ? resolveLiveSpec(profile.live, profile.guardrails) : undefined,
+            input: resolveInputParts(profile, safe),
+            canary: plantedCanary(profile),
+            resolvedSystem: resolveTurnSystemPrompt(profile, safe),
+            host: safe.host,
+        },
+    };
+}
+function primaryImageSpec(profile) {
+    return profile.type === 'image' ? profile.image : null;
+}
+/** Projects a profile into the plain object a host reads: its id, type, handle, models, inputs, outputs, and the tools it can use. Throws for a host or decision profile. */
+function projectProfileObject(tools, input) {
+    const profile = requireModelProfile(input, 'projectProfile');
+    const { identity } = profile;
+    const inputs = profileInputs(profile) ?? null;
+    const outputs = profile.type === 'live' ? null : (profile.outputs ?? null);
+    return {
+        id: profile.id,
+        type: profile.type,
+        handle: identity.handle,
+        models: profile.models,
+        defaultModel: profile.defaultModel,
+        allowModelSelect: profile.allowModelSelect,
+        maxSteps: profile.maxSteps,
+        tools: projectTools(tools, profile),
+        inputs,
+        outputs,
+        image: primaryImageSpec(profile),
+        speech: profile.type === 'speech' ? profile.speech : null,
+        live: profile.type === 'live' ? profile.live : null,
+    };
+}
+function projectProfileInRegistry(registry, id) {
+    return projectProfileObject(registry.tools, registry.profiles.get(id));
+}
+export { isModelProfile, pickModel, projectProfileInRegistry, projectProfileObject, requireModelProfile, resolveTurnInRegistry, };

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

@@ -0,0 +1,12 @@
+import type { StructuredSpec } from '../types.js';
+/** The structured-output schemas a registry holds, by id: `register`, `get` (throws when there is none) and `find`. */
+interface SchemaRegistry {
+    register(id: string, spec: StructuredSpec): void;
+    /** Throws when there is none. */
+    get(id: string): StructuredSpec;
+    find(id: string): StructuredSpec | undefined;
+}
+/** Creates an empty schema registry; `register` rejects a spec that still carries the removed `enforced` field. */
+declare function createSchemaRegistry(): SchemaRegistry;
+export type { SchemaRegistry };
+export { createSchemaRegistry };

package/esm/src/kernel/registry/schemas.js

@@ -0,0 +1,27 @@
+import { TheoremError } from '../../guardrails/error.js';
+/** Creates an empty schema registry; `register` rejects a spec that still carries the removed `enforced` field. */
+function createSchemaRegistry() {
+    const schemas = new Map();
+    return {
+        register(id, spec) {
+            if ('enforced' in spec) {
+                throw new TheoremError('config', `registerStructured '${id}': enforced was removed; every structured schema is sent to the model as its response format`);
+            }
+            if (!spec.jsonSchema ||
+                typeof spec.jsonSchema !== 'object' ||
+                Array.isArray(spec.jsonSchema)) {
+                throw new TheoremError('config', `registerStructured '${id}': jsonSchema must be a JSON Schema object`);
+            }
+            schemas.set(id, spec);
+        },
+        get(id) {
+            const spec = schemas.get(id);
+            if (!spec) {
+                throw new TheoremError('config', `Unknown structured schema '${id}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            return spec;
+        },
+        find: (id) => schemas.get(id),
+    };
+}
+export { createSchemaRegistry };

package/esm/src/kernel/registry/slot-fill.d.ts

@@ -0,0 +1,7 @@
+import type { Profile } from '../types.js';
+/**
+ * Replaces each `{name}` that names one of the profile's slots with the value the request chose.
+ * A `{name}` that is no slot stays as written. A prompt that uses a slot the request left
+ * unfilled is a request error. Every value is one the profile lists, so no free text is written.
+ */
+export declare function fillSlots(profile: Profile, text: string, slots: Record<string, string> | undefined, where: string): string;

package/esm/src/kernel/registry/slot-fill.js

@@ -0,0 +1,22 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { profileInputs } from './catalog.js';
+const SLOT_REF = /\{([A-Za-z_][\w-]*)\}/g;
+/**
+ * Replaces each `{name}` that names one of the profile's slots with the value the request chose.
+ * A `{name}` that is no slot stays as written. A prompt that uses a slot the request left
+ * unfilled is a request error. Every value is one the profile lists, so no free text is written.
+ */
+export function fillSlots(profile, text, slots, where) {
+    const declared = profileInputs(profile)?.slots;
+    if (!declared)
+        return text;
+    return text.replace(SLOT_REF, (whole, name) => {
+        if (!Object.hasOwn(declared, name))
+            return whole;
+        const value = slots && Object.hasOwn(slots, name) ? slots[name] : undefined;
+        if (value === undefined) {
+            throw new TheoremError('request', `Profile ${profile.id}: ${where} uses slot '${name}', and the request chose no value for it`);
+        }
+        return value;
+    });
+}

package/esm/src/kernel/registry/sole-model.d.ts

@@ -0,0 +1,2 @@
+import type { ModelId } from '../types.js';
+export declare function soleModelId(models: Record<ModelId, unknown>): ModelId | undefined;

package/esm/src/kernel/registry/sole-model.js

@@ -0,0 +1,4 @@
+export function soleModelId(models) {
+    const ids = Object.keys(models);
+    return ids.length === 1 ? ids[0] : undefined;
+}

package/esm/src/kernel/registry/system-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { ModelProfile, SystemPiece, TurnRequest } from '../types.js';
+/**
+ * Synchronous: snapshotted in `resolveTurn` before any async work. Each source
+ * keeps its own marks: a `{ private }` part in `req.system` leaves the
+ * profile's prompt as private as it was written.
+ */
+declare function resolveTurnSystemPrompt(profile: ModelProfile, req: TurnRequest): SystemPiece[];
+export { resolveTurnSystemPrompt };

package/esm/src/kernel/registry/system-prompt.js

@@ -0,0 +1,32 @@
+import { joinSystemPieces, mapSystemPrompt, systemPieces } from '../system-parts.js';
+import { fillSlots } from './slot-fill.js';
+import { pickSystemRole } from './system-role.js';
+/**
+ * `identity.system` is trusted author-time copy and crosses no boundary: no detector reads it.
+ * A `{slot}` in it becomes the value the request chose, which is one the profile lists.
+ * `req.system` is `assembled` per turn and is read at the `system` boundary.
+ */
+function systemFromProfile(profile, role, slots) {
+    if (profile.type === 'speech') {
+        return [];
+    }
+    const { systemByRole, system } = profile.identity;
+    const prompt = systemByRole?.[role] || system || '';
+    if (!prompt) {
+        return [];
+    }
+    return systemPieces(mapSystemPrompt(prompt, `Profile ${profile.id} identity.system`, (text) => fillSlots(profile, text, slots, 'identity.system')));
+}
+/**
+ * Synchronous: snapshotted in `resolveTurn` before any async work. Each source
+ * keeps its own marks: a `{ private }` part in `req.system` leaves the
+ * profile's prompt as private as it was written.
+ */
+function resolveTurnSystemPrompt(profile, req) {
+    const role = pickSystemRole(profile, req.input?.role);
+    return joinSystemPieces([
+        systemFromProfile(profile, role, req.input?.slots),
+        req.system === undefined ? [] : systemPieces(req.system),
+    ]);
+}
+export { resolveTurnSystemPrompt };

package/esm/src/kernel/registry/system-role.d.ts

@@ -0,0 +1,3 @@
+import type { ModelProfile } from '../types.js';
+declare function pickSystemRole(profile: ModelProfile, requested?: string): string;
+export { pickSystemRole };

package/esm/src/kernel/registry/system-role.js

@@ -0,0 +1,9 @@
+function pickSystemRole(profile, requested) {
+    const { handle } = profile.identity;
+    const systemByRole = profile.type === 'speech' ? undefined : profile.identity.systemByRole;
+    if (requested && systemByRole && Object.hasOwn(systemByRole, requested)) {
+        return requested;
+    }
+    return handle;
+}
+export { pickSystemRole };

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

@@ -0,0 +1,14 @@
+import type { JsonObject } from '../json.js';
+import type { KeySlot } from '../types.js';
+/** A key as the vault holds it: a string, or an object for a provider that signs in with several fields. */
+export type KeyCredential = string | JsonObject;
+export interface CredentialContext {
+    providerId: string;
+    apiId: string;
+    keySlot: KeySlot;
+    signal?: AbortSignal;
+}
+/** Reads a key when a call needs it, e.g. from a secret manager. */
+export type CredentialResolver = (context: CredentialContext) => KeyCredential | Promise<KeyCredential>;
+/** The host's keys, by slot. The kernel reads a slot only for the call that names it. */
+export type KeyVault = Readonly<Record<KeySlot, KeyCredential | CredentialResolver | undefined>>;

package/esm/src/kernel/registry/vault.js

@@ -0,0 +1 @@
+export {};