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

package/dist/src/commands/sync.js

@@ -3,6 +3,7 @@ import { join, basename } from "path";
 import { createHash } from "crypto";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefError, SchemaBreaksOpsError, SchemaHasUncheckableOpsError, TomlParseError, OpsExistError, } from "../lib/api-client.js";
+import { retryOnStoragePending } from "../lib/storage-pending-retry.js";
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
 import { canEmitNative } from "../lib/toml-native-form.js";
 // #1446's `type: "json"` emission rule, shared with `serializeFunction` since
@@ -34,10 +35,18 @@ import { WORKFLOW_MODEL_DEFAULTS } from "../lib/workflow-defaults.js";
 // #2644 — the one definition per configuration object, vendored from the server.
 import { BLOB_BUCKET_TABLE, COLLECTION_TYPE_CONFIG_TABLE, CRON_TRIGGER_TABLE, DATABASE_TYPE_TABLE, EMAIL_TEMPLATE_TABLE, GROUP_TYPE_CONFIG_TABLE, INTEGRATION_TABLE, METADATA_CATEGORY_CONFIG_TABLE, PROMPT_CONFIG_TABLE, PROMPT_TABLE, RULE_SET_TABLE, SERVER_FUNCTION_TABLE, TEST_CASE_SURFACE, TEST_CASE_TABLE, WEBHOOK_TABLE, WORKFLOW_TABLE, configDeclaredTypeErrors, fieldServerDefault, findMisshapenTables, findUnknownDocumentKeys, findUnknownGroupedTomlKeys, findUnknownServerKeys, findUnknownTomlKeys, misshapenTableMessage, retiredConfigKey, spellsDecimalNumber, unrecognizedPullKeysMessage, unrecognizedPushKeysMessage, unrecognizedPushTablesMessage, warnUnrecognizedServerKeys, } from "../lib/config-surface.js";
 import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, tomlOwned, } from "../lib/config-payload.js";
-import { CONFIG_SURFACES, isEmptyForEmit, } from "../lib/generated-config-surfaces.js";
+import { CONFIG_SURFACES, isEmptyForEmit, tomlGroupsOf, } from "../lib/generated-config-surfaces.js";
 // #3626 — the prompt KIND rule, vendored with the definitions so the CLI's
 // preflight refuses exactly what the admin routes refuse.
 import { hoistDeprecatedChatKeys, promptKindOf, resolvePromptKind, } from "../lib/generated-config-surfaces.js";
+// #3798 — the `[prompt.agent]` declaration rule, vendored the same way.
+import { agentDeclarationFunctionKeys, agentTestCaseRefusal, resolveAgentDeclaration, } from "../lib/generated-config-surfaces.js";
+// #3799 — the meaning-preserving schema translation, vendored the same way, so
+// the preflight refuses exactly the schemas the admin routes refuse.
+import { agentSchemaTranslationRefusals } from "../lib/generated-config-surfaces.js";
+// #3801 — the strict-output rule, vendored the same way, so the preflight
+// refuses exactly the strict configs the admin routes refuse.
+import { resolvePromptStrictOutput } from "../lib/generated-config-surfaces.js";
 // #3179 — the function's two halves: the header payloads and the envelope
 // `config push` sends, and the bytes `config pull` writes back.
 import { applyFunctionPull, buildFunctionConfigPush, createDocumentSchemaDropWarner, documentSchemaRetentionFailure, buildFunctionCreatePayload, buildFunctionUpdatePayload, functionDiffEntity, functionTomlIgnoredKeyWarnings, functionTomlPreflightErrors, planDocumentSchemaPull, planFunctionPull, serializeFunction, } from "../lib/function-sync.js";
@@ -1668,22 +1677,20 @@ export function buildBlobBucketUpdatePayload(bucket) {
  */
 const PROMPT_CONFIG_DEFAULT_STATUS = fieldServerDefault(PROMPT_CONFIG_TABLE, "status");
 /**
- * The status a freshly CREATED prompt config still owes the file, or null
- * (#3201).
+ * #3201's post-create status patch is RETIRED — #3799 (DSO-3799-005).
  *
- * `status` is update-only — `POST /prompts` and `POST /prompts/:id/configs`
- * both assign `active` whatever the body says — so an authored
- * `status = "archived"` was silently dropped on every create path: a pulled
- * tree pushed from a clean clone into a fresh environment brought every
- * retired config back into service. Read through the push payload builder, so
- * a file that omits the key asks for the default and needs no request.
+ * `status` was update-only, so `POST /prompts` and `POST /prompts/:id/configs`
+ * both assigned `active` whatever the body said, and an authored
+ * `status = "archived"` needed a follow-up PATCH ordered after the activation of
+ * the entry the file marks live. Both create paths honor the key now
+ * (`writableOn: BOTH`, validated by one rule on all three paths), so the entry
+ * lands retired on its own create: the same end state, two fewer calls per
+ * retired config, and no window in which the server holds a status the file
+ * never asked for. That window is what made a pulled tree unpushable into a
+ * fresh environment once an agent's schemas are checked against each
+ * non-archived config's provider — the check fired on the transient active
+ * state.
  */
-export function createdConfigStatusPatch(tomlConfig) {
-    const { status } = buildPromptConfigPayload(tomlConfig, { mode: "update" });
-    return typeof status === "string" && status !== PROMPT_CONFIG_DEFAULT_STATUS
-        ? { status }
-        : null;
-}
 /**
  * Which `[[configs]]` entry a prompt file marks as live (issue #2645).
  *
@@ -1791,6 +1798,11 @@ export function serializePrompt(prompt, logger) {
             ...projectRecordToToml(PROMPT_TABLE, prompt, {
                 inputSchema: jsonField(promptSubject),
                 outputSchema: jsonField(promptSubject),
+                // #3798 — the agent declaration goes out as `[prompt.agent]` tables
+                // (JSON-string fallback for a `null` TOML cannot spell), exactly as
+                // stored: the server keeps it as authored, so what pull writes is
+                // what the author pushed.
+                agent: jsonField(promptSubject),
             }),
         },
         configs: (prompt.configs || []).map((config) => ({
@@ -1819,7 +1831,10 @@ export function serializePrompt(prompt, logger) {
                 // `config pull` and `config diff` down with it. The JSON-string
                 // fallback keeps the declaration whole either way.
                 questions: jsonField(`Prompt '${prompt?.promptKey}' config '${config?.configName}'`),
-            }),
+            }, 
+            // #3798 — the model settings chat and agent share are written under the
+            // block the prompt's kind names: `[configs.agent]` for an agent.
+            { tomlGroup: promptKindOf(prompt) }),
             // #2645 — the live config has to be identifiable in the repo. Emitted
             // only on the active entry (`undefined` elsewhere so the key is omitted),
             // which keeps the marker unambiguous by construction.
@@ -1891,6 +1906,16 @@ export function buildPromptPushPayload(key, tomlData, { mode = "update" } = {})
                 // dropped and leaving a stale rule live. On create it is omitted so
                 // the push-adopt path (#1006) can still reach the server's 409.
                 accessRule: (value) => (create ? value : (value ?? null)),
+                // #3798 — the agent declaration, as authored: the server stores it
+                // unchanged, so the value sent is the value pull writes back. On
+                // update a deleted block CLEARS it — for an agent only: a chat or
+                // decisions file carries no block to delete, and omitting the key
+                // keeps its body what it was before this field existed.
+                agent: (value) => create || value !== undefined
+                    ? value
+                    : promptKindOf(prompt) === "agent"
+                        ? null
+                        : undefined,
                 // #3626, CR3626-004 — the kind NORMALIZED, exactly as the resolver
                 // that validates it reads it. `kind = " chat "` and `kind = ""` both
                 // mean `chat` to `resolvePromptKind`, so the server stores `chat` and
@@ -1914,6 +1939,10 @@ export function buildPromptPushPayload(key, tomlData, { mode = "update" } = {})
     };
     if (create)
         payload.promptKey = key;
+    // #3798 — a prompt that declares no agent block sends no `agent` key at all,
+    // so a chat or decisions body is byte for byte what it was.
+    if (payload.agent === undefined)
+        delete payload.agent;
     return payload;
 }
 /**
@@ -1947,9 +1976,15 @@ export function buildPromptCreatePayload(key, tomlData) {
     // #3626, SO3626-001 — the placeholder is a CHAT fallback. A decisions prompt
     // has no template at all (its input is a `state` value plus its questions),
     // and injecting one would store a chat key the block rule then refuses on
-    // every later update.
-    if (promptKindOf(prompt) === "decisions") {
-        return { ...prompt, ...seed };
+    // every later update. #3798 — nor has an agent: the model sees each message
+    // as sent.
+    if (promptKindOf(prompt) !== "chat") {
+        const body = { ...prompt, ...seed };
+        for (const field of Object.keys(body)) {
+            if (body[field] === undefined)
+                delete body[field];
+        }
+        return body;
     }
     return {
         ...prompt,
@@ -1987,12 +2022,11 @@ const SEEDED_CONFIG_DEFERRED = ["outputSchema", "description"];
  * response rather than assumed, so a handler that one day honors the name
  * produces no needless PATCH.
  *
- * #3201 — the entry's `status` is deferred the OTHER way and is deliberately
- * not here. The create points the prompt's `activeConfigId` at this seeded
- * config, so retiring it in this early patch would archive the config the
- * prompt is serving from and leave it there until the marked entry is created
- * and activated — a window a failed create or activation freezes. It is
- * applied after activation instead (`createdConfigStatusPatch`).
+ * #3201 — the entry's `status` was deferred the OTHER way, to a patch after the
+ * activation, because the create pointed the prompt's `activeConfigId` at a
+ * config it had forced live. #3799 (DSO-3799-005) — the create carries the
+ * entry's `status` itself now, so there is no deferral either way and this patch
+ * is the two fields `POST /prompts` cannot express, nothing more.
  */
 export function seededOnlyPromptConfigFields(firstConfig, seededConfigName = "default") {
     const full = buildPromptConfigPayload(firstConfig || {}, { mode: "update" });
@@ -2049,6 +2083,12 @@ export function buildPromptConfigPayload(tomlConfig, { mode = "update" } = {}) {
         mode,
         values: {
             provider: (value) => (create ? value || "openrouter" : value),
+            // #3799 (DSO-3799-005) — carried on CREATE when the entry names one, and
+            // omitted otherwise, so the create body for a file that says nothing
+            // about status is what the server has always received (principle 5). On
+            // update it still sends the declared default for an absent key, which is
+            // what lets a deleted line converge (#2880 DSO-002).
+            status: (value) => create ? value : (value ?? PROMPT_CONFIG_DEFAULT_STATUS),
             model: (value) => create ? value || "google/gemini-2.0-flash-001" : value,
             description: tomlOwned,
             systemPrompt: tomlOwned,
@@ -2065,6 +2105,9 @@ export function buildPromptConfigPayload(tomlConfig, { mode = "update" } = {}) {
             // the merged config refused as "both set".
             reasoningEffort: tomlOwned,
             reasoningBudget: tomlOwned,
+            // #3801 — deleting `strictOutput = true` has to turn strict output off
+            // server-side, or the file stops describing the request that is sent.
+            strictOutput: tomlOwned,
             // #3626, SO3626-002 — the decisions declaration is TOML-owned on the
             // same terms: deleting `[configs.decisions]` has to clear `questions`
             // server-side, or the file stops describing what the model is asked.
@@ -2182,13 +2225,14 @@ export function configUnknownKeyError(filePath, tomlData, table) {
     const misplaced = trulyUnknown
         .map((key) => ({
         key,
-        group: table.fields.find((f) => f.tomlKey === key && f.tomlGroup)
-            ?.tomlGroup,
+        groups: tomlGroupsOf(table.fields.find((f) => f.tomlKey === key && f.tomlGroup) ??
+            {}),
     }))
-        .filter((entry) => !!entry.group);
-    for (const { key, group } of misplaced) {
+        .filter((entry) => entry.groups.length > 0);
+    for (const { key, groups } of misplaced) {
+        // #3798 — a key two blocks share names both; the prompt's kind picks one.
         messages.push(`${filePath}: ${prefix}[0].${key} is not a [[${prefix}]] key; ` +
-            `write it under [${prefix}.${group}]`);
+            `write it under ${groups.map((g) => `[${prefix}.${g}]`).join(" or ")}`);
     }
     const misplacedKeys = new Set(misplaced.map((m) => m.key));
     const stillUnknown = trulyUnknown.filter((k) => !misplacedKeys.has(k));
@@ -2568,6 +2612,15 @@ export async function runConfigPushPreflight(input) {
                 knownTargets =
                     treeTargets.integrations.size > 0 ? treeTargets : null;
             }
+            // #3719 — the project's document schema rides every function version,
+            // so a unique constraint on a stringset field in it refuses the push
+            // here, once, rather than deploying with seeding silently off. Bounded
+            // by the selection like the rest of this block: only a push that
+            // carries a function carries the schema.
+            const documentSchemaError = documentSchemaPreflightError(resolveDocumentSchema(configDir));
+            if (documentSchemaError) {
+                preflightValidationErrors.push(`  ${documentSchemaError}`);
+            }
             for (const file of functionFiles) {
                 const filePath = join(preflightFunctionsDir, file);
                 let tomlData;
@@ -2636,6 +2689,9 @@ export async function runConfigPushPreflight(input) {
     // single pull-then-push clears the notice. Printed even under `--dry-run`,
     // which never reaches the apply — the notice is about the FILE.
     const preflightPromptsDir = join(configDir, "prompts");
+    // #3798 — the functions an agent's references are checked against, read
+    // once and only when a selected prompt is an agent that names one.
+    let agentFunctions = null;
     if (existsSync(preflightPromptsDir)) {
         for (const file of selectFiles("prompt", preflightPromptsDir, readdirSync(preflightPromptsDir).filter((f) => f.endsWith(".toml")))) {
             const filePath = join(preflightPromptsDir, file);
@@ -2650,8 +2706,36 @@ export async function runConfigPushPreflight(input) {
             const notice = promptFlatChatKeyWarning(filePath, tomlData);
             if (notice)
                 warn(`  ${notice}`);
+            // #3798 — an agent's tool, turn-context and history functions must
+            // exist, and a tool's must declare both schemas, before anything is
+            // applied. Bounded by `--only` like the rest of this loop.
+            if (promptKindOf(tomlData?.prompt) === "agent" &&
+                agentDeclarationFunctionKeys(tomlData?.prompt?.agent).length > 0) {
+                if (!agentFunctions) {
+                    let live = null;
+                    try {
+                        live = (await client.listFunctions(resolvedAppId)).items;
+                    }
+                    catch {
+                        live = null;
+                    }
+                    agentFunctions = agentFunctionFactsForPush({
+                        configDir,
+                        pushSelection,
+                        live,
+                    });
+                }
+                for (const message of promptAgentFunctionErrors(filePath, tomlData, agentFunctions)) {
+                    preflightValidationErrors.push(`  ${message}`);
+                }
+            }
         }
     }
+    // #3798 — a test case on an agent is refused by the admin routes; say so
+    // here, before any other file is applied.
+    for (const message of promptAgentSidecarErrors(configDir)) {
+        preflightValidationErrors.push(`  ${message}`);
+    }
     // The `<key>.tests/*.toml` sidecars, which sit beside the block they
     // test rather than in a type directory of their own. Same posture,
     // reached through the registry's `test-case` surface — and through the
@@ -2691,6 +2775,41 @@ export async function runConfigPushPreflight(input) {
  * whose spelling is not the declared type. A file that does not parse is left
  * to the per-type loop that reads it, which names the parse error itself.
  */
+/**
+ * The blocks one `[[configs]]` entry carries that its prompt's kind does not
+ * name — #3798. An agent's entry may carry only `[configs.agent]`; a chat or
+ * decisions entry may not carry it. `movedFlat` are the deprecated flat chat
+ * keys the hoist moved under `chat`, named as the author wrote them.
+ *
+ * Only the blocks the other arms of `resolvePromptKind` cannot see are checked
+ * here: a decisions block on a chat entry, and chat keys on a decisions entry,
+ * stay the resolver's refusals with their #3626 wording.
+ */
+function promptEntryBlockErrors(kind, entry, movedFlat) {
+    const has = (block) => entry != null && typeof entry === "object" && entry[block] !== undefined;
+    const errors = [];
+    if (kind === "agent") {
+        if (movedFlat.length > 0) {
+            errors.push(`sets ${movedFlat.join(", ")} flat — the deprecated [configs.chat] ` +
+                'spelling — but prompt kind is "agent", so it may carry only a ' +
+                "[configs.agent] block; write them under [configs.agent]");
+        }
+        for (const block of ["chat", "decisions"]) {
+            if (!has(block))
+                continue;
+            errors.push(`carries a [configs.${block}] block, but prompt kind is "agent", so ` +
+                "it may carry only a [configs.agent] block (systemPrompt, " +
+                "temperature, topP, maxTokens, reasoningEffort, reasoningBudget)");
+        }
+        return errors;
+    }
+    if (has("agent")) {
+        errors.push(`carries a [configs.agent] block, but prompt kind is "${kind}", so it ` +
+            `may carry only a [configs.${kind}] block. An agent is its own ` +
+            'prompt: create it under a new key with kind = "agent"');
+    }
+    return errors;
+}
 /**
  * A prompt file's KIND errors — #3626, decidable from the file alone.
  *
@@ -2702,15 +2821,94 @@ export async function runConfigPushPreflight(input) {
  * the server's cannot disagree — and this one lands in the preflight, before
  * the first mutating call.
  */
+/**
+ * The `[[configs]]` entries of a prompt file as the agent rules read them —
+ * #3799: which provider each named configuration runs on, and whether the file
+ * retires it.
+ *
+ * An archived entry is skipped by the translation rule (a config the server does
+ * not run cannot make the declaration untranslatable), which is what lets a
+ * pulled tree keep a retired config on a provider the current schemas could not
+ * reach. `status` is read through the same default the surface declares, so an
+ * entry that omits the key is live.
+ */
+function promptFileConfigFacts(entries) {
+    return (entries || []).map((entry, index) => ({
+        configName: String(entry?.name ?? `configs[${index}]`),
+        provider: String(entry?.provider ?? ""),
+        status: String(entry?.status ?? PROMPT_CONFIG_DEFAULT_STATUS),
+    }));
+}
 export function promptKindFileErrors(filePath, tomlData) {
     const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
     const errors = [];
+    const fileKind = promptKindOf(tomlData?.prompt);
+    // #3798 — the `[prompt.agent]` declaration's file-decidable half: its shape,
+    // and `[prompt].outputSchema` on an agent. The function half needs app state
+    // and runs in the push preflight (`promptAgentFunctionErrors`).
+    const declaration = resolveAgentDeclaration({
+        kind: tomlData?.prompt?.kind,
+        agent: tomlData?.prompt?.agent,
+        outputSchema: tomlData?.prompt?.outputSchema,
+    });
+    if (declaration.ok === false) {
+        for (const refusal of declaration.refusals) {
+            errors.push(`${filePath}: ${refusal.message}`);
+        }
+    }
+    else if (fileKind === "agent") {
+        // #3799 — the schemas a CLIENT tool and an event declare are in the file,
+        // so whether each provider the file configures can carry them without
+        // losing meaning is file-decidable too: `config diff` reports the same row
+        // as `config push`. A server tool's schemas are its FUNCTION's and need app
+        // state, so they are checked in the push preflight
+        // (`promptAgentFunctionErrors`). Only after the shape refusals above, so a
+        // malformed declaration is not also reported as untranslatable.
+        for (const refusal of agentSchemaTranslationRefusals({
+            declaration: tomlData?.prompt?.agent,
+            configs: promptFileConfigFacts(entries),
+        })) {
+            errors.push(`${filePath}: ${refusal.message}`);
+        }
+    }
     for (const [index, entry] of entries.entries()) {
         const hoisted = hoistDeprecatedChatKeys(entry);
         for (const key of hoisted.conflicts) {
             errors.push(`${filePath}: configs[${index}].${key} is set both flat and under ` +
                 `[configs.chat]; keep the [configs.chat] spelling`);
         }
+        // #3798 — the block rule for three kinds, stated per entry: an entry may
+        // carry only the block its prompt's kind names. An agent's `[configs.agent]`
+        // holds keys chat also holds, so a stray block would otherwise be read (or
+        // ignored) in silence by the payload builder.
+        const blockErrors = promptEntryBlockErrors(fileKind, entry, hoisted.moved).map((message) => `${filePath}: configs[${index}] ${message}`);
+        if (blockErrors.length > 0) {
+            errors.push(...blockErrors);
+            continue;
+        }
+        if (fileKind === "agent") {
+            const agent = hoisted.entry.agent ?? {};
+            const resolution = resolvePromptKind({
+                kind: "agent",
+                provider: hoisted.entry.provider,
+                model: hoisted.entry.model,
+                config: {
+                    systemPrompt: agent.systemPrompt,
+                    temperature: agent.temperature,
+                    topP: agent.topP,
+                    maxTokens: agent.maxTokens,
+                    reasoningEffort: agent.reasoningEffort,
+                    reasoningBudget: agent.reasoningBudget,
+                    // #3801 — a chat key: named, so the refusal says which key an agent
+                    // does not take (§D1: an agent has no output schema).
+                    strictOutput: agent.strictOutput,
+                },
+            });
+            if (resolution.ok === false) {
+                errors.push(`${filePath}: configs[${index}] — ${resolution.error}`);
+            }
+            continue;
+        }
         const chat = hoisted.entry.chat ?? {};
         const decisions = hoisted.entry.decisions ?? {};
         // #3626 — the FIRST entry of a chat prompt carries the create seed's
@@ -2726,7 +2924,7 @@ export function promptKindFileErrors(filePath, tomlData) {
         // `userPromptTemplate`, so reading absence more narrowly than the builder
         // does refused the file this CLI had just written, for a value the create
         // would have replaced with the placeholder anyway.
-        const seedsTemplate = index === 0 && promptKindOf(tomlData?.prompt) !== "decisions";
+        const seedsTemplate = index === 0 && fileKind === "chat";
         const userPromptTemplate = seedsTemplate
             ? chat.userPromptTemplate || "{{ input }}"
             : chat.userPromptTemplate;
@@ -2744,12 +2942,200 @@ export function promptKindFileErrors(filePath, tomlData) {
                 outputSchema: chat.outputSchema,
                 reasoningEffort: chat.reasoningEffort,
                 reasoningBudget: chat.reasoningBudget,
+                strictOutput: chat.strictOutput,
                 questions: decisions.questions,
             },
         });
         if (resolution.ok === false) {
             errors.push(`${filePath}: configs[${index}] — ${resolution.error}`);
+            continue;
+        }
+        // #3801 — strict output, file-decidable: the entry's own keys, the file's
+        // `[prompt].outputSchema` and the entry's status (an archived entry is not
+        // held to the prompt schema, DSO-3801-002). The route runs the same rule
+        // against what the server holds.
+        if (resolution.kind === "chat") {
+            const strict = resolvePromptStrictOutput({
+                provider: hoisted.entry.provider,
+                strictOutput: chat.strictOutput,
+                outputFormat: chat.outputFormat,
+                configOutputSchema: chat.outputSchema,
+                promptOutputSchema: tomlData?.prompt?.outputSchema,
+                status: hoisted.entry.status ?? PROMPT_CONFIG_DEFAULT_STATUS,
+            });
+            if (strict.ok === false) {
+                errors.push(`${filePath}: configs[${index}] — ${strict.error} (${strict.code})`);
+            }
+        }
+    }
+    return errors;
+}
+/** A schema slot counts as declared when it holds anything but nothing. */
+function declaresSchema(value) {
+    if (value === undefined || value === null)
+        return false;
+    return !(typeof value === "string" && value.trim() === "");
+}
+/**
+ * The functions an agent's references are checked against at push — #3798,
+ * DSO-3798-002.
+ *
+ * `config push` applies prompts, then (for agents) the server functions leg,
+ * so a reference may be satisfied by a function that is live already or by one
+ * this push creates. What the push BELIEVES is therefore the live listing
+ * overlaid by the function files this push SELECTS (`--only`, every file when
+ * unscoped): a selected file's schemas are what the server will hold after the
+ * push, so it wins over the live row. An UNSELECTED file is not read at all —
+ * its edits will not be applied, and a function only it declares will not
+ * exist afterwards.
+ *
+ * `live` is `null` when the listing could not be fetched: the selected files
+ * still count, and `liveListed` lets the refusal say why every other reference
+ * could not be confirmed. A live row that is archived is a tombstone, not a
+ * function; an inactive one is accepted (the turn engine re-checks
+ * availability on every call).
+ */
+export function agentFunctionFactsForPush(input) {
+    const facts = {};
+    for (const row of input.live ?? []) {
+        const key = String(row?.functionKey ?? "");
+        if (!key || row?.status === "archived")
+            continue;
+        facts[key] = {
+            hasInputSchema: declaresSchema(row.inputSchema),
+            hasOutputSchema: declaresSchema(row.outputSchema),
+            // #3799 — the schemas themselves, as stored (a JSON string from the API,
+            // an object from a tree file), so a server tool's two schemas can be
+            // translated for each of the agent's providers.
+            inputSchema: row.inputSchema,
+            outputSchema: row.outputSchema,
+        };
+    }
+    const functionsDir = join(input.configDir, "functions");
+    if (existsSync(functionsDir)) {
+        for (const file of filterFilesBySelection(input.pushSelection, "function", functionsDir, readdirSync(functionsDir).filter(isFunctionDeclarationFile))) {
+            let table;
+            try {
+                table = parseTomlFile(join(functionsDir, file))?.function ?? {};
+            }
+            catch {
+                // Reported by the function preflight with its own message.
+                continue;
+            }
+            const key = table.key || basename(file, ".toml");
+            facts[key] = {
+                hasInputSchema: declaresSchema(table.inputSchema),
+                hasOutputSchema: declaresSchema(table.outputSchema),
+                // #3799 — a SELECTED file's schemas are what the server will hold after
+                // this push, so they are what the translation is checked against.
+                inputSchema: table.inputSchema,
+                outputSchema: table.outputSchema,
+            };
+        }
+    }
+    return { facts, liveListed: input.live !== null };
+}
+/**
+ * The function half of an agent's declaration — #3798: every tool, turn
+ * context and history function that the functions this push believes
+ * (`agentFunctionFactsForPush`) do not have, and every tool function lacking an
+ * input or output schema. The same `resolveAgentDeclaration` the admin routes
+ * run; only its function refusals are reported here, because the collector
+ * (`promptKindFileErrors`) already reported the file-decidable ones.
+ */
+export function promptAgentFunctionErrors(filePath, tomlData, known) {
+    if (promptKindOf(tomlData?.prompt) !== "agent")
+        return [];
+    const result = resolveAgentDeclaration({
+        kind: "agent",
+        agent: tomlData?.prompt?.agent,
+        functions: known.facts,
+    });
+    const errors = result.ok === false
+        ? result.refusals
+            .filter((refusal) => refusal.code === "AGENT_TOOL_FUNCTION_MISSING" ||
+            refusal.code === "AGENT_TOOL_FUNCTION_SCHEMA_MISSING")
+            .map((refusal) => refusal.code === "AGENT_TOOL_FUNCTION_MISSING" && !known.liveListed
+            ? `${filePath}: ${refusal.message} (the app's live functions could ` +
+                "not be listed, so only the function files this push applies were " +
+                "checked)"
+            : `${filePath}: ${refusal.message}`)
+        : [];
+    // #3799 — a SERVER tool's schemas are its function's, so translating them
+    // needs the facts this push believes (the live listing overlaid by the
+    // function files it selects, DSO-3798-002). The client-tool and event half is
+    // file-decidable and reported by `promptKindFileErrors`, which `config diff`
+    // runs too; passing the facts here means only the server-tool refusals are
+    // new, because that collector already saw the rest.
+    const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
+    const configs = promptFileConfigFacts(entries);
+    const fileDecidable = new Set(agentSchemaTranslationRefusals({
+        declaration: tomlData?.prompt?.agent,
+        configs,
+    }).map((refusal) => refusal.message));
+    for (const refusal of agentSchemaTranslationRefusals({
+        declaration: tomlData?.prompt?.agent,
+        functions: known.facts,
+        configs,
+    })) {
+        if (fileDecidable.has(refusal.message))
+            continue;
+        errors.push(`${filePath}: ${refusal.message}`);
+    }
+    return errors;
+}
+/**
+ * The order `config push` applies prompt files in — #3798. An agent names
+ * server functions that must exist when it is created, and the push applies
+ * prompts before functions, so agent files go AFTER the server-functions leg;
+ * every other file keeps its place. A file that does not parse stays first, so
+ * the leg reports it where it always has.
+ */
+export function partitionPromptFilesForPush(promptsDir, files) {
+    const beforeFunctions = [];
+    const afterFunctions = [];
+    for (const file of files) {
+        let kind = "chat";
+        try {
+            kind = promptKindOf(parseTomlFile(join(promptsDir, file))?.prompt);
+        }
+        catch {
+            beforeFunctions.push(file);
+            continue;
+        }
+        (kind === "agent" ? afterFunctions : beforeFunctions).push(file);
+    }
+    return { beforeFunctions, afterFunctions };
+}
+/**
+ * Every `prompts/<key>.tests/*.toml` sidecar whose prompt is an agent — #3798
+ * (§D1: prompt test cases are refused for the kind in v1). The admin test-case
+ * routes refuse the same case with `AGENT_TEST_CASE_NOT_SUPPORTED`; this says
+ * so before anything is applied.
+ */
+export function promptAgentSidecarErrors(configDir) {
+    const promptsDir = join(configDir, "prompts");
+    const errors = [];
+    for (const filePath of testCaseTomlFiles(configDir)) {
+        const parent = basename(join(filePath, ".."));
+        if (!filePath.startsWith(promptsDir) || !parent.endsWith(".tests"))
+            continue;
+        const key = parent.slice(0, -".tests".length);
+        const owner = join(promptsDir, `${key}.toml`);
+        if (!existsSync(owner))
+            continue;
+        let tomlData;
+        try {
+            tomlData = parseTomlFile(owner);
+        }
+        catch {
+            continue;
         }
+        if (promptKindOf(tomlData?.prompt) !== "agent")
+            continue;
+        const promptKey = tomlData?.prompt?.key || key;
+        errors.push(`${filePath.slice(configDir.length + 1)}: ` +
+            agentTestCaseRefusal(promptKey, "subject").message);
     }
     return errors;
 }
@@ -3059,6 +3445,17 @@ export function workflowPushSendsUpdate(configDir, key, parsedWorkflowToml, sync
  *
  * Returns `null` when the name is present.
  */
+/**
+ * The preflight error a project's document schema contributes, or `null` —
+ * #3719.
+ *
+ * Only a `refusal` counts: a unique constraint on a stringset field, which no
+ * writer can key consistently, so the push stops before any mutation. Every
+ * other unusable-schema case stays the apply loop's warning (D3455-004).
+ */
+export function documentSchemaPreflightError(resolution) {
+    return resolution.refusal;
+}
 export function workflowUpdateNameError(filePath, workflow) {
     const name = workflow?.name;
     if (typeof name === "string" && name.trim() !== "")
@@ -10772,8 +11169,14 @@ What a push guarantees (two stages):
             }
             // Process prompts
             const promptsDir = join(configDir, "prompts");
-            if (existsSync(promptsDir)) {
-                const files = selectFiles("prompt", promptsDir, readdirSync(promptsDir).filter((f) => f.endsWith(".toml")));
+            // #3798 — the prompt leg as one function, called twice. `config push`
+            // applies prompts BEFORE server functions, and an agent's tools name
+            // functions the server must hold when the agent is created, so a tree
+            // that pushes an agent together with its tool functions would be
+            // refused on its first push. Chat and decisions files keep their place;
+            // agent files are applied after the server-functions leg below
+            // (`deferredAgentPromptFiles`). Nothing inside the leg changed.
+            const pushPromptFiles = async (files) => {
                 // #2869 — prompts join the live-state reconcile (#2731 B3). #2748
                 // gave the type diff's comparator and left push on the manifest byte
                 // hash, so the two commands answered "changed?" from different
@@ -10976,6 +11379,79 @@ What a push guarantees (two stages):
                     // (mirrors `applyWorkflowUpdate`). The adopt branch seeds the
                     // sync-state entity record before calling this so the stamp lands.
                     const applyPromptUpdate = async (promptId, expectedModifiedAt) => {
+                        // #3799 (CSO-3799-005) — an agent's declaration is checked against
+                        // every config the server holds non-archived, so a file that
+                        // retires a config AND declares a schema that config's provider
+                        // cannot carry must retire it first: sent the other way round,
+                        // the prompt PATCH is refused for a config the file has already
+                        // archived, and no re-run changes the order. Only the entries
+                        // the file archives and the server does not yet — every other
+                        // config update still follows the prompt, and decisions prompts
+                        // keep their sequence. A config PATCH does not move the
+                        // prompt's `modifiedAt`, so the concurrency guard below still
+                        // holds.
+                        //
+                        // #3801 (DSO-3801-001) — the same staging, with a second admission
+                        // rule. The admin API refuses clearing a CHAT prompt's
+                        // `[prompt].outputSchema` while a config it holds non-archived is
+                        // strict, so a file that clears the schema AND turns strict output
+                        // off (or retires the config) would be refused on every push if the
+                        // prompt went first. Those config updates go ahead of the prompt
+                        // PATCH, with the payload they would have been sent anyway. The
+                        // read this needs is the one the name→id mapping below makes,
+                        // moved ahead of the PATCH, so the request count does not grow.
+                        const stagedFirst = new Set();
+                        const fileKind = promptKindOf(tomlData?.prompt);
+                        const retiring = configs.filter((c) => c?.name &&
+                            String(c?.status ?? "").trim().toLowerCase() === "archived");
+                        const stagesRetiringAgent = fileKind === "agent" && retiring.length > 0;
+                        const clearsPromptSchema = fileKind === "chat" &&
+                            !declaresSchema(tomlData?.prompt?.outputSchema);
+                        const current = stagesRetiringAgent || clearsPromptSchema
+                            ? await client.getPrompt(resolvedAppId, promptId)
+                            : null;
+                        const liveServerConfig = (name) => {
+                            const found = (current?.configs ?? []).find((c) => c.configName === name);
+                            return found && String(found.status ?? "active") !== "archived"
+                                ? found
+                                : null;
+                        };
+                        const staged = [];
+                        if (stagesRetiringAgent) {
+                            for (const tomlConfig of retiring) {
+                                const serverConfig = liveServerConfig(tomlConfig.name);
+                                if (serverConfig)
+                                    staged.push({ tomlConfig, serverConfig });
+                            }
+                        }
+                        if (clearsPromptSchema && declaresSchema(current?.outputSchema)) {
+                            for (const tomlConfig of configs) {
+                                if (!tomlConfig?.name)
+                                    continue;
+                                const serverConfig = liveServerConfig(tomlConfig.name);
+                                if (!serverConfig || serverConfig.strictOutput !== true)
+                                    continue;
+                                const chat = hoistDeprecatedChatKeys(tomlConfig).entry.chat ?? {};
+                                const retired = String(tomlConfig?.status ?? "").trim().toLowerCase() ===
+                                    "archived";
+                                // An entry that stays strict AND live is refused in preflight
+                                // (no schema to send); it is never staged.
+                                if (chat.strictOutput === true && !retired)
+                                    continue;
+                                staged.push({ tomlConfig, serverConfig });
+                            }
+                        }
+                        for (const { tomlConfig, serverConfig } of staged) {
+                            if (stagedFirst.has(tomlConfig.name))
+                                continue;
+                            try {
+                                await client.updatePromptConfig(resolvedAppId, promptId, serverConfig.configId, buildPromptConfigPayload(tomlConfig, { mode: "update" }));
+                            }
+                            catch (err) {
+                                throw wrapPromptConfigError(err, "update", key, tomlConfig.name);
+                            }
+                            stagedFirst.add(tomlConfig.name);
+                        }
                         const updated = await client.updatePrompt(resolvedAppId, promptId, buildPromptPushPayload(key, tomlData, { mode: "update" }), expectedModifiedAt);
                         info(`  Updated prompt: ${key}`);
                         // Record the `modifiedAt` this PATCH just caused, so a later
@@ -10998,7 +11474,10 @@ What a push guarantees (two stages):
                         try {
                             // Fetch full prompt to get config name→ID mappings
                             // (updatePrompt response doesn't include configs)
-                            const fullPrompt = await client.getPrompt(resolvedAppId, promptId);
+                            // #3801 — the read made ahead of the prompt PATCH when the
+                            // staging needed it (neither the PATCH nor a staged config
+                            // update moves a config's id or the activation).
+                            const fullPrompt = current ?? (await client.getPrompt(resolvedAppId, promptId));
                             if (fullPrompt?.configs) {
                                 for (const config of fullPrompt.configs) {
                                     promptConfigNameToId.set(`${key}#${config.configName}`, config.configId);
@@ -11012,6 +11491,10 @@ What a push guarantees (two stages):
                                         continue;
                                     const serverConfig = fullPrompt.configs.find((c) => c.configName === configName);
                                     if (serverConfig) {
+                                        // Staged ahead of the prompt PATCH, with this same
+                                        // payload (#3799 CSO-3799-005, #3801 DSO-3801-001).
+                                        if (stagedFirst.has(configName))
+                                            continue;
                                         // Update existing config
                                         try {
                                             await client.updatePromptConfig(resolvedAppId, promptId, serverConfig.configId, buildPromptConfigPayload(tomlConfig, { mode: "update" }));
@@ -11032,18 +11515,9 @@ What a push guarantees (two stages):
                                         }
                                         if (newConfig?.configId) {
                                             promptConfigNameToId.set(`${key}#${configName}`, newConfig.configId);
-                                            // #3201 — the create assigned `active`; a file that
-                                            // retired this entry says so in the only mode the
-                                            // server accepts the key in.
-                                            const statusPatch = createdConfigStatusPatch(tomlConfig);
-                                            if (statusPatch) {
-                                                try {
-                                                    await client.updatePromptConfig(resolvedAppId, promptId, newConfig.configId, statusPatch);
-                                                }
-                                                catch (err) {
-                                                    throw wrapPromptConfigError(err, "update", key, configName);
-                                                }
-                                            }
+                                            // #3799 — the create body carried the entry's own
+                                            // `status`, so there is no follow-up patch (#3201's is
+                                            // retired).
                                         }
                                     }
                                 }
@@ -11377,21 +11851,11 @@ What a push guarantees (two stages):
                                             throw wrapPromptConfigError(err, "create", key, extraName);
                                         }
                                         if (extraCreated?.configId) {
-                                            const configName = extraName;
-                                            promptConfigNameToId.set(`${key}#${configName}`, extraCreated.configId);
-                                            // #3201 — as on the update path: the create ignored
-                                            // the entry's `status`, so a retired one is applied
-                                            // here or the fresh environment runs a config the
-                                            // file retired.
-                                            const statusPatch = createdConfigStatusPatch(extraConfig);
-                                            if (statusPatch) {
-                                                try {
-                                                    await client.updatePromptConfig(resolvedAppId, created.promptId, extraCreated.configId, statusPatch);
-                                                }
-                                                catch (err) {
-                                                    throw wrapPromptConfigError(err, "update", key, configName);
-                                                }
-                                            }
+                                            promptConfigNameToId.set(`${key}#${extraName}`, extraCreated.configId);
+                                            // #3799 — as on the update path: the create carried the
+                                            // entry's `status`, so a retired entry is retired when
+                                            // it is created and the fresh environment never runs a
+                                            // config the file retired.
                                         }
                                     }
                                     info(`    Created ${configs.length - 1} additional config(s) for prompt: ${key}`);
@@ -11423,25 +11887,17 @@ What a push guarantees (two stages):
                                         activated = true;
                                     }
                                 }
-                                // #3201 — the seeded config's own `status`, applied LAST for
-                                // the same reason activation runs after the extra creates:
-                                // the create points `activeConfigId` at this config, so a
-                                // file that retires it is asking for a state that only makes
-                                // sense once the entry it marks active exists and is live.
-                                // Retiring it earlier would leave the prompt serving from an
-                                // archived config for the length of the remaining calls, and
-                                // permanently if one of them failed.
-                                const seededStatusPatch = seededConfigId
-                                    ? createdConfigStatusPatch(firstConfig || {})
-                                    : null;
-                                if (created?.promptId && seededConfigId && seededStatusPatch) {
-                                    try {
-                                        await client.updatePromptConfig(resolvedAppId, created.promptId, seededConfigId, seededStatusPatch);
-                                    }
-                                    catch (err) {
-                                        throw wrapPromptConfigError(err, "update", key, firstConfigPatch?.configName || seededConfig?.configName);
-                                    }
-                                }
+                                // #3799 (DSO-3799-005) — the seeded config's `status` is in
+                                // the create body (`POST /prompts` honors it now), so #3201's
+                                // trailing patch is gone. Activation still runs after every
+                                // create (#2645), so the marked entry is what the prompt ends
+                                // up serving; when the FIRST entry is the retired one, the
+                                // seeded config the prompt points at is created archived and
+                                // the activation moves the pointer off it. A push that dies
+                                // between the two leaves a prompt pointing at an archived
+                                // config — recovered by re-running the push, and the price of
+                                // never creating a config in a state the file did not ask for
+                                // (which is what an agent's schema check fires on).
                                 // Stamp sync state ONLY after all create work (base prompt +
                                 // every extra config) succeeded. If an extra-config create
                                 // above threw, we never reach here, so the file hash is not
@@ -11477,6 +11933,13 @@ What a push guarantees (two stages):
                         }
                     }
                 }
+            };
+            let deferredAgentPromptFiles = [];
+            if (existsSync(promptsDir)) {
+                const files = selectFiles("prompt", promptsDir, readdirSync(promptsDir).filter((f) => f.endsWith(".toml")));
+                const ordered = partitionPromptFilesForPush(promptsDir, files);
+                deferredAgentPromptFiles = ordered.afterFunctions;
+                await pushPromptFiles(ordered.beforeFunctions);
             }
             // Process transforms (Rhai scripts) — issue #892, slice 7 of #783.
             //
@@ -13850,7 +14313,11 @@ What a push guarantees (two stages):
                     let pushedVersion;
                     try {
                         if (!functionId) {
-                            const created = await client.createFunction(resolvedAppId, buildFunctionCreatePayload(key, tomlData.function ?? {})).catch(async (err) => {
+                            // #3835 — a create the server could not confirm in storage
+                            // (`STORAGE_CONSISTENCY_PENDING`) is asked again, not recorded
+                            // as not applied. Its row keeps the key, so a retry that meets
+                            // it as a 409 is adopted below like any other held key.
+                            const created = await retryOnStoragePending(() => client.createFunction(resolvedAppId, buildFunctionCreatePayload(key, tomlData.function ?? {}))).catch(async (err) => {
                                 // #1006 — a function the server already holds under this key
                                 // is adopted rather than re-created. The conflict may name a
                                 // WORKFLOW, a script or a webhook instead: those are the
@@ -13949,6 +14416,11 @@ What a push guarantees (two stages):
                     }
                 }
             }
+            // #3798 — the agent prompts, now that every function they name that
+            // this push applies is on the server (see `pushPromptFiles`).
+            if (deferredAgentPromptFiles.length > 0) {
+                await pushPromptFiles(deferredAgentPromptFiles);
+            }
             // Process group type configs
             const groupTypeConfigsDir = join(configDir, "group-type-configs");
             if (existsSync(groupTypeConfigsDir)) {