@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/schema.js

@@ -3,15 +3,27 @@
  *
  * @module
  */
-/** lexicon-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+/** labels-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
 import "../../_dnt.polyfills.js";
-import { LEXICON_NOTES } from '../guardrails/lexicon.js';
-import { EGRESS_ON_BLOCK, TAINT_GATES } from '../guardrails/types.js';
+import { BOUNDARIES, BOUNDARY_META, recordOf } from '../guardrails/boundaries.js';
+import { DETECT_ACTION_META, DETECT_ACTIONS, DETECT_DEFAULTS, DETECTOR_BOUNDARIES, DETECTOR_META, DETECTORS, } from '../guardrails/detectors.js';
+import { LABEL_NOTES } from '../guardrails/labels.js';
+import { BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, TAINT_GATES, } from '../guardrails/types.js';
 import { GOOGLE_SPEECH_VOICES } from '../presets/google/speech-voices.js';
 import { PROFILE_FIELD_PRESENCE } from './profile-presence.js';
-import { profileFieldScope } from './profile-scope.js';
-export { EGRESS_ON_BLOCK };
-export const PROFILE_TYPES = ['text', 'image', 'speech', 'live', 'decision', 'host'];
+import { isProfileRootField, profileFieldScope } from './profile-scope.js';
+export { BLOCKED_REPLY_ON_BLOCK };
+/** The kinds of profile: each fixes which fields and models a profile may use. */
+export const PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+    'embedding',
+    'host',
+];
+/** Reasoning effort levels, lowest to highest; a model accepts only the levels its catalog row lists. */
 export const THINKING_LEVELS = [
     'none',
     'minimal',
@@ -21,45 +33,40 @@ export const THINKING_LEVELS = [
     'xhigh',
     'max',
 ];
-export const PROTOCOLS = ['geminiInteractions', 'geminiLive', 'openAi', 'decision'];
-export const PROVIDERS = ['google', 'openrouter', 'local', 'typesafe'];
-/** Turn pairs are handled by `createProvider`; decision pairs by `runDecision`. */
-export const PROTOCOL_PROVIDERS = {
-    geminiInteractions: ['google'],
-    geminiLive: ['google'],
-    openAi: ['openrouter', 'local'],
-    decision: ['typesafe', 'openrouter'],
-};
-export const PROFILE_TYPE_PROTOCOLS = {
-    text: ['geminiInteractions', 'openAi'],
-    image: ['geminiInteractions', 'openAi'],
-    speech: ['geminiInteractions', 'openAi'],
-    live: ['geminiLive'],
-    decision: ['decision'],
-    host: [],
-};
-export function protocolsForProfileType(type) {
-    return PROFILE_TYPE_PROTOCOLS[type];
-}
-export function isValidProfileProtocol(type, protocol) {
-    return PROFILE_TYPE_PROTOCOLS[type].includes(protocol);
-}
-/** Letters, digits, `-` and `_`, up to 32 characters, starting with a letter or digit. */
+/** The longest a profile's `id` may be, in characters: room for a dotted or generated one. */
+export const PROFILE_ID_MAX_CHARS = 64;
+/** The longest a profile's `identity.handle` may be, in characters: it is a name people read. */
+export const PROFILE_HANDLE_MAX_CHARS = 32;
+/** Letters, digits, `-`, and `_`, up to 32 characters, starting with a letter or digit. */
 export const KEY_SLOT_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
+/** True when the value is a legal key slot name. */
 export function isKeySlotName(value) {
     return typeof value === 'string' && KEY_SLOT_NAME.test(value);
 }
+/** The kinds of media a model can take as input. */
 export const MEDIA_INPUT_KIND_VALUES = ['image', 'audio', 'video', 'document'];
+/** Whether thought summaries are asked for (`auto`) or not (`none`). */
 export const SUMMARY_MODES = ['auto', 'none'];
+/** Whether the provider call streams (`sse`) or is one buffered call. */
 export const STREAM_MODES = ['sse', 'buffered'];
+/** Audio encodings a speech profile can return. */
 export const SPEECH_AUDIO_FORMATS = ['pcm', 'mp3'];
+/** Who can send a turn its context: the browser, or the host's own code. */
+/** How long a caller is away, in milliseconds, before `live.resumed.prompt` is sent, when the profile sets no `afterMs`. */
+export const DEFAULT_RESUMED_AFTER_MS = 3000;
+export const CONTEXT_SENDERS = ['client', 'server'];
+/** What the user starting to speak does to a live model that is mid-reply. */
 export const LIVE_ACTIVITY_HANDLINGS = ['START_OF_ACTIVITY_INTERRUPTS', 'NO_INTERRUPTION'];
+/** How readily live voice detection decides the user has started speaking. */
 export const LIVE_START_SENSITIVITIES = [
     'START_SENSITIVITY_LOW',
     'START_SENSITIVITY_HIGH',
 ];
+/** How readily live voice detection decides the user has stopped speaking. */
 export const LIVE_END_SENSITIVITIES = ['END_SENSITIVITY_LOW', 'END_SENSITIVITY_HIGH'];
+/** What compaction counts against its token limit: the stored history or the next request's input. */
 export const COMPACTION_METERS = ['history', 'input'];
+/** Whether compaction runs before or after a turn. */
 export const COMPACTION_TIMINGS = ['before', 'after'];
 /**
  * - `compacted`: a summary replaced the compacted messages.
@@ -67,8 +74,11 @@ export const COMPACTION_TIMINGS = ['before', 'after'];
  * - `dropped`: the compactor failed over `maxTokens`, so the compacted messages were dropped.
  */
 export const COMPACTION_OUTCOMES = ['compacted', 'deferred', 'dropped'];
+/** Which part of the prompt is cached: the whole request (`automatic`) or the system instruction only (`system`). */
 export const CACHE_MODES = ['automatic', 'system'];
+/** How long a provider keeps a cached prompt. */
 export const CACHE_TTLS = ['5m', '1h'];
+/** Why a turn stopped, as `done.stop.kind` reports it. */
 export const TURN_STOP_KINDS = [
     'completed',
     'length',
@@ -80,12 +90,19 @@ export const TURN_STOP_KINDS = [
     'provider_error',
     'cancelled',
     'stream_incomplete',
+    /** The turn made its last allowed model call and that call asked for tools: there is no answer. */
+    'step_limit',
     'interrupted',
     /** Live: model finished generating audio/text for this utterance; turn may still be open. */
     'generation_complete',
 ];
+/** What a text turn's last allowed model call may do, as `turnBehaviour.atStepLimit` sets it. */
+export const STEP_LIMIT_MODES = ['stop', 'answer'];
+/** What happens to a list item its check refuses, as `outputs.validation.items.*.onFail` sets it. */
+export const ITEM_FAIL_ACTIONS = ['drop', 'fix'];
 /** Every other stop resumes by another host path, or not at all. */
 export const CONTINUE_STOP_KINDS = ['length', 'stream_incomplete', 'provider_error'];
+/** The points in a turn where a stage handler runs. */
 export const TURN_STAGES = [
     'pre_turn',
     'pre_tool',
@@ -94,24 +111,29 @@ export const TURN_STAGES = [
     'post_turn',
 ];
 const TURN_STAGE_SET = new Set(TURN_STAGES);
+/** True when the value names a turn stage. */
 export function isTurnStage(value) {
     return typeof value === 'string' && TURN_STAGE_SET.has(value);
 }
 /** Stages where an inject can land; the inject gate still applies. */
 export const TURN_INJECT_STAGES = ['pre_turn', 'post_tool', 'before_end'];
 const TURN_INJECT_STAGE_SET = new Set(TURN_INJECT_STAGES);
+/** True when the value names a stage an inject can land in. */
 export function isTurnInjectStage(value) {
     return typeof value === 'string' && TURN_INJECT_STAGE_SET.has(value);
 }
-/** `pre_tool` gates; not `awaiting_user_input`. */
-export const TOOL_GATE_KINDS = ['confirmation', 'permission', 'auth'];
+/** `pre_tool` gates; not `awaiting_user_input`. `page` holds a call for the page that answers it. */
+export const TOOL_GATE_KINDS = ['confirmation', 'permission', 'auth', 'page'];
 /** Why a refused gate settles: the user said no, walked away, or let it run out. */
 export const TOOL_RESUME_CAUSES = ['declined', 'abandoned', 'expired'];
 const TOOL_GATE_KIND_SET = new Set(TOOL_GATE_KINDS);
+/** True when the value names a tool gate kind. */
 export function isToolGateKind(value) {
     return typeof value === 'string' && TOOL_GATE_KIND_SET.has(value);
 }
+/** The questions a turn can pause to ask the user. */
 export const AWAITING_USER_INPUT_KINDS = ['confirm', 'choice', 'text'];
+/** Why a stage handler's result was partly or wholly ignored. */
 export const STAGE_APPLY_WARNING_CODES = [
     'affordance_not_allowed',
     'inject_not_allowed',
@@ -121,22 +143,30 @@ export const STAGE_APPLY_WARNING_CODES = [
     'deny_invalid',
     'confirm_invalid',
     'mutate_invalid',
+    'label_failed_invalid',
     'abort_invalid',
+    'wait_for_invalid',
     'unknown_field',
     'result_invalid',
 ];
+/** The `status` of a tool output that asks the user a question. */
 export const AWAITING_USER_INPUT_STATUS = 'awaiting_user_input';
 /** Enforced by the kernel at resolve time. */
-export const TOOL_LOAD_TIERS = ['T0', 'T1', 'T2'];
+export const TOOL_LOAD_TIERS = ['T0', 'T2'];
+/** The HTTP methods an `http` tool may use. */
 export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 /** When remote tool auth is missing or expired. */
-export const AUTH_UNAUTHENTICATED_POLICIES = ['gate', 'report_to_model'];
-export const TOOL_TYPES = ['builtin', 'function', 'http', 'mcp'];
+export const AUTH_UNAUTHENTICATED_POLICIES = ['gate', 'report_to_model', 'fail'];
+/** The kinds of tool a profile can list. */
+export const TOOL_TYPES = ['builtin', 'function', 'http', 'mcp', 'agent'];
+/** How much a tool can change: nothing, data, or irreversibly. */
 export const TOOL_ACCESS = ['read-only', 'read-write', 'destructive'];
+/** When the user must approve a tool call: never, once per session, or every call. */
 export const TOOL_PERMISSION = ['auto', 'session_consent', 'always_confirm'];
+/** The credential shapes a remote tool can authenticate with. */
 export const TOOL_AUTH_TYPES = ['bearer', 'api_key', 'oauth2'];
 /** Adds UI-only `none`, which omits auth at compile time. */
-export const PLAYGROUND_AUTH_TYPES = ['none', ...TOOL_AUTH_TYPES];
+export const STUDIO_AUTH_TYPES = ['none', ...TOOL_AUTH_TYPES];
 /**
  * The package's complete media-input vocabulary: `assertMediaMime` refuses any MIME not
  * here, so hosts keep no second table. Rows follow Google Interactions / Live's documented
@@ -200,6 +230,7 @@ export const MEDIA_WILDCARDS = ['image/*', 'audio/*', 'video/*'];
 function mimesOf(kind) {
     return Object.keys(MEDIA_INPUT_KINDS).filter((mime) => MEDIA_INPUT_KINDS[mime] === kind);
 }
+/** The MIME types a text profile's `accept` entries may list. */
 export const ATTACHMENT_ACCEPT_MIMES = [
     'image/*',
     'video/*',
@@ -219,35 +250,8 @@ export const IMAGE_ATTACHMENT_ACCEPT_MIMES = [
     ...mimesOf('video'),
     'application/pdf',
 ];
+/** The MIME types a voice profile's `accept` entries may list. */
 export const VOICE_ACCEPT_MIMES = ['audio/*', ...mimesOf('audio')];
-export function providersFor(protocol) {
-    return PROTOCOL_PROVIDERS[protocol];
-}
-export function protocolsFor(provider) {
-    const found = [];
-    for (const protocol of PROTOCOLS) {
-        if (PROTOCOL_PROVIDERS[protocol].includes(provider)) {
-            found.push(protocol);
-        }
-    }
-    return found;
-}
-/** True when `createProvider` will accept this pair. */
-export function isValidPair(protocol, provider) {
-    return PROTOCOL_PROVIDERS[protocol].includes(provider);
-}
-/** When protocol changes, snap provider to a valid partner. */
-export function coerceProvider(protocol, provider) {
-    const allowed = providersFor(protocol);
-    const [first] = allowed;
-    return allowed.includes(provider) ? provider : first;
-}
-/** When provider changes, snap protocol to a valid partner. */
-export function coerceProtocol(protocol, provider) {
-    const allowed = protocolsFor(provider);
-    const [first] = allowed;
-    return allowed.includes(protocol) ? protocol : first;
-}
 function unionType(values) {
     return values.map((value) => `'${value}'`).join(' | ');
 }
@@ -273,12 +277,17 @@ export const DYNAMIC_FIELD_PARENTS = new Set([
     'models',
     'models.*.efforts',
     'identity.systemByRole',
-    'lexicon',
+    'labels',
     'inputs.slots',
     'inputs.limitsByMime',
     'outputs.validation.fields',
+    'outputs.validation.items',
 ]);
+/** Turns a key path into its catalog path, replacing host-chosen map keys with `*`. */
 export function catalogPathFor(keys) {
+    const [first] = keys;
+    if (keys.length === 1 && first !== undefined && isProfileRootField(first))
+        return `profile.${first}`;
     const resolved = [];
     for (const key of keys) {
         const prefix = resolved.join('.');
@@ -291,6 +300,181 @@ export function catalogPathFor(keys) {
     }
     return resolved.join('.');
 }
+const DETECT_ACTION_DOCS = recordOf(DETECT_ACTIONS, (action) => DETECT_ACTION_META[action].doc);
+/** The `allow` rows of a detector: the URLs it lets through, or for `tool_leak` the names. */
+function allowFields(path, detector) {
+    if (DETECTOR_META[detector].allow === 'names') {
+        return [
+            [`${path}.allow`, field('NameAllow', 'The names that are innocent in a reply.')],
+            [
+                `${path}.allow.names`,
+                {
+                    ...field('string[]', 'Names of tools or parameters that are not read for, such as a tool called search.'),
+                    unset: 'None',
+                },
+            ],
+        ];
+    }
+    const hosts = detector === 'ungiven_links'
+        ? 'Hostnames whose links pass whatever their URL; the hosts ungiven_images allows pass too.'
+        : 'Hostnames whose images load whatever their URL, such as your own CDN.';
+    return [
+        [
+            `${path}.allow`,
+            field('UrlAllow', 'What passes besides the URLs the model was given this turn.'),
+        ],
+        [`${path}.allow.hosts`, { ...field('string[]', hosts), unset: 'None' }],
+        [
+            `${path}.allow.fromTools`,
+            {
+                ...field('boolean', 'Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user, and history gave.'),
+                unset: 'On',
+            },
+        ],
+    ];
+}
+const COMPILED_DOC = 'The table your patterns compile to, from compileDetect or `agents detect-compile`. Needed whenever patterns is set.';
+/** The rows of one pattern in a detector's `patterns`. */
+function patternRows(path) {
+    const each = `${path}.patterns.*`;
+    return [
+        [`${each}.name`, field('string', 'What a match is called in the trace.')],
+        [
+            `${each}.pattern`,
+            field('string', 'The source of a regular expression. A pattern takes this or words.'),
+        ],
+        [
+            `${each}.flags`,
+            {
+                ...field('string', 'Regular-expression flags, each a letter: i ignores case, m matches ^ and $ at each line, s lets . match a line break, u reads Unicode. Not g or y: every match is always found.'),
+                unset: 'None',
+            },
+        ],
+        [
+            `${each}.words`,
+            field('string[]', 'Words to match whole, whatever their case. A space in one matches any run of whitespace.'),
+        ],
+    ];
+}
+/** The rows of a detector of the host's own, under a key with a dot. */
+function hostDetectorFields(path) {
+    const action = (doc) => field('DetectAction', doc, DETECT_ACTIONS, DETECT_ACTION_DOCS);
+    return [
+        [
+            path,
+            field('HostDetectorConfig', 'Your own detector, keyed with a dot: acme.codenames. No default action.'),
+        ],
+        [`${path}.label`, field('string', 'What an editor and the trace call it.')],
+        [
+            `${path}.action`,
+            {
+                ...action('What a match does, at every boundary.'),
+                unset: 'Only the boundaries at names are read',
+            },
+        ],
+        [`${path}.at`, field('{ [boundary]: DetectAction }', 'An action per boundary, over action.')],
+        ...BOUNDARIES.map((boundary) => [
+            `${path}.at.${boundary}`,
+            { ...action(BOUNDARY_META[boundary].doc), unset: DETECT_ACTION_META.ignore.label },
+        ]),
+        [
+            `${path}.patterns`,
+            {
+                ...field('HostPattern[]', 'Its patterns, each a name and a regular expression or a list of words, read on the text as written.'),
+                unset: 'None',
+            },
+        ],
+        ...patternRows(path),
+        [`${path}.compiled`, field('CompiledPatterns', COMPILED_DOC)],
+        [
+            `${path}.hint`,
+            {
+                ...field('string', 'One line telling the model what to leave out, sent when this detector blocks a reply that is then retried.'),
+                unset: 'The labels’s detect.hint.own, which names the label',
+            },
+        ],
+        [
+            `${path}.find`,
+            field('HostFind', 'Its own reading, for what patterns cannot say: a function that returns where the matches start and end. It runs on every text crossing a boundary the detector reads, so it returns at once.'),
+        ],
+    ];
+}
+/** The rows of a detector that reads with patterns: whose it reads with. */
+function patternFields(path) {
+    return [
+        [
+            `${path}.theorem`,
+            {
+                ...field('boolean', 'Whether Theorem’s own patterns run. Off with no patterns of your own turns the detector off.'),
+                unset: 'On',
+            },
+        ],
+        [
+            `${path}.patterns`,
+            {
+                ...field('HostPattern[]', 'Your own patterns, each a name and a regular expression or a list of words. A match takes this detector’s action.'),
+                unset: 'None',
+            },
+        ],
+        ...patternRows(path),
+        [`${path}.compiled`, field('CompiledPatterns', COMPILED_DOC)],
+        [
+            `${path}.hint`,
+            {
+                ...field('string', 'One line telling the model what to leave out, sent when this detector blocks a reply that is then retried. Set it beside patterns of your own.'),
+                unset: `The labels’s detect.hint line for this detector`,
+            },
+        ],
+    ];
+}
+/** The settings a detector's full form takes, as a sentence lists them. */
+function settingsOf(detector) {
+    const { allow, patterns } = DETECTOR_META[detector];
+    if (allow && patterns)
+        return 'action, at, allow, theorem, patterns, and hint';
+    if (allow)
+        return 'action, at, and allow';
+    return patterns ? 'action, at, theorem, patterns, and hint' : 'action and at';
+}
+/** The `guardrails.detect` rows: one for the setting, one per detector, and one per detector and boundary. */
+function detectFields() {
+    const action = (type, doc) => field(type, doc, DETECT_ACTIONS, DETECT_ACTION_DOCS);
+    const rows = [
+        [
+            'guardrails.detect',
+            action('DetectAction | { [detector]: DetectorRule }', 'What a guardrail does when a detector matches. One action covers every detector; an object sets each detector (or one of your own) apart. Absent: each detector keeps its default action.'),
+        ],
+    ];
+    for (const detector of DETECTORS) {
+        const path = `guardrails.detect.${detector}`;
+        rows.push([
+            path,
+            action('DetectAction | DetectorConfig', `${DETECTOR_META[detector].doc} Set one action, or ${settingsOf(detector)}.`),
+        ]);
+        if (DETECTOR_META[detector].allow)
+            rows.push(...allowFields(path, detector));
+        if (DETECTOR_META[detector].patterns)
+            rows.push(...patternFields(path));
+        rows.push([
+            `${path}.action`,
+            {
+                ...action('DetectAction', 'What a match of this detector does at every boundary it reads, unless `at` names that boundary.'),
+                unset: 'Each boundary keeps its default',
+            },
+        ]);
+        rows.push([
+            `${path}.at`,
+            field('{ [boundary]: DetectAction }', 'An action per boundary, over action or the default.'),
+        ]);
+        for (const boundary of DETECTOR_BOUNDARIES[detector]) {
+            const unset = DETECT_ACTION_META[DETECT_DEFAULTS[detector][boundary]].label;
+            const meta = action('DetectAction', BOUNDARY_META[boundary].doc);
+            rows.push([`${path}.at.${boundary}`, { ...meta, unset }]);
+        }
+    }
+    rows.push(...hostDetectorFields('guardrails.detect.*'));
+    return Object.fromEntries(rows);
+}
 function withScopeAndPresence(fields) {
     return Object.fromEntries(Object.entries(fields).map(([path, meta]) => {
         const scope = profileFieldScope(path);
@@ -309,61 +493,59 @@ function withScopeAndPresence(fields) {
  * take it, and record it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters.
  */
 export const PROFILE_FIELDS = withScopeAndPresence({
-    id: field('string', 'The name this profile is registered and looked up by; registering the same id again replaces it.'),
-    type: field("'text' | 'image' | 'speech' | 'live' | 'decision' | 'host'", 'What kind of agent this is, and so what each call gives back: text, image, speech, live, decision or host.', PROFILE_TYPES, {
+    'profile.id': field('string', 'The name this profile is registered and looked up by, at most 64 characters; registering the same id again replaces it.'),
+    'profile.type': field("'text' | 'image' | 'speech' | 'live' | 'decision' | 'embedding' | 'host'", 'What kind of agent this is, and so what each call gives back: text, image, speech, live, decision, embedding, or host.', PROFILE_TYPES, {
         text: 'A chat or task agent. Each turn the model answers in text, or in JSON when outputs ask for a structured reply, and can call tools on the way.',
-        image: 'Makes pictures from a prompt, in the shape, size and format the image block sets.',
+        image: 'Makes pictures from a prompt, in the shape, size, and format the image block sets.',
         speech: 'Gives your app a voice. Each turn reads text aloud in the voice the speech block names.',
-        live: 'For talking in real time. One continuous voice and video session over Gemini Live, rather than separate turns.',
-        decision: 'For when your app needs a judgement, not a reply. It answers questions about a JSON state, each with a choice, a score or a number.',
-        host: 'A governed passthrough to your tool registry, with no model. It calls MCP, HTTP and in-app function tools under the same permissions, guardrails and traces as any agent.',
+        live: 'For talking in real time. One continuous voice and video session, rather than separate turns.',
+        decision: 'For when your app needs a judgement, not a reply. It answers questions about a JSON state, each with a choice, a score, or a number.',
+        embedding: 'For when your app needs vectors from text or provider-supported media.',
+        host: 'A governed passthrough to your tool registry, with no model. It calls MCP, HTTP, and in-app function tools under the same permissions and traces as any agent, guarded by detect and network.',
     }),
     identity: field('{ handle, system?, systemByRole? }', "The agent's display name and the system instruction it is given."),
-    'identity.handle': field('string', "The agent's display name for hosts and users (the model never sees it), and the systemByRole entry a turn gets when it names no known role."),
-    'identity.system': field('string | Array<string | { private: string }>', 'The instruction the model gets on every turn unless a systemByRole entry replaces it; OpenRouter image profiles send it only with includeText on. Mark what must not leak as { private: text }; only that is guarded. With none, the whole prompt is.'),
+    'identity.handle': field('string', 'The name hosts and users see for this agent, at most 32 characters; the model never sees it. It is also the role a turn gets when it names none, so identity.systemByRole may hold an entry under it.'),
+    'identity.system': field('string | Array<string | { private: string }>', 'The instruction the model gets on every turn unless a systemByRole entry replaces it; some providers send it for an image profile only with includeText on. Mark what must not leak as { private: text }; only that is guarded. With none, the whole prompt is.'),
     'identity.systemByRole': field('Record<string, string | Array<string | { private: string }>>', 'Other system instructions, picked by the role a turn names.'),
     'identity.systemByRole.*': field('string | Array<string | { private: string }>', 'The instruction that replaces identity.system when a turn names this role.'),
-    models: field('Record<ModelId, ModelBinding | DecisionModelBinding>', 'The models this profile can use, each under a name you choose.'),
+    models: field('Record<ModelId, ModelBinding | DecisionModelBinding>', 'The trained AI systems that turn input into results. Each entry binds a local name to an upstream model and its call settings.'),
     'models.*': field('ModelBinding | DecisionModelBinding', 'One model: how to reach it and the settings sent with it.'),
-    'models.*.protocol': field(unionType(PROTOCOLS), 'The API this model is called through: Gemini, OpenAI-style, or the Decisions API.', PROTOCOLS, {
-        geminiInteractions: "Google's Gemini Interactions API.",
-        geminiLive: "Google's Gemini Live streaming API.",
-        openAi: 'The OpenAI-style API, served by OpenRouter or a local server.',
-        decision: 'The typed Decisions API, served by TypeSafe or OpenRouter.',
-    }),
-    'models.*.provider': field(unionType(PROVIDERS), 'Who serves the model: Google, OpenRouter, a local server, or TypeSafe.', PROVIDERS, {
-        google: "Google's Gemini API.",
-        openrouter: 'OpenRouter, which routes to many model vendors.',
-        local: "A server you run (Ollama, llama.cpp, vLLM); it can't serve image profiles.",
-        typesafe: 'TypeSafe, serving its native decision models.',
-    }),
-    'models.*.apiId': field('string', "The model's name at the provider."),
+    'models.*.protocol': field('string', 'The API shape this model is spoken to in.'),
+    'models.*.provider': field('string', 'The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its registration supplies the endpoint and authentication.'),
+    'models.*.keySlot': field('KeySlot', "The key slot this model's calls are signed with, instead of the provider's. Use it to bill one model to a different key. Absent: the provider's primary slot."),
+    'models.*.fallbackKeySlot': field('KeySlot', "The key slot tried once after a rate limit or a busy model on the primary slot, instead of the provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot, if it has one."),
+    'models.*.options': field('JsonObject', "Settings only this model's protocol has, such as a task type or vector size. Each is checked when the profile loads. Any left out keep the provider's default."),
+    providerContinuation: field('ProviderContinuationPolicy', 'Who holds the conversation a saved provider state continues.'),
+    'providerContinuation.history': field("'host' | 'stateless' | 'provider'", 'Who holds the conversation a checkpoint continues: the host passes history back, the provider keeps it and the checkpoint travels alone, or the profile is stateless and every request stands alone.', ['host', 'stateless', 'provider']),
+    'models.*.apiId': field('string', "The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name this model has in the profile is its key in models."),
     'models.*.timeoutMs': field('number', 'How long a decision waits for its provider, in milliseconds. Omit for no timeout.'),
     decision: field('{ contract: DecisionContractId }', 'Names the host decision this profile makes.'),
-    'decision.contract': field('string', "Your name for this decision, recorded on its traces; it isn't sent to the model or checked against the questions."),
-    'models.*.efforts': field('Record<string, ThinkingLevel>', 'Named thinking levels for this model, which a turn can pick between when allowEffortSelect is on; local models ignore them.'),
+    'decision.contract': field('string', 'Your name for this decision, on its traces. Not sent to the model. Not checked against the questions.'),
+    'models.*.efforts': field('Record<string, ThinkingLevel>', 'Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a level its model does not take. Speech ignores them, and so may an image profile without includeText.'),
     'models.*.efforts.*': field(unionType(THINKING_LEVELS), 'The thinking level sent to the provider for this name.', THINKING_LEVELS, {
-        none: 'No thinking; OpenRouter only.',
+        none: 'No thinking, where the provider has that level.',
         minimal: 'The least thinking.',
         low: 'Light thinking.',
         medium: 'Moderate thinking.',
         high: 'Heavy thinking.',
-        xhigh: 'Heavier thinking; OpenRouter only.',
-        max: 'The most thinking the model supports; OpenRouter only.',
+        xhigh: 'Heavier thinking, where the provider has that level.',
+        max: 'The most thinking the model supports, where the provider has that level.',
     }),
     'models.*.defaultEffort': field('string', "The effort a turn gets when it doesn't pick one."),
     'models.*.allowEffortSelect': field('boolean', 'Lets a turn pick an effort; needs two or more efforts.'),
-    'models.*.summaries': field('boolean', 'Asks Gemini Interactions for summaries of its thinking; on OpenRouter, off only hides thoughts, and other providers ignore it.'),
-    'models.*.maxOutputTokens': field('number', 'The most tokens the model may write in one reply.'),
-    'models.*.temperature': field('number', "How varied the model's wording is; higher is more random."),
-    'models.*.builtInTools': field('BuiltinToolId[]', "The provider's own tools, such as Google Search, this model may use; each must be registered as a builtin tool."),
-    'models.*.key': field('KeySlot', "The key slot this model's calls use, ahead of the profile's key."),
-    'models.*.fallbackKey': field('KeySlot', "The key slot this model's calls retry on when its key is refused for quota, ahead of the profile's fallbackKey."),
-    'models.*.compaction': field('CompactionSpec', 'Summarises older history once it grows past a threshold; the agent writes the summary unless profile names another.'),
+    'models.*.summaries': field('boolean', 'Asks the model for summaries of its thinking, which not every model sends; with some providers, off only hides thoughts, and others ignore it.'),
+    'models.*.maxOutputTokens': field('number', 'The token limit for one reply. Some providers never send it for speech, or for image without includeText.'),
+    'models.*.temperature': field('number', "How varied the model's wording is; higher is more random. Some providers never send it for speech, or for image without includeText."),
+    'models.*.builtInTools': field('BuiltinToolId[]', "The provider's own tools, such as Google Search, this model may use; each must be registered as a builtin tool and declared by the provider's adapter."),
+    'models.*.compaction': field('CompactionSpec', 'Summarises history past a threshold. A text agent can write the summary. Other types name a compaction profile.'),
     'models.*.compaction.maxTokens': field('number', 'The token budget compactAt is a fraction of.'),
-    'models.*.compaction.compactAt': field('number', 'The fraction of maxTokens, between 0 and 1, at which compaction starts.'),
-    'models.*.compaction.previousExchanges': field('number', 'How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of maxTokens (between 0 and 1), or 0 to compact it all.'),
-    'models.*.compaction.profile': field('ProfileId', 'The profile that writes the summary; register it before this one. Leave it out and the agent summarises its own history, with its own instructions and model and no tools.'),
+    'models.*.compaction.trigger': field('(ctx: CompactionTriggerContext) => boolean | Promise<boolean>', 'Your function that decides when to compact, in place of compactAt and maxTokens.'),
+    'models.*.compaction.compactAt': field('number', 'The fraction of maxTokens, between 0 and 1, at which compaction starts, unless trigger decides.'),
+    'models.*.compaction.previousExchanges': field('number', 'How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of maxTokens below compactAt, or 0 to compact it all.'),
+    'models.*.compaction.profile': {
+        ...field('ProfileId', 'The text profile that writes the summary; register it before this one. Leave it out and a text agent summarises its own history, with its own instructions and model and no tools. Its registered model binding selects the provider independently of the calling agent.'),
+        unset: 'The agent itself',
+    },
     'models.*.compaction.timing': field(unionType(COMPACTION_TIMINGS), 'Whether the kernel compacts before the turn or tells the host to compact after it.', COMPACTION_TIMINGS, {
         before: 'The kernel compacts before the turn runs.',
         after: "The turn's done event says compaction is due, and the host runs it.",
@@ -372,67 +554,62 @@ export const PROFILE_FIELDS = withScopeAndPresence({
         history: 'Tokens in the earlier conversation.',
         input: 'The prompt tokens the provider reported for the last call, or the count the host passes in.',
     }),
-    'models.*.cache': field('CacheSpec', 'Prompt caching on OpenRouter: reuses the start of a prompt it has already seen.'),
-    'models.*.cache.mode': field(unionType(CACHE_MODES), 'Which part of the prompt is cached.', CACHE_MODES, {
-        automatic: 'The whole request, so the cached part grows with the conversation.',
-        system: 'The system instruction only; nothing is cached without one.',
-    }),
-    'models.*.cache.ttl': field(unionType(CACHE_TTLS), 'How long a cached prompt lasts.', CACHE_TTLS, {
-        '5m': 'Five minutes.',
-        '1h': 'One hour; writing the cache costs more, which pays off in long sessions.',
-    }),
-    'models.*.store': field('boolean', 'Whether Google stores the interaction (Gemini Interactions only); a turn can override it.'),
-    'models.*.persistViaInteractionId': field('boolean', 'Whether Google builds the context from its stored interaction (true) or every call sends the history the host passes plus the steps of this turn (false); Gemini Interactions only, and true needs storing on.'),
-    'models.*.server': field('string', "Which local server runs the model (ollama, vllm, …), recorded on traces; it doesn't change where requests go."),
-    defaultModel: field('ModelId', "The model a turn gets when it doesn't pick one."),
-    allowModelSelect: field('boolean', 'Lets a turn pick a model; needs two or more models.'),
-    maxSteps: field('number', 'The most model calls one turn may make while using tools, where 1 runs the tools asked for but never sends their results back; live sessions ignore it.'),
-    key: field('KeySlot', 'The key slot used when a model has no key of its own.'),
-    fallbackKey: field('KeySlot', 'The key slot a call retries on once when its key is refused for quota. Off unless set.'),
-    tools: field('{ allow: ToolId[]; t1Policy?; t2Loader? }', 'Which of your registered tools this profile may use, and how they load; built-in tools are turned on per model.'),
+    'profile.defaultModel': field('ModelId', "The model a turn gets when it doesn't pick one."),
+    'profile.allowModelSelect': field('boolean', 'Lets a turn name the model it runs on; a name the profile does not declare is refused.'),
+    'profile.maxSteps': field('number', 'The most model calls one turn may make while using tools, counted afresh for each rewrite; 1 runs the tools asked for but never sends their results back. Live sessions ignore it.'),
+    tools: field('{ allow: ToolId[]; t1Policy?; t2Loader?; parallel? }', 'The registered tools this profile may use, and how they load. Built-in tools are set per model.'),
     'tools.allow': field('ToolId[]', "Your registered tools this agent may use; the provider's own tools go on the model's builtInTools instead."),
-    'tools.t1Policy': field('(ctx) => ToolId[] | Promise<ToolId[]>', 'Your function that picks, at the start of each turn, which T1 tools to load.'),
-    'tools.t2Loader': field('ToolId', 'The function tool the model calls to load T2 tools; it must be in allow and return the ids to load.'),
+    'tools.t1Policy': field('(ctx) => ToolId[] | Promise<ToolId[]>', 'Your function that picks, at the start of each turn, which T2 tools to load up front; the rest wait for tools.t2Loader.'),
+    'tools.t2Loader': field('ToolId', "The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be called from the next step: a step's calls see the tools as they stood when the step began."),
+    'tools.parallel': field('boolean', 'true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts its body once those calls settle. Left out or false: they run one at a time, in the order the model made them. A step is the calls the model makes together in a turn, or the calls a host runs through invokeToolStep.'),
     inputs: field('ProfileInputsSpec | DecisionInputsSpec', 'What a turn may send (text, files, voice, choices), or on a decision, the state it reads.'),
     'inputs.state': field("'json'", 'A decision reads JSON state, passed on each call.', ['json']),
     'inputs.maxStateBytes': field('number', 'The largest state, in bytes, a decision call may send; larger state is refused before it leaves your process.'),
     'inputs.text': field('boolean', 'Whether a turn may send text.'),
     'inputs.attachments': field('{ accept: string[] }', 'Lets turns send files.'),
-    'inputs.attachments.accept': field('string[]', 'The file types a turn may send, where type/* matches a whole family; image profiles take only images, video and PDF.', ATTACHMENT_ACCEPT_MIMES, "Types the kernel knows; a listed type it doesn't know is refused when a turn sends it."),
+    'inputs.attachments.accept': field('string[]', 'The file types a turn may send, where type/* matches a whole family; image profiles take only images, video, and PDF.', ATTACHMENT_ACCEPT_MIMES, "Types the kernel knows; a listed type it doesn't know is refused when a turn sends it."),
     'inputs.voice': field('{ accept: string[] }', 'Lets turns send voice clips.'),
     'inputs.voice.accept': field('string[]', 'The audio types a voice clip may be; audio/* matches them all.', VOICE_ACCEPT_MIMES, 'Audio types the kernel knows.'),
-    'inputs.maxFiles': field('number', 'The most files and voice clips one turn may send, counted together.'),
-    'inputs.maxBytes': field('number', 'The largest file or clip, in bytes, a turn may send inline.'),
-    'inputs.maxTurnBytes': field('number', 'The most bytes one turn may send inline across all its files and clips.'),
+    'inputs.maxFiles': field('number', 'The most files and voice clips one turn or embedding request may send, counted together.'),
+    'inputs.maxBytes': field('number', 'The largest file or clip, in bytes, a turn or embedding request may send inline.'),
+    'inputs.maxTurnBytes': field('number', 'The most bytes one turn or embedding request may send inline across all its files and clips.'),
     'inputs.limitsByMime': field('Record<string, number>', 'Size limits by file type that replace maxBytes for those types.'),
-    'inputs.limitsByMime.*': field('number', 'The largest file of this type (or type/* family), in bytes, a turn may send inline.'),
-    'inputs.slots': field('Record<string, string[]>', 'Named choices a turn can make, such as language, each with its allowed values.'),
+    'inputs.limitsByMime.*': field('number', 'The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.'),
+    'inputs.slots': field('Record<string, string[]>', 'Named choices a turn or a call can make, such as language, each with its allowed values. {name} in a prompt becomes the chosen value.'),
     'inputs.slots.*': field('string[]', 'The values a turn may choose for this slot; any other is refused.'),
+    'inputs.context': field('{ from: ContextSender[]; maxChars: number }', 'Lets the page or the host send the agent one package of things to know, read at the context boundary.'),
+    'inputs.context.from': field("Array<'client' | 'server'>", 'Who may send context; context from anyone else is refused.', CONTEXT_SENDERS, {
+        client: 'The browser. A visitor can change it, so it is untrusted.',
+        server: "The host's own code. It is assembled, like turn system text.",
+    }),
+    'inputs.context.maxChars': field('number', 'The longest package, in characters of its JSON, each sender may send.'),
     outputs: field('ProfileOutputsSpec', 'The shape of the reply, how it is checked, and how it streams.'),
-    'outputs.structured': field('StructuredSchemaId | StructuredBySlot | null', 'The registered JSON schema the reply must follow, which can vary by slot.'),
-    image: field('ProfileImageSpec', 'Settings for the images this profile makes.'),
+    'outputs.structured': field('StructuredSchemaId | StructuredBySlot | null', 'The registered JSON schema the reply must follow, which can vary by slot; register it before the profile.'),
+    image: field('ProfileImageSpec', 'How the images this profile generates are shaped and made: size, format, quality and references. Each setting is sent only where the provider has it; one it lacks is refused or ignored, as that setting says.'),
     'image.aspectRatio': field('string', 'The shape of generated images, such as 16:9.'),
     'image.resolution': field('string', 'How detailed generated images are, such as 1K, 2K or 4K.'),
-    'image.mimeType': field('string', 'The file type of generated images; OpenRouter takes png, jpeg or webp and uses png for anything else.'),
-    'image.quality': field('string', 'How much effort the model spends on each image; OpenRouter takes auto, low, medium or high.'),
-    'image.background': field('string', 'The background of generated images; OpenRouter takes auto, transparent or opaque.'),
-    'image.n': field('number', 'How many images one request makes; only OpenRouter `/images` takes it, up to 10.'),
-    'image.seed': field('number', 'A seed for repeatable images; OpenRouter `/images` and Google take it, where the model honours it.'),
-    'image.outputCompression': field('number', 'Compression from 0 to 100 for jpeg and webp images; OpenRouter only.'),
-    'image.references': field('Array<TurnBlob | TurnMediaRef>', 'Reference images sent with every turn, ahead of the ones the user attaches; each is bytes (`data`) or a link (`uri`).'),
-    'image.includeText': field('boolean', 'Whether the model may write text alongside its images; on OpenRouter this also sends the system instruction and history.'),
-    speech: field('ProfileSpeechSpec', 'Settings for the audio this profile speaks.'),
-    'speech.voice': field('string', 'The voice the speech is read in.'),
-    'speech.format': field(unionType(SPEECH_AUDIO_FORMATS), 'The audio format asked of the provider.', SPEECH_AUDIO_FORMATS, {
+    'image.mimeType': field('string', 'The file type of generated images; a provider that takes a fixed set of types may use png for any other.'),
+    'image.quality': field('string', 'How much effort the model spends on each image: auto, low, medium, or high. A provider that has no such setting refuses it.'),
+    'image.background': field('string', 'The background of generated images: auto, transparent, or opaque. A provider that has no such setting refuses it.'),
+    'image.n': field('number', 'How many images one request makes, where the provider takes a count.'),
+    'image.seed': field('number', 'A seed for repeatable images, where the provider and the model honour it.'),
+    'image.outputCompression': field('number', 'Compression from 0 to 100 for jpeg and webp images, where the provider takes it.'),
+    'image.references': field('Array<TurnBlob | TurnMediaRef>', "Images sent with every turn, before the user's. Each is bytes (`data`) or a link (`uri`). Some providers take http(s) links only, and none with includeText."),
+    'image.includeText': field('boolean', 'Whether the model may write text alongside its images; with some providers this also sends the system instruction and history.'),
+    speech: field('ProfileSpeechSpec', "How the profile's speech sounds and is delivered: voice, style, speed and audio format. A turn may replace voice, style and speed for that turn."),
+    'speech.voice': field('string', "The voice the speech is read in, by the provider's own name for it; a turn's speech.voice replaces it."),
+    'speech.style': field('string', "How the script is delivered, in plain words (pace, mood, accent); it is never read aloud, and a turn's speech.style replaces it. A model that takes no direction ignores it."),
+    'speech.speed': field('number', "The speaking rate, where 1 is the voice's own pace; a turn's speech.speed replaces it. A provider that has no rate refuses it or ignores it."),
+    'speech.format': field(unionType(SPEECH_AUDIO_FORMATS), "The audio encoding each turn's speech comes back in, and so what the host plays or stores.", SPEECH_AUDIO_FORMATS, {
         pcm: 'Uncompressed audio, delivered as WAV.',
-        mp3: 'Compressed audio; OpenRouter only.',
+        mp3: 'Compressed audio; a provider that cannot make it refuses the turn.',
     }),
-    live: field('ProfileLiveSpec', 'Settings for the realtime voice and video session.'),
+    live: field('ProfileLiveSpec', 'How a realtime voice and video session runs: what it accepts from the user, the voice it answers in, when it hears the user start and stop, and how it resumes and trims its context.'),
     'live.ingress': field('LiveIngressSpec', 'Which channels the session accepts from the user.'),
     'live.ingress.audio': field('boolean', 'Whether the session accepts microphone audio.'),
     'live.ingress.video': field('boolean', 'Whether the session accepts camera frames.'),
     'live.ingress.text': field('boolean', 'Whether the session accepts typed text.'),
-    'live.voice': field('string', 'The voice the model speaks in.', GOOGLE_SPEECH_VOICES, "Google's voice names; any other name is sent as written."),
+    'live.voice': field('string', 'The voice the model speaks in.', GOOGLE_SPEECH_VOICES, 'Voice names to pick from; any other name is sent as written.'),
     'live.vad': field('LiveVadSpec', 'How the session detects when the user starts and stops speaking.'),
     'live.vad.activityHandling': field(unionType(LIVE_ACTIVITY_HANDLINGS), "Whether the user speaking interrupts the model's reply.", LIVE_ACTIVITY_HANDLINGS, {
         START_OF_ACTIVITY_INTERRUPTS: 'The user speaking cuts the reply off.',
@@ -448,22 +625,30 @@ export const PROFILE_FIELDS = withScopeAndPresence({
     }),
     'live.vad.prefixPaddingMs': field('number', 'How long speech must last, in milliseconds, before it counts as the user starting to speak.'),
     'live.vad.silenceDurationMs': field('number', "How long a silence, in milliseconds, ends the user's speech."),
-    'live.sessionResumption': field('boolean', 'Whether Google sends resume handles, which the host can pass to a new session to carry this one on.'),
+    'live.sessionResumption': field('boolean', 'Whether the provider sends resume handles, which the host can pass to a new session to carry this one on.'),
+    'live.greeting': field('string', 'A prompt the call sends itself when it opens new, so the agent speaks first. The visitor does not see it. It may use {slot}.'),
+    'live.resumed': field('{ prompt: string; afterMs?: number }', 'What happens when a call comes back after a drop. It needs live.sessionResumption.'),
+    'live.resumed.prompt': field('string', 'A prompt the call sends itself when it resumes, so the agent says it is back. The visitor does not see it. It may use {slot}.'),
+    'live.resumed.afterMs': field('number', 'The shortest time away, in milliseconds, that earns the prompt; a shorter drop resumes silently.'),
     'live.contextCompression': field('LiveContextCompressionSpec', "Trims the session's context once it grows past the trigger."),
     'live.contextCompression.triggerTokens': field('number', 'The context size, in tokens, that starts trimming.'),
     'live.contextCompression.slidingWindow': field('LiveSlidingWindowSpec', 'Trims by dropping the oldest turns; the system instruction stays.'),
     'live.contextCompression.slidingWindow.targetTokens': field('number', 'The context size, in tokens, to trim down to; below the trigger.'),
     'live.transcription': field('LiveTranscriptionSpec', "Text transcripts of the session's speech."),
     'live.transcription.input': field('boolean', "Whether the user's speech is transcribed."),
-    'live.transcription.output': field('boolean', "Whether the model's speech is transcribed."),
+    'live.transcription.output': field('boolean', "Whether the model's speech is transcribed; always on while a detector reads live_reply, since it reads the transcript."),
     'outputs.validation': field('ProfileValidationSpec', 'Your checks on a structured reply, and how many rewrites a failure gets.'),
-    'outputs.validation.fields': field('Record<string, ProfileValidator>', 'Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid.'),
-    'outputs.validation.fields.*': field('(candidate: unknown, slots?: Record<string, string>) => ValidationResult | Promise<ValidationResult>', 'Your check on this part of the reply; a failure sends its error back to the model to rewrite.'),
-    'outputs.validation.maxRetries': field('number', 'How many times the model may rewrite a reply that fails your checks before it goes out as it is; the larger of this and egress.maxRetries applies to both.'),
+    'outputs.validation.fields': field('Record<string, ProfileValidator>', 'Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a path no structured schema reaches is refused when the profile registers.'),
+    'outputs.validation.fields.*': field('(candidate: unknown, slots?: Record<string, string>) => ValidationResult | Promise<ValidationResult>', 'Your check on this part of the reply, reached through object properties only; a failure sends its error back to the model to rewrite while retries remain.'),
+    'outputs.validation.items': field('Record<string, ProfileItemRule>', 'Your checks on the items of a list, each keyed by the dotted path of that list in the structured reply, such as claims; a path no structured schema reaches as a list is refused when the profile registers.'),
+    'outputs.validation.items.*': field('ProfileItemRule', 'Your check on each item of this list. A refused item never fails the reply and the rest of the reply is kept.'),
+    'outputs.validation.items.*.check': field('(item: unknown, turn: ItemCheckTurn) => ValidationResult | Promise<ValidationResult>', 'Your check on one item, given what the tools of the turn returned (turn.toolResults); its error is the reason the model reads on a rewrite and the host reads on the removed item.'),
+    'outputs.validation.items.*.onFail': field("'drop' | 'fix'", 'drop removes a refused item. fix first asks the model to rewrite the refused items alone, once and while retries remain, then removes any refused again. Removed items leave on the structured event as removed.', ITEM_FAIL_ACTIONS),
+    'outputs.validation.maxRetries': field('number', "How many times the model may rewrite a reply that fails your checks or the schema's required keys before it goes out as it is; under sse, an attempt that gets rewritten has already streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too."),
     'outputs.streaming': field('ProfileStreamingSpec', 'How the reply reaches the host, and whether its thinking does.'),
-    'outputs.streaming.mode': field(unionType(STREAM_MODES), 'Whether the provider call streams.', STREAM_MODES, {
-        sse: 'Events arrive as the model writes.',
-        buffered: 'One non-streaming call; its events arrive together when it answers.',
+    'outputs.streaming.mode': field(unionType(STREAM_MODES), 'Whether the reply reaches the host as the model writes it, or whole.', STREAM_MODES, {
+        sse: 'Events arrive as the model writes, so a reply that fails outputs.validation has already streamed when it is rewritten; some providers always answer image and speech in one piece.',
+        buffered: 'One non-streaming call, whose events arrive together; under outputs.validation, only once the reply passes or retries run out. Thinking still streams.',
     }),
     'outputs.streaming.streamThoughts': field('boolean', "Whether the model's thinking reaches the host."),
     turnBehaviour: field('ProfileTurnBehaviourSpec', 'Whether a reply that stopped early can be continued, and whether a running turn can be steered.'),
@@ -473,181 +658,238 @@ export const PROFILE_FIELDS = withScopeAndPresence({
         stream_incomplete: 'The connection dropped mid-reply.',
         provider_error: 'The provider returned an error or timed out.',
     }),
-    'turnBehaviour.resumption.autoContinue': field('ContinueStopKind[]', 'Which early stops the host continues once without asking; each must also be in allowContinue.', CONTINUE_STOP_KINDS, {
+    'turnBehaviour.resumption.autoContinue': field('ContinueStopKind[]', 'Which early stops are continued without asking, whether or not allowContinue offers a Continue for them. When set, a text turn sends a listed failed model call that gave no reply again itself; the host continues the rest.', CONTINUE_STOP_KINDS, {
         length: 'The reply hit the output token limit.',
         stream_incomplete: 'The connection dropped mid-reply.',
         provider_error: 'The provider returned an error or timed out.',
     }),
-    'turnBehaviour.resumption.maxContinues': field('number', 'How many times one reply may be continued; once set, each continue must say which one it is.'),
-    'turnBehaviour.allowSteering': field('boolean', 'Whether your onStage hook may add messages to a running turn; text profiles also offer the user a way to steer.'),
-    guardrails: field('ProfileGuardrailsSpec', "Protections for this profile's turns."),
-    'guardrails.quota': field('QuotaGuardrailSpec', "A daily turn limit your server middleware enforces; runTurn itself doesn't count turns."),
-    'guardrails.quota.perDay': field('number', 'Turns each client IP may run on this profile per UTC day.'),
-    'guardrails.canary': field('boolean', 'Plants a secret token in the system instruction and stops the reply if the model repeats it.'),
-    'guardrails.promptEcho': field('boolean', 'With the canary on, also stops a reply that repeats 12 words in a row of the private system instruction. On by default; mark the lines meant to be quoted as shareable parts, or turn it off when the whole instruction is meant to be quoted.'),
-    'guardrails.sanitizeInput': field('boolean', 'Replaces prompt-injection text in user input, history and tool results before the model sees it.'),
-    'guardrails.redactSensitive': field('boolean | SensitiveSwitches', 'Replaces credentials and personal data in user input, history and tool results before the model sees them. true (the default) covers every group, false none; an object turns groups off one by one.'),
-    'guardrails.redactSensitive.ids': field('boolean', 'US SSN, ITIN and EIN numbers.'),
-    'guardrails.redactSensitive.financial': field('boolean', 'IBANs and card numbers.'),
-    'guardrails.redactSensitive.network': field('boolean', 'IPv4 and IPv6 addresses.'),
-    'guardrails.redactSensitive.credentials': field('boolean', 'API keys, access tokens, bearer tokens and private keys.'),
-    'guardrails.egress': field('ProfileEgressSpec', 'Your check on the reply before the user sees it.'),
-    'guardrails.egress.enforce': field('EgressEnforcer', 'Your own check on the reply, run as it streams and when it ends. Return allow, flag (log only), redact (swap in your text) or block (see onBlock); a block or redact holds the rest of the stream, and a throw counts as a block. Set this or checks, not both.'),
-    'guardrails.egress.checks': field('boolean | EgressChecks', 'The bundled checks on the reply, blocking on what they find. true runs each at its default, false none but the system-prompt leak checks, and an object switches the ones it names. Set this or enforce, not both.'),
-    'guardrails.egress.checks.sensitive': field('boolean | SensitiveSwitches', 'Credentials and personal data in the reply, by group. Every group but network by default: an address in a reply is not a secret.'),
-    'guardrails.egress.checks.sensitive.ids': field('boolean', 'US SSN, ITIN and EIN numbers.'),
-    'guardrails.egress.checks.sensitive.financial': field('boolean', 'IBANs and card numbers.'),
-    'guardrails.egress.checks.sensitive.network': field('boolean', 'IPv4 and IPv6 addresses.'),
-    'guardrails.egress.checks.sensitive.credentials': field('boolean', 'API keys, access tokens, bearer tokens and private keys.'),
-    'guardrails.egress.checks.boundary': field('boolean', 'The markers the kernel puts around user data, and the canary note, repeated in the reply.'),
-    'guardrails.egress.checks.injection': field('boolean', 'Prompt-injection phrasing in the reply, as written or disguised.'),
-    'guardrails.egress.checks.images': field('boolean | UrlCheck', 'Images in the reply that load a URL the model was not given, which would send data off the device with no click.'),
-    'guardrails.egress.checks.images.hosts': field('string[]', 'Hostnames whose images load whatever their URL, such as your own CDN.'),
-    'guardrails.egress.checks.images.fromTools': field('boolean', 'Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user and history gave.'),
-    'guardrails.egress.checks.links': field('boolean | UrlCheck', 'Links in the reply to a URL the model was not given. Turn it on when your app unfurls links into previews.'),
-    'guardrails.egress.checks.links.hosts': field('string[]', 'Hostnames whose links pass whatever their URL; the images hosts pass too.'),
-    'guardrails.egress.checks.links.fromTools': field('boolean', 'Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user and history gave.'),
-    'guardrails.egress.onBlock': field(unionType(EGRESS_ON_BLOCK), 'What happens when enforce blocks the reply.', EGRESS_ON_BLOCK, {
-        reject_to_agent: 'The model reads why and rewrites the reply, up to maxRetries times; once retries run out, the reply is withheld and the turn ends with a safety error.',
-        refuse_to_user: 'The user sees the egress.refusal wording in place of the reply, and the turn ends.',
+    'turnBehaviour.resumption.maxContinues': field('number', 'How many times one reply may be continued; once set, each continue must say which one it is. Also how many failed model calls one text turn sends again itself (one when unset).'),
+    'turnBehaviour.allowSteering': field('boolean', 'Lets your onStage hook add messages to a running turn. Text profiles also let the user steer.'),
+    'turnBehaviour.atStepLimit': field("'stop' | 'answer'", 'What happens when a turn reaches maxSteps while the model still wants tools: the turn stops with no answer, or the last call is made without tools so it answers.', STEP_LIMIT_MODES, {
+        stop: 'It may still call tools; if it does, they run and the turn stops as step_limit with no answer.',
+        answer: 'It is sent without tools, so it writes the answer from what the turn has gathered.',
+    }),
+    guardrails: field('ProfileGuardrailsSpec', 'Theorem checks what enters or leaves an agent’s context and generation against built-in or custom rules at each configured boundary.'),
+    'guardrails.quota': field('QuotaGuardrailSpec', 'A daily turn limit. Your server enforces it with takeSlot.'),
+    'guardrails.quota.perDay': field('number', 'Turns each client IP may run on this profile per UTC day, one at a time; counts live in the process, and a loopback caller is not counted.'),
+    ...detectFields(),
+    'guardrails.blockedReply': field('BlockedReplySpec', 'How a reply a guardrail blocked is handled: the model rewrites it, or the user gets a refusal, and how many rewrites it gets.'),
+    'guardrails.blockedReply.onBlock': field(unionType(BLOCKED_REPLY_ON_BLOCK), 'Whether the model gets to rewrite a reply a guardrail blocked, or the user gets a refusal in its place.', BLOCKED_REPLY_ON_BLOCK, {
+        retry: 'The model reads why and rewrites the reply, up to maxRetries times; once retries run out, the reply is withheld and the turn ends with a safety error. Live never rewrites: it withholds at once.',
+        refuse: 'The user sees the egress.refusal wording in place of the reply, and the turn ends.',
     }),
-    'guardrails.egress.maxRetries': field('number', 'How many times the model may rewrite a blocked reply; the larger of this and outputs.validation.maxRetries applies to both.'),
-    'guardrails.egress.holdback': field('number', 'How many characters the stream holds back so your own enforce can catch text split across chunks (default 256; 96 on Live). The bundled policy holds exactly what it needs and ignores this.'),
-    'guardrails.network': field('NetworkGuardrailSpec', 'Which addresses your HTTP and MCP tools may reach.'),
+    'guardrails.blockedReply.maxRetries': field('number', 'How many times the model may rewrite a blocked reply. Live ignores it.'),
+    'guardrails.network': field('NetworkGuardrailSpec', 'Addresses HTTP and MCP tools may reach.'),
     'guardrails.network.allowPrivateNetworks': field('boolean', 'Lets tools reach localhost and private network addresses, for local development.'),
-    'guardrails.network.allowedHosts': field('string[]', "Hostnames tools may reach even when they resolve to a private address; public hosts don't need listing."),
+    'guardrails.network.allowedHosts': field('string[]', "Hostnames tools may reach even when they resolve to a private address; public hosts don't need listing. Names are resolved only when the host passes resolveHost."),
     'guardrails.network.allowedSchemes': field('string[]', 'The URL schemes tools may use.'),
-    'guardrails.taint': field('TaintGuardrailSpec', "What tools may still do after the turn reads a remote tool's result."),
+    'guardrails.taint': field('TaintGuardrailSpec', 'Tool limits after a remote read.'),
     'guardrails.taint.afterRemoteRead': field(unionType(TAINT_GATES), "Which tool calls are refused, by each tool's access, once the turn has read a remote tool's result.", TAINT_GATES, {
         off: 'None; risky calls are only logged.',
         destructive: 'Destructive calls.',
         write: 'Read-write and destructive calls.',
     }),
+    'guardrails.taint.remoteDestination': field(unionType(DESTINATION_GATES), "What happens to a tool call, read-only ones too, that sends to an email address, a link's host or a bank account number (IBAN) that only the running text of a remote tool's result named. One the user, the system prompt, or a local tool gave passes, and so does one that is a whole field of the result.", DESTINATION_GATES, {
+        off: 'The call runs; it is only logged.',
+        confirm: 'The call waits for the user to approve it; an approval runs it.',
+        block: 'The call is refused, and the model is told why.',
+    }),
     'guardrails.disclosure': field('{ enforce: DecisionDisclosureEnforcer }', 'Your check on the state before a decision sends it to the model.'),
     'guardrails.disclosure.enforce': field('(state, context) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>', 'Your function that allows or blocks the state before it is sent.'),
-    lexicon: field('LexiconOverrides', "This profile's own wording for error lines, notices and notes to the model, by lexicon key."),
-    'lexicon.*': field('string', 'The wording for this lexicon key; canary.bind_note must keep its {canary} placeholder.'),
+    labels: field('LabelOverrides', "This profile's own wording for error lines, notices, and notes to the model, by labels key."),
+    'labels.*': field('string', 'The wording for this labels key; canary.bind_note must keep its {canary} placeholder.'),
     observability: field('ProfileObservabilitySpec', "Where this profile's traces go and what they keep."),
-    'observability.writeTo': field('false | string | TraceSink', 'Where traces are written: a destination id you registered, your own writer, or false for none; a sink passed straight to runTurn replaces it.'),
-    'observability.sampleRate': field('number', 'The share of traces kept, from 0 to 1, each kept or dropped whole.'),
+    'observability.writeTo': field('false | string | TraceSink', 'Where traces go: a registered destination id, your own writer, or false. An unregistered id fails the turn at the start. A sink passed to runTurn replaces it.'),
+    'observability.sampleRate': field('number', 'The share of traces kept, from 0 to 1, each kept or dropped whole; a sink passed straight to runTurn keeps every trace.'),
     'observability.include': field('TraceIncludeSpec', 'Which optional parts of a trace are kept.'),
-    'observability.include.upstreamLog': field('boolean', 'Keeps each row the provider sent back, scrubbed, as it arrived.'),
+    'observability.include.upstreamLog': field('boolean', 'Keeps each row the provider sent back, scrubbed, as it arrived, with media bytes replaced by their sha256.'),
     'observability.include.outboundWire': field('boolean', 'Keeps each request body sent to the provider, scrubbed.'),
-    'observability.include.evidenceRaw': field('boolean', "Keeps the provider's raw payload on grounding results such as search citations."),
-    'observability.include.usage': field('boolean', 'Keeps token counts and other usage figures.'),
+    'observability.include.evidenceRaw': field('boolean', "Keeps the provider's raw payload on grounding results such as search citations; upstreamLog rows keep their own copy."),
+    'observability.include.usage': field('boolean', 'Keeps token counts and other usage figures on spans; upstreamLog rows keep their own.'),
     'observability.include.guardrailDecisions': field('boolean', 'Keeps each guardrail decision.'),
-    'observability.include.guardrailMatchPreview': field('boolean', "Keeps the exact text each guardrail matched, on the trace and the host's event stream; for debugging only."),
+    'observability.include.guardrailMatchPreview': field('boolean', "Keeps the exact text each guardrail matched, unscrubbed, on the trace and the host's event stream; for debugging only."),
     'observability.resource': field('Record<string, TraceAttributeValue>', 'Attributes stamped on every trace, such as service.name.'),
     'observability.scrub': field('TraceScrubSpec', "What is removed from stored traces, separately from the turn's guardrails."),
-    'observability.scrub.sensitive': field('boolean', 'Removes credentials and personal data from stored traces.'),
-    'observability.scrub.injection': field('boolean', 'Removes prompt-injection text from stored traces.'),
-    'observability.scrub.canary': field('boolean', 'Removes the canary token from stored traces.'),
-    'observability.retainForDays': field('number', 'How many days each trace is kept; 0 or less keeps them forever.'),
+    'observability.scrub.sensitive': field('ScrubSwitch', "Removes what the data detectors (IDs, Financial, Network, Credentials) and your own detectors find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both for the trace alone."),
+    'observability.scrub.injection': field('ScrubSwitch', "Removes what Injection and Tool instructions find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both for the trace alone."),
+    'observability.scrub.canary': field('ScrubSwitch', "Removes the canary token from stored traces. The canary is Theorem's, so { theorem: false } keeps it."),
+    'observability.retainForDays': field('number', 'Days a trace file is kept, by its UTC day. The next write removes old files. 0 or less keeps all.'),
     'observability.rotateAfterMiB': field('number', 'File size in MiB at which a file-based destination starts a new file, handed to every destination with the record. Default 32.'),
-    'observability.onWriteError': field('(err: unknown) => void', "Your function called when a trace can't be built or written; the turn carries on, and a destination's own error handler takes priority."),
+    'observability.onWriteError': field('(err: unknown) => void', "Your function called when a trace can't be built or written; the turn carries on, and a destination's own error handler takes priority. An unregistered writeTo id is a config error instead."),
 });
 const TOOL_TYPE_FIELD = field(unionType(TOOL_TYPES), 'How the tool runs.', TOOL_TYPES, {
     builtin: "The provider's own tool, such as Google Search, run by the provider.",
     function: 'Your handler runs it.',
     http: 'The kernel calls your HTTP endpoint.',
     mcp: 'The kernel calls a tool on a remote MCP server.',
+    agent: 'The kernel runs one turn of another registered agent and returns its reply.',
 });
 const CREDENTIAL_KINDS = {
     bearer: 'A token; a secret typed in at the prompt becomes a bearer token.',
     ['api_' + 'key']: 'An API key; a secret typed in at the prompt becomes an API key.',
     oauth2: 'An OAuth sign-in; the host supplies the token.',
 };
+/**
+ * The catalog of the fields `registerTool` takes, keyed `registerTool.<field>`. The `studio.` and
+ * `local.` rows are the studio's own; a builder never sets them.
+ */
 export const EXTRA_FIELDS = {
-    /** Playground / UI path — avoids collision with profile `type` in fieldMeta(). */
+    'done.stop.kind': field('TurnStopKind', 'Why the turn ended, on the done event: its stop.kind.', TURN_STOP_KINDS, {
+        completed: 'The model finished its reply.',
+        length: 'The model reached its token limit.',
+        tool: 'The model called tools and the turn hands them to the host, in done.tools.',
+        gate: 'A pre_tool stage held a tool call. The host resumes it with invokeTool, not continueFrom.',
+        filtered: 'The provider filtered the reply, or the egress guardrail withheld it.',
+        provider_error: 'The provider failed or reported an error.',
+        cancelled: 'The turn was cancelled, by the user or by a stage that aborted it.',
+        stream_incomplete: 'The stream ended without the provider reporting a final status.',
+        step_limit: 'The last model call maxSteps allows asked for tools, so the turn ended with no answer.',
+        interrupted: 'A live utterance was cut off by an interruption.',
+        generation_complete: 'Live: the model finished generating audio or text for this utterance. The turn may still be open.',
+    }),
     'registerTool.type': TOOL_TYPE_FIELD,
-    name: field('string', "The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model calls a custom tool by."),
-    description: field('string', 'Tells the model what the tool does (custom tools only).'),
-    input: field('ZodSchema', "The Zod schema for the tool's arguments, sent to the model and checked on every call."),
-    output: field('ZodSchema', 'The Zod schema every result must match.'),
-    handler: field('ToolHandler', 'Your function that runs the tool; it can also yield progress as it goes.'),
-    endpoint: field('string', 'The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host must be written out.'),
-    method: field(unionType(HTTP_METHODS), 'The HTTP method; every method but GET sends a JSON body.', HTTP_METHODS),
-    headers: field('Record<string, string>', "Headers sent with every request to the tool's own host, never to a host it redirects to."),
-    mapping: field('{ pathParams?, queryParams?, bodyParam? }', 'Where each argument goes in the request.'),
-    'mapping.pathParams': field('string[]', 'Arguments that fill the {name} placeholders in the endpoint.'),
-    'mapping.queryParams': field('string[]', 'Arguments added to the query string.'),
-    'mapping.bodyParam': field('string', 'The one argument sent as the whole JSON body; without it, a method other than GET sends every argument the path and query leave unused.'),
-    serverUrl: field('string', "The MCP server's URL."),
-    mcpToolName: field('string', "The tool's name on the MCP server."),
-    auth: {
+    /** Studio-only rows: the editor's local-model connection, and a decision's questions and images. */
+    'local.baseUrl': field('string', 'Where your local model server listens, such as Ollama, llama.cpp or vLLM. The browser calls it directly.'),
+    'studio.remoteTools': {
+        ...field('boolean', 'Whether tools that reach other hosts (HTTP and MCP) may run while a local model is in use. Off, a run with a local model reaches no host.'),
+        unset: 'Off',
+    },
+    'decision.questions.id': field('string', "The question's name. Its answer comes back under it."),
+    'decision.questions.type': field("'choice' | 'score' | 'noul' | 'box'", 'The kind of answer the question takes.', ['choice', 'score', 'noul', 'box'], {
+        choice: 'One of the named options, with a confidence and a probability for each option.',
+        score: 'A level on an ordered scale, with a confidence.',
+        noul: 'One number, which may weigh named criteria.',
+        box: 'Where something is in an image: its top, bottom, left and right edges, with a confidence.',
+    }),
+    'decision.questions.instructions': field('DecisionEntry', "What to ask about the state. Name a state field in backticks, such as `photo`, and one of the decision's images by its reference, such as <ginger>. A box looks in its In image, else in the image of the first field it names."),
+    'decision.questions.image': {
+        ...field('string', "The image a box is in: one of the decision's images, such as <ghs02>, or a state field its instructions name, such as `photo`. The model is told it in the instructions."),
+        unset: 'The image the instructions name',
+    },
+    'decision.images': field('Record<string, DecisionAsset>', 'Pictures sent with every decision, beside the state. A question names one by its reference, such as <ghs02>. A PNG or JPEG.'),
+    'decision.images.name': field('string', 'The reference a question writes, without its angle brackets: ghs02 is written <ghs02>. Lowercase letters, digits and _.'),
+    'registerTool.name': field('string', "The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model calls a custom tool by."),
+    'registerTool.description': field('string', 'Tells the model what the tool does (custom tools only).'),
+    'registerTool.input': field('ZodSchema', "The Zod schema for the tool's arguments, sent to the model and checked on every call."),
+    'registerTool.output': field('ZodSchema', "The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is not checked."),
+    'registerTool.handler': field('ToolHandler', 'Your function that runs the tool; it can also yield progress as it goes.'),
+    'registerTool.endpoint': field('string', 'The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host must be written out.'),
+    'registerTool.method': field(unionType(HTTP_METHODS), 'The HTTP method; every method but GET sends a JSON body.', HTTP_METHODS),
+    'registerTool.headers': field('Record<string, string>', "Headers sent with every request to the tool's own origin, never once a redirect leaves it."),
+    'registerTool.mapping': field('{ pathParams?, queryParams?, bodyParam? }', 'Where each argument goes in the request.'),
+    'registerTool.mapping.pathParams': field('string[]', 'Arguments that fill the {name} placeholders in the endpoint.'),
+    'registerTool.mapping.queryParams': field('string[]', 'Arguments added to the query string.'),
+    'registerTool.mapping.bodyParam': field('string', 'The one argument sent as the whole JSON body; without it, a method other than GET sends every argument the path and query leave unused.'),
+    'registerTool.serverUrl': field('string', "The MCP server's URL."),
+    'registerTool.mcpToolName': field('string', "The tool's name on the MCP server."),
+    'registerTool.profile': field('ProfileId', 'The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls may stop on a gate.'),
+    'registerTool.answeredBy': {
+        ...field("'page'", 'Who answers a call to a function tool. With page, the page the agent is on returns the output, and the tool has no handler.', ['page']),
+        unset: 'Its handler',
+    },
+    'registerTool.maxCallsPerTurn': {
+        ...field('number', 'How many times one turn of the calling agent may run this tool.'),
+        unset: 'As many as its steps allow',
+    },
+    'registerTool.fieldText': {
+        ...field('Partial<Record<keyof AgentToolInput, string>>', 'What the calling model reads on a field of an agent tool input, such as text. A field the profile does not take is refused when the tool registers.'),
+        unset: 'The fields carry no text',
+    },
+    'registerTool.hostFields': {
+        ...field('Record<string, ZodType>', 'Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them as hostInput and turns them into what the agent is sent; the agent never sees them. A name the input already has is refused when the tool registers.'),
+        unset: 'The input is only what the profile takes',
+    },
+    'registerTool.hostOnly': {
+        ...field("Array<'attachments' | 'voice' | 'slots'>", 'Channels the called profile takes that the calling model cannot fill on an agent tool; only onAgentCall sends them. A channel the profile does not take is refused when the tool registers.'),
+        unset: 'The model can fill every channel the profile takes',
+    },
+    'registerTool.auth': {
         ...field('ToolAuthConfig', 'How the tool gets its credential.'),
         unset: 'No credential',
     },
-    'auth.type': field(unionType(TOOL_AUTH_TYPES), 'The kind of credential the tool expects, shown when a turn stops to ask for one.', TOOL_AUTH_TYPES, CREDENTIAL_KINDS),
-    'auth.slot': field('string', 'Which of the credentials the turn passes in this tool uses.'),
-    'auth.service': field('string', 'The service the person signs in to, as they know it, named when a turn stops to ask for a credential.'),
-    'auth.headerName': {
-        ...field('string', 'The header the credential goes in.'),
+    'registerTool.auth.type': field(unionType(TOOL_AUTH_TYPES), "The kind of credential the tool expects, shown when a turn stops to ask for one; the header follows the stored credential's own kind.", TOOL_AUTH_TYPES, CREDENTIAL_KINDS),
+    'registerTool.auth.slot': field('string', 'Which of the credentials the turn passes in this tool uses.'),
+    'registerTool.auth.service': field('string', 'The service the person signs in to, as they know it, named when a turn stops to ask for a credential.'),
+    'registerTool.auth.headerName': {
+        ...field('string', "The header the credential goes in; an API key's own headerName comes first."),
         unset: 'Authorization',
     },
-    'auth.headerPrefix': {
-        ...field('string', 'Text put before the credential in the header.'),
+    'registerTool.auth.headerPrefix': {
+        ...field('string', "Text put before the credential in the header; an API key's own headerPrefix comes first."),
         unset: '"Bearer " for tokens, nothing for API keys',
     },
-    'auth.onUnauthenticated': {
-        ...field(unionType(AUTH_UNAUTHENTICATED_POLICIES), "What happens when the credential is missing, expired or can't be refreshed.", AUTH_UNAUTHENTICATED_POLICIES, {
+    'registerTool.auth.queryParam': {
+        ...field('string', 'For a service that takes its API key in the URL: the query parameter the key goes in, in place of a header.'),
+        unset: 'The key goes in a header',
+    },
+    'registerTool.auth.onUnauthenticated': {
+        ...field(unionType(AUTH_UNAUTHENTICATED_POLICIES), "What happens when the credential is missing, expired, can't be refreshed or is refused by the service.", AUTH_UNAUTHENTICATED_POLICIES, {
             gate: 'The turn stops and asks the host for a credential.',
             report_to_model: "The model is told the tool isn't signed in, and the turn goes on.",
+            fail: 'The call fails as not signed in, for a key the host holds that no person can sign in to replace.',
         }),
         unset: 'gate',
     },
-    'auth.scopes': field('string[]', 'The OAuth scopes the tool needs, shown when a turn stops to ask for a credential.'),
-    'auth.clientId': field('string', "Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it."),
-    'auth.redirectUri': field('string', "Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it."),
-    'playground.authType': field(unionType(PLAYGROUND_AUTH_TYPES), 'The kind of credential the tool expects, or none.', PLAYGROUND_AUTH_TYPES, { none: 'The tool sends no credential.', ...CREDENTIAL_KINDS }),
-    'playground.testCredential': field('string', 'A credential for one connection test, never saved.'),
-    'playground.stubOutput': {
-        ...field('Record<string, unknown>', 'The playground has no code to run, so a function tool returns this.'),
+    'registerTool.auth.scopes': field('string[]', 'The OAuth scopes the tool needs, shown when a turn stops to ask for a credential. A service asking for any other scope fails the call, with no new sign-in.'),
+    'registerTool.auth.clientId': field('string', "Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it."),
+    'registerTool.auth.redirectUri': field('string', "Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it."),
+    'studio.authType': field(unionType(STUDIO_AUTH_TYPES), 'The kind of credential the tool expects, or none.', STUDIO_AUTH_TYPES, { none: 'The tool sends no credential.', ...CREDENTIAL_KINDS }),
+    'studio.testCredential': field('string', "A credential for this tool's connection tests, kept in the tab and never saved."),
+    'studio.stubOutput': {
+        ...field('Record<string, unknown>', 'What a function tool returns in the studio, unless a demo handler has its name.'),
         unset: 'A stand-in built from the output schema',
     },
-    'playground.sampleInput': field('Record<string, unknown>', 'Arguments for the connection test, never saved.'),
-    'playground.inputSchema': field('Record<string, unknown>', "The tool's arguments as a JSON Schema, sent to the model."),
-    'playground.outputSchema': field('Record<string, unknown>', "The tool's result as a JSON Schema, which a function tool's stand-in result is built from."),
+    'studio.sampleInput': field('Record<string, unknown>', 'Arguments for the connection test, never saved.'),
+    'registerTool.inputSchema': field('Record<string, unknown>', "The tool's arguments as a JSON Schema, sent to the model."),
+    'registerTool.outputSchema': field('Record<string, unknown>', "The tool's result as a JSON Schema, which a function tool's stand-in result is built from."),
     'registerStructured.jsonSchema': field('Record<string, unknown>', 'The JSON Schema a structured reply must follow, sent to the model as its response format.'),
-    access: field(unionType(TOOL_ACCESS), "What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a remote tool's result.", TOOL_ACCESS, {
+    'registerTool.access': field(unionType(TOOL_ACCESS), "What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a remote tool's result.", TOOL_ACCESS, {
         'read-only': 'Only reads.',
         'read-write': 'Creates or updates things.',
         destructive: 'Deletes, charges, or does something else hard to undo.',
     }),
-    loadTier: field(unionType(TOOL_LOAD_TIERS), 'When the tool becomes available to the model; live and host profiles load every allowed tool at the start.', TOOL_LOAD_TIERS, {
+    'registerTool.loadTier': field(unionType(TOOL_LOAD_TIERS), 'When the tool becomes available to the model; live and host profiles load every allowed tool at the start.', TOOL_LOAD_TIERS, {
         T0: 'At the start of every turn.',
-        T1: 'When tools.t1Policy picks it at the start of a turn.',
-        T2: 'When the tools.t2Loader tool loads it mid-turn (custom tools only).',
+        T2: 'On demand: when tools.t1Policy picks it at the start of a turn, or when the tools.t2Loader tool loads it mid-turn (custom tools only).',
     }),
-    permission: field(unionType(TOOL_PERMISSION), "Whether the host must approve a call before it runs; the provider's own tools never ask.", TOOL_PERMISSION, {
+    'registerTool.permission': field(unionType(TOOL_PERMISSION), "Whether the host must approve a call before it runs; the provider's own tools never ask.", TOOL_PERMISSION, {
         auto: 'Runs without asking.',
         session_consent: 'Asks once; the approval lasts as long as the host keeps passing it back.',
         always_confirm: 'Asks every time.',
     }),
-    category: field('string', 'A label for grouping tools; nothing reads it yet.'),
-    labels: field('ToolLabels', "What the transcript says about a call. Each {path} is filled from the call; {results.0.name} steps into a list, and {path|text} shows the text when it's empty."),
-    'labels.activity': {
-        ...field('string', "What the transcript says while a call runs, e.g. 'Saving {title} to your collection'. Each {path} is filled from the call's input."),
+    'registerTool.category': field('string', 'A label for grouping tools; nothing reads it yet.'),
+    'registerTool.labels': field('ToolLabels', "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit."),
+    'registerTool.labels.activity': {
+        ...field('string | string[]', "Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the call's input."),
+        unset: 'The tool name, in words',
+    },
+    'registerTool.labels.activityPast': {
+        ...field('string | string[]', "What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is filled from the call's input, then its output."),
         unset: 'The tool name, in words',
     },
-    'labels.activityPast': {
-        ...field('string', "What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is filled from the call's input, then its output."),
+    'registerTool.labels.activityFailed': {
+        ...field('string | string[]', "What the transcript says when a call fails or the host labels it failed, e.g. 'Couldn't save {title}'. Each {path} is filled from the call's input."),
+        unset: "Couldn't complete, then the tool name in words",
+    },
+    'registerTool.labels.request': {
+        ...field('string | string[]', "What the approval card says the agent wants to do, e.g. 'check the weather in {city}'. Each {path} is filled from the call's input."),
         unset: 'The tool name, in words',
     },
-    paths: {
-        ...field('string[]', 'The turn paths this tool is offered on, where * means every path; a turn with no path gets only * tools.'),
+    'registerTool.paths': {
+        ...field('string[]', 'The turn paths this tool is offered on, where * means every path; a turn with no path gets only * tools. Host profiles ignore it.'),
         unset: 'Every path',
     },
 };
-/** `lexicon.<key>` resolves to `lexicon.*` with that key's own note. */
+/** `labels.<key>` resolves to `labels.*` with that key's own note. */
 export function fieldMeta(path) {
     const meta = PROFILE_FIELDS[path] ?? EXTRA_FIELDS[path];
-    if (meta || !path.startsWith('lexicon.'))
+    if (meta || !path.startsWith('labels.'))
         return meta;
-    const key = path.slice('lexicon.'.length);
-    const wildcard = PROFILE_FIELDS['lexicon.*'];
-    if (!wildcard || !Object.hasOwn(LEXICON_NOTES, key))
+    const key = path.slice('labels.'.length);
+    const wildcard = PROFILE_FIELDS['labels.*'];
+    if (!wildcard || !Object.hasOwn(LABEL_NOTES, key))
         return undefined;
-    return { ...wildcard, doc: LEXICON_NOTES[key] };
+    return { ...wildcard, doc: LABEL_NOTES[key] };
 }
+export { API_EXPORTS, REQUEST_FIELDS } from './api-catalog.js';
 export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType } from './profile-graph.js';