primitive-admin 1.2.0-alpha.3 → 1.2.0-alpha.4

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

@@ -2386,6 +2386,21 @@ export const RETIRED_CONFIG_KEYS = {
                 "`admin-only` (app admins; `personal-uploads` is the per-uploader " +
                 "preset).",
         },
+        // #4283 — #4116 made the bucket author its rule set by name and kept the
+        // id spelling as a deprecated key. Its own sentence rather than the type
+        // configs' shared one, which says a pulled file already spells the name:
+        // a bucket file pulled before #4116 does not. The `request` half is never
+        // surfaced, for the reason given at `RULE_SET_ID_RETIRED`.
+        ruleSetId: {
+            toml: "`ruleSetId` is no longer authored in TOML (#4283). A rule-set id " +
+                "names a row in one app and resolves to nothing in another, so the " +
+                "reference is authored by name: replace this line with " +
+                '`ruleSetName = "<name>"`, where the name is the `name` the rule ' +
+                "set's own `rule-sets/<key>.toml` declares, and push again, or " +
+                "`config pull` rewrites the file.",
+            request: "`ruleSetId` is the live request key on this surface; only its TOML " +
+                "spelling is retired (#4283). Send the rule set's id.",
+        },
     },
     // #2645 — pausing moved off `state` onto its own field, so `state` stopped
     // being author-writable rather than becoming a second way to say "paused".
@@ -2423,8 +2438,8 @@ export const RETIRED_CONFIG_KEYS = {
         },
     },
     // #3997 — keyed by each table's TOML prefix. Only `database-type-config`
-    // uses `[type]`, so that entry cannot reach another surface; the blob
-    // bucket's `[bucket] ruleSetId` is its live key and is not listed.
+    // uses `[type]`, so that entry cannot reach another surface. The blob
+    // bucket's `[bucket] ruleSetId` has its own entry under `bucket` (#4283).
     type: { ruleSetId: RULE_SET_ID_RETIRED },
     groupTypeConfig: { ruleSetId: RULE_SET_ID_RETIRED },
     collectionTypeConfig: { ruleSetId: RULE_SET_ID_RETIRED },
@@ -3336,7 +3351,8 @@ export function parseFunctionManifest(value) {
 // ── src/config-surface/function-retired-keys.ts ──────────────────────────
 /**
  * The runtime keys a `functions/<key>.toml` no longer decides anything with —
- * #3482, project `server-functions` phase 4.
+ * #3482 retired them, and #3188 (project `server-functions` phase 5) refuses
+ * them.
  *
  * The sponsor settled it on 2026-09-15 (the intent, "Mode vocabulary?",
  * amended again): the config says NOTHING about how a function runs. A
@@ -3345,44 +3361,50 @@ export function parseFunctionManifest(value) {
  * and a function that must not run under one runtime tests for it in code with
  * `assertRuntime`.
  *
- * ── Why these keys are accepted, not refused ──────────────────────────────
+ * ── Accepted through phase 4, refused from phase 5 ────────────────────────
  *
- * Every tree pushed since #3454 that declares a cron trigger carries
- * `mode = …` ON THE ENTRY, because `cron-trigger-mode-required` demanded it;
- * plenty carry a top-level `mode` or the older `durable`. Removing the keys
- * from the accepted set outright would refuse those trees with an unknown-key
- * error one day after the platform insisted on them, which is the opposite of
- * principle 5 inside a non-breaking phase.
+ * Every tree pushed since #3454 that declares a cron trigger carried
+ * `mode = …` ON THE ENTRY, because `cron-trigger-mode-required` demanded it,
+ * so #3482 accepted the keys and warned rather than refusing them one day
+ * after the platform insisted on them. Phase 5 is the declared breaking phase
+ * that ends the grace: `mode`, `durable` and a cron entry's `mode` are refused
+ * with one sentence per key, naming the key, saying the caller picks the
+ * runtime, and saying to delete the line. `config pull` still strips them
+ * (`stripRetiredFunctionKeys` in the CLI reads this scanner), so a tree pulled
+ * from a version pushed before the retirement pushes again unchanged.
  *
- * So through phase 4 they are ACCEPTED and IGNORED, with one warning per key
- * naming it and the line to delete; from phase 5 (#3188) they are refused with
- * the rest of the retirement matrix. The value is not validated — there is
- * nothing left to validate it against, and refusing a bad value for a key
- * nobody reads would be a refusal about spelling alone.
+ * One rule id, one handler: `refusedFunctionKeys` is declared `preflight` on
+ * the `function` surface and the CLI's push preflight runs it before the first
+ * request. The value is not validated — the key's PRESENCE is the refusal.
  *
- * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity). Both
- * the CLI preflight (vendored by `cli/scripts/gen-config-surfaces.mjs`) and the
- * admin config-version route read this one scanner, so the warning an author
- * sees from `config push` is the sentence the API answers with.
+ * Pure: no models, no tenant context, no `env` (see `types.ts` §Purity). The
+ * CLI preflight reaches this module through the vendored copy
+ * (`cli/scripts/gen-config-surfaces.mjs`), so the sentence an author reads from
+ * `config push` is the one this module writes.
  */
 /** The two `[function]` keys that no longer say anything (#3482). */
 export const RETIRED_FUNCTION_RUNTIME_KEYS = ["mode", "durable"];
+/**
+ * The rule ids this module owns, declared on the `function` surface (#3374's
+ * anchor). One id covers the three spellings: they are one rule — the config
+ * does not choose the runtime — met in three places.
+ */
+export const RETIRED_RUNTIME_KEY_RULE_IDS = ["retired-runtime-key"];
+/** The one refusal constructor (#3373's anchor). */
+function refuseRuntimeKey(ruleId, path, message) {
+    return { ruleId, path, message };
+}
 const RUNTIME_IS_THE_CALLERS = "a function is a function, and the caller picks the runtime at each call — " +
     "`invoke` runs it inside the request, `start` runs it as a task";
-const FROM_PHASE_5 = "Remove the line; from phase 5 it is refused.";
 /**
- * Every retired runtime key a `[function]` table still carries.
+ * Every retired runtime key a `[function]` table carries.
  *
  * Reads the table the way the author wrote it: the two top-level keys, and a
- * `mode` on each `[[function.triggers.cron]]` entry. A cron entry's sentence
- * says the extra thing its author needs to hear — that the schedule no longer
- * chooses, because every fire starts a task run (#3334's runner branch is
- * gone).
- *
- * Order is the order an author reads their file in: the top-level keys first,
- * then the cron entries in declaration order.
+ * `mode` on each `[[function.triggers.cron]]` entry. Order is the order an
+ * author reads their file in: the top-level keys first, then the cron entries
+ * in declaration order.
  */
-export function ignoredFunctionKeys(functionTable) {
+function retiredKeySites(functionTable) {
     const table = functionTable;
     if (!table || typeof table !== "object" || Array.isArray(table))
         return [];
@@ -3390,10 +3412,7 @@ export function ignoredFunctionKeys(functionTable) {
     for (const key of RETIRED_FUNCTION_RUNTIME_KEYS) {
         if (table[key] === undefined)
             continue;
-        found.push({
-            path: key,
-            message: `\`${key}\` is ignored (#3482): ${RUNTIME_IS_THE_CALLERS}. ${FROM_PHASE_5}`,
-        });
+        found.push({ path: key, cronEntry: null, key });
     }
     const triggers = table.triggers;
     const rawCron = triggers && typeof triggers === "object" && !Array.isArray(triggers)
@@ -3411,19 +3430,38 @@ export function ignoredFunctionKeys(functionTable) {
             return;
         const rawName = entry.name;
         const name = typeof rawName === "string" && rawName ? rawName : `#${index + 1}`;
-        found.push({
-            path: `triggers.cron.${name}.mode`,
-            message: `\`mode\` on cron trigger '${name}' is ignored (#3482): every cron ` +
-                `fire starts a task run, and ${RUNTIME_IS_THE_CALLERS}. ${FROM_PHASE_5}`,
-        });
+        found.push({ path: `triggers.cron.${name}.mode`, cronEntry: name, key: "mode" });
     });
     return found;
 }
+/**
+ * Every retired runtime key the table carries, each as the refusal the author
+ * reads. A cron entry's sentence says the extra thing its author needs to hear
+ * — that the schedule no longer chooses, because every fire starts a task run.
+ */
+export function refusedFunctionKeys(functionTable) {
+    return retiredKeySites(functionTable).map((site) => refuseRuntimeKey("retired-runtime-key", site.path, site.cronEntry === null
+        ? `\`${site.key}\` is not a key of a function: ${RUNTIME_IS_THE_CALLERS}. ` +
+            "Delete the line."
+        : `\`mode\` on cron trigger '${site.cronEntry}' is not a key of a ` +
+            `function: every cron fire starts a task run, and ${RUNTIME_IS_THE_CALLERS}. ` +
+            "Delete the line."));
+}
+/**
+ * The same refusals, rendered for one file — the shape `config push` and
+ * `config diff` print.
+ *
+ * `label` is what the reader can act on: `functions/<key>.toml` from the CLI,
+ * and the function's key from the API, which has no file to name.
+ */
+export function refusedFunctionKeyMessages(label, functionTable) {
+    return refusedFunctionKeys(functionTable).map((refusal) => `${label}: ${refusal.message}`);
+}
 /**
  * The database types a `[function]` table's retired trigger block names —
  * #3483.
  *
- * Beside `ignoredFunctionKeys` because it answers the same question about the
+ * Beside `refusedFunctionKeys` because it answers the same question about the
  * same table, for the same reader: `config pull` writes a version's AUTHORED
  * bytes, and a version pushed before the removal carries the block. Without
  * this the pulled tree would be refused on its next push — a tree an author
@@ -3484,16 +3522,6 @@ function retiredDatabaseTriggerValue(functionTable) {
     }
     return triggers.database;
 }
-/**
- * The same scan, rendered for one file — the shape `config push` and
- * `config diff` print and the admin route answers with.
- *
- * `label` is what the reader can act on: `functions/<key>.toml` from the CLI,
- * and the function's key from the API, which has no file to name.
- */
-export function ignoredFunctionKeyWarnings(label, functionTable) {
-    return ignoredFunctionKeys(functionTable).map((ignored) => `${label}: ${ignored.message}`);
-}
 export const EMPTY_TRIGGER_DECLARATION = {
     webhook: null,
     cron: [],
@@ -4339,6 +4367,10 @@ export const WORKFLOW_SURFACE = {
                 // Accepted on BOTH modes — #807's deferred second PATCH is an update
                 // call. The CLI's create-only send is a sequencing invariant owned by
                 // `applyWorkflowBody`, not a statement about what the server accepts.
+                // #3188 retired the synchronous run route this flag opted into; the
+                // field still round-trips (pull, diff, push) until the workflow
+                // surface itself retires, and `config push` notes a `true` as
+                // ignored. Its step-kind rule went with the route.
                 {
                     field: "syncCallable",
                     tomlKey: "syncCallable",
@@ -4594,8 +4626,6 @@ export const WORKFLOW_SURFACE = {
         workflowApplyRule("access-rule-required", "validateWorkflowIdentityConfig", "On create, a caller-mode workflow must state its `accessRule` (`\"true\"` " +
             "for any app member), so a locked workflow is a decision rather than a " +
             "default."),
-        workflowApplyRule("sync-callable-step-kind", "validateSyncCallableSteps", "A `syncCallable = true` workflow may not carry a step kind that only " +
-            "the durable runtime can execute (`delay`, `event.wait`)."),
     ],
 };
 const FIELD_RANGES = [
@@ -5697,6 +5727,9 @@ export const AGENT_ERROR_CODES = [
     "AGENT_TOOL_ARGUMENTS_INVALID",
     "AGENT_ROUND_TRUNCATED",
     "AGENT_ROUND_EMPTY",
+    // #4262 — a single-round test case whose seeded history, context or
+    // assertions cannot be a round of this agent (`agent-test-case.ts`).
+    "AGENT_TEST_CASE_INVALID",
 ];
 /**
  * The platform maximums. An agent may lower `maxSteps`, `waitLimitSeconds`
@@ -5721,6 +5754,20 @@ 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"];
+/**
+ * The result the platform records for a call to a client tool with
+ * `endsTurn = true`: the call is final when its response is committed, and
+ * later rounds read this as its tool result.
+ */
+export const AGENT_TERMINAL_CALL_OUTPUT = Object.freeze({
+    delivered: true,
+});
+/** The schema of `AGENT_TERMINAL_CALL_OUTPUT`: a terminal client tool's output type. */
+export const AGENT_TERMINAL_CALL_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    properties: { delivered: { type: "boolean" } },
+    required: ["delivered"],
+});
 const AGENT_TOP_LEVEL_KEYS = [
     "answeredBy",
     "maxSteps",
@@ -5742,6 +5789,7 @@ const AGENT_TOOL_KEYS = [
     "approval",
     "statusText",
     "historyScope",
+    "endsTurn",
     "inputSchema",
     "outputSchema",
 ];
@@ -5870,8 +5918,22 @@ function checkAgentTool(tool, index, names, out) {
             out.push(agentInvalid(`${path}.invoke`, `must be one of ${AGENT_TOOL_INVOKE.join(" | ")}`));
         }
     }
+    const terminal = tool.endsTurn === true;
+    if (tool.endsTurn !== undefined && typeof tool.endsTurn !== "boolean") {
+        out.push(agentInvalid(`${path}.endsTurn`, "must be true or false"));
+    }
+    if (terminal && tool.approval === true) {
+        out.push(agentInvalid(`${path}.endsTurn`, "cannot be set with approval = true: a terminal call never pauses"));
+    }
     for (const key of ["inputSchema", "outputSchema"]) {
         const schemaPath = `${path}.${key}`;
+        if (isClient && terminal && key === "outputSchema") {
+            if (tool[key] !== undefined) {
+                out.push(agentInvalid(schemaPath, "is not declared on a client tool with endsTurn = true: the " +
+                    "platform records a terminal client call's result — remove it"));
+            }
+            continue;
+        }
         if (isClient) {
             if (tool[key] === undefined) {
                 out.push(agentInvalid(schemaPath, "is required on a client tool"));
@@ -6146,17 +6208,14 @@ export function agentRoundNotAgentRefusal(promptKey) {
         "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.
+ * The refusal of a prompt test case that names an agent as its judge (§D1: an
+ * evaluator runs single-shot, which an agent never does). A case written ON an
+ * agent is a single-round test since #4262 (`agent-test-case.ts`), so
+ * `evaluator` is the one role left.
  */
-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");
+export function agentTestCaseRefusal(promptKey, _role = "evaluator") {
+    return agentRefusal("AGENT_TEST_CASE_NOT_SUPPORTED", `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) {
@@ -6165,7 +6224,7 @@ function agentCopy(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"`.
+ * tools), `approval = false`, `historyScope = "session"` and `endsTurn = false`.
  *
  * The ONLY accessor for defaults — the stored value never carries them
  * (DSO-3798-001). Takes a value `resolveAgentDeclaration` accepted (or `null`)
@@ -6185,6 +6244,7 @@ export function normalizeAgentDeclaration(declaration) {
             ...(tool.runs === "client" ? {} : { invoke: tool.invoke ?? "request" }),
             approval: tool.approval ?? false,
             historyScope: tool.historyScope ?? "session",
+            endsTurn: tool.endsTurn ?? false,
         })),
         events: source.events ?? [],
     };
@@ -6902,6 +6962,365 @@ export function agentSchemaTranslationRefusals(input) {
     }
     return out;
 }
+// ── src/config-surface/agent-test-case.ts ────────────────────────────────
+/**
+ * What an agent test case may say — issue #4262 (single-round prompt tests
+ * from a seeded history; design-docs/agents.md §D1).
+ *
+ * A test case on an agent prompt carries one `[test.agent]` block: a seeded
+ * `history` (JSON text), the round's turn `context`, `timezone` and `locale`,
+ * and two assertions on the round's calls (`expectedToolCall`,
+ * `expectedNoToolCall`). On the wire and in storage those are six flat
+ * `BlockTestCase` fields, `agentHistory` … `agentExpectedNoToolCall`.
+ *
+ * This module is the whole FILE-DECIDABLE rule for them: the history's shape,
+ * its turns, its call and result pairing, where its events sit, the
+ * assertions' shapes, and — when the caller passes the agent's declaration —
+ * that the event kinds and the asserted tool are declared. The admin test-case
+ * routes call it, and so does the CLI's push preflight through the vendored
+ * artifact, so a refusal at push and a refusal at the route cannot disagree.
+ * What needs app state or a schema validator (the input, context and event
+ * schemas, the send route's zone and tag rules) is `agent-test-round.ts`'s.
+ *
+ * Every refusal carries `AGENT_TEST_CASE_INVALID` and the caller gets every
+ * offending item at once, as the declaration resolver does.
+ *
+ * Pure and dependency-free apart from the agent declaration's types, like
+ * every module under `src/config-surface/`.
+ */
+/** The six wire and stored fields, in the order the surface declares them. */
+export const AGENT_TEST_CASE_FIELDS = [
+    "agentHistory",
+    "agentContext",
+    "agentTimezone",
+    "agentLocale",
+    "agentExpectedToolCall",
+    "agentExpectedNoToolCall",
+];
+function agentTestRefusal(message) {
+    return { code: "AGENT_TEST_CASE_INVALID", message: `[test.agent] ${message}` };
+}
+function agentTestIsObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function agentTestIsText(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** `null` and `undefined` are absence; so is `""` for a text field. */
+function agentTestIsUnset(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+/** A JSON field: the value as given, or the JSON text a sidecar carries parsed. */
+function agentTestJsonValue(value) {
+    if (typeof value !== "string")
+        return { ok: true, value };
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** The names a declaration declares, or `null` when the caller passed none. */
+function agentTestDeclaredNames(declaration, given) {
+    if (!given)
+        return null;
+    let block = declaration;
+    if (typeof block === "string") {
+        try {
+            block = JSON.parse(block);
+        }
+        catch {
+            block = null;
+        }
+    }
+    const names = (list) => new Set((Array.isArray(list) ? list : [])
+        .map((item) => (agentTestIsObject(item) ? item.name : undefined))
+        .filter((name) => typeof name === "string"));
+    const source = agentTestIsObject(block) ? block : {};
+    return { tools: names(source.tools), events: names(source.events) };
+}
+const AGENT_TEST_ENTRY_KEYS = {
+    user: ["role", "text"],
+    assistant: ["role", "text", "reasoning", "calls"],
+    tool: ["role", "callId", "output", "error"],
+    event: ["role", "kind", "refersTo", "data"],
+};
+/**
+ * The history's entries and every refusal of their shape. A user entry
+ * starts a turn and the last one's turn is the current one; every call is
+ * answered exactly once, by a tool entry that follows its assistant entry;
+ * an event precedes the current turn's user entry (a live event reaches the
+ * model only in a later turn's history).
+ */
+function agentTestReadHistory(raw, names, out) {
+    if (agentTestIsUnset(raw)) {
+        out.push(agentTestRefusal("history is required on an agent case: a JSON array of user, assistant, tool and event entries, oldest first"));
+        return null;
+    }
+    if (typeof raw !== "string") {
+        out.push(agentTestRefusal("history must be JSON text (a JSON array written as one string)"));
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        out.push(agentTestRefusal(`history is not valid JSON (${error?.message ?? "parse failed"})`));
+        return null;
+    }
+    if (!Array.isArray(parsed)) {
+        out.push(agentTestRefusal("history must be a JSON array of entries"));
+        return null;
+    }
+    const entries = [];
+    const calls = new Map();
+    /** The calls of the last assistant entry, which tool entries may answer. */
+    let open = new Set();
+    let seenUser = false;
+    const lastUser = parsed.reduce((at, entry, index) => (agentTestIsObject(entry) && entry.role === "user" ? index : at), -1);
+    if (lastUser === -1) {
+        out.push(agentTestRefusal("history needs at least one user entry; the last one is the round's current turn"));
+    }
+    parsed.forEach((entry, index) => {
+        const at = `history[${index}]`;
+        if (!agentTestIsObject(entry)) {
+            out.push(agentTestRefusal(`${at} must be an object with a role`));
+            return;
+        }
+        // An own-property read: a role such as "constructor" or "__proto__" must
+        // not resolve to an inherited member of the table.
+        const allowed = typeof entry.role === "string" && Object.prototype.hasOwnProperty.call(AGENT_TEST_ENTRY_KEYS, entry.role)
+            ? AGENT_TEST_ENTRY_KEYS[entry.role]
+            : undefined;
+        if (!allowed) {
+            out.push(agentTestRefusal(`${at}.role must be "user", "assistant", "tool" or "event"; found ${JSON.stringify(entry.role)}`));
+            return;
+        }
+        const unknown = Object.keys(entry).filter((key) => !allowed.includes(key));
+        if (unknown.length > 0) {
+            out.push(agentTestRefusal(`${at} has ${unknown.map((k) => `"${k}"`).join(", ")}, which a ${entry.role} entry does not carry; allowed: ${allowed.join(", ")}`));
+        }
+        if (entry.role === "user") {
+            if (typeof entry.text !== "string" || entry.text === "") {
+                out.push(agentTestRefusal(`${at}.text must be a non-empty string`));
+                return;
+            }
+            open = new Set();
+            seenUser = true;
+            entries.push({ role: "user", text: entry.text });
+            return;
+        }
+        if (entry.role === "assistant") {
+            if (!seenUser) {
+                out.push(agentTestRefusal(`${at} is an assistant entry before the first user entry; a turn starts with a user entry`));
+            }
+            const hasText = entry.text !== undefined;
+            const hasCalls = entry.calls !== undefined;
+            if (hasText && typeof entry.text !== "string") {
+                out.push(agentTestRefusal(`${at}.text must be a string`));
+            }
+            if (entry.reasoning !== undefined && typeof entry.reasoning !== "string") {
+                out.push(agentTestRefusal(`${at}.reasoning must be a string`));
+            }
+            const read = [];
+            if (hasCalls) {
+                if (!Array.isArray(entry.calls) || entry.calls.length === 0) {
+                    out.push(agentTestRefusal(`${at}.calls must be a non-empty array of { callId, name, arguments }`));
+                }
+                else {
+                    entry.calls.forEach((call, callIndex) => {
+                        const callAt = `${at}.calls[${callIndex}]`;
+                        if (!agentTestIsObject(call) ||
+                            !agentTestIsText(call.callId) ||
+                            !agentTestIsText(call.name) ||
+                            !("arguments" in call) ||
+                            Object.keys(call).some((key) => !["callId", "name", "arguments"].includes(key))) {
+                            out.push(agentTestRefusal(`${callAt} must be { callId, name, arguments }`));
+                            return;
+                        }
+                        if (calls.has(call.callId)) {
+                            out.push(agentTestRefusal(`${callAt}: call id "${call.callId}" is used twice; call ids are unique across the history`));
+                            return;
+                        }
+                        calls.set(call.callId, { answered: false });
+                        read.push({ callId: call.callId, name: call.name, arguments: call.arguments });
+                    });
+                }
+            }
+            if (!(typeof entry.text === "string" && entry.text !== "") && read.length === 0 && !hasCalls) {
+                out.push(agentTestRefusal(`${at} needs text or calls`));
+            }
+            open = new Set(read.map((call) => call.callId));
+            entries.push({
+                role: "assistant",
+                ...(typeof entry.text === "string" ? { text: entry.text } : {}),
+                ...(typeof entry.reasoning === "string" ? { reasoning: entry.reasoning } : {}),
+                ...(read.length > 0 ? { calls: read } : {}),
+            });
+            return;
+        }
+        if (entry.role === "tool") {
+            if (!agentTestIsText(entry.callId)) {
+                out.push(agentTestRefusal(`${at}.callId must name a call of an earlier assistant entry`));
+                return;
+            }
+            const hasOutput = "output" in entry;
+            const hasError = "error" in entry;
+            if (hasOutput === hasError) {
+                out.push(agentTestRefusal(`${at} must carry exactly one of output or error`));
+                return;
+            }
+            const call = calls.get(entry.callId);
+            if (!call) {
+                out.push(agentTestRefusal(`${at} answers call "${entry.callId}", which no earlier assistant entry makes`));
+                return;
+            }
+            if (call.answered) {
+                out.push(agentTestRefusal(`${at} is a second result for call "${entry.callId}"; every call has exactly one`));
+                return;
+            }
+            if (!open.has(entry.callId)) {
+                out.push(agentTestRefusal(`${at} answers call "${entry.callId}", which is not a call of the assistant entry just before it; ` +
+                    "a result follows its call"));
+                return;
+            }
+            call.answered = true;
+            if (hasError) {
+                const error = entry.error;
+                if (!agentTestIsObject(error) || !agentTestIsText(error.code) || typeof error.message !== "string") {
+                    out.push(agentTestRefusal(`${at}.error must be { code, message }`));
+                    return;
+                }
+                entries.push({ role: "tool", callId: entry.callId, error: { code: error.code, message: error.message } });
+                return;
+            }
+            entries.push({ role: "tool", callId: entry.callId, output: entry.output });
+            return;
+        }
+        // An event.
+        if (!agentTestIsText(entry.kind)) {
+            out.push(agentTestRefusal(`${at}.kind must name an event kind the agent declares`));
+            return;
+        }
+        if (names && !names.events.has(entry.kind)) {
+            out.push(agentTestRefusal(`${at} has event kind "${entry.kind}", which the agent does not declare` +
+                (names.events.size > 0 ? ` (declared: ${[...names.events].join(", ")})` : "")));
+        }
+        if (entry.refersTo !== undefined && (!agentTestIsText(entry.refersTo) || !calls.has(entry.refersTo))) {
+            out.push(agentTestRefusal(`${at}.refersTo names call ${JSON.stringify(entry.refersTo)}, which no earlier assistant entry makes`));
+        }
+        if (lastUser !== -1 && index > lastUser) {
+            out.push(agentTestRefusal(`${at} is an event after the current turn's user entry; a live event reaches the model only in a ` +
+                "later turn, so place it before the last user entry"));
+        }
+        entries.push({
+            role: "event",
+            kind: entry.kind,
+            ...(typeof entry.refersTo === "string" ? { refersTo: entry.refersTo } : {}),
+            data: entry.data ?? null,
+        });
+    });
+    for (const [callId, call] of calls) {
+        if (!call.answered) {
+            out.push(agentTestRefusal(`call "${callId}" has no result; write one tool entry for it (an unanswered call as an error, ` +
+                'e.g. { "code": "superseded", "message": "…" })'));
+        }
+    }
+    const last = parsed[parsed.length - 1];
+    if (agentTestIsObject(last) && last.role === "assistant") {
+        out.push(agentTestRefusal("history ends with an assistant entry; a round starts from a user entry or a tool result"));
+    }
+    return entries;
+}
+function agentTestReadExpectedToolCall(raw, names, out) {
+    if (agentTestIsUnset(raw))
+        return null;
+    const parsed = agentTestJsonValue(raw);
+    const value = parsed.ok ? parsed.value : undefined;
+    if (!agentTestIsObject(value) ||
+        !agentTestIsText(value.name) ||
+        Object.keys(value).some((key) => key !== "name" && key !== "arguments")) {
+        out.push(agentTestRefusal("expectedToolCall must be { name, arguments? } (arguments is matched as a subset)"));
+        return null;
+    }
+    if (names && !names.tools.has(value.name)) {
+        out.push(agentTestRefusal(`expectedToolCall names tool "${value.name}", which the agent does not declare` +
+            (names.tools.size > 0 ? ` (declared: ${[...names.tools].join(", ")})` : "")));
+    }
+    return { name: value.name, ...("arguments" in value ? { arguments: value.arguments } : {}) };
+}
+/**
+ * The one rule: is this case's agent block something a round can be built
+ * from? `{ ok: true, testCase }` carries it read (`null` on a case whose
+ * prompt is not an agent). On a chat or decisions case, every agent key
+ * holding a non-null value is refused by name; an explicit `null` is unset on
+ * any case, which is how a full-state update clears one.
+ */
+export function resolveAgentTestCase(input) {
+    const { fields } = input;
+    const kind = agentTestIsUnset(input.kind) ? "chat" : String(input.kind).trim();
+    const refusals = [];
+    if (kind !== "agent") {
+        const owner = kind === "chat" || kind === "decisions" ? `a ${kind} prompt` : `a ${kind}`;
+        for (const key of AGENT_TEST_CASE_FIELDS) {
+            const value = fields[key];
+            if (value !== null && value !== undefined) {
+                refusals.push(agentTestRefusal(`${key} is set on a case of ${owner}; only an agent prompt's case carries the agent block. ` +
+                    "Remove it, or send it as null"));
+            }
+        }
+        return refusals.length > 0 ? { ok: false, refusals } : { ok: true, testCase: null };
+    }
+    const names = agentTestDeclaredNames(input.declaration, "declaration" in input);
+    const history = agentTestReadHistory(fields.agentHistory, names, refusals);
+    let context = null;
+    if (!agentTestIsUnset(fields.agentContext)) {
+        const parsed = agentTestJsonValue(fields.agentContext);
+        if (parsed.ok && agentTestIsObject(parsed.value))
+            context = parsed.value;
+        else
+            refusals.push(agentTestRefusal("context must be a JSON object (turn.* for the round)"));
+    }
+    const text = (key, label, example) => {
+        const value = fields[key];
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value !== "string" || value === "") {
+            refusals.push(agentTestRefusal(`${label} must be ${example}`));
+            return null;
+        }
+        return value;
+    };
+    const timezone = text("agentTimezone", "timezone", 'an IANA time zone name such as "America/New_York"');
+    const locale = text("agentLocale", "locale", 'a BCP 47 language tag such as "en-US"');
+    const expectedToolCall = agentTestReadExpectedToolCall(fields.agentExpectedToolCall, names, refusals);
+    let expectedNoToolCall = false;
+    const noCall = fields.agentExpectedNoToolCall;
+    if (noCall !== null && noCall !== undefined) {
+        if (typeof noCall !== "boolean")
+            refusals.push(agentTestRefusal("expectedNoToolCall must be true or false"));
+        else
+            expectedNoToolCall = noCall;
+    }
+    if (expectedToolCall && expectedNoToolCall) {
+        refusals.push(agentTestRefusal("sets both expectedToolCall and expectedNoToolCall = true; a round cannot both call a tool and call none"));
+    }
+    const subset = fields.expectedJsonSubset;
+    if (!agentTestIsUnset(subset) && !(agentTestIsObject(subset) && Object.keys(subset).length === 0) && subset !== "{}") {
+        refusals.push(agentTestRefusal("expectedJsonSubset is not used on an agent case: an agent's answer is text, and anything structured is a " +
+            "tool call. Assert it with expectedToolCall"));
+    }
+    if (refusals.length > 0 || !history)
+        return { ok: false, refusals };
+    return {
+        ok: true,
+        testCase: { history, context, timezone, locale, expectedToolCall, expectedNoToolCall },
+    };
+}
 // ── src/config-surface/prompt.ts ─────────────────────────────────────────
 /**
  * The `prompt` configuration object's definition (issue #2644, phase 2).
@@ -8246,8 +8665,8 @@ export const CRON_TRIGGER_SURFACE = {
  * halves of the access model (#1020), and the only access keys: at most one may
  * change per request, which is the controller's rule and stays there. The rule
  * set is authored by name (`ruleSetName`) and sent as `ruleSetId`, as the type
- * configs do (#4116); the id spelling in TOML is deprecated. The pre-#1020
- * `accessPolicy` spelling is a retired key (#3996, `retired-keys.ts`).
+ * configs do (#4116). The id spelling in TOML (#4283) and the pre-#1020
+ * `accessPolicy` spelling (#3996) are retired keys (`retired-keys.ts`).
  */
 const BLOB_BUCKET_HANDLER = "src/app-api/controllers/blob-buckets-controller.ts";
 export const BLOB_BUCKET_SURFACE = {
@@ -8303,7 +8722,7 @@ export const BLOB_BUCKET_SURFACE = {
                     // Authored as a name, sent as an id (#4116), so a tree copied into
                     // another app binds that app's rule set. Existence-checked against
                     // AccessRuleSet; mutually exclusive with a preset change in the same
-                    // request.
+                    // request. The TOML spelling of the id is a retired key (#4283).
                     validation: handledBy(BLOB_BUCKET_HANDLER, "BlobBucketsController", "apply"),
                 },
             ],
@@ -8353,14 +8772,6 @@ export const BLOB_BUCKET_SURFACE = {
                     note: "The bucket key. `config pull` writes it for readability; push takes " +
                         "the identity from the file name and attaches `bucketKey` itself.",
                 },
-                ruleSetId: {
-                    kind: "deprecated",
-                    note: "The id spelling of the rule-set reference (#4116). An id names a " +
-                        "rule set in one app, so a copied tree cannot resolve it; " +
-                        "`ruleSetName` is the authored key. Still accepted on push, with " +
-                        "an advisory line, and `config pull` rewrites the file to " +
-                        "`ruleSetName`. Retiring it is a later change of its own.",
-                },
             },
             responseOnlyKeys: {},
         },
@@ -9219,7 +9630,7 @@ export const TRANSFORM_SURFACE = {
  * config version (`ServerFunctionConfig`), but it is ONE table in the file: an
  * author does not write a version, they write a function and push it. The
  * definition therefore declares the header's field surface and lists the
- * version-carried keys (`entry`, `mode`, `limits`) in `tomlOnlyKeys` beside
+ * version-carried keys (`entry`, `limits`) in `tomlOnlyKeys` beside
  * `key` — they are authored, they are not fields of the header model, and they
  * travel on the config-version route rather than in the header body. Declaring
  * a second table over `ServerFunctionConfig` at the same `tomlPath` is not
@@ -9307,6 +9718,20 @@ const TRIGGER_DECLARATION_RULES = functionRules("preflight", "src/config-surface
     ["cron-trigger-expression-required", "A cron entry carries a `cron` expression."],
     ["cron-trigger-overlap-policy", "`overlapPolicy` is `skip` or `allow`."],
 ]);
+/**
+ * The retired runtime keys (#3188). `mode`, `durable` and a cron entry's
+ * `mode` were accepted with a warning through phase 4 (#3482); phase 5 refuses
+ * them, first in the preflight's order, so an author reads them in the order
+ * their file carries them.
+ */
+const RETIRED_RUNTIME_KEY_RULES = functionRules("preflight", "src/config-surface/function-retired-keys.ts", "refusedFunctionKeys", [
+    [
+        "retired-runtime-key",
+        "`mode`, `durable` and a cron entry's `mode` are refused: the caller " +
+            "picks the runtime at each call (`invoke` or `start`) and every cron " +
+            "fire starts a task run, so the file has nothing to say. Delete the line.",
+    ],
+]);
 /**
  * The file-decidable half of the webhook `signingSecret` rule (#3320). The
  * SAME handler under the SAME ids is declared `apply` on the standalone
@@ -9508,24 +9933,21 @@ export const SERVER_FUNCTION_SURFACE = {
                 },
                 mode: {
                     kind: "structural",
-                    note: "RETIRED (#3482), and still ACCEPTED through phase 4. A function " +
-                        "is a function: the CALLER picks the runtime at each call, with " +
-                        "`invoke` running it inside the request and `start` running it as " +
-                        "a task, cron fires always starting a task run and webhook " +
-                        "deliveries always running as a request. A file that still " +
-                        "carries the key pushes, with a warning naming it as ignored and " +
-                        "every other key applied, and `config pull` removes it; from " +
-                        "phase 5 (#3188) it is refused as an unknown key. Nothing reads " +
-                        "it, and its value is not validated. A function that must not run " +
-                        "under one runtime says so in code with `assertRuntime`.",
+                    note: "RETIRED (#3482) and REFUSED from phase 5 (#3188) by the " +
+                        "`retired-runtime-key` rule, whose sentence names the key and " +
+                        "says to delete the line. A function is a function: the CALLER " +
+                        "picks the runtime at each call, with `invoke` running it inside " +
+                        "the request and `start` running it as a task, cron fires always " +
+                        "starting a task run and webhook deliveries always running as a " +
+                        "request. Listed here so the refusal is the rule's sentence rather " +
+                        "than the generic unknown-key one; `config pull` removes it from a " +
+                        "version pushed before the retirement.",
                 },
                 durable: {
                     kind: "structural",
-                    note: "RETIRED (#3482), and still ACCEPTED through phase 4 — the same " +
-                        "as `mode`, whose alias it was. It named one runner for the whole " +
-                        "function, and there is no such thing any more. A file that " +
-                        "carries it pushes with a warning, `config pull` removes it, and " +
-                        "phase 5 refuses it.",
+                    note: "RETIRED (#3482) and REFUSED from phase 5 (#3188) — the same as " +
+                        "`mode`, whose alias it was, by the same rule. It named one runner " +
+                        "for the whole function, and there is no such thing any more.",
                 },
                 limits: {
                     kind: "structural",
@@ -9563,11 +9985,12 @@ export const SERVER_FUNCTION_SURFACE = {
     tomlDocumentKeys: {},
     // ── Cross-field rules (#3374) ─────────────────────────────────────────────
     //
-    // Single-field refusals inside these modules (`mode`'s value, a webhook
+    // Single-field refusals inside these modules (a retired `mode` key, a webhook
     // block's `verificationScheme`) are declared here too: this is the only
     // id-bearing slot until #3375 gives `ConfigField.validation` a stage, and a
     // module's list must equal its declarations in both directions.
     crossFieldRules: [
+        ...RETIRED_RUNTIME_KEY_RULES,
         ...TRIGGER_DECLARATION_RULES,
         ...SIGNING_SECRET_RULES,
         // #3376 — after the signing-secret group, mirroring the order
@@ -9601,8 +10024,23 @@ export const SERVER_FUNCTION_SURFACE = {
  * WIRE shape is the parsed value. That asymmetry is the handler's, not the
  * definition's: `parseTestCaseToml` parses on push and the admin API
  * re-stringifies on store.
+ *
+ * #4262 — an agent prompt's case carries one more block, `[test.agent]`: the
+ * seeded history its single round starts from, the round's turn context, zone
+ * and tag, and two assertions on the round's calls. Six flat fields on the
+ * wire, each `whenSet`, so a chat case's sidecar never grows an empty block.
+ * `history` is typed `string` — JSON text in TOML, on the wire and in storage —
+ * because `isEmptyForEmit` reads every array as empty for a `json` field, so a
+ * `whenSet` array would never pull and would compare equal to anything.
  */
 const TEST_CASE_HANDLER = "src/admin-api.ts";
+/**
+ * #4262 — the agent block's one rule, vendored: the admin routes call it on
+ * create and update, the CLI's preflight on an agent prompt's sidecar. Its
+ * schema half (input, context and event schemas) needs the app's agent, so the
+ * stage is `apply`.
+ */
+const AGENT_TEST_CASE_RULE = handledBy("src/config-surface/agent-test-case.ts", "resolveAgentTestCase", "apply");
 /**
  * ── Why this module's CLI handler is declared `apply` (#3375) ─────────────
  *
@@ -9704,7 +10142,72 @@ export const TEST_CASE_SURFACE = {
                     // JSON object, deep-partial-matched against the parsed output.
                     validation: handledBy(CLI_SYNC, "parseTestCaseToml", "apply"),
                 },
+                // #4262 — `[test.agent]`, an agent prompt's case only.
+                {
+                    field: "agentHistory",
+                    tomlKey: "history",
+                    tomlGroup: "agent",
+                    // JSON text of the seeded history, stored as authored.
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentContext",
+                    tomlKey: "context",
+                    tomlGroup: "agent",
+                    // `turn.*` for the round; TOML carries the JSON text.
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentTimezone",
+                    tomlKey: "timezone",
+                    tomlGroup: "agent",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentLocale",
+                    tomlKey: "locale",
+                    tomlGroup: "agent",
+                    type: "string",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentExpectedToolCall",
+                    tomlKey: "expectedToolCall",
+                    tomlGroup: "agent",
+                    // `{ name, arguments? }`; TOML carries the JSON text.
+                    type: "json",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
+                {
+                    field: "agentExpectedNoToolCall",
+                    tomlKey: "expectedNoToolCall",
+                    tomlGroup: "agent",
+                    type: "boolean",
+                    emit: "whenSet",
+                    writableOn: BOTH,
+                    validation: AGENT_TEST_CASE_RULE,
+                },
             ],
+            tomlGroups: {
+                agent: {
+                    note: "#4262 — `[test.agent]`: the seeded history, turn context and " +
+                        "tool-call assertions of a single-round test on an agent prompt. " +
+                        "Refused on any other case.",
+                },
+            },
             notExposed: {
                 testCaseId: {
                     kind: "server-owned",
@@ -10561,6 +11064,12 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "evaluatorPromptId",
         "evaluatorConfigId",
         "attachments",
+        "agentHistory",
+        "agentContext",
+        "agentTimezone",
+        "agentLocale",
+        "agentExpectedToolCall",
+        "agentExpectedNoToolCall",
         "createdBy",
         "createdAt",
         "modifiedAt",