primitive-admin 1.1.0-alpha.85 → 1.1.0-alpha.86

package/dist/src/lib/generated-config-surfaces.js

@@ -372,13 +372,26 @@ export function handlerReferences(table) {
 // functions are the whole mechanism: everything else — the pull projection, the
 // push payload builder, the CLI's unknown-key and declared-type checks — reads
 // the declaration through them.
+/**
+ * The blocks a field is authored under, in declaration order: `[]` for a root
+ * key, one name for most grouped keys, several for a key two blocks share
+ * (#3798). Every reader of `tomlGroup` goes through this.
+ */
+export function tomlGroupsOf(field) {
+    const group = field.tomlGroup;
+    if (group === undefined)
+        return [];
+    return typeof group === "string" ? [group] : group;
+}
 /** The group names this table declares, sorted. Empty for an ungrouped table. */
 export function tomlGroupNames(table) {
     return Object.keys(table.tomlGroups ?? {}).sort();
 }
 /** The TOML keys accepted INSIDE `group`: every field that declares it. */
 export function acceptedGroupTomlKeys(table, group) {
-    return new Set(table.fields.filter((f) => f.tomlGroup === group).map((f) => f.tomlKey));
+    return new Set(table.fields
+        .filter((f) => tomlGroupsOf(f).includes(group))
+        .map((f) => f.tomlKey));
 }
 /**
  * TOML keys this table accepts AT ITS ROOT: the UNGROUPED fields, the declared
@@ -437,13 +450,13 @@ export function findUnknownGroupedTomlKeys(tomlTable, table) {
  */
 export function findBadTomlGroupDeclarations(table) {
     const declared = new Set(tomlGroupNames(table));
-    const used = new Set(table.fields
-        .map((f) => f.tomlGroup)
-        .filter((g) => typeof g === "string"));
+    const used = new Set(table.fields.flatMap((f) => [...tomlGroupsOf(f)]));
     const bad = [];
     for (const field of table.fields) {
-        if (field.tomlGroup && !declared.has(field.tomlGroup)) {
-            bad.push(`${field.field}: tomlGroup "${field.tomlGroup}" is not declared in tomlGroups`);
+        for (const group of tomlGroupsOf(field)) {
+            if (!declared.has(group)) {
+                bad.push(`${field.field}: tomlGroup "${group}" is not declared in tomlGroups`);
+            }
         }
     }
     for (const [group, entry] of Object.entries(table.tomlGroups ?? {})) {
@@ -2146,8 +2159,9 @@ export function requestSchemaKeys(table, mode) {
  */
 export function configRequestSchema(table, mode) {
     const properties = {};
+    const deprecatedFields = new Set(table.fields.filter((f) => f.deprecated).map((f) => f.field));
     for (const key of requestSchemaKeys(table, mode)) {
-        properties[key] = {};
+        properties[key] = deprecatedFields.has(key) ? { deprecated: true } : {};
     }
     const schema = {
         type: "object",
@@ -2210,8 +2224,9 @@ export function retiredRequestKeys(schema) {
 export function mergeRequestSchemas(...schemas) {
     const properties = {};
     for (const schema of schemas) {
-        for (const key of Object.keys(schema.properties))
-            properties[key] = {};
+        for (const [key, property] of Object.entries(schema.properties)) {
+            properties[key] = { ...(properties[key] ?? {}), ...property };
+        }
     }
     // The union's guidance is the union of its halves'. A key one table retired
     // and another accepts is admitted by the merged key set, so `rememberRetiredKeys`
@@ -4859,7 +4874,7 @@ function geminiResolution(model, effort, budget) {
 /**
  * What a prompt's KIND admits — issue #3626.
  *
- * A prompt declares `[prompt] kind = "chat" | "decisions"`. The kind decides
+ * A prompt declares `[prompt] kind = "chat" | "decisions" | "agent"`. The kind decides
  * the input envelope (`variables` rendered into templates for chat, a `state`
  * value for decisions), the provider endpoint the executor posts to, and which
  * `[configs.<kind>]` block a `[[configs]]` entry may carry. Adding a kind is a
@@ -4876,13 +4891,22 @@ function geminiResolution(model, effort, budget) {
  *
  * Pure and dependency-free, like every module under `src/config-surface/`.
  */
-/** The kinds a prompt may declare. An omitted `kind` is `chat`. */
-export const PROMPT_KINDS = ["chat", "decisions"];
 /**
- * The nine settings that describe a CHAT COMPLETION and nothing else. They are
- * authored under `[configs.chat]`; the flat spelling is deprecated (#3642).
+ * The kinds a prompt may declare. An omitted `kind` is `chat`.
+ *
+ * #3798 — `agent` is a prompt run turn by turn in a session: no template, no
+ * output schema, never run single-shot. Its tools and events are declared in
+ * `[prompt.agent]` (`agent-declaration.ts`); its configs carry
+ * `[configs.agent]`.
  */
-export const CHAT_CONFIG_KEYS = [
+export const PROMPT_KINDS = ["chat", "decisions", "agent"];
+/**
+ * The nine chat settings that existed before `[configs.chat]` did. Only these
+ * keep the deprecated FLAT spelling (#3642): a key added to the block later was
+ * never written flat by any file, so it has none (the `questions` posture,
+ * SO3626-013).
+ */
+export const LEGACY_FLAT_CHAT_KEYS = [
     "systemPrompt",
     "userPromptTemplate",
     "temperature",
@@ -4893,8 +4917,35 @@ export const CHAT_CONFIG_KEYS = [
     "reasoningEffort",
     "reasoningBudget",
 ];
+/**
+ * The settings that describe a CHAT COMPLETION and nothing else. They are
+ * authored under `[configs.chat]`; the flat spelling of the nine legacy keys
+ * is deprecated (#3642).
+ *
+ * #3801 — `strictOutput`, the opt-in that sends `[prompt].outputSchema` as a
+ * strict `json_schema` on OpenRouter (`prompt-strict-output.ts`). Not an agent
+ * key (§D1: an agent has no output schema), so the agent arm refuses it.
+ */
+export const CHAT_CONFIG_KEYS = [
+    ...LEGACY_FLAT_CHAT_KEYS,
+    "strictOutput",
+];
 /** The settings that describe a DECISIONS request. */
 export const DECISIONS_CONFIG_KEYS = ["questions"];
+/**
+ * #3798 — the settings of an AGENT's model round: the chat block less
+ * `userPromptTemplate` (the model sees each message as sent), `outputFormat`
+ * and `outputSchema` (an agent's final answer is text; anything structured is
+ * a tool call). The same wire keys as chat, authored under `[configs.agent]`.
+ */
+export const AGENT_CONFIG_KEYS = [
+    "systemPrompt",
+    "temperature",
+    "topP",
+    "maxTokens",
+    "reasoningEffort",
+    "reasoningBudget",
+];
 /**
  * The WIRE field names each kind's block holds. The config surface declares the
  * same grouping through `ConfigField.tomlGroup`, and the drift guard asserts
@@ -4905,11 +4956,26 @@ export const DECISIONS_CONFIG_KEYS = ["questions"];
 export const PROMPT_KIND_BLOCKS = {
     chat: CHAT_CONFIG_KEYS,
     decisions: DECISIONS_CONFIG_KEYS,
+    agent: AGENT_CONFIG_KEYS,
 };
 /** The question types TypeSafe's System One models answer. */
 export const DECISIONS_QUESTION_TYPES = ["choice", "score", "noul"];
 /** A question name the endpoint accepts, and that reads as a JSON key. */
 const QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * #3813 — where a `choice` question's options come from. `"static"`: the
+ * config's `criteria` table. `"dynamic"`: each run supplies the table as
+ * `variables.criteria.<question>`. Required on every `choice` question, with
+ * no default, and a platform key: it is removed before the provider request.
+ */
+export const DECISIONS_CRITERIA_SOURCES = ["static", "dynamic"];
+/**
+ * #3813 — the code a decisions run carries when the options it was asked to
+ * choose between are refused before the provider call: malformed per-run
+ * criteria, criteria for a question that does not take them, or a stored
+ * `choice` question that does not say where its options come from.
+ */
+export const PROMPT_CRITERIA_INVALID = "PROMPT_CRITERIA_INVALID";
 /**
  * The prompt's kind, normalized.
  *
@@ -4961,20 +5027,96 @@ function parseQuestions(value) {
 function chatKeysSet(config) {
     return CHAT_CONFIG_KEYS.filter((key) => !isUnset(config[key]));
 }
+/**
+ * The block a stray key is authored under: `questions` is decisions', every
+ * other key chat's (the agent block's keys are chat keys too, so a key an
+ * agent refuses is one only the chat block holds).
+ */
+function owningBlock(key) {
+    return DECISIONS_CONFIG_KEYS.includes(key)
+        ? "decisions"
+        : "chat";
+}
 /**
  * One rule replaces the nine per-key refusals: a `[[configs]]` entry may carry
  * only the block named by its prompt's kind.
+ *
+ * #3798 — the offending keys are named with the block each belongs to. Keys
+ * from ONE block read exactly as they did before a third kind existed.
  */
 function wrongBlockError(kind, offending) {
-    const wrongKind = kind === "chat" ? "decisions" : "chat";
-    return (`prompt kind is "${kind}", so a [[configs]] entry may carry only a ` +
-        `[configs.${kind}] block; this one sets ${offending.join(", ")} ` +
-        `([configs.${wrongKind}] in TOML). Move them to a ${wrongKind} prompt or ` +
-        "remove them.");
+    const blocks = [...new Set(offending.map(owningBlock))];
+    const head = `prompt kind is "${kind}", so a [[configs]] entry may carry only a ` +
+        `[configs.${kind}] block; this one sets `;
+    if (blocks.length === 1) {
+        const wrongKind = blocks[0];
+        return (head +
+            `${offending.join(", ")} ([configs.${wrongKind}] in TOML). Move them ` +
+            `to a ${wrongKind} prompt or remove them.`);
+    }
+    const named = blocks
+        .map((block) => `${offending.filter((key) => owningBlock(key) === block).join(", ")} ` +
+        `([configs.${block}] in TOML)`)
+        .join("; ");
+    return head + `${named}. Move them to a prompt of that kind or remove them.`;
 }
 function questionError(name, detail) {
     return `questions.${name} ${detail}`;
 }
+/**
+ * #3813 — the one rule for a `choice` question's options table, whoever
+ * supplies it: the config (`criteriaSource = "static"`) or the run
+ * (`"dynamic"`). `null` when the table is usable, otherwise the detail the
+ * caller prefixes with where the table came from.
+ *
+ * At least two options; each key non-empty with no leading or trailing
+ * whitespace (the endpoint answers `choice` as the key, so a padded key is an
+ * answer no caller would match); each description a non-empty string or a
+ * non-empty JSON object, which is how a run describes a structured option such
+ * as a previous transaction.
+ */
+function criteriaTableError(table) {
+    if (!isPlainObject(table)) {
+        return "must be a table of option key = description";
+    }
+    const entries = Object.entries(table);
+    if (entries.length < 2) {
+        return ("needs at least two options; a choice between one option is not a " +
+            "choice");
+    }
+    for (const [key, description] of entries) {
+        if (key.trim() === "" || key !== key.trim()) {
+            return (`has the option key ${JSON.stringify(key)}, which is empty or starts ` +
+                "or ends with whitespace");
+        }
+        const usable = isPlainObject(description)
+            ? Object.keys(description).length > 0
+            : isNonEmptyString(description);
+        if (!usable) {
+            return (`option '${key}' needs a non-empty description (a string or a JSON ` +
+                "object)");
+        }
+    }
+    return null;
+}
+/** `criteriaSource` as the question declares it, or `undefined` when unset. */
+function criteriaSourceOf(question) {
+    return question.criteriaSource;
+}
+function isCriteriaSource(value) {
+    return (typeof value === "string" &&
+        DECISIONS_CRITERIA_SOURCES.includes(value));
+}
+/** The refusal for a `choice` question whose options' source is unusable. */
+function criteriaSourceError(name, source) {
+    if (source === undefined) {
+        return questionError(name, 'is a choice question, so it needs criteriaSource = "static" (its ' +
+            'options in a criteria table here) or "dynamic" (each run supplies ' +
+            `them as variables.criteria.${name})`);
+    }
+    return questionError(name, `criteriaSource must be "static" or "dynamic"; found ` +
+        JSON.stringify(source));
+}
 /** Every refusal a single decisions question can earn, or `null`. */
 function decisionsQuestionError(name, question) {
     if (!QUESTION_NAME.test(name)) {
@@ -4992,20 +5134,32 @@ function decisionsQuestionError(name, question) {
     if (!isNonEmptyString(question.instructions)) {
         return questionError(name, "needs instructions — the sentence the model answers");
     }
-    if (type === "choice") {
-        const criteria = question.criteria;
-        if (!isPlainObject(criteria)) {
-            return questionError(name, "is a choice question, so it needs a criteria table of option key = " +
-                "description");
+    const source = criteriaSourceOf(question);
+    if (type !== "choice") {
+        // #3813 — only a choice question has options to source.
+        if (source !== undefined) {
+            return questionError(name, `is a ${type} question; criteriaSource applies only to a choice ` +
+                "question");
         }
-        const entries = Object.entries(criteria);
-        if (entries.length < 2) {
-            return questionError(name, "needs at least two criteria entries; a choice between one option is " +
-                "not a choice");
+    }
+    else {
+        if (!isCriteriaSource(source))
+            return criteriaSourceError(name, source);
+        const criteria = question.criteria;
+        if (source === "dynamic") {
+            if (criteria !== undefined && criteria !== null) {
+                return questionError(name, 'has criteriaSource = "dynamic", so its options come from each ' +
+                    `run as variables.criteria.${name}; remove its criteria table`);
+            }
         }
-        const blank = entries.find(([, value]) => !isNonEmptyString(value));
-        if (blank) {
-            return questionError(name, `criteria.${blank[0]} needs a non-empty description`);
+        else {
+            if (!isPlainObject(criteria)) {
+                return questionError(name, 'has criteriaSource = "static", so it needs a criteria table of ' +
+                    "option key = description");
+            }
+            const tableError = criteriaTableError(criteria);
+            if (tableError)
+                return questionError(name, `criteria ${tableError}`);
         }
     }
     // Every other key on a question — `score`'s array `criteria`, anything
@@ -5035,6 +5189,23 @@ export function resolvePromptKind(input) {
         kind = text;
     }
     const config = input.config || {};
+    // ── agent (#3798) ──────────────────────────────────────────────────────
+    // No template: the model sees each message as sent. Either provider; the
+    // capability checks are the provider mapping's (#3799), not the kind's.
+    if (kind === "agent") {
+        const stray = [
+            ...CHAT_CONFIG_KEYS.filter((key) => !AGENT_CONFIG_KEYS.includes(key)),
+            ...DECISIONS_CONFIG_KEYS,
+        ].filter((key) => !isUnset(config[key]));
+        if (stray.length > 0) {
+            return {
+                ok: false,
+                error: wrongBlockError("agent", stray),
+                code: "AGENT_CONFIG_KEY_NOT_ALLOWED",
+            };
+        }
+        return { ok: true, kind: "agent" };
+    }
     if (kind === "chat") {
         if (!isUnset(config.questions)) {
             return { ok: false, error: wrongBlockError("chat", ["questions"]) };
@@ -5072,6 +5243,126 @@ export function resolvePromptKind(input) {
     }
     return { ok: true, kind: "decisions", questions };
 }
+/** A run-time refusal, naming the question the way the executor's errors do. */
+function runQuestionError(name, detail) {
+    return `Decisions question '${name}' ${detail}`;
+}
+/**
+ * #3813 — the questions one run sends to the provider.
+ *
+ * `questions` is the RAN config's declaration, as stored; `runCriteria` is
+ * the run's `variables.criteria` (`undefined` when the run sent none). A
+ * `"dynamic"` question is given the run's table as its `criteria`; every
+ * question loses `criteriaSource`, which is the platform's key and not the
+ * endpoint's. The config still owns each question's name, type and
+ * instructions: a run can supply options only for a question declared
+ * `"dynamic"`, so nothing a run sends can change what is being asked.
+ *
+ * Refuses, before any provider call: a `variables.criteria` that is not an
+ * object; criteria for a name the config does not declare, for a `"static"`
+ * question, or for a `score` or `noul` one; a `"dynamic"` question with no
+ * table or a table the criteria rule refuses; and a stored `choice` question
+ * with no usable `criteriaSource` — a config written before the key existed,
+ * which is refused rather than given a silent default.
+ *
+ * Pure: the stored questions object is never mutated.
+ */
+export function resolveDecisionsRunQuestions(questions, runCriteria) {
+    if (runCriteria !== undefined && !isPlainObject(runCriteria)) {
+        return {
+            ok: false,
+            error: "variables.criteria must be an object keyed by question name, each " +
+                "value a table of option key = description; found " +
+                (Array.isArray(runCriteria)
+                    ? "an array"
+                    : runCriteria === null
+                        ? "null"
+                        : `a ${typeof runCriteria}`),
+        };
+    }
+    const supplied = isPlainObject(runCriteria)
+        ? runCriteria
+        : {};
+    for (const name of Object.keys(supplied)) {
+        // Own keys only: a question name such as `__proto__` passes QUESTION_NAME,
+        // and an inherited property is not a declared question.
+        const question = Object.prototype.hasOwnProperty.call(questions, name)
+            ? questions[name]
+            : undefined;
+        if (!isPlainObject(question)) {
+            return {
+                ok: false,
+                error: runQuestionError(name, `is not a question this config declares, so variables.criteria.` +
+                    `${name} cannot be supplied (the config does not declare it)`),
+            };
+        }
+        if (question.type !== "choice") {
+            return {
+                ok: false,
+                error: runQuestionError(name, `is a ${String(question.type)} question; only a choice question ` +
+                    'declared with criteriaSource = "dynamic" takes ' +
+                    `variables.criteria.${name}`),
+            };
+        }
+        if (criteriaSourceOf(question) === "static") {
+            return {
+                ok: false,
+                error: runQuestionError(name, 'takes its criteria from the config (criteriaSource = "static"), ' +
+                    `so variables.criteria.${name} cannot be supplied`),
+            };
+        }
+    }
+    const resolved = {};
+    // Defined, not assigned: `resolved.__proto__ = …` would set the prototype and
+    // the question would vanish from the provider request.
+    const keep = (name, value) => Object.defineProperty(resolved, name, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    for (const [name, question] of Object.entries(questions)) {
+        if (!isPlainObject(question)) {
+            keep(name, question);
+            continue;
+        }
+        const { criteriaSource: source, ...sent } = question;
+        if (question.type === "choice") {
+            if (!isCriteriaSource(source)) {
+                return {
+                    ok: false,
+                    error: runQuestionError(name, source === undefined
+                        ? 'is a choice question with no criteriaSource; declare ' +
+                            'criteriaSource = "static" or "dynamic" on it and push the ' +
+                            "prompt again"
+                        : `has criteriaSource ${JSON.stringify(source)}; it must be ` +
+                            '"static" or "dynamic"'),
+                };
+            }
+            if (source === "dynamic") {
+                if (!Object.prototype.hasOwnProperty.call(supplied, name)) {
+                    return {
+                        ok: false,
+                        error: runQuestionError(name, "takes its criteria from the run (criteriaSource = " +
+                            `"dynamic"), and variables.criteria.${name} is missing`),
+                    };
+                }
+                const table = supplied[name];
+                const tableError = criteriaTableError(table);
+                if (tableError) {
+                    return {
+                        ok: false,
+                        error: runQuestionError(name, `takes its criteria from the run, and variables.criteria.` +
+                            `${name} ${tableError}`),
+                    };
+                }
+                sent.criteria = { ...table };
+            }
+        }
+        keep(name, sent);
+    }
+    return { ok: true, questions: resolved };
+}
 /**
  * Move the deprecated flat chat keys of one `[[configs]]` entry under `chat`
  * — #3626 §4, the blob-bucket `accessPolicy` precedent made reusable.
@@ -5093,7 +5384,9 @@ export function hoistDeprecatedChatKeys(entry) {
     const group = existingGroup ?? {};
     const moved = [];
     const conflicts = [];
-    for (const key of CHAT_CONFIG_KEYS) {
+    // #3801 — only the legacy keys have a flat spelling to hoist; `strictOutput`
+    // at the root is an unknown key naming its block.
+    for (const key of LEGACY_FLAT_CHAT_KEYS) {
         if (!(key in out))
             continue;
         if (existingGroup && key in existingGroup) {
@@ -5109,128 +5402,1557 @@ export function hoistDeprecatedChatKeys(entry) {
         out.chat = group;
     return { entry: out, moved: moved.sort(), conflicts: conflicts.sort() };
 }
-// ── src/config-surface/prompt.ts ─────────────────────────────────────────
+// ── src/config-surface/prompt-strict-output.ts ───────────────────────────
+/**
+ * Strict output for a chat config — issue #3801 (project `agents`, §D6).
+ *
+ * A chat prompt's OpenRouter request asks for JSON mode (`outputFormat =
+ * "json"`) and the answer is checked AFTERWARDS against `[prompt].outputSchema`
+ * (`derivePromptRunEnvelope`). A config that sets `[configs.chat].strictOutput
+ * = true` asks the provider to constrain the answer instead: the prompt-level
+ * schema is sent as `response_format: { type: "json_schema", json_schema: {
+ * name: "output", strict: true, schema } }`, with `provider: {
+ * require_parameters: true }` so OpenRouter refuses an endpoint that would
+ * ignore it rather than dropping it in silence (the #3358 posture).
+ *
+ * This module is the whole rule, and it is read in both places a config is
+ * written: the admin routes, and (vendored) the CLI's push preflight, so a
+ * refusal at push and at the route cannot disagree — `resolvePromptReasoning`
+ * and `resolvePromptKind`'s posture.
+ *
+ * Which schema is sent is never ambiguous: always the PROMPT's (§D6), so a
+ * config that also declares its own `outputSchema` is refused. Five refusals,
+ * in this order, each with its own code:
+ *
+ *  - `PROMPT_STRICT_OUTPUT_INVALID` — the value is not a boolean.
+ *  - `PROMPT_STRICT_OUTPUT_SCHEMA_CONFLICT` — the config declares its own
+ *    `outputSchema` too.
+ *  - `PROMPT_STRICT_OUTPUT_PROVIDER_UNSUPPORTED` — not OpenRouter. A Gemini
+ *    config already constrains its request through `responseSchema`.
+ *  - `PROMPT_STRICT_OUTPUT_FORMAT_CONFLICT` — `outputFormat = "text"`.
+ *  - `PROMPT_STRICT_OUTPUT_SCHEMA_MISSING` — the prompt declares no usable
+ *    `[prompt].outputSchema`.
+ *
+ * The first four are about the config itself and apply whatever its status.
+ * The last depends on PROMPT-level state that can change under a config, so it
+ * is skipped for an ARCHIVED config (DSO-3801-002): a retired strict config may
+ * be pulled, pushed and renamed after its prompt dropped the schema, and the
+ * requirement is enforced when a config is or becomes active — the #3799
+ * posture, "an archive is never checked".
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/** Every code the rule answers, in the order it checks. */
+export const PROMPT_STRICT_OUTPUT_CODES = [
+    "PROMPT_STRICT_OUTPUT_INVALID",
+    "PROMPT_STRICT_OUTPUT_SCHEMA_CONFLICT",
+    "PROMPT_STRICT_OUTPUT_PROVIDER_UNSUPPORTED",
+    "PROMPT_STRICT_OUTPUT_FORMAT_CONFLICT",
+    "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING",
+];
 /**
- * The `prompt` configuration object's definition (issue #2644, phase 2).
+ * The one code a RUN can also carry: the executor refuses a strict config whose
+ * stored prompt schema is absent or unusable before any provider call, rather
+ * than downgrading the request to JSON mode.
+ */
+export const PROMPT_STRICT_OUTPUT_SCHEMA_MISSING = "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING";
+/**
+ * `json_schema.name`. The OpenAI-shaped API requires one and the executor has
+ * no prompt key to hand, so it is fixed — the same request for the same schema.
+ */
+export const STRICT_OUTPUT_SCHEMA_NAME = "output";
+/** `null`, `undefined` and `""` are absence; `false` is a value. */
+function isStrictOutputUnset(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+function isSchemaObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Does this config opt in? Only a literal `true` does. */
+export function isStrictOutput(value) {
+    return value === true;
+}
+/**
+ * The schema strict output sends, from a stored or authored
+ * `[prompt].outputSchema`: a JSON object (or its text), else `null`.
+ */
+export function strictOutputSchemaOf(value) {
+    if (isSchemaObject(value))
+        return value;
+    if (typeof value !== "string" || value.trim() === "")
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return isSchemaObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is this (provider, strictOutput, outputFormat, schemas, status) a config the
+ * platform can run as strict — or not strict at all?
+ */
+export function resolvePromptStrictOutput(input) {
+    const value = input.strictOutput;
+    if (isStrictOutputUnset(value) || value === false)
+        return { ok: true, strict: false };
+    if (value !== true) {
+        return {
+            ok: false,
+            code: "PROMPT_STRICT_OUTPUT_INVALID",
+            error: "strictOutput must be true or false; found " +
+                `${JSON.stringify(value)} (${typeof value}). Write strictOutput = true ` +
+                "without quotes, or remove the line.",
+        };
+    }
+    if (!isStrictOutputUnset(input.configOutputSchema)) {
+        return {
+            ok: false,
+            code: "PROMPT_STRICT_OUTPUT_SCHEMA_CONFLICT",
+            error: "strictOutput = true sends the prompt's [prompt].outputSchema as the " +
+                "strict json_schema, and this config also declares its own " +
+                "[configs.chat].outputSchema, so which schema is sent would be " +
+                "ambiguous. Remove the config's outputSchema (declare the schema on " +
+                "[prompt]), or remove strictOutput.",
+        };
+    }
+    const provider = typeof input.provider === "string" ? input.provider.trim().toLowerCase() : "";
+    if (provider && provider !== "openrouter") {
+        return {
+            ok: false,
+            code: "PROMPT_STRICT_OUTPUT_PROVIDER_UNSUPPORTED",
+            error: `strictOutput = true is an OpenRouter option; this config runs on ` +
+                `"${provider}". A gemini config already constrains its request with ` +
+                "[prompt].outputSchema as responseSchema — remove strictOutput.",
+        };
+    }
+    const outputFormat = typeof input.outputFormat === "string"
+        ? input.outputFormat.trim().toLowerCase()
+        : "";
+    if (outputFormat === "text") {
+        return {
+            ok: false,
+            code: "PROMPT_STRICT_OUTPUT_FORMAT_CONFLICT",
+            error: 'strictOutput = true asks for JSON matching [prompt].outputSchema, and ' +
+                'this config says outputFormat = "text". Set outputFormat = "json" (or ' +
+                "remove it), or remove strictOutput.",
+        };
+    }
+    const status = typeof input.status === "string" ? input.status.trim().toLowerCase() : "";
+    if (status !== "archived" && strictOutputSchemaOf(input.promptOutputSchema) === null) {
+        return {
+            ok: false,
+            code: "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING",
+            error: "strictOutput = true sends the prompt's [prompt].outputSchema as the " +
+                "strict json_schema, and this prompt declares none that is a JSON " +
+                "object. Declare [prompt].outputSchema, or remove strictOutput.",
+        };
+    }
+    return { ok: true, strict: true };
+}
+// ── src/config-surface/agent-declaration.ts ──────────────────────────────
+/**
+ * What an agent prompt may declare — issue #3798 (project `agents`, §D1).
  *
- * `prompts/<key>.toml` carries TWO field tables: the `[prompt]` table backed by
- * `AppPrompt`, and the repeated `[[configs]]` table backed by `AppPromptConfig`
- * — one entry per named LLM configuration. Both are declared here, so a field
- * added to either model is covered by the same guard.
+ * An agent is a prompt of `kind = "agent"`. Its configs carry `[configs.agent]`
+ * (the rule for those is `resolvePromptKind`); its contract lives in ONE
+ * prompt-level block, `[prompt.agent]`: the tools the model may call, the event
+ * kinds members record, the turn context, how history is selected, who answers
+ * a paused call, and the limits an agent may lower but never raise.
  *
- * The `[[configs]]` entries are the reason prompts have two tables rather than
- * a `structural` note: they are a real field surface the CLI pushes
- * (`createPromptConfig` / `updatePromptConfig`) and pulls, not an opaque blob.
+ * This module is the whole rule for that block. `resolveAgentDeclaration` is
+ * called by the CLI's push preflight through the vendored artifact and by the
+ * admin prompt routes, so a refusal at push and a refusal at the route cannot
+ * disagree — the `resolvePromptKind` posture of #3626.
+ *
+ * STORED AS WRITTEN (DSO-3798-001). The resolver returns the AUTHORED value —
+ * a block written as one JSON string is parsed to the object it encodes, and
+ * nothing is added. `config diff` compares a `json` field by value with no
+ * defaults applied, so a stored declaration with defaults filled in would read
+ * Modified after every push, and `config pull` would write keys the author
+ * never did. The defaults live in one reader instead, `normalizeAgentDeclaration`,
+ * which every consumer (the executor, codegen, the turn engine) calls.
+ *
+ * Every refusal carries a stable code (intent criterion 22) and a refusal lists
+ * EVERY offending item, so an author fixes a declaration in one pass.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
  */
-const PROMPT_HANDLER = "src/admin-api.ts";
+/** The stable codes every agent agentRefusal this project adds carries. */
+export const AGENT_ERROR_CODES = [
+    "AGENT_DECLARATION_INVALID",
+    "AGENT_TOOL_FUNCTION_MISSING",
+    "AGENT_TOOL_FUNCTION_SCHEMA_MISSING",
+    "AGENT_OUTPUT_SCHEMA_NOT_ALLOWED",
+    "AGENT_CONFIG_KEY_NOT_ALLOWED",
+    "AGENT_NOT_RUNNABLE",
+    "AGENT_TEST_CASE_NOT_SUPPORTED",
+    // #3799 §7 — a tool or event schema that cannot be mapped without loss to
+    // the provider of a config that is not archived (`provider-schema.ts`).
+    "AGENT_SCHEMA_NOT_TRANSLATABLE",
+    // #3799 §7 — the capability rule (`src/llm/model-capabilities.ts`). The
+    // catalog does not list the model; it lists it and it lacks a capability an
+    // agent needs; or the capability could not be established at all
+    // (DSO-3799-002 — a refusal, not a pass).
+    "AGENT_MODEL_UNKNOWN",
+    "AGENT_MODEL_CAPABILITY_MISSING",
+    "AGENT_MODEL_CAPABILITIES_UNAVAILABLE",
+    // #3800 §3 — the agent round. A round asked of a prompt that is not an
+    // agent; a round whose input cannot mean anything; a call naming a tool the
+    // round did not declare; a call whose arguments fail its tool's schema; a
+    // response cut off at the token limit; a response with nothing in it.
+    "AGENT_ROUND_NOT_AGENT",
+    "AGENT_ROUND_INPUT_INVALID",
+    "AGENT_TOOL_UNKNOWN",
+    "AGENT_TOOL_ARGUMENTS_INVALID",
+    "AGENT_ROUND_TRUNCATED",
+    "AGENT_ROUND_EMPTY",
+];
 /**
- * #3626 §4 — the nine chat keys, still accepted FLAT under `[[configs]]`.
- *
- * The blob-bucket `accessPolicy` precedent: declared `deprecated`, so
- * `config push` keeps taking a file written before the `[configs.chat]` block
- * existed, while `config pull` never writes the spelling again. One
- * pull-then-push migrates a file. `hoistDeprecatedChatKeys` moves them into the
- * group before the payload is built; rejecting the flat spelling outright is
- * #3642.
+ * The platform maximums. An agent may lower `maxSteps` and `waitLimitSeconds`,
+ * never raise them; the tool and event counts bound what one declaration can
+ * make every turn carry (principle 2).
  */
-const DEPRECATED_FLAT_CHAT_KEYS = Object.fromEntries(CHAT_CONFIG_KEYS.map((key) => [
-    key,
-    {
-        kind: "deprecated",
-        note: `#3626 — the pre-kind spelling of \`[configs.chat].${key}\`. Still ` +
-            "accepted flat so no existing prompt file breaks (push hoists it " +
-            "into the block and warns); `config pull` writes only the grouped " +
-            "spelling, so one pull-then-push migrates the file. Rejecting the " +
-            "flat spelling is #3642.",
-    },
-]));
-export const PROMPT_SURFACE = {
-    label: "prompt",
-    tables: [
-        {
-            tomlPath: ["prompt"],
-            repeated: false,
-            model: "AppPrompt",
-            // Declaration order reproduces the pre-#2644 serializer's key order.
-            fields: [
-                // #3626 — WHAT this prompt runs. `chat` is today's prompt (a chat
-                // completion rendered from templates); `decisions` names OpenRouter's
-                // `/api/alpha/decisions` endpoint, which takes a `state` value plus
-                // named typed questions. It lives on the PROMPT because it decides the
-                // input envelope, the output type, the meaning of `inputSchema` /
-                // `outputSchema` and the shape of every test case's `inputVariables` —
-                // all of which are asserted per prompt KEY.
-                //
-                // `emit: "always"` so a pulled file says which kind it is; an omitted
-                // key is `chat`, so no file written before this changes meaning, and
-                // `serverDefault` is what lets push send `chat` for an absent key and
-                // `config diff` read both spellings as one value.
-                //
-                // CREATE_ONLY, and immutable in the strong sense (D3626-008): changing
-                // a prompt's kind under its key would change the contract of every
-                // caller compiled against it, so the update handler never reads it and
-                // the push gate declines the change as `immutable` — the `ttlTier`
-                // precedent. The prompt comparator projects `[prompt]` in CREATE mode
-                // for exactly that reason (SO3626-008).
-                {
-                    field: "kind",
-                    tomlKey: "kind",
-                    type: "string",
-                    emit: "always",
-                    writableOn: CREATE_ONLY,
-                    serverDefault: "chat",
-                    validation: handledBy("src/config-surface/prompt-kinds.ts", "resolvePromptKind", "apply"),
-                },
-                {
-                    field: "displayName",
-                    tomlKey: "displayName",
-                    type: "string",
-                    emit: "always",
-                    writableOn: BOTH,
-                    validation: "passthrough",
-                },
-                {
-                    field: "description",
-                    tomlKey: "description",
-                    type: "string",
-                    emit: "whenSet",
-                    writableOn: BOTH,
-                    validation: "passthrough",
-                },
-                // JSON Schema objects. Stored as JSON strings, returned parsed; TOML
-                // may present them as an inline table or a JSON string.
-                {
-                    field: "inputSchema",
-                    tomlKey: "inputSchema",
-                    type: "json",
-                    emit: "whenSet",
-                    writableOn: BOTH,
-                    validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
-                },
-                // #2644 — accepted by both handlers and returned by the detail, but
-                // never written to TOML before this: a prompt's declared output shape
-                // was invisible to config-as-code.
-                {
-                    field: "outputSchema",
-                    tomlKey: "outputSchema",
-                    type: "json",
-                    emit: "whenSet",
-                    writableOn: BOTH,
-                    validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
-                },
-                // #2652 — the CEL rule gating who may execute the prompt. Required at
-                // create; an explicit null/"" on update clears it (fail-closed). This
-                // declaration is the whole authoring channel: the admin routes' unknown
-                // key guard reads the same table, so it is what makes `accessRule` an
-                // accepted body key as well as a pulled and pushed TOML line.
-                {
-                    field: "accessRule",
-                    tomlKey: "accessRule",
-                    type: "string",
+export const AGENT_LIMITS = {
+    maxSteps: 25,
+    waitLimitSeconds: 604800,
+    tools: 64,
+    events: 64,
+};
+/**
+ * A tool or event name: the intersection of OpenRouter's and Gemini's
+ * function-name rules, so one declaration maps onto either provider.
+ */
+export const AGENT_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+export const AGENT_ANSWERED_BY = ["initiator", "participants"];
+export const AGENT_TOOL_INVOKE = ["request", "task"];
+export const AGENT_TOOL_HISTORY_SCOPES = ["session", "turn"];
+const AGENT_TOP_LEVEL_KEYS = [
+    "answeredBy",
+    "maxSteps",
+    "waitLimitSeconds",
+    "turnContext",
+    "history",
+    "tools",
+    "events",
+];
+const AGENT_TURN_CONTEXT_KEYS = ["schema", "function"];
+const AGENT_HISTORY_KEYS = ["function", "maxHistoryChars"];
+const AGENT_TOOL_KEYS = [
+    "name",
+    "description",
+    "function",
+    "invoke",
+    "runs",
+    "approval",
+    "statusText",
+    "historyScope",
+    "inputSchema",
+    "outputSchema",
+];
+const AGENT_EVENT_KEYS = ["name", "schema"];
+/** Where every message points: the author's own spelling of the block. */
+const AGENT_BLOCK = "[prompt.agent]";
+/**
+ * The same label, for the sibling rules that refuse a declaration from their
+ * own module (#3799's `provider-schema.ts`), so every agent refusal points at
+ * the block the author wrote.
+ */
+export const AGENT_BLOCK_LABEL = AGENT_BLOCK;
+function agentRefusal(code, message) {
+    return { code, message };
+}
+function agentInvalid(path, detail) {
+    return agentRefusal("AGENT_DECLARATION_INVALID", `${AGENT_BLOCK} ${path ? `${path} ` : ""}${detail}`);
+}
+/** `null`, `undefined` and `""` are absence; `false` and `0` are values. */
+function agentIsUnset(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+function agentIsPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function agentIsNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function agentKindOf(kind) {
+    return agentIsUnset(kind) ? "chat" : String(kind).trim();
+}
+/**
+ * The block as a value: a table as it is, a JSON string parsed. `undefined`
+ * for anything that is not a JSON object, which the resolver refuses.
+ */
+function parseAgentBlock(agent) {
+    if (agentIsPlainObject(agent))
+        return agent;
+    if (typeof agent === "string") {
+        try {
+            const parsed = JSON.parse(agent);
+            return agentIsPlainObject(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function agentUnknownKeys(value, allowed, path, out) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            out.push(agentInvalid(path ? `${path}.${key}` : key, `is not a key an agent declares; allowed: ${allowed.join(", ")}`));
+        }
+    }
+}
+/**
+ * A schema position holds an OBJECT. A JSON string there is refused rather
+ * than parsed: the stored value must equal the pushed one, and a nested string
+ * parsed server-side would not (DSO-3798-001).
+ */
+function agentSchemaError(value, path) {
+    if (agentIsPlainObject(value))
+        return null;
+    const found = typeof value === "string"
+        ? "a string"
+        : Array.isArray(value)
+            ? "a list"
+            : typeof value;
+    return agentInvalid(path, `must be a table (a JSON Schema object); found ${found}. Write it as ` +
+        "TOML tables, or as an object inside a block written as one JSON string");
+}
+function agentIntegerInRange(value, path, max, out) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        out.push(agentInvalid(path, `must be an integer from 1 to ${max}`));
+        return;
+    }
+    if (value < 1 || value > max) {
+        out.push(agentInvalid(path, `must be from 1 to ${max} (the platform maximum); found ${value}`));
+    }
+}
+function checkAgentName(value, path, seen, what, out) {
+    if (typeof value !== "string" || !AGENT_NAME.test(value)) {
+        out.push(agentInvalid(path, `is not a usable ${what} name; names match ` +
+            "[A-Za-z_][A-Za-z0-9_-]{0,63} (the rule both providers accept)"));
+        return;
+    }
+    if (seen.has(value)) {
+        out.push(agentInvalid(path, `repeats the ${what} name "${value}"; names are unique`));
+        return;
+    }
+    seen.add(value);
+}
+function checkAgentTool(tool, index, names, out) {
+    const path = `tools[${index}]`;
+    if (!agentIsPlainObject(tool)) {
+        out.push(agentInvalid(path, "must be a table declaring the tool"));
+        return;
+    }
+    agentUnknownKeys(tool, AGENT_TOOL_KEYS, path, out);
+    checkAgentName(tool.name, `${path}.name`, names, "tool", out);
+    if (!agentIsNonEmptyString(tool.description)) {
+        out.push(agentInvalid(`${path}.description`, "is required — the sentence the model reads to decide when to call it"));
+    }
+    const hasFunction = tool.function !== undefined;
+    const hasRuns = tool.runs !== undefined;
+    if (hasFunction === hasRuns) {
+        out.push(agentInvalid(path, hasFunction
+            ? 'sets both function and runs; a tool is a server tool (function = "<key>") or a client tool (runs = "client"), not both'
+            : 'needs function = "<key>" (a server tool) or runs = "client" (a client tool)'));
+    }
+    if (hasRuns && tool.runs !== "client") {
+        out.push(agentInvalid(`${path}.runs`, `must be "client"; found ${JSON.stringify(tool.runs)}`));
+    }
+    if (hasFunction && !agentIsNonEmptyString(tool.function)) {
+        out.push(agentInvalid(`${path}.function`, "must name a server function by key"));
+    }
+    const isClient = hasRuns && !hasFunction;
+    if (tool.invoke !== undefined) {
+        if (isClient) {
+            out.push(agentInvalid(`${path}.invoke`, "is for server tools; a client tool is answered by a member's client"));
+        }
+        else if (!AGENT_TOOL_INVOKE.includes(tool.invoke)) {
+            out.push(agentInvalid(`${path}.invoke`, `must be one of ${AGENT_TOOL_INVOKE.join(" | ")}`));
+        }
+    }
+    for (const key of ["inputSchema", "outputSchema"]) {
+        const schemaPath = `${path}.${key}`;
+        if (isClient) {
+            if (tool[key] === undefined) {
+                out.push(agentInvalid(schemaPath, "is required on a client tool"));
+                continue;
+            }
+            const error = agentSchemaError(tool[key], schemaPath);
+            if (error)
+                out.push(error);
+        }
+        else if (hasFunction && tool[key] !== undefined) {
+            out.push(agentInvalid(schemaPath, "is not declared on a server tool; its function's schemas are the " +
+                "tool's (one source of truth) — remove it"));
+        }
+    }
+    if (tool.approval !== undefined && typeof tool.approval !== "boolean") {
+        out.push(agentInvalid(`${path}.approval`, "must be true or false"));
+    }
+    if (tool.statusText !== undefined && !agentIsNonEmptyString(tool.statusText)) {
+        out.push(agentInvalid(`${path}.statusText`, "must be a non-empty string"));
+    }
+    if (tool.historyScope !== undefined &&
+        !AGENT_TOOL_HISTORY_SCOPES.includes(tool.historyScope)) {
+        out.push(agentInvalid(`${path}.historyScope`, `must be one of ${AGENT_TOOL_HISTORY_SCOPES.join(" | ")}`));
+    }
+}
+function checkAgentEvent(event, index, names, out) {
+    const path = `events[${index}]`;
+    if (!agentIsPlainObject(event)) {
+        out.push(agentInvalid(path, "must be a table declaring the event kind"));
+        return;
+    }
+    agentUnknownKeys(event, AGENT_EVENT_KEYS, path, out);
+    checkAgentName(event.name, `${path}.name`, names, "event", out);
+    if (event.schema === undefined) {
+        out.push(agentInvalid(`${path}.schema`, "is required — the shape of the event's payload"));
+    }
+    else {
+        const error = agentSchemaError(event.schema, `${path}.schema`);
+        if (error)
+            out.push(error);
+    }
+}
+function checkAgentList(value, path, max, check, out) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        out.push(agentInvalid(path, `must be a list of tables ([[prompt.agent.${path}]])`));
+        return;
+    }
+    if (value.length > max) {
+        out.push(agentInvalid(path, `declares ${value.length}; at most ${max} are allowed`));
+        return;
+    }
+    const names = new Set();
+    value.forEach((item, index) => check(item, index, names, out));
+}
+/** Every file-decidable agentRefusal of a parsed block. */
+function agentShapeRefusals(agent) {
+    const out = [];
+    agentUnknownKeys(agent, AGENT_TOP_LEVEL_KEYS, "", out);
+    if (agent.answeredBy !== undefined &&
+        !AGENT_ANSWERED_BY.includes(agent.answeredBy)) {
+        out.push(agentInvalid("answeredBy", `must be one of ${AGENT_ANSWERED_BY.join(" | ")}`));
+    }
+    if (agent.maxSteps !== undefined) {
+        agentIntegerInRange(agent.maxSteps, "maxSteps", AGENT_LIMITS.maxSteps, out);
+    }
+    if (agent.waitLimitSeconds !== undefined) {
+        agentIntegerInRange(agent.waitLimitSeconds, "waitLimitSeconds", AGENT_LIMITS.waitLimitSeconds, out);
+    }
+    if (agent.turnContext !== undefined) {
+        const turnContext = agent.turnContext;
+        if (!agentIsPlainObject(turnContext)) {
+            out.push(agentInvalid("turnContext", "must be a table: { schema, function? }"));
+        }
+        else {
+            agentUnknownKeys(turnContext, AGENT_TURN_CONTEXT_KEYS, "turnContext", out);
+            if (turnContext.schema === undefined) {
+                out.push(agentInvalid("turnContext.schema", "is required — the shape of the context a send carries"));
+            }
+            else {
+                const error = agentSchemaError(turnContext.schema, "turnContext.schema");
+                if (error)
+                    out.push(error);
+            }
+            if (turnContext.function !== undefined &&
+                !agentIsNonEmptyString(turnContext.function)) {
+                out.push(agentInvalid("turnContext.function", "must name a server function by key"));
+            }
+        }
+    }
+    if (agent.history !== undefined) {
+        const history = agent.history;
+        if (!agentIsPlainObject(history)) {
+            out.push(agentInvalid("history", "must be a table: { function } or { maxHistoryChars }"));
+        }
+        else {
+            agentUnknownKeys(history, AGENT_HISTORY_KEYS, "history", out);
+            const hasFunction = history.function !== undefined;
+            const hasCap = history.maxHistoryChars !== undefined;
+            if (hasFunction === hasCap) {
+                out.push(agentInvalid("history", hasFunction
+                    ? "sets both function and maxHistoryChars; a hook selects history or a cap trims it, not both"
+                    : "needs function = \"<key>\" (a hook) or maxHistoryChars (a cap)"));
+            }
+            if (hasFunction && !agentIsNonEmptyString(history.function)) {
+                out.push(agentInvalid("history.function", "must name a server function by key"));
+            }
+            if (hasCap &&
+                (typeof history.maxHistoryChars !== "number" ||
+                    !Number.isInteger(history.maxHistoryChars) ||
+                    history.maxHistoryChars < 1)) {
+                out.push(agentInvalid("history.maxHistoryChars", "must be a positive integer"));
+            }
+        }
+    }
+    checkAgentList(agent.tools, "tools", AGENT_LIMITS.tools, checkAgentTool, out);
+    checkAgentList(agent.events, "events", AGENT_LIMITS.events, checkAgentEvent, out);
+    return out;
+}
+/** Every function reference, with the path that makes it. */
+function agentFunctionReferences(agent) {
+    const refs = [];
+    if (Array.isArray(agent.tools)) {
+        agent.tools.forEach((tool, index) => {
+            if (agentIsPlainObject(tool) && agentIsNonEmptyString(tool.function)) {
+                refs.push({
+                    key: tool.function,
+                    tool: typeof tool.name === "string" ? tool.name : undefined,
+                    path: `tools[${index}].function`,
+                    needsSchemas: true,
+                });
+            }
+        });
+    }
+    const turnContext = agent.turnContext;
+    if (agentIsPlainObject(turnContext) && agentIsNonEmptyString(turnContext.function)) {
+        refs.push({
+            key: turnContext.function,
+            path: "turnContext.function",
+            needsSchemas: false,
+        });
+    }
+    const history = agent.history;
+    if (agentIsPlainObject(history) && agentIsNonEmptyString(history.function)) {
+        refs.push({ key: history.function, path: "history.function", needsSchemas: false });
+    }
+    return refs;
+}
+/**
+ * The function keys a declaration references (tools, turn context, history),
+ * each once, in declaration order. What a caller resolves into the
+ * `functions` facts before calling the resolver. `[]` for a block that is
+ * absent or does not parse — the resolver refuses the latter itself.
+ */
+/**
+ * `[prompt.agent]` as a value: a table as it is, one JSON string parsed,
+ * `undefined` for absence or for anything that is not a JSON object (which
+ * `resolveAgentDeclaration` refuses on its own).
+ *
+ * Exported for the sibling rules that read the same block — #3799's
+ * `agentSchemaTranslationRefusals` — so a declaration written as one JSON
+ * string is read identically by every rule that consumes it.
+ */
+export function parseAgentDeclarationBlock(agent) {
+    return parseAgentBlock(agent);
+}
+export function agentDeclarationFunctionKeys(agent) {
+    const parsed = parseAgentBlock(agent);
+    if (!parsed)
+        return [];
+    return [...new Set(agentFunctionReferences(parsed).map((ref) => ref.key))];
+}
+function agentFunctionRefusals(agent, functions) {
+    const out = [];
+    for (const ref of agentFunctionReferences(agent)) {
+        const subject = ref.tool
+            ? `tool "${ref.tool}" (${ref.path})`
+            : ref.path;
+        const facts = Object.prototype.hasOwnProperty.call(functions, ref.key)
+            ? functions[ref.key]
+            : null;
+        if (!facts) {
+            out.push(agentRefusal("AGENT_TOOL_FUNCTION_MISSING", `${AGENT_BLOCK} ${subject} names function "${ref.key}", which this app ` +
+                "does not have. Push the function first, or include its file in " +
+                "this push"));
+            continue;
+        }
+        if (!ref.needsSchemas)
+            continue;
+        const missing = [
+            facts.hasInputSchema ? null : "inputSchema",
+            facts.hasOutputSchema ? null : "outputSchema",
+        ].filter((name) => name !== null);
+        if (missing.length > 0) {
+            out.push(agentRefusal("AGENT_TOOL_FUNCTION_SCHEMA_MISSING", `${AGENT_BLOCK} ${subject} names function "${ref.key}", which declares ` +
+                `no ${missing.join(" or ")}. A tool's schemas are its function's: ` +
+                `declare ${missing.join(" and ")} in functions/${ref.key}.toml`));
+        }
+    }
+    return out;
+}
+/**
+ * The one rule: is this `[prompt.agent]` declaration (with the prompt's kind
+ * and `outputSchema`) something the platform can run?
+ *
+ * `{ ok: true, declaration }` carries the AUTHORED value — parsed when the
+ * block was one JSON string, otherwise unchanged — or `null` for an absent
+ * block. Callers store exactly this.
+ */
+export function resolveAgentDeclaration(input) {
+    const kind = agentKindOf(input.kind);
+    const refusals = [];
+    if (kind !== "agent") {
+        if (agentIsUnset(input.agent))
+            return { ok: true, declaration: null };
+        return {
+            ok: false,
+            refusals: [
+                agentInvalid("", `is declared on a prompt whose kind is "${kind}"; only a ` +
+                    'kind = "agent" prompt carries it. Remove the block, or create ' +
+                    "the agent under a new key"),
+            ],
+        };
+    }
+    if (!agentIsUnset(input.outputSchema)) {
+        refusals.push(agentRefusal("AGENT_OUTPUT_SCHEMA_NOT_ALLOWED", "[prompt].outputSchema is not declared on an agent: its final answer " +
+            "is text for people, and anything structured is a tool call. Remove " +
+            "outputSchema, or declare a tool whose schema carries the structure"));
+    }
+    let declaration = null;
+    if (!agentIsUnset(input.agent)) {
+        const parsed = parseAgentBlock(input.agent);
+        if (!parsed) {
+            refusals.push(agentInvalid("", "must be a table (or one JSON string encoding a table) declaring " +
+                "the agent's tools, events, turn context, history and limits"));
+        }
+        else {
+            declaration = parsed;
+            refusals.push(...agentShapeRefusals(parsed));
+            if (input.functions) {
+                refusals.push(...agentFunctionRefusals(parsed, input.functions));
+            }
+        }
+    }
+    if (refusals.length > 0)
+        return { ok: false, refusals };
+    return { ok: true, declaration: declaration };
+}
+/**
+ * The refusal of a single-shot run of an agent — `ctx.prompts.run`, the member
+ * execute route, the admin execute and preview routes, the workflow
+ * `prompt.execute` step and the executor itself (§D1: an agent runs turn by
+ * turn in a session, never once).
+ */
+export function agentNotRunnableRefusal(promptKey) {
+    const subject = promptKey === undefined ? "This prompt" : `Prompt "${promptKey}"`;
+    return agentRefusal("AGENT_NOT_RUNNABLE", `${subject} is an agent (kind = "agent"), which runs turn by turn in a ` +
+        "session and cannot be run single-shot. Run a chat or decisions " +
+        "prompt here instead");
+}
+/**
+ * The refusal of an agent round asked of a prompt that is not an agent —
+ * #3800 (`PromptExecutionService.resolveAgentTurnConfig` and
+ * `executeAgentRound`). The mirror of `agentNotRunnableRefusal`.
+ */
+export function agentRoundNotAgentRefusal(promptKey) {
+    return agentRefusal("AGENT_ROUND_NOT_AGENT", `Prompt "${promptKey}" is not an agent (kind = "agent"), so it has no ` +
+        "agent rounds. Run it with ctx.prompts.run, or name an agent prompt");
+}
+/**
+ * The refusal of a prompt test case that involves an agent (§D1: prompt test
+ * cases are refused for the kind in v1; multi-turn tests are deferred).
+ * `subject` is a case written ON the agent, `evaluator` a case that names the
+ * agent as its judge.
+ */
+export function agentTestCaseRefusal(promptKey, role) {
+    return agentRefusal("AGENT_TEST_CASE_NOT_SUPPORTED", role === "subject"
+        ? `Prompt "${promptKey}" is an agent (kind = "agent"); prompt test ` +
+            "cases are not supported for agents yet. Test its tools as functions"
+        : `Prompt "${promptKey}" is an agent (kind = "agent") and cannot be an ` +
+            "evaluator: an evaluator is run single-shot. Name a chat prompt");
+}
+/** A deep copy, so a reader's defaults never reach the caller's value. */
+function agentCopy(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+/**
+ * The declaration with every default applied: `answeredBy = "initiator"`, the
+ * platform maximums for the limits, and per tool `invoke = "request"` (server
+ * tools), `approval = false` and `historyScope = "session"`.
+ *
+ * The ONLY accessor for defaults — the stored value never carries them
+ * (DSO-3798-001). Takes a value `resolveAgentDeclaration` accepted (or `null`)
+ * and leaves it untouched.
+ */
+export function normalizeAgentDeclaration(declaration) {
+    const source = agentCopy(declaration ?? {});
+    return {
+        answeredBy: source.answeredBy ?? "initiator",
+        maxSteps: source.maxSteps ?? AGENT_LIMITS.maxSteps,
+        waitLimitSeconds: source.waitLimitSeconds ?? AGENT_LIMITS.waitLimitSeconds,
+        turnContext: source.turnContext ?? null,
+        history: source.history ?? null,
+        tools: (source.tools ?? []).map((tool) => ({
+            ...tool,
+            ...(tool.runs === "client" ? {} : { invoke: tool.invoke ?? "request" }),
+            approval: tool.approval ?? false,
+            historyScope: tool.historyScope ?? "session",
+        })),
+        events: source.events ?? [],
+    };
+}
+/**
+ * The keywords that constrain only a value of one type, and so belong to that
+ * type's member when a type union is rewritten as `anyOf` (CSO-3799-003). A
+ * bare `{ type: "object" }` or `{ type: "array" }` member would be the
+ * free-form object and the untyped array Gemini cannot carry.
+ */
+const GEMINI_UNION_MEMBER_KEYWORDS = {
+    object: [
+        "properties",
+        "required",
+        "minProperties",
+        "maxProperties",
+        "propertyOrdering",
+    ],
+    array: ["items", "minItems", "maxItems"],
+};
+/** The six `type` names Gemini's function `Schema` accepts. */
+const GEMINI_TYPES = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+];
+/**
+ * Keywords Gemini spells the same way, with the same meaning. `required` is
+ * here rather than under the structural keywords because Gemini reads it
+ * verbatim.
+ */
+const GEMINI_PASS_KEYWORDS = [
+    "description",
+    "title",
+    "default",
+    "minimum",
+    "maximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minItems",
+    "maxItems",
+    "minProperties",
+    "maxProperties",
+    "required",
+    // Gemini's own spellings, accepted as authored.
+    "nullable",
+    "propertyOrdering",
+    "example",
+];
+/** Annotations with no value meaning: dropped in silence (spec §3). */
+const GEMINI_DROPPED_KEYWORDS = ["$schema", "$id", "$comment"];
+/** Keywords handled by their own rule below, not by the tables. */
+const GEMINI_STRUCTURAL_KEYWORDS = [
+    "type",
+    "enum",
+    "const",
+    "format",
+    "properties",
+    "items",
+    "anyOf",
+    "oneOf",
+    "additionalProperties",
+];
+/** `format` values Gemini documents. Anything else is refused. */
+const GEMINI_FORMATS = [
+    "date-time",
+    "enum",
+    "int32",
+    "int64",
+    "float",
+    "double",
+];
+/**
+ * Keywords Gemini's function `Schema` has no spelling for. Each is refused
+ * rather than dropped: dropping any of them widens what the model may produce.
+ */
+const GEMINI_REFUSED_KEYWORDS = {
+    $ref: "Gemini's function Schema has no $ref — inline the referenced schema",
+    $defs: "Gemini's function Schema has no $defs — inline each definition where it is used",
+    definitions: "Gemini's function Schema has no definitions — inline each definition where it is used",
+    allOf: "Gemini's function Schema has no allOf — merge the members into one schema",
+    not: "Gemini's function Schema has no not — state what is allowed instead",
+    if: "Gemini's function Schema has no conditional schemas (if/then/else) — declare a discriminated oneOf instead",
+    then: "Gemini's function Schema has no conditional schemas (if/then/else) — declare a discriminated oneOf instead",
+    else: "Gemini's function Schema has no conditional schemas (if/then/else) — declare a discriminated oneOf instead",
+    patternProperties: "Gemini's function Schema has no patternProperties — name the properties",
+    propertyNames: "Gemini's function Schema has no propertyNames — name the properties",
+    dependencies: "Gemini's function Schema has no property dependencies — declare a discriminated oneOf instead",
+    dependentRequired: "Gemini's function Schema has no property dependencies — declare a discriminated oneOf instead",
+    dependentSchemas: "Gemini's function Schema has no property dependencies — declare a discriminated oneOf instead",
+    prefixItems: "Gemini's function Schema has no tuple items (prefixItems) — declare one items schema",
+    contains: "Gemini's function Schema has no contains — declare items instead",
+    uniqueItems: "Gemini's function Schema has no uniqueItems, and dropping it would let the model repeat an entry",
+    multipleOf: "Gemini's function Schema has no multipleOf, and dropping it would widen the allowed numbers",
+    exclusiveMinimum: "Gemini's function Schema has only minimum (inclusive), and dropping the exclusive bound would widen the allowed numbers",
+    exclusiveMaximum: "Gemini's function Schema has only maximum (inclusive), and dropping the exclusive bound would widen the allowed numbers",
+    examples: "Gemini's function Schema spells a sample as example (singular) — use example",
+    contentMediaType: "Gemini's function Schema has no contentMediaType — describe the encoding in description",
+    contentEncoding: "Gemini's function Schema has no contentEncoding — describe the encoding in description",
+    readOnly: "Gemini's function Schema has no readOnly — drop it, or say so in description",
+    writeOnly: "Gemini's function Schema has no writeOnly — drop it, or say so in description",
+    deprecated: "Gemini's function Schema has no deprecated — say so in description",
+};
+/**
+ * Sibling keywords that make a `oneOf` node a MIXED schema rather than a clean
+ * tagged union. Exactly `describeSchema`'s list
+ * (`src/workflows/schema-descriptor.ts`) — the platform's own rule for what a
+ * discriminated union is, restated here because that module is vendored
+ * separately and cannot be imported from `src/config-surface/`.
+ */
+const ONEOF_SIBLING_KEYWORDS = [
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+];
+function isPlainSchemaObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaCopy(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+/** A tag literal the platform validator can branch on with strict `===`. */
+function isScalarTag(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
+/** `properties.amount` under `items` is `items.properties.amount`. */
+function childPath(path, step) {
+    return path === "" ? step : `${path}.${step}`;
+}
+/** What a message calls the root. */
+export function schemaPathLabel(path) {
+    return path === "" ? "the schema root" : path;
+}
+/**
+ * The single-literal-tag properties of one `oneOf` member: `{ name → literal }`
+ * for every property declared as a one-entry `enum` or a scalar `const`.
+ */
+function memberTagLiterals(member) {
+    const tags = new Map();
+    const properties = member.properties;
+    if (!isPlainSchemaObject(properties))
+        return tags;
+    for (const [name, sub] of Object.entries(properties)) {
+        if (!isPlainSchemaObject(sub))
+            continue;
+        if (Array.isArray(sub.enum) && sub.enum.length === 1 && isScalarTag(sub.enum[0])) {
+            tags.set(name, sub.enum[0]);
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(sub, "const") && isScalarTag(sub.const)) {
+            tags.set(name, sub.const);
+        }
+    }
+    return tags;
+}
+/**
+ * Is this `oneOf` a discriminated union whose members are mutually exclusive
+ * BY CONSTRUCTION, so that `anyOf` of the same members admits exactly the same
+ * values (DSO-3799-003)?
+ *
+ * `describeSchema`'s rule, plus the one thing it does not check: the
+ * discriminant must be listed under `required` in every member. Without that,
+ * two members with optional tags both admit `{}`, which the authored `oneOf`
+ * and the platform validator reject but an `anyOf` of the same members accepts
+ * — so the rewrite would widen what the model may produce. The platform
+ * validator already rejects a value whose tag is missing
+ * (`src/workflows/schema-validation.ts`), so requiring it refuses nothing the
+ * platform accepts at run time.
+ */
+function discriminatedOneOf(node, members) {
+    const objects = members.filter((member) => isPlainSchemaObject(member) && member.type === "object");
+    if (objects.length !== members.length || members.length < 2) {
+        return {
+            ok: false,
+            reason: "Gemini's function Schema has no oneOf. Only a DISCRIMINATED oneOf can " +
+                "be rewritten as anyOf without widening it, and that needs at least two " +
+                'members, every one of them type = "object"',
+        };
+    }
+    const sibling = ONEOF_SIBLING_KEYWORDS.filter((key) => Object.prototype.hasOwnProperty.call(node, key));
+    if (sibling.length > 0) {
+        return {
+            ok: false,
+            reason: "Gemini's function Schema has no oneOf, and this one is not a clean " +
+                `discriminated union: it carries the sibling constraint${sibling.length > 1 ? "s" : ""} ` +
+                `${sibling.join(", ")}. Move the shared constraints into each member`,
+        };
+    }
+    if (Object.prototype.hasOwnProperty.call(node, "anyOf")) {
+        return {
+            ok: false,
+            reason: "Gemini's function Schema has no oneOf, and this node already carries " +
+                "an anyOf the rewrite would replace. Declare one or the other",
+        };
+    }
+    const tags = objects.map(memberTagLiterals);
+    const candidates = [];
+    for (const name of tags[0].keys()) {
+        if (!tags.every((map) => map.has(name)))
+            continue;
+        const literals = tags.map((map) => map.get(name));
+        const distinct = new Set(literals.map((literal) => JSON.stringify(literal)));
+        if (distinct.size === literals.length)
+            candidates.push(name);
+    }
+    if (candidates.length !== 1) {
+        return {
+            ok: false,
+            reason: candidates.length === 0
+                ? "Gemini's function Schema has no oneOf, and this one is not " +
+                    "discriminated: every member must share exactly one property " +
+                    "declared as a distinct single-literal enum (or const)"
+                : "Gemini's function Schema has no oneOf, and this one's " +
+                    `discriminant is ambiguous: ${candidates.join(", ")} all qualify. ` +
+                    "Exactly one is required",
+        };
+    }
+    const discriminant = candidates[0];
+    const omitting = objects
+        .map((member, index) => Array.isArray(member.required) && member.required.includes(discriminant)
+        ? null
+        : index)
+        .filter((index) => index !== null);
+    if (omitting.length > 0) {
+        return {
+            ok: false,
+            reason: `Gemini's function Schema has no oneOf. Rewriting this one as anyOf ` +
+                `would widen it, because member${omitting.length > 1 ? "s" : ""} ` +
+                `${omitting.join(", ")} do${omitting.length > 1 ? "" : "es"} not list ` +
+                `the discriminant "${discriminant}" under required, so a value with no ` +
+                `"${discriminant}" would match every member. List "${discriminant}" ` +
+                "under required in every member",
+        };
+    }
+    return { ok: true, discriminant };
+}
+/**
+ * Translate one node into Gemini's `Schema`, appending every refusal it holds
+ * to `out`. Returns the translated node, or `null` when the node itself is not
+ * a schema object.
+ */
+function translateGeminiNode(node, path, out) {
+    if (!isPlainSchemaObject(node)) {
+        out.push({
+            path,
+            keyword: "(schema)",
+            reason: "is not a JSON Schema object; Gemini's function Schema needs a table " +
+                "declaring at least a type",
+        });
+        return null;
+    }
+    const result = {};
+    /** Faults raised AT THIS NODE — nested ones must not suppress its own rules. */
+    let nodeFaults = 0;
+    const refuse = (keyword, reason) => {
+        nodeFaults += 1;
+        out.push({ path, keyword, reason });
+    };
+    // ── Pass one: the tables, in the author's own key order ────────────────
+    const deferred = new Set();
+    for (const key of Object.keys(node)) {
+        if (GEMINI_DROPPED_KEYWORDS.includes(key))
+            continue;
+        if (key === "additionalProperties") {
+            // Dropped for `false` and `true` alike: Gemini has no closed-object
+            // spelling, and the platform validates the ORIGINAL schema (DSO-3799-001).
+            const value = node[key];
+            if (value === false || value === true)
+                continue;
+            refuse(key, isPlainSchemaObject(value)
+                ? "Gemini's function Schema has no additionalProperties, so a schema " +
+                    "for the extra properties cannot be carried — name the properties"
+                : "additionalProperties must be true or false (Gemini carries neither, " +
+                    "but the platform validates the original schema)");
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(GEMINI_REFUSED_KEYWORDS, key)) {
+            refuse(key, GEMINI_REFUSED_KEYWORDS[key]);
+            continue;
+        }
+        if (GEMINI_PASS_KEYWORDS.includes(key)) {
+            result[key] = schemaCopy(node[key]);
+            continue;
+        }
+        if (GEMINI_STRUCTURAL_KEYWORDS.includes(key)) {
+            deferred.add(key);
+            continue;
+        }
+        // Fail closed: a keyword nobody classified could mean anything.
+        refuse(key, "is not a keyword Gemini's function Schema carries, and dropping a " +
+            "keyword whose meaning the platform does not know could widen what the " +
+            "model may produce");
+    }
+    // ── Pass two: the structural keywords, in a fixed order ────────────────
+    if (deferred.has("enum")) {
+        const values = node.enum;
+        if (!Array.isArray(values) || values.length === 0) {
+            refuse("enum", "must be a non-empty list of strings");
+        }
+        else if (values.every((value) => typeof value === "string")) {
+            result.enum = schemaCopy(values);
+        }
+        else {
+            refuse("enum", "Gemini's function Schema takes only STRING enum values; write the " +
+                "allowed values as strings, or state the constraint in description");
+        }
+    }
+    if (deferred.has("const")) {
+        const value = node.const;
+        if (typeof value !== "string") {
+            refuse("const", "Gemini's function Schema has no const, and only a string one can be " +
+                'rewritten as enum: ["…"]');
+        }
+        else if (deferred.has("enum")) {
+            refuse("const", "Gemini's function Schema has no const; it is rewritten as a " +
+                "single-literal enum, which this node already declares. Keep one of the two");
+        }
+        else {
+            result.enum = [value];
+        }
+    }
+    if (deferred.has("format")) {
+        const value = node.format;
+        if (typeof value === "string" &&
+            GEMINI_FORMATS.includes(value)) {
+            result.format = value;
+        }
+        else {
+            refuse("format", `Gemini's function Schema documents only ${GEMINI_FORMATS.join(", ")}; ` +
+                "state anything else in description");
+        }
+    }
+    /** A type union to rewrite as `anyOf`, once its members' keywords are translated. */
+    let unionTypes = null;
+    if (deferred.has("type")) {
+        const typeSpec = node.type;
+        if (typeof typeSpec === "string") {
+            if (GEMINI_TYPES.includes(typeSpec)) {
+                result.type = typeSpec;
+            }
+            else {
+                refuse("type", `Gemini's function Schema takes one of ${GEMINI_TYPES.join(", ")}; ` +
+                    `found ${JSON.stringify(typeSpec)}` +
+                    (typeSpec === "null"
+                        ? '. A nullable value is spelled type: [T, "null"]'
+                        : ""));
+            }
+        }
+        else if (Array.isArray(typeSpec)) {
+            const nullable = typeSpec.includes("null");
+            const named = typeSpec.filter((entry) => entry !== "null");
+            const unknown = named.filter((entry) => typeof entry !== "string" ||
+                !GEMINI_TYPES.includes(entry));
+            if (unknown.length > 0) {
+                refuse("type", `Gemini's function Schema takes one of ${GEMINI_TYPES.join(", ")}; ` +
+                    `found ${unknown.map((entry) => JSON.stringify(entry)).join(", ")}`);
+            }
+            else if (named.length === 0) {
+                refuse("type", "Gemini's function Schema has no null type on its own; a nullable " +
+                    'value is spelled type: [T, "null"]');
+            }
+            else if (named.length === 1) {
+                result.type = named[0];
+                if (nullable)
+                    result.nullable = true;
+            }
+            else if (deferred.has("anyOf")) {
+                refuse("type", "a type union is rewritten as anyOf of the single types, which this " +
+                    "node already declares. Write the union inside the anyOf instead");
+            }
+            else {
+                unionTypes = named;
+                if (nullable)
+                    result.nullable = true;
+            }
+        }
+        else {
+            refuse("type", `must be a type name or a list of them; found ${typeof typeSpec}`);
+        }
+    }
+    if (deferred.has("properties")) {
+        const properties = node.properties;
+        if (!isPlainSchemaObject(properties)) {
+            refuse("properties", "must be a table of property name to schema");
+        }
+        else {
+            const translated = {};
+            for (const [name, sub] of Object.entries(properties)) {
+                const child = translateGeminiNode(sub, childPath(path, `properties.${name}`), out);
+                // Defined, not assigned: a JSON-parsed schema may name a property
+                // `__proto__`, and assigning it would set the prototype and drop the
+                // property from what Gemini is sent (CSO-3799-006).
+                if (child) {
+                    Object.defineProperty(translated, name, {
+                        value: child,
+                        enumerable: true,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
+            }
+            result.properties = translated;
+        }
+    }
+    if (deferred.has("items")) {
+        const child = translateGeminiNode(node.items, childPath(path, "items"), out);
+        if (child)
+            result.items = child;
+    }
+    if (deferred.has("anyOf")) {
+        const members = node.anyOf;
+        if (!Array.isArray(members) || members.length === 0) {
+            refuse("anyOf", "must be a non-empty list of schemas");
+        }
+        else {
+            const translated = [];
+            members.forEach((member, index) => {
+                const child = translateGeminiNode(member, childPath(path, `anyOf[${index}]`), out);
+                if (child)
+                    translated.push(child);
+            });
+            result.anyOf = translated;
+        }
+    }
+    if (deferred.has("oneOf")) {
+        const members = node.oneOf;
+        if (!Array.isArray(members)) {
+            refuse("oneOf", "must be a list of schemas");
+        }
+        else {
+            const verdict = discriminatedOneOf(node, members);
+            if (verdict.ok === false) {
+                refuse("oneOf", verdict.reason);
+            }
+            else {
+                // A discriminated oneOf whose members all require their tag is mutually
+                // exclusive by construction, so anyOf of the same members admits
+                // exactly the same values (DSO-3799-003).
+                const translated = [];
+                members.forEach((member, index) => {
+                    const child = translateGeminiNode(member, childPath(path, `oneOf[${index}]`), out);
+                    if (child)
+                        translated.push(child);
+                });
+                result.anyOf = translated;
+            }
+        }
+    }
+    // A type union becomes `anyOf` of the single types, each member carrying the
+    // keywords that constrain its type (CSO-3799-003): `{ type: ["object",
+    // "string"], properties }` means an object WITH those properties, or a
+    // string. Everything else stays on the node, beside the `anyOf`.
+    if (unionTypes) {
+        const members = unionTypes.map((type) => {
+            const member = { type };
+            for (const key of GEMINI_UNION_MEMBER_KEYWORDS[type] ?? []) {
+                if (result[key] !== undefined)
+                    member[key] = result[key];
+            }
+            return member;
+        });
+        for (const type of unionTypes) {
+            for (const key of GEMINI_UNION_MEMBER_KEYWORDS[type] ?? []) {
+                delete result[key];
+            }
+        }
+        result.anyOf = members;
+    }
+    // ── Pass three: what Gemini requires of a complete node ────────────────
+    //
+    // Only when this node raised no fault of its own: a node refused for `$ref`
+    // or `allOf` would otherwise be refused a second time for the type that
+    // keyword was carrying.
+    if (nodeFaults === 0) {
+        const hasBranches = deferred.has("anyOf") || deferred.has("oneOf");
+        // A STRING enum carries its own type — every value it admits is a string —
+        // so a node declaring one needs no `type` beside it. That is what keeps the
+        // platform's own discriminated-union dialect inside Gemini's reach: a tag is
+        // spelled `{ enum: ["cash"] }` with no type (`schema-descriptor.ts`), and
+        // Gemini accepts exactly that on a `functionDeclarations[].parameters`
+        // property (verified live, #3799 behavior 23). `result.enum` also covers a
+        // string `const` rewritten above.
+        const hasEnum = result.enum !== undefined;
+        if (!deferred.has("type") && !hasBranches && !hasEnum) {
+            refuse("type", "Gemini's function Schema needs a type on every schema (one of " +
+                `${GEMINI_TYPES.join(", ")}), or an anyOf of typed members`);
+        }
+        else if (result.type === "object") {
+            const properties = result.properties;
+            if (!isPlainSchemaObject(properties) || Object.keys(properties).length === 0) {
+                refuse("properties", "Gemini needs the object's properties: its function Schema has no " +
+                    "free-form object, and the existing clean-up rewrote one as a " +
+                    "string, which changes what the model may produce. Name the " +
+                    "properties the model may send");
+            }
+        }
+        else if (result.type === "array" && result.items === undefined) {
+            refuse("items", "Gemini needs the array's items: its function Schema has no untyped array");
+        }
+        // The members a type union was rewritten into are held to the same rule
+        // as a single-typed node, so a union cannot carry the free-form object or
+        // the untyped array past it (CSO-3799-003).
+        if (unionTypes) {
+            const members = result.anyOf;
+            for (const member of members) {
+                if (member.type === "object" &&
+                    (!isPlainSchemaObject(member.properties) ||
+                        Object.keys(member.properties).length === 0)) {
+                    refuse("properties", "Gemini needs the object's properties, for the object member of " +
+                        "this type union too: its function Schema has no free-form " +
+                        "object. Name the properties the model may send");
+                }
+                else if (member.type === "array" && member.items === undefined) {
+                    refuse("items", "Gemini needs the array's items, for the array member of this type " +
+                        "union too: its function Schema has no untyped array");
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Translate one schema for one provider, or refuse it naming every keyword it
+ * cannot carry.
+ *
+ * OpenRouter is identity — a deep copy of the input, so a caller that edits the
+ * result never reaches the stored original. Gemini follows the table in spec
+ * §4. Every refusal of one schema is returned at once, so an author fixes it in
+ * one pass (principle 6).
+ */
+export function translateSchemaForProvider(schema, provider) {
+    if (provider !== "gemini") {
+        // Identity: the request carries the schema as declared and the model's
+        // upstream owns its dialect.
+        if (!isPlainSchemaObject(schema)) {
+            return {
+                ok: false,
+                refusals: [
+                    {
+                        path: "",
+                        keyword: "(schema)",
+                        reason: "is not a JSON Schema object",
+                    },
+                ],
+            };
+        }
+        return { ok: true, schema: schemaCopy(schema) };
+    }
+    const refusals = [];
+    const translated = translateGeminiNode(schema, "", refusals);
+    if (refusals.length > 0)
+        return { ok: false, refusals };
+    return { ok: true, schema: translated };
+}
+/** `{ gemini: ["default", "slow"] }` — the non-archived configs, by provider. */
+function configsByProvider(configs) {
+    const order = [];
+    const names = new Map();
+    for (const config of configs) {
+        if (String(config?.status ?? "active") === "archived")
+            continue;
+        const provider = String(config?.provider ?? "").toLowerCase();
+        if (!provider)
+            continue;
+        if (!names.has(provider)) {
+            names.set(provider, []);
+            order.push(provider);
+        }
+        names.get(provider).push(String(config.configName ?? ""));
+    }
+    return order.map((provider) => ({
+        provider,
+        configNames: names.get(provider),
+    }));
+}
+/** A stored schema value: an object as it is, a JSON string parsed. */
+function readStoredSchema(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string") {
+        if (value.trim() === "")
+            return null;
+        try {
+            return { ok: true, schema: JSON.parse(value) };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    return { ok: true, schema: value };
+}
+/**
+ * Every schema of an agent that the model reads: each tool's `inputSchema` and
+ * `outputSchema` (from the TOML for a client tool, from the function's own
+ * schemas for a server tool) and each event's `schema`.
+ */
+function agentSchemaSubjects(declaration, functions) {
+    const subjects = [];
+    const tools = Array.isArray(declaration.tools) ? declaration.tools : [];
+    tools.forEach((tool) => {
+        if (!isPlainSchemaObject(tool))
+            return;
+        const name = typeof tool.name === "string" ? tool.name : "(unnamed)";
+        const functionKey = typeof tool.function === "string" && tool.function.trim() !== ""
+            ? tool.function.trim()
+            : null;
+        if (functionKey === null) {
+            // A client tool: its schemas are in the declaration.
+            for (const which of ["inputSchema", "outputSchema"]) {
+                if (tool[which] === undefined)
+                    continue;
+                subjects.push({ subject: `tool "${name}"`, which, schema: tool[which] });
+            }
+            return;
+        }
+        // A server tool: its schemas are its function's. `undefined` facts are the
+        // function-missing and schema-missing refusals of #3798, not this rule's.
+        if (!functions)
+            return;
+        const facts = Object.prototype.hasOwnProperty.call(functions, functionKey)
+            ? functions[functionKey]
+            : null;
+        if (!facts)
+            return;
+        const subject = `tool "${name}" (function "${functionKey}")`;
+        for (const which of ["inputSchema", "outputSchema"]) {
+            const read = readStoredSchema(which === "inputSchema" ? facts.inputSchema : facts.outputSchema);
+            if (read === null)
+                continue;
+            if (read.ok === false) {
+                subjects.push({ subject, which, unparsable: functionKey });
+                continue;
+            }
+            subjects.push({ subject, which, schema: read.schema });
+        }
+    });
+    const events = Array.isArray(declaration.events) ? declaration.events : [];
+    events.forEach((event) => {
+        if (!isPlainSchemaObject(event))
+            return;
+        if (event.schema === undefined)
+            return;
+        const name = typeof event.name === "string" ? event.name : "(unnamed)";
+        subjects.push({
+            subject: `event "${name}"`,
+            which: "schema",
+            schema: event.schema,
+        });
+    });
+    return subjects;
+}
+/** `config "default"` / `configs "default", "slow"`. */
+function configList(configNames) {
+    const quoted = configNames.map((name) => `"${name}"`).join(", ");
+    return `${configNames.length === 1 ? "config" : "configs"} ${quoted}`;
+}
+/**
+ * Every `AGENT_SCHEMA_NOT_TRANSLATABLE` refusal an agent's declaration owes,
+ * checked against the provider of every config that is not archived
+ * (intent criterion 2).
+ *
+ * One refusal per (schema, path, keyword, provider): it names the tool or
+ * event, which schema, the dotted path, the keyword, the provider, the config
+ * names on that provider, and the remedy. Two configs on the same provider
+ * produce ONE refusal naming both — the author's fix is the same either way.
+ *
+ * A declaration with no tools and no events reads no function schema at all.
+ */
+export function agentSchemaTranslationRefusals(input) {
+    const declaration = parseAgentDeclarationBlock(input.declaration);
+    if (!declaration)
+        return [];
+    const providers = configsByProvider(input.configs ?? []);
+    if (providers.length === 0)
+        return [];
+    const subjects = agentSchemaSubjects(declaration, input.functions);
+    if (subjects.length === 0)
+        return [];
+    const out = [];
+    for (const subject of subjects) {
+        if (subject.unparsable !== undefined) {
+            out.push({
+                code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
+                message: `${AGENT_BLOCK_LABEL} ${subject.subject} ${subject.which} is not a ` +
+                    `JSON Schema the platform can read, so it cannot be translated for ` +
+                    `any provider. Fix ${subject.which} in ` +
+                    `functions/${subject.unparsable}.toml`,
+            });
+            continue;
+        }
+        for (const { provider, configNames } of providers) {
+            const result = translateSchemaForProvider(subject.schema, provider);
+            if (result.ok === true)
+                continue;
+            for (const refusal of result.refusals) {
+                out.push({
+                    code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
+                    message: `${AGENT_BLOCK_LABEL} ${subject.subject} ${subject.which} at ` +
+                        `${schemaPathLabel(refusal.path)}: ${refusal.keyword} cannot be ` +
+                        `translated for ${provider} without losing meaning — ` +
+                        `${refusal.reason}. ${configList(configNames)} run on ${provider}; ` +
+                        `rewrite the schema, or archive every ${provider} config of this prompt`,
+                });
+            }
+        }
+    }
+    return out;
+}
+// ── src/config-surface/prompt.ts ─────────────────────────────────────────
+/**
+ * The `prompt` configuration object's definition (issue #2644, phase 2).
+ *
+ * `prompts/<key>.toml` carries TWO field tables: the `[prompt]` table backed by
+ * `AppPrompt`, and the repeated `[[configs]]` table backed by `AppPromptConfig`
+ * — one entry per named LLM configuration. Both are declared here, so a field
+ * added to either model is covered by the same guard.
+ *
+ * The `[[configs]]` entries are the reason prompts have two tables rather than
+ * a `structural` note: they are a real field surface the CLI pushes
+ * (`createPromptConfig` / `updatePromptConfig`) and pulls, not an opaque blob.
+ */
+const PROMPT_HANDLER = "src/admin-api.ts";
+/**
+ * #3798 — the blocks a model setting both kinds use is authored under: the
+ * chat block, and the agent block that is the chat block less its template
+ * and output keys (`AGENT_CONFIG_KEYS`).
+ */
+const SHARED_WITH_AGENT = ["chat", "agent"];
+/**
+ * #3626 §4 — the nine chat keys, still accepted FLAT under `[[configs]]`.
+ *
+ * The blob-bucket `accessPolicy` precedent: declared `deprecated`, so
+ * `config push` keeps taking a file written before the `[configs.chat]` block
+ * existed, while `config pull` never writes the spelling again. One
+ * pull-then-push migrates a file. `hoistDeprecatedChatKeys` moves them into the
+ * group before the payload is built; rejecting the flat spelling outright is
+ * #3642. #3801 — only the nine: a chat key added later (`strictOutput`) was
+ * never written flat, so it has no deprecated spelling to accept.
+ */
+const DEPRECATED_FLAT_CHAT_KEYS = Object.fromEntries(LEGACY_FLAT_CHAT_KEYS.map((key) => [
+    key,
+    {
+        kind: "deprecated",
+        note: `#3626 — the pre-kind spelling of \`[configs.chat].${key}\`. Still ` +
+            "accepted flat so no existing prompt file breaks (push hoists it " +
+            "into the block and warns); `config pull` writes only the grouped " +
+            "spelling, so one pull-then-push migrates the file. Rejecting the " +
+            "flat spelling is #3642.",
+    },
+]));
+export const PROMPT_SURFACE = {
+    label: "prompt",
+    tables: [
+        {
+            tomlPath: ["prompt"],
+            repeated: false,
+            model: "AppPrompt",
+            // Declaration order reproduces the pre-#2644 serializer's key order.
+            fields: [
+                // #3626 — WHAT this prompt runs. `chat` is today's prompt (a chat
+                // completion rendered from templates); `decisions` names OpenRouter's
+                // `/api/alpha/decisions` endpoint, which takes a `state` value plus
+                // named typed questions. It lives on the PROMPT because it decides the
+                // input envelope, the output type, the meaning of `inputSchema` /
+                // `outputSchema` and the shape of every test case's `inputVariables` —
+                // all of which are asserted per prompt KEY.
+                //
+                // `emit: "always"` so a pulled file says which kind it is; an omitted
+                // key is `chat`, so no file written before this changes meaning, and
+                // `serverDefault` is what lets push send `chat` for an absent key and
+                // `config diff` read both spellings as one value.
+                //
+                // CREATE_ONLY, and immutable in the strong sense (D3626-008): changing
+                // a prompt's kind under its key would change the contract of every
+                // caller compiled against it, so the update handler never reads it and
+                // the push gate declines the change as `immutable` — the `ttlTier`
+                // precedent. The prompt comparator projects `[prompt]` in CREATE mode
+                // for exactly that reason (SO3626-008).
+                {
+                    field: "kind",
+                    tomlKey: "kind",
+                    type: "string",
+                    emit: "always",
+                    writableOn: CREATE_ONLY,
+                    serverDefault: "chat",
+                    validation: handledBy("src/config-surface/prompt-kinds.ts", "resolvePromptKind", "apply"),
+                },
+                {
+                    field: "displayName",
+                    tomlKey: "displayName",
+                    type: "string",
+                    emit: "always",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                {
+                    field: "description",
+                    tomlKey: "description",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: "passthrough",
+                },
+                // JSON Schema objects. Stored as JSON strings, returned parsed; TOML
+                // may present them as an inline table or a JSON string.
+                {
+                    field: "inputSchema",
+                    tomlKey: "inputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
+                },
+                // #2644 — accepted by both handlers and returned by the detail, but
+                // never written to TOML before this: a prompt's declared output shape
+                // was invisible to config-as-code.
+                {
+                    field: "outputSchema",
+                    tomlKey: "outputSchema",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
+                },
+                // #2652 — the CEL rule gating who may execute the prompt. Required at
+                // create; an explicit null/"" on update clears it (fail-closed). This
+                // declaration is the whole authoring channel: the admin routes' unknown
+                // key guard reads the same table, so it is what makes `accessRule` an
+                // accepted body key as well as a pulled and pushed TOML line.
+                {
+                    field: "accessRule",
+                    tomlKey: "accessRule",
+                    type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
                     validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
                 },
+                // #3798 — an AGENT's contract: its tools, event kinds, turn context,
+                // history selection, who answers a paused call, and its limits. One
+                // prompt-level block because they belong to the prompt, like
+                // `inputSchema`, not to a named config (intent §D1).
+                //
+                // A `json` field like the schemas: authored as nested tables
+                // (`[prompt.agent]`, `[[prompt.agent.tools]]`) or as one JSON string,
+                // stored as the AUTHORED value with no defaults filled in and returned
+                // parsed, so `config diff`'s value comparison reads a pushed file
+                // Synced (DSO-3798-001). Only a `kind = "agent"` prompt may carry it.
+                {
+                    field: "agent",
+                    tomlKey: "agent",
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy("src/config-surface/agent-declaration.ts", "resolveAgentDeclaration", "apply"),
+                },
             ],
             notExposed: {
                 promptId: {
@@ -5342,6 +7064,12 @@ export const PROMPT_SURFACE = {
                         "named typed questions OpenRouter's /api/alpha/decisions endpoint " +
                         "answers. Authored under `[configs.decisions.questions.<name>]`.",
                 },
+                agent: {
+                    note: "#3798 — the model settings of a `kind = \"agent\"` prompt: the " +
+                        "six keys it shares with chat (systemPrompt, temperature, topP, " +
+                        "maxTokens, reasoningEffort, reasoningBudget), and no template, " +
+                        "outputFormat or outputSchema. Authored under `[configs.agent]`.",
+                },
             },
             fields: [
                 {
@@ -5356,9 +7084,16 @@ export const PROMPT_SURFACE = {
                 // #2645 — a config's status is configuration: `prompts configs update
                 // --status archived` used to be the only way to retire one, and pull
                 // emitted nothing, so the file could not say which of its configs the
-                // server still runs. Update-only: create hard-codes "active" and
-                // ignores a supplied status, same statement `writableOn` makes for
-                // every create-assigned field.
+                // server still runs.
+                //
+                // #3799 (DSO-3799-005) — writable on CREATE too. It was update-only,
+                // which meant `config push` created every config live and archived it
+                // afterwards; a pulled tree whose retired config is on a provider the
+                // new schema-translation check refuses could therefore not be pushed
+                // into a fresh environment at all, because the refusal fired on a state
+                // the file never asked for. Both create paths honor `active |
+                // archived` now (default `active`, so a body that omits it is
+                // unchanged), and the post-create status patches are retired.
                 //
                 // #3201 — emitted only when it is NOT the create default, so a pulled
                 // file says `status = "archived"` about a retired config and says
@@ -5373,7 +7108,7 @@ export const PROMPT_SURFACE = {
                     tomlKey: "status",
                     type: "string",
                     emit: "whenSet",
-                    writableOn: UPDATE_ONLY,
+                    writableOn: BOTH,
                     validation: handledBy(PROMPT_HANDLER, "AdminAPI", "apply"),
                     serverDefault: "active",
                 },
@@ -5405,7 +7140,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "systemPrompt",
                     tomlKey: "systemPrompt",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5425,7 +7160,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "temperature",
                     tomlKey: "temperature",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5443,7 +7178,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "topP",
                     tomlKey: "topP",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5455,7 +7190,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "maxTokens",
                     tomlKey: "maxTokens",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5504,7 +7239,7 @@ export const PROMPT_SURFACE = {
                 {
                     field: "reasoningEffort",
                     tomlKey: "reasoningEffort",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "string",
                     emit: "whenSet",
                     writableOn: BOTH,
@@ -5513,12 +7248,29 @@ export const PROMPT_SURFACE = {
                 {
                     field: "reasoningBudget",
                     tomlKey: "reasoningBudget",
-                    tomlGroup: "chat",
+                    tomlGroup: SHARED_WITH_AGENT,
                     type: "number",
                     emit: "whenSet",
                     writableOn: BOTH,
                     validation: handledBy("src/config-surface/prompt-reasoning.ts", "resolvePromptReasoning", "apply"),
                 },
+                // #3801 — the opt-in that sends `[prompt].outputSchema` as a strict
+                // `json_schema` on OpenRouter instead of JSON mode checked afterwards
+                // (§D6). A chat key only: an agent has no output schema (§D1), and a
+                // decisions config's answer is typed by its questions. No flat
+                // spelling. The rule — one boolean, never beside a config-level
+                // `outputSchema`, OpenRouter only, never with `outputFormat = "text"`,
+                // and a prompt schema to send when the config is not archived — is
+                // `resolvePromptStrictOutput`, read by the routes and the preflight.
+                {
+                    field: "strictOutput",
+                    tomlKey: "strictOutput",
+                    tomlGroup: "chat",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: handledBy("src/config-surface/prompt-strict-output.ts", "resolvePromptStrictOutput", "apply"),
+                },
                 // #3626 — the named typed questions a DECISIONS config asks. A `json`
                 // field like `outputSchema`: stored as a JSON string, returned parsed,
                 // and authored either as nested tables
@@ -6776,6 +8528,11 @@ export const DATABASE_TYPE_SURFACE = {
                     writableOn: BOTH,
                     // CEL, parsed before storing (#1336). The legacy `metadataAccess`
                     // spelling stays readable on push — see tomlOnlyKeys.
+                    deprecated: {
+                        note: "one CEL expression gates both read and update of the database " +
+                            "CEL context; use a resource metadata category, which has " +
+                            "separate readRule and writeRule",
+                    },
                     validation: handledBy(DB_TYPE_HANDLER, "DatabaseTypeConfigController", "apply"),
                 },
                 {
@@ -8578,6 +10335,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "kind",
         "displayName",
         "description",
+        "agent",
         "copiedFromCatalogId",
         "inputSchema",
         "outputSchema",
@@ -8611,6 +10369,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "questions",
         "reasoningEffort",
         "reasoningBudget",
+        "strictOutput",
         "status",
         "createdBy",
         "createdAt",