@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,6 +1,6 @@
 import type { ToolRegistry } from '../tools/registry.js';
-import type { BuiltinToolId, ProviderBuiltin, ProviderCompleteRequest, ResolvedGeneration } from '../types.js';
-declare function providerBuiltins(tools: ToolRegistry, ids: readonly BuiltinToolId[]): ProviderBuiltin[];
+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): ProviderCompleteRequest;
+declare function providerCompleteRequest(tools: ToolRegistry, generation: ResolvedGeneration, system: string): ModelRequest;
 export { providerBuiltins, providerCompleteRequest };

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

@@ -1,42 +1,34 @@
 import { TheoremError } from '../../guardrails/error.js';
-function providerBuiltins(tools, ids) {
+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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new TheoremError('config', `Builtin '${id}' is not registered`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
-        return { id, wire: tool.wire };
+        const given = args[id];
+        return given ? { id, args: given } : { id };
     });
 }
 /** Shared by execution and tracing. */
 function providerCompleteRequest(tools, generation, system) {
-    const isInteractions = generation.transport === 'interactions';
     return {
         model: generation.model,
         apiId: generation.apiId,
-        previousInteractionId: isInteractions ? generation.previousInteractionId : undefined,
-        store: isInteractions ? generation.store : undefined,
         stream: generation.stream,
         thinking: generation.thinking,
         summaries: generation.summaries,
         maxOutputTokens: generation.maxOutputTokens,
         temperature: generation.temperature,
-        builtins: providerBuiltins(tools, generation.builtins),
-        googleMapsLocation: isInteractions ? generation.googleMapsLocation : undefined,
-        cache: generation.cache,
+        builtins: providerBuiltins(tools, generation.builtins, generation.builtInArgs),
         sessionId: generation.sessionId,
         system,
         input: generation.input,
         history: generation.history,
-        continuation: isInteractions ? generation.continuation : undefined,
         wireTools: generation.tools.wire,
         structured: generation.structured,
         image: generation.image,
         speech: generation.speech,
         live: generation.live,
-        sessionResumptionHandle: generation.sessionResumptionHandle,
-        keySlot: generation.keySlot,
-        fallbackKeySlot: generation.fallbackKeySlot,
     };
 }
 export { providerBuiltins, providerCompleteRequest };

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

@@ -2,13 +2,16 @@ 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;
-declare function resolveTurnInRegistry(registry: KernelRegistry, req: TurnRequest): {
+/** `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

@@ -1,33 +1,39 @@
 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, assertTurnSlots, resolveImageFormat, resolveInputParts, } from './ingress.js';
+import { assertOutputMode, assertSpeechRole, assertTurnContext, assertTurnSlots, resolveImageFormat, resolveInputParts, resolveSpeech, } from './ingress.js';
 import { resolveTurnSystemPrompt } from './system-prompt.js';
-import { resolveKeySlot } from './vault.js';
 function isModelProfile(profile) {
-    return profile.type !== 'host' && profile.type !== 'decision';
+    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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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;
     }
@@ -52,7 +58,7 @@ function resolveEffort(profile, binding, modelId, requested) {
         }
         return level;
     }
-    // Registration requires a default whenever more than one effort is declared.
+    // why: Registration requires a default whenever more than one effort is declared.
     return efforts[binding.defaultEffort ?? keys[0]];
 }
 function resolveSummaries(binding) {
@@ -90,32 +96,8 @@ function resolveStreamFlag(profile) {
     }
     return profile.outputs?.streaming?.mode !== 'buffered';
 }
-function resolveStore(binding, reqStore) {
-    if (reqStore !== undefined) {
-        return reqStore;
-    }
-    return binding.store;
-}
-/**
- * A turn chains only on a binding that says so: an interaction id sent to one
- * that does not, or a chaining turn that switches storage off, is a request error.
- */
-function assertTurnChaining(profile, model, chains, req, store) {
-    if (req.previousInteractionId && !chains) {
-        throw new TheoremError('request', `Profile ${profile.id} model '${model}': previousInteractionId needs a binding with persistViaInteractionId: true`);
-    }
-    if (chains && store === false) {
-        throw new TheoremError('request', `Profile ${profile.id} model '${model}': store: false cannot apply to a binding with persistViaInteractionId: true — Google chains only from a stored interaction`);
-    }
-}
-function resolveTransport(profile, binding) {
-    if (profile.type === 'live') {
-        return 'geminiLive';
-    }
-    if (binding.protocol === 'geminiInteractions' && binding.provider === 'google') {
-        return 'interactions';
-    }
-    return 'openAiCompat';
+function resolveTransport(profile, _binding) {
+    return profile.type === 'live' ? 'live' : 'turn';
 }
 function assertTurnResumption(profile, req) {
     if (!req.continueFrom) {
@@ -134,73 +116,92 @@ function assertTurnResumption(profile, req) {
         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`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        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 (canary or `egress.enforce`) always transcribes its
- * own speech: the outbound gate can only check audio through its transcript.
+ * 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) {
-    const policy = resolveGuardrailPolicy(guardrails);
-    if (!policy.canary && !policy.egress?.enforce) {
+    if (!replyIsJudged(resolveGuardrailPolicy(guardrails), ['live_reply'])) {
         return live;
     }
     return { ...live, transcription: { ...live?.transcription, output: true } };
 }
-function resolveTurnInRegistry(registry, req) {
+/**
+ * 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 model = pickModel(profile, safe.model);
-    const binding = requireModelBinding(profile, model);
-    const toolSnapshot = resolveTurnTools(registry.tools, profile, safe, model);
+    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 keys = resolveKeySlot(profile, binding);
+    const builtInArgs = resolveBuiltInArgs(profile, picked, binding, safe.builtInArgs);
     const transport = resolveTransport(profile, binding);
-    const chains = binding.persistViaInteractionId === true;
-    const store = resolveStore(binding, safe.store);
-    assertTurnChaining(profile, model, chains, safe, store);
     return {
         profile,
         generation: {
-            model,
+            model: picked,
             apiId: binding.apiId,
             transport,
-            chains,
-            previousInteractionId: safe.previousInteractionId,
-            store,
             stream: resolveStreamFlag(profile),
-            thinking: resolveEffort(profile, binding, model, safe.effort),
+            thinking: resolveEffort(profile, binding, picked, safe.effort),
             summaries: resolveSummaries(binding),
             maxOutputTokens: binding.maxOutputTokens,
             temperature: binding.temperature,
             builtins,
-            googleMapsLocation: safe.googleMapsLocation,
-            cache: binding.cache,
+            builtInArgs,
             sessionId: safe.sessionId,
             tools: toolSnapshot,
             sessionPermissions: safe.sessionPermissions,
+            execution: safe.execution,
+            pageExecution: safe.pageExecution,
             history: input.history,
-            maxSteps: profile.maxSteps,
+            maxSteps: profile.maxSteps ?? DEFAULT_MAX_STEPS,
             structured: structuredId
                 ? { id: structuredId, jsonSchema: registry.schemas.get(structuredId).jsonSchema }
                 : null,
             image: resolveImageFormat(profile),
-            speech: profile.type === 'speech' ? profile.speech : undefined,
+            speech: resolveSpeech(profile, safe),
             live: profile.type === 'live' ? resolveLiveSpec(profile.live, profile.guardrails) : undefined,
             input: resolveInputParts(profile, safe),
-            ...keys,
-            canary: resolveGuardrailPolicy(profile.guardrails).canary ? mintCanary() : '',
-            sessionResumptionHandle: safe.sessionResumptionHandle ?? input.sessionResumptionHandle,
+            canary: plantedCanary(profile),
             resolvedSystem: resolveTurnSystemPrompt(profile, safe),
             host: safe.host,
         },
@@ -209,6 +210,7 @@ function resolveTurnInRegistry(registry, req) {
 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;
@@ -222,7 +224,6 @@ function projectProfileObject(tools, input) {
         defaultModel: profile.defaultModel,
         allowModelSelect: profile.allowModelSelect,
         maxSteps: profile.maxSteps,
-        key: profile.key,
         tools: projectTools(tools, profile),
         inputs,
         outputs,

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

@@ -1,9 +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

@@ -1,4 +1,5 @@
 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 {
@@ -16,10 +17,11 @@ function createSchemaRegistry() {
         get(id) {
             const spec = schemas.get(id);
             if (!spec) {
-                throw new TheoremError('config', `Unknown structured schema '${id}'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                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/system-prompt.js

@@ -1,12 +1,12 @@
-import { detectionForTrust, resolveGuardrailPolicy } from '../../guardrails/policy.js';
-import { sanitizeText } from '../../guardrails/sanitize.js';
 import { joinSystemPieces, mapSystemPrompt, systemPieces } from '../system-parts.js';
+import { fillSlots } from './slot-fill.js';
 import { pickSystemRole } from './system-role.js';
 /**
- * Routed through the policy at `trust: 'trusted'` so the exemption is declared where it applies,
- * not implied by skipping the sanitizer. `req.system` is `assembled` per turn and not exempt.
+ * `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) {
+function systemFromProfile(profile, role, slots) {
     if (profile.type === 'speech') {
         return [];
     }
@@ -15,8 +15,7 @@ function systemFromProfile(profile, role) {
     if (!prompt) {
         return [];
     }
-    const detection = detectionForTrust(resolveGuardrailPolicy(profile.guardrails), 'trusted');
-    return systemPieces(mapSystemPrompt(prompt, `Profile ${profile.id} identity.system`, (text) => sanitizeText(text, detection)));
+    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
@@ -26,7 +25,7 @@ function systemFromProfile(profile, role) {
 function resolveTurnSystemPrompt(profile, req) {
     const role = pickSystemRole(profile, req.input?.role);
     return joinSystemPieces([
-        systemFromProfile(profile, role),
+        systemFromProfile(profile, role, req.input?.slots),
         req.system === undefined ? [] : systemPieces(req.system),
     ]);
 }

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

@@ -1,13 +1,14 @@
-import type { KeySlot, ModelBinding } from '../types.js';
-/**
- * The slots a model's calls use: its own, else the profile's. A local model uses only its own, so
- * the profile's hosted key never reaches a local server; naming none, it sends no key.
- */
-declare function resolveKeySlot(profile: {
-    key?: KeySlot;
-    fallbackKey?: KeySlot;
-}, binding: ModelBinding): {
-    keySlot?: KeySlot;
-    fallbackKeySlot?: KeySlot;
-};
-export { resolveKeySlot };
+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

@@ -1,14 +1 @@
-/**
- * The slots a model's calls use: its own, else the profile's. A local model uses only its own, so
- * the profile's hosted key never reaches a local server; naming none, it sends no key.
- */
-function resolveKeySlot(profile, binding) {
-    const inherited = binding.provider === 'local' ? {} : profile;
-    const keySlot = binding.key ?? inherited.key;
-    const fallbackKeySlot = binding.fallbackKey ?? inherited.fallbackKey;
-    return {
-        ...(keySlot ? { keySlot } : {}),
-        ...(fallbackKeySlot ? { fallbackKeySlot } : {}),
-    };
-}
-export { resolveKeySlot };
+export {};