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

package/dist/src/lib/generated-config-surfaces.d.ts

@@ -87,6 +87,33 @@ export interface ConfigField {
     field: string;
     /** Key inside the TOML table (often identical to `field`). */
     tomlKey: string;
+    /**
+     * The SUB-TABLE inside this field's table that the key is authored under
+     * (#3626) — `tomlGroup: "chat"` means `[configs.chat].systemPrompt` rather
+     * than `systemPrompt` at the `[[configs]]` root.
+     *
+     * A statement of WHERE a key is authored and nothing else (#1976): the pull
+     * projection writes it there, the push builder reads it from there, the
+     * unknown-key check stops accepting it at the root, and the declared-type
+     * check labels it with the group. No behavior is attached, and the WIRE stays
+     * flat — the admin and app API bodies carry `systemPrompt` beside `questions`
+     * exactly as before, each its own typed column.
+     *
+     * Prompts are the first object to need it: a prompt declares a `kind` and a
+     * `[[configs]]` entry may carry only the block named by that kind, so the
+     * next kind (embeddings, rerank) is a group declaration plus its fields
+     * rather than another round of implicit discrimination.
+     *
+     * The group must be declared in the table's `tomlGroups`
+     * (`findBadTomlGroupDeclarations`).
+     *
+     * #3798 — a LIST names a key authored under more than one block: the six
+     * model settings an agent shares with chat are `["chat", "agent"]`. Push
+     * reads the key from whichever of its blocks the entry carries, and pull
+     * writes it under the block the caller names (the prompt's kind), the first
+     * one otherwise. Read it through `tomlGroupsOf`, never directly.
+     */
+    tomlGroup?: string | readonly string[];
     type: FieldType;
     /** "whenSet" omits the key on pull when the value is empty; see #1033's `emit`. */
     emit: "always" | "whenSet";
@@ -143,6 +170,17 @@ export interface ConfigField {
     dualEncoded?: {
         note: string;
     };
+    /**
+     * The field is still accepted but deprecated, and `note` says what to use
+     * instead (#1815). Unlike `NotExposed`'s `deprecated` kind, the field stays
+     * on the TOML surface: it round-trips on pull and push exactly as before.
+     * The generated request schema marks the key `deprecated: true` in the
+     * published OpenAPI spec. `config push` does not read this note; any push
+     * warning for the field lives in the CLI's push preflight.
+     */
+    deprecated?: {
+        note: string;
+    };
     /**
      * The value the SERVER materializes when a create omits this key (#2880
      * DSO-002).
@@ -165,6 +203,20 @@ export interface ConfigTable {
     /** The `models.yaml` model backing this table — the coverage anchor. */
     model: string;
     fields: readonly ConfigField[];
+    /**
+     * The CLOSED set of sub-table names this table's fields may be authored under
+     * (#3626), each with the reason it exists. A field's `tomlGroup` must name
+     * one of these, and a name declared here that no field uses is a failure —
+     * both checked by `findBadTomlGroupDeclarations`, the same rule `notExposed`
+     * follows one level down: absence from a hand-written list is never a
+     * decision.
+     *
+     * Omitted on every table whose keys are all authored at its root, which is
+     * all of them but `prompt`'s `[[configs]]`.
+     */
+    tomlGroups?: Readonly<Record<string, {
+        note: string;
+    }>>;
     /** Every model field not in `fields`, with its reason. Coverage is exhaustive. */
     notExposed: Readonly<Record<string, NotExposed>>;
     /**
@@ -559,8 +611,43 @@ export declare function findUnclassifiedSecretishFields(table: ConfigTable, mode
  * when the module or the export is missing (#2644 behavior 2b).
  */
 export declare function handlerReferences(table: ConfigTable): string[];
-/** TOML keys this table accepts: the exposed fields plus the declared extras. */
+/**
+ * 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 declare function tomlGroupsOf(field: ConfigField): readonly string[];
+/** The group names this table declares, sorted. Empty for an ungrouped table. */
+export declare function tomlGroupNames(table: ConfigTable): string[];
+/** The TOML keys accepted INSIDE `group`: every field that declares it. */
+export declare function acceptedGroupTomlKeys(table: ConfigTable, group: string): Set<string>;
+/**
+ * TOML keys this table accepts AT ITS ROOT: the UNGROUPED fields, the declared
+ * group names, and the declared extras.
+ *
+ * A grouped leaf written at the root (`questions` directly under `[[configs]]`)
+ * is therefore an unknown key rather than one the payload builder silently
+ * ignores (SO3626-013) — the builder reads a grouped field only from
+ * `source[group][tomlKey]`, so accepting it here would drop the author's value
+ * without a word. The nine deprecated flat chat keys stay accepted through
+ * their `tomlOnlyKeys` declarations, which is what keeps old files pushing.
+ */
 export declare function acceptedTomlKeys(table: ConfigTable): Set<string>;
+/**
+ * Keys inside a group table that no field declares under it, as
+ * `"<group>.<key>"` — plus the bare `"<group>"` for a group value that is not a
+ * table at all (`chat = "yes"`), which has no keys to check and would otherwise
+ * be read as an empty block.
+ */
+export declare function findUnknownGroupedTomlKeys(tomlTable: unknown, table: ConfigTable): string[];
+/**
+ * Group declarations that do not hold together: a field naming a group the
+ * table does not declare, a declared group no field is authored under, and a
+ * declaration with no reason. All three are failures, for the reason
+ * `notExposed` carries a note — a name in a list with nothing behind it reads
+ * as a decision and is not one.
+ */
+export declare function findBadTomlGroupDeclarations(table: ConfigTable): string[];
 /** Top-level TOML keys this object's file accepts: its tables plus the extras. */
 export declare function acceptedTomlDocumentKeys(surface: ConfigObjectSurface): Set<string>;
 /**
@@ -891,8 +978,8 @@ export declare function findUnreachedPreflightRules(surface: ConfigObjectSurface
  * unrecognized TOML keys locally (criterion 6).
  *
  * ── What the schema says, and what it deliberately does not ──────────────
- * It states the KEY SET only: each property is the empty schema, so no value is
- * type-checked here. That is the decision of record (#1976, carried forward at
+ * It states the KEY SET only: each property is the empty schema (or carries
+ * only the `deprecated` annotation, #1815), so no value is type-checked here. That is the decision of record (#1976, carried forward at
  * #2644's design gate): the definition classifies, handlers behave. The
  * `status` enum, the queue limits' integer coercion, `runAs`'s caller|system
  * check, the CEL parse of `accessRule` — all stay in the handlers the
@@ -927,7 +1014,15 @@ export declare function findUnreachedPreflightRules(surface: ConfigObjectSurface
  */
 export interface ConfigRequestSchema {
     type: "object";
-    properties: Record<string, Record<string, never>>;
+    /**
+     * Each property is the empty schema, or `{ deprecated: true }` for a field
+     * the definition marks `deprecated` (#1815). `deprecated` is an OpenAPI
+     * annotation: it constrains no value, so the schema still states the key set
+     * and nothing more.
+     */
+    properties: Record<string, {
+        deprecated?: true;
+    }>;
     additionalProperties: false;
     /**
      * Structural-typing escape hatch: the app API's `meta.request` slot is a
@@ -2102,6 +2197,622 @@ export declare function hasPromptReasoning(input: PromptReasoningInput): boolean
  * error and what the admin routes answer 400 with.
  */
 export declare function resolvePromptReasoning(input: PromptReasoningInput): PromptReasoningResolution;
+/**
+ * What a prompt's KIND admits — issue #3626.
+ *
+ * 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
+ * group declaration plus its fields, not another round of implicit
+ * discrimination: the earlier design inferred "this is a decisions config" from
+ * the presence of `questions` on a table otherwise shaped for chat, and refused
+ * the nine chat keys one by one.
+ *
+ * This module is the whole rule. `resolvePromptKind` is called by the CLI's
+ * push preflight through the vendored artifact, by `createAppPrompt`,
+ * `createPromptConfig` and `updatePromptConfig`, so a refusal at push and a
+ * refusal at the admin route cannot disagree — the `resolvePromptReasoning`
+ * posture of #3358, for the same reason.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/**
+ * 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 declare const PROMPT_KINDS: readonly ["chat", "decisions", "agent"];
+export type PromptKind = (typeof PROMPT_KINDS)[number];
+/**
+ * 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 declare const LEGACY_FLAT_CHAT_KEYS: readonly ["systemPrompt", "userPromptTemplate", "temperature", "topP", "maxTokens", "outputFormat", "outputSchema", "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 declare const CHAT_CONFIG_KEYS: readonly ["systemPrompt", "userPromptTemplate", "temperature", "topP", "maxTokens", "outputFormat", "outputSchema", "reasoningEffort", "reasoningBudget", "strictOutput"];
+export type ChatConfigKey = (typeof CHAT_CONFIG_KEYS)[number];
+/** The settings that describe a DECISIONS request. */
+export declare const DECISIONS_CONFIG_KEYS: readonly ["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 declare const AGENT_CONFIG_KEYS: readonly ["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
+ * the two agree — so a chat key added to the surface without a home here (or
+ * the reverse) fails `cli-unit-tests` rather than being accepted under a
+ * decisions prompt.
+ */
+export declare const PROMPT_KIND_BLOCKS: Readonly<Record<PromptKind, readonly string[]>>;
+/** The question types TypeSafe's System One models answer. */
+export declare const DECISIONS_QUESTION_TYPES: readonly ["choice", "score", "noul"];
+export type DecisionsQuestionType = (typeof DECISIONS_QUESTION_TYPES)[number];
+/**
+ * #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 declare const DECISIONS_CRITERIA_SOURCES: readonly ["static", "dynamic"];
+export type DecisionsCriteriaSource = (typeof DECISIONS_CRITERIA_SOURCES)[number];
+/**
+ * #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 declare const PROMPT_CRITERIA_INVALID = "PROMPT_CRITERIA_INVALID";
+/**
+ * The prompt's kind, normalized.
+ *
+ * Every reader goes through this: rows created before #3626 carry no `kind`
+ * attribute at all, and an absent one is `chat` everywhere — the detail route,
+ * pull, diff, execution and codegen.
+ */
+export declare function promptKindOf(prompt: unknown): PromptKind;
+/** The config values the rule reads — the wire spelling, not the TOML one. */
+export interface PromptKindConfigInput {
+    systemPrompt?: unknown;
+    userPromptTemplate?: unknown;
+    temperature?: unknown;
+    topP?: unknown;
+    maxTokens?: unknown;
+    outputFormat?: unknown;
+    outputSchema?: unknown;
+    reasoningEffort?: unknown;
+    reasoningBudget?: unknown;
+    /** #3801 — a chat key; the agent and decisions arms refuse it. */
+    strictOutput?: unknown;
+    questions?: unknown;
+}
+export interface PromptKindInput {
+    /** `[prompt].kind`. `null`, `undefined` and `""` are unset, meaning `chat`. */
+    kind?: unknown;
+    provider?: unknown;
+    model?: unknown;
+    /**
+     * The EFFECTIVE config: the payload value where the request carries one, the
+     * stored value otherwise. `outputSchema` here is the CONFIG's own field —
+     * never the prompt-level schema, which is legal on either kind (§3, SO3626-003).
+     */
+    config: PromptKindConfigInput;
+}
+export type PromptKindResolution = {
+    ok: true;
+    kind: "chat";
+} | {
+    ok: true;
+    kind: "decisions";
+    questions: Record<string, unknown>;
+} | {
+    ok: true;
+    kind: "agent";
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * The one rule: does this (kind, provider, config) triple describe something
+ * the platform can run?
+ *
+ * `{ ok: true, kind: "chat" }` is today's behavior byte for byte. The decisions
+ * arm returns the NORMALIZED questions so the caller stores one spelling
+ * whichever transport the author used.
+ */
+export declare function resolvePromptKind(input: PromptKindInput): PromptKindResolution;
+export type DecisionsRunQuestionsResolution = {
+    ok: true;
+    questions: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * #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 declare function resolveDecisionsRunQuestions(questions: Record<string, unknown>, runCriteria: unknown): DecisionsRunQuestionsResolution;
+/** What the hoist did to one `[[configs]]` entry. */
+export interface DeprecatedChatKeyHoist {
+    /** A COPY of the entry with the flat chat keys moved under `chat`. */
+    entry: Record<string, unknown>;
+    /** The flat keys that were moved, sorted — what the warning names. */
+    moved: string[];
+    /** Keys set BOTH flat and under `[configs.chat]`; the caller refuses these. */
+    conflicts: string[];
+}
+/**
+ * Move the deprecated flat chat keys of one `[[configs]]` entry under `chat`
+ * — #3626 §4, the blob-bucket `accessPolicy` precedent made reusable.
+ *
+ * Push keeps accepting the nine keys flat so no existing file breaks, and pull
+ * rewrites them, so one pull-then-push migrates a file. A key present in BOTH
+ * spellings is not merged: the grouped value is left standing and the key is
+ * reported in `conflicts`, which the caller turns into a refusal naming the
+ * entry. Nothing else in the entry is touched — `providerConfig` is
+ * provider-keyed rather than chat-keyed (D3626-002) and `questions` has no flat
+ * spelling at all (SO3626-013).
+ */
+export declare function hoistDeprecatedChatKeys(entry: unknown): DeprecatedChatKeyHoist;
+/**
+ * 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 declare const PROMPT_STRICT_OUTPUT_CODES: readonly ["PROMPT_STRICT_OUTPUT_INVALID", "PROMPT_STRICT_OUTPUT_SCHEMA_CONFLICT", "PROMPT_STRICT_OUTPUT_PROVIDER_UNSUPPORTED", "PROMPT_STRICT_OUTPUT_FORMAT_CONFLICT", "PROMPT_STRICT_OUTPUT_SCHEMA_MISSING"];
+export type PromptStrictOutputErrorCode = (typeof PROMPT_STRICT_OUTPUT_CODES)[number];
+/**
+ * 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 declare 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 declare const STRICT_OUTPUT_SCHEMA_NAME = "output";
+export interface PromptStrictOutputInput {
+    provider?: unknown;
+    /** `[configs.chat].strictOutput` as authored or stored. */
+    strictOutput?: unknown;
+    outputFormat?: unknown;
+    /** The CONFIG's own `outputSchema` — the one strict output never sends. */
+    configOutputSchema?: unknown;
+    /** `[prompt].outputSchema` — the one it does. */
+    promptOutputSchema?: unknown;
+    /** The config's effective status; absent is `active`. */
+    status?: unknown;
+}
+export type PromptStrictOutputResolution = {
+    ok: true;
+    strict: boolean;
+} | {
+    ok: false;
+    code: PromptStrictOutputErrorCode;
+    error: string;
+};
+/** Does this config opt in? Only a literal `true` does. */
+export declare function isStrictOutput(value: unknown): boolean;
+/**
+ * The schema strict output sends, from a stored or authored
+ * `[prompt].outputSchema`: a JSON object (or its text), else `null`.
+ */
+export declare function strictOutputSchemaOf(value: unknown): Record<string, unknown> | null;
+/**
+ * Is this (provider, strictOutput, outputFormat, schemas, status) a config the
+ * platform can run as strict — or not strict at all?
+ */
+export declare function resolvePromptStrictOutput(input: PromptStrictOutputInput): PromptStrictOutputResolution;
+/**
+ * What an agent prompt may declare — issue #3798 (project `agents`, §D1).
+ *
+ * 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.
+ *
+ * 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/`.
+ */
+/** The stable codes every agent agentRefusal this project adds carries. */
+export declare const AGENT_ERROR_CODES: readonly ["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", "AGENT_SCHEMA_NOT_TRANSLATABLE", "AGENT_MODEL_UNKNOWN", "AGENT_MODEL_CAPABILITY_MISSING", "AGENT_MODEL_CAPABILITIES_UNAVAILABLE", "AGENT_ROUND_NOT_AGENT", "AGENT_ROUND_INPUT_INVALID", "AGENT_TOOL_UNKNOWN", "AGENT_TOOL_ARGUMENTS_INVALID", "AGENT_ROUND_TRUNCATED", "AGENT_ROUND_EMPTY"];
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
+/** One agentRefusal: the code a client branches on, and the sentence a person reads. */
+export interface AgentRefusal {
+    code: AgentErrorCode;
+    message: string;
+}
+/**
+ * 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).
+ */
+export declare const AGENT_LIMITS: {
+    readonly maxSteps: 25;
+    readonly waitLimitSeconds: 604800;
+    readonly tools: 64;
+    readonly 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 declare const AGENT_NAME: RegExp;
+export declare const AGENT_ANSWERED_BY: readonly ["initiator", "participants"];
+export declare const AGENT_TOOL_INVOKE: readonly ["request", "task"];
+export declare const AGENT_TOOL_HISTORY_SCOPES: readonly ["session", "turn"];
+export type AgentAnsweredBy = (typeof AGENT_ANSWERED_BY)[number];
+export type AgentToolInvoke = (typeof AGENT_TOOL_INVOKE)[number];
+export type AgentToolHistoryScope = (typeof AGENT_TOOL_HISTORY_SCOPES)[number];
+/** A JSON Schema object, as the declaration holds one. */
+export type AgentSchema = Record<string, unknown>;
+/** One `[[prompt.agent.tools]]` entry, as authored. */
+export interface AgentToolDeclaration {
+    name: string;
+    description: string;
+    /** A server tool: the function whose schemas are the tool's. */
+    function?: string;
+    invoke?: AgentToolInvoke;
+    /** A client tool: answered by a member's client, schemas in the TOML. */
+    runs?: "client";
+    inputSchema?: AgentSchema;
+    outputSchema?: AgentSchema;
+    approval?: boolean;
+    statusText?: string;
+    historyScope?: AgentToolHistoryScope;
+}
+/** One `[[prompt.agent.events]]` entry. */
+export interface AgentEventDeclaration {
+    name: string;
+    schema: AgentSchema;
+}
+/** `[prompt.agent]` as authored: every key optional. */
+export interface AgentDeclaration {
+    answeredBy?: AgentAnsweredBy;
+    maxSteps?: number;
+    waitLimitSeconds?: number;
+    turnContext?: {
+        schema: AgentSchema;
+        function?: string;
+    };
+    history?: {
+        function?: string;
+        maxHistoryChars?: number;
+    };
+    tools?: AgentToolDeclaration[];
+    events?: AgentEventDeclaration[];
+}
+/** A tool with its defaults applied. */
+export type NormalizedAgentTool = AgentToolDeclaration & {
+    approval: boolean;
+    historyScope: AgentToolHistoryScope;
+};
+/** The declaration with every default applied — what readers consume. */
+export interface NormalizedAgentDeclaration {
+    answeredBy: AgentAnsweredBy;
+    maxSteps: number;
+    waitLimitSeconds: number;
+    turnContext: {
+        schema: AgentSchema;
+        function?: string;
+    } | null;
+    history: {
+        function?: string;
+        maxHistoryChars?: number;
+    } | null;
+    tools: NormalizedAgentTool[];
+    events: AgentEventDeclaration[];
+}
+/**
+ * What the caller knows about each function a declaration may name: `null` (or
+ * absence from the map) is a function this app does not have. The CLI resolves
+ * it from the live listing overlaid by the function files this push selects;
+ * the admin routes from an app-scoped lookup.
+ */
+export type AgentFunctionFacts = Readonly<Record<string, AgentFunctionFact | null>>;
+/**
+ * What one function declares. `hasInputSchema`/`hasOutputSchema` are #3798's
+ * presence facts; `inputSchema`/`outputSchema` are #3799's — the stored value,
+ * a JSON string or an object, which `agentSchemaTranslationRefusals` translates
+ * for each of the agent's providers. Both schema fields are OPTIONAL, so a
+ * caller that only needs the presence half is unchanged (principle 5).
+ */
+export interface AgentFunctionFact {
+    hasInputSchema: boolean;
+    hasOutputSchema: boolean;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}
+export interface AgentDeclarationInput {
+    /** `[prompt].kind`; unset means `chat`. */
+    kind?: unknown;
+    /** `[prompt.agent]`: a table, a JSON string encoding one, or unset. */
+    agent?: unknown;
+    /** `[prompt].outputSchema` — refused on an agent. */
+    outputSchema?: unknown;
+    /**
+     * The function facts. Omitted means "not known here": the file-decidable
+     * half runs alone (the CLI's `config diff` collector has no app state).
+     */
+    functions?: AgentFunctionFacts;
+}
+export type AgentDeclarationResolution = {
+    ok: true;
+    declaration: AgentDeclaration | null;
+} | {
+    ok: false;
+    refusals: AgentRefusal[];
+};
+/**
+ * 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 declare const AGENT_BLOCK_LABEL = "[prompt.agent]";
+/**
+ * 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 declare function parseAgentDeclarationBlock(agent: unknown): Record<string, unknown> | undefined;
+export declare function agentDeclarationFunctionKeys(agent: unknown): string[];
+/**
+ * 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 declare function resolveAgentDeclaration(input: AgentDeclarationInput): AgentDeclarationResolution;
+/**
+ * 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 declare function agentNotRunnableRefusal(promptKey?: string): AgentRefusal;
+/**
+ * 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 declare function agentRoundNotAgentRefusal(promptKey: string): AgentRefusal;
+/**
+ * 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 declare function agentTestCaseRefusal(promptKey: string, role: "subject" | "evaluator"): AgentRefusal;
+/**
+ * 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 declare function normalizeAgentDeclaration(declaration: AgentDeclaration | null | undefined): NormalizedAgentDeclaration;
+/**
+ * Meaning-preserving schema translation, per provider — issue #3799
+ * (project `agents`, §D6, intent criterion 2).
+ *
+ * A tool or event schema reaches a provider only through a translation that
+ * preserves its meaning; anything else is refused at push, naming the path, the
+ * keyword and the provider. The lossy `sanitizeSchemaForGemini` clean-up
+ * (`src/services/block-executor.ts`) is NOT reused here: it drops unions and
+ * references and rewrites a free-form object as a string, all of which change
+ * what the model may produce. It stays where it is, for chat output schemas
+ * (the project's non-goal: chat is unchanged).
+ *
+ * ## What "lossless" means (spec §3)
+ *
+ * Every keyword is either
+ *   (a) passed to the provider unchanged with the same meaning,
+ *   (b) rewritten into a provider spelling that admits exactly the same set of
+ *       values, or
+ *   (c) dropped because dropping it changes neither what the model is told it
+ *       may produce nor what the platform enforces on what it produced.
+ *
+ * Anything else is refused. The only silent drops are the annotations with no
+ * value meaning (`$schema`, `$id`, `$comment`) and `additionalProperties`
+ * (DSO-3799-001): Gemini's function `Schema` has no spelling for a closed
+ * object at all, the platform validates every tool argument against the
+ * ORIGINAL, untranslated schema (#3800, criterion 3) so an extra key becomes
+ * the structured error the model sees, and a model following `properties` is
+ * never told it may add keys. Refusing it instead would put the platform's own
+ * closed-object marker — `additionalProperties: false` is how
+ * `src/workflows/schema-descriptor.ts` spells a closed object — outside
+ * Gemini's reach.
+ *
+ * The TRANSLATED schema is what the provider is sent; the ORIGINAL is what the
+ * platform keeps and validates against. Neither function here mutates its
+ * input.
+ *
+ * ## The two providers
+ *
+ * - `openrouter` forwards `tools[].function.parameters` as JSON Schema to the
+ *   model's own upstream. The platform cannot know each upstream's dialect, so
+ *   the only honest translation is identity — nothing is refused.
+ * - `gemini` takes the OpenAPI 3.0 `Schema` object that
+ *   `functionDeclarations[].parameters` accepts: one `type` from a closed list,
+ *   `nullable`, `format` from a documented list, `enum` of strings,
+ *   `properties`/`required`, `items`, the numeric and length bounds,
+ *   `propertyOrdering`, `example`, and `anyOf`. It has no `$ref`, `oneOf`,
+ *   `allOf`, `not`, `const`, `additionalProperties`, type arrays or
+ *   `type: "null"`; an object needs non-empty `properties` and an array needs
+ *   `items`. Lowercase type names are accepted (the existing `responseSchema`
+ *   path already sends them).
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`, and
+ * vendored into the CLI artifact after `agent-declaration.ts` so the push
+ * preflight and the admin routes refuse exactly the same schemas.
+ */
+/** The providers a prompt config may name. */
+export type SchemaProvider = "openrouter" | "gemini";
+/** One untranslatable keyword: where it is, what it is, and why it cannot go. */
+export interface SchemaTranslationRefusal {
+    /**
+     * The dotted path from the schema root, with indexes — `properties.amount`,
+     * `items.properties.kind`, `anyOf[1].properties.x`. `""` is the root itself.
+     */
+    path: string;
+    /** The keyword that cannot be carried, as the author spelled it. */
+    keyword: string;
+    /** What the provider cannot express, and what to write instead. */
+    reason: string;
+}
+export type SchemaTranslation = {
+    ok: true;
+    schema: Record<string, unknown>;
+} | {
+    ok: false;
+    refusals: SchemaTranslationRefusal[];
+};
+/** What a message calls the root. */
+export declare function schemaPathLabel(path: string): string;
+/**
+ * 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 declare function translateSchemaForProvider(schema: unknown, provider: SchemaProvider | string): SchemaTranslation;
+/** One non-archived config of the prompt: which provider, under which name. */
+export interface AgentSchemaConfigFact {
+    configName: string;
+    provider: string;
+    /** The per-version status; `archived` is skipped (spec §3). */
+    status?: string | null;
+}
+export interface AgentSchemaTranslationInput {
+    /** `[prompt.agent]` as authored: a table, one JSON string encoding one, or unset. */
+    declaration: unknown;
+    /**
+     * What this app holds for each function the declaration names, including the
+     * schemas a server tool's two schemas come from. Omitted means "not known
+     * here" — server tools are then not checked, and the caller that does know
+     * checks them.
+     */
+    functions?: AgentFunctionFacts;
+    /** Every config of the prompt. Archived ones are skipped. */
+    configs: ReadonlyArray<AgentSchemaConfigFact>;
+}
+/**
+ * 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 declare function agentSchemaTranslationRefusals(input: AgentSchemaTranslationInput): AgentRefusal[];
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;
 export declare const WEBHOOK_SURFACE: ConfigObjectSurface;