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

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

@@ -31,7 +31,7 @@
  * server; the CLI vendors them at build time into
  * `cli/src/lib/generated-config-surfaces.ts`
  * (`cli/scripts/gen-config-surfaces.mjs`), the same server→CLI vendoring
- * `gen-operation-def-descriptor.mjs` (#1544) already uses, so the published CLI
+ * `gen-workflow-schema-descriptor.mjs` (#1442) already uses, so the published CLI
  * still imports no server code at runtime.
  *
  * ── Scope: declarative classification and coverage ONLY ──────────────────
@@ -1101,6 +1101,19 @@ export interface RetiredConfigKey {
     request: string;
 }
 export declare const RETIRED_CONFIG_KEYS: Record<string, Record<string, RetiredConfigKey>>;
+/**
+ * Top-level TOML tables a configuration object's FILE retired — keyed by the
+ * surface's label, then by the table key. Only the TOML half exists: these were
+ * sub-trees applied through their own endpoints, never request keys of the
+ * object itself, so no request body can carry one.
+ *
+ * Without an entry here a retired table would be answered as an unrecognized
+ * one ("check the spelling, or upgrade the CLI"), which is backwards for a
+ * table removed on purpose.
+ */
+export declare const RETIRED_DOCUMENT_KEYS: Record<string, Record<string, RetiredTomlSpelling>>;
+/** The retired-table guidance for `key` on the surface labelled `label`, or null. */
+export declare function retiredDocumentKey(label: string, key: string): RetiredTomlSpelling | null;
 /** The retired-key entry for `key` under `prefix`, or null when it is simply unknown. */
 export declare function retiredConfigKey(prefix: string, key: string): RetiredConfigKey | null;
 /**
@@ -1492,7 +1505,8 @@ export interface ParsedManifest {
 export declare function parseFunctionManifest(value: unknown): ParsedManifest;
 /**
  * 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
@@ -1501,58 +1515,70 @@ export declare function parseFunctionManifest(value: unknown): ParsedManifest;
  * 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 declare const RETIRED_FUNCTION_RUNTIME_KEYS: readonly ["mode", "durable"];
 export type RetiredFunctionRuntimeKey = (typeof RETIRED_FUNCTION_RUNTIME_KEYS)[number];
-/** One ignored key met in a `[function]` table. */
-export interface IgnoredFunctionKey {
+/**
+ * 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 declare const RETIRED_RUNTIME_KEY_RULE_IDS: readonly ["retired-runtime-key"];
+type RetiredRuntimeKeyRuleId = (typeof RETIRED_RUNTIME_KEY_RULE_IDS)[number];
+/** One retired key met in a `[function]` table. */
+export interface RetiredFunctionKey extends RuleRefusal<RetiredRuntimeKeyRuleId> {
     /**
      * Where it was: `mode`, `durable`, or `triggers.cron.<name>.mode`. Never
      * rendered on its own — a reader that wants to branch reads this, and every
      * printer reads `message`.
      */
     path: string;
-    /** The sentence the author is owed, with no file prefix (the caller adds it). */
-    message: string;
 }
 /**
- * Every retired runtime key a `[function]` table still 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).
+ * The pre-phase-5 name of a met key, kept for the CLI's pull strip, which only
+ * needs `path`. Every key met is refused now.
+ */
+export type IgnoredFunctionKey = RetiredFunctionKey;
+/**
+ * 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 declare function refusedFunctionKeys(functionTable: unknown): RetiredFunctionKey[];
+/**
+ * The same refusals, rendered for one file — the shape `config push` and
+ * `config diff` print.
  *
- * Order is the order an author reads their file in: the top-level keys first,
- * then the cron entries in declaration order.
+ * `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 declare function ignoredFunctionKeys(functionTable: unknown): IgnoredFunctionKey[];
+export declare function refusedFunctionKeyMessages(label: string, functionTable: unknown): string[];
 /**
  * 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
@@ -1584,14 +1610,6 @@ export declare function retiredDatabaseTriggerTypes(functionTable: unknown): str
  * of them would call a block and the other would not cannot exist.
  */
 export declare function hasRetiredDatabaseTriggerBlock(functionTable: unknown): boolean;
-/**
- * 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 declare function ignoredFunctionKeyWarnings(label: string, functionTable: unknown): string[];
 /**
  * The trigger blocks a function declares, derived from its authored TOML
  * (#3181, project `server-functions`, criterion 4).
@@ -1963,7 +1981,7 @@ export declare function validateSigningSecretDeclaration(input: {
  * `preflight`.
  */
 /** The rule ids this module owns — the union type below anchors them (#3373). */
-export declare const WORKFLOW_RULE_IDS: readonly ["system-access-rule"];
+export declare const WORKFLOW_RULE_IDS: readonly ["system-access-rule", "retired-database-step-kind"];
 type WorkflowRuleId = (typeof WORKFLOW_RULE_IDS)[number];
 /** A violation of one of this module's rules, for a site to render. */
 export interface WorkflowRuleViolation extends RuleRefusal<WorkflowRuleId> {
@@ -1981,6 +1999,31 @@ export declare function checkWorkflowSystemAccessRule(input: {
     runAs?: unknown;
     accessRule?: unknown;
 }): WorkflowRuleViolation | null;
+/**
+ * The DSL step kinds that executed a registered database operation (#3189,
+ * phase 6 of project `server-functions`, matrix row M8).
+ *
+ * Every `database.*` runner except `database.syncIndexes` called
+ * `DatabaseOperationsController.execute`, so retiring database operations
+ * retires these fourteen kinds with them: the seven base kinds and their seven
+ * `*ForUser` twins. `database.syncIndexes` (which calls the records index
+ * route), `database.create` and `database.delete` (resource lifecycle) are not
+ * here and keep running until the engine retires.
+ */
+export declare const RETIRED_DATABASE_STEP_KINDS: readonly ["database.query", "database.mutate", "database.count", "database.aggregate", "database.pipeline", "database.applyToQuery", "database.batch", "database.queryForUser", "database.mutateForUser", "database.countForUser", "database.aggregateForUser", "database.pipelineForUser", "database.applyToQueryForUser", "database.batchForUser"];
+/**
+ * Every step in a definition — or the one step a run has reached — whose kind
+ * is a retired database kind, with the sentence naming the replacement.
+ *
+ * Walks the top-level `steps` and a `collect` step's nested `step`, the one
+ * place a step definition nests another. Push (the CLI preflight), save, the
+ * activation lint and the engine all ask this one question, so a definition is
+ * refused by the same words wherever it is caught, and a run that reaches such
+ * a step fails with them.
+ */
+export declare function checkWorkflowRetiredStepKinds(input: {
+    steps?: unknown;
+}): WorkflowRuleViolation[];
 export declare const WORKFLOW_SURFACE: ConfigObjectSurface;
 /**
  * Cron-expression and timezone VALIDITY — the half of `src/cron-parser.ts`
@@ -2495,7 +2538,7 @@ export declare function resolvePromptStrictOutput(input: PromptStrictOutputInput
  * Pure and dependency-free, like every module under `src/config-surface/`.
  */
 /** The stable codes every agent agentRefusal this project adds carries. */
-export declare const AGENT_ERROR_CODES: readonly ["AGENT_DECLARATION_INVALID", "AGENT_TOOL_FUNCTION_MISSING", "AGENT_TOOL_FUNCTION_SCHEMA_MISSING", "AGENT_OUTPUT_SCHEMA_NOT_ALLOWED", "AGENT_CONFIG_KEY_NOT_ALLOWED", "AGENT_NOT_RUNNABLE", "AGENT_TEST_CASE_NOT_SUPPORTED", "AGENT_SCHEMA_NOT_TRANSLATABLE", "AGENT_MODEL_UNKNOWN", "AGENT_MODEL_CAPABILITY_MISSING", "AGENT_MODEL_CAPABILITIES_UNAVAILABLE", "AGENT_ROUND_NOT_AGENT", "AGENT_ROUND_INPUT_INVALID", "AGENT_TOOL_UNKNOWN", "AGENT_TOOL_ARGUMENTS_INVALID", "AGENT_ROUND_TRUNCATED", "AGENT_ROUND_EMPTY"];
+export declare const AGENT_ERROR_CODES: readonly ["AGENT_DECLARATION_INVALID", "AGENT_TOOL_FUNCTION_MISSING", "AGENT_TOOL_FUNCTION_SCHEMA_MISSING", "AGENT_OUTPUT_SCHEMA_NOT_ALLOWED", "AGENT_CONFIG_KEY_NOT_ALLOWED", "AGENT_NOT_RUNNABLE", "AGENT_TEST_CASE_NOT_SUPPORTED", "AGENT_SCHEMA_NOT_TRANSLATABLE", "AGENT_MODEL_UNKNOWN", "AGENT_MODEL_CAPABILITY_MISSING", "AGENT_MODEL_CAPABILITIES_UNAVAILABLE", "AGENT_ROUND_NOT_AGENT", "AGENT_ROUND_INPUT_INVALID", "AGENT_TOOL_UNKNOWN", "AGENT_TOOL_ARGUMENTS_INVALID", "AGENT_ROUND_TRUNCATED", "AGENT_ROUND_EMPTY", "AGENT_TEST_CASE_INVALID"];
 export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
 /** One agentRefusal: the code a client branches on, and the sentence a person reads. */
 export interface AgentRefusal {
@@ -2544,6 +2587,12 @@ export interface AgentToolDeclaration {
     approval?: boolean;
     statusText?: string;
     historyScope?: AgentToolHistoryScope;
+    /**
+     * A call to this tool ends the turn: once every call of its response is
+     * final, the turn settles with no further model round. A client tool with
+     * it is never answered — the platform records its result.
+     */
+    endsTurn?: boolean;
 }
 /** One `[[prompt.agent.events]]` entry. */
 export interface AgentEventDeclaration {
@@ -2571,7 +2620,18 @@ export interface AgentDeclaration {
 export type NormalizedAgentTool = AgentToolDeclaration & {
     approval: boolean;
     historyScope: AgentToolHistoryScope;
+    endsTurn: boolean;
+};
+/**
+ * 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 declare const AGENT_TERMINAL_CALL_OUTPUT: {
+    delivered: true;
 };
+/** The schema of `AGENT_TERMINAL_CALL_OUTPUT`: a terminal client tool's output type. */
+export declare const AGENT_TERMINAL_CALL_OUTPUT_SCHEMA: AgentSchema;
 /** The declaration with every default applied — what readers consume. */
 export interface NormalizedAgentDeclaration {
     answeredBy: AgentAnsweredBy;
@@ -2675,16 +2735,16 @@ export declare function agentNotRunnableRefusal(promptKey?: string): AgentRefusa
  */
 export declare function agentRoundNotAgentRefusal(promptKey: string): AgentRefusal;
 /**
- * The refusal of a prompt test case that involves an agent (§D1: prompt test
- * cases are refused for the kind in v1; multi-turn tests are deferred).
- * `subject` is a case written ON the agent, `evaluator` a case that names the
- * agent as its judge.
+ * 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 declare function agentTestCaseRefusal(promptKey: string, role: "subject" | "evaluator"): AgentRefusal;
+export declare function agentTestCaseRefusal(promptKey: string, _role?: "evaluator"): AgentRefusal;
 /**
  * The declaration with every default applied: `answeredBy = "initiator"`, the
  * platform maximums for the limits, and per tool `invoke = "request"` (server
- * tools), `approval = false` and `historyScope = "session"`.
+ * 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`)
@@ -2812,6 +2872,109 @@ export interface AgentSchemaTranslationInput {
  * A declaration with no tools and no events reads no function schema at all.
  */
 export declare function agentSchemaTranslationRefusals(input: AgentSchemaTranslationInput): AgentRefusal[];
+/**
+ * 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 declare const AGENT_TEST_CASE_FIELDS: readonly ["agentHistory", "agentContext", "agentTimezone", "agentLocale", "agentExpectedToolCall", "agentExpectedNoToolCall"];
+export type AgentTestCaseField = (typeof AGENT_TEST_CASE_FIELDS)[number];
+/** One call of a seeded assistant entry. */
+export interface AgentTestCall {
+    callId: string;
+    name: string;
+    arguments: unknown;
+}
+/** One entry of a seeded history, oldest first. */
+export type AgentTestHistoryEntry = {
+    role: "user";
+    text: string;
+} | {
+    role: "assistant";
+    text?: string;
+    reasoning?: string;
+    calls?: AgentTestCall[];
+} | {
+    role: "tool";
+    callId: string;
+    output: unknown;
+} | {
+    role: "tool";
+    callId: string;
+    error: {
+        code: string;
+        message: string;
+    };
+} | {
+    role: "event";
+    kind: string;
+    refersTo?: string;
+    data: unknown;
+};
+/** The `[test.agent]` block, read. */
+export interface AgentTestCase {
+    history: AgentTestHistoryEntry[];
+    context: Record<string, unknown> | null;
+    timezone: string | null;
+    locale: string | null;
+    expectedToolCall: {
+        name: string;
+        arguments?: unknown;
+    } | null;
+    /** `false` when unset: no assertion. */
+    expectedNoToolCall: boolean;
+}
+export interface AgentTestCaseInput {
+    /**
+     * The prompt's kind; unset means `chat`. The admin routes pass a block type
+     * (`workflow`, `script`, `integration`) for a case that is not a prompt's.
+     */
+    kind?: unknown;
+    /**
+     * The agent's `[prompt.agent]` (a table, one JSON string, or `null` for an
+     * agent that declares none). Omitted means "not known here": the declared
+     * names are not checked (the CLI preflight reads the sidecar alone).
+     */
+    declaration?: unknown;
+    /** The case's fields, in wire spelling (`agentHistory`, …, `expectedJsonSubset`). */
+    fields: Record<string, unknown>;
+}
+export type AgentTestCaseResolution = {
+    ok: true;
+    testCase: AgentTestCase | null;
+} | {
+    ok: false;
+    refusals: AgentRefusal[];
+};
+/**
+ * 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 declare function resolveAgentTestCase(input: AgentTestCaseInput): AgentTestCaseResolution;
 export declare const PROMPT_SURFACE: ConfigObjectSurface;
 export declare const INTEGRATION_SURFACE: ConfigObjectSurface;
 export declare const WEBHOOK_SURFACE: ConfigObjectSurface;