primitive-admin 1.2.0-alpha.6 → 1.2.0-alpha.7

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

@@ -2695,6 +2695,18 @@ export type AgentDeclarationResolution = {
  * the block the author wrote.
  */
 export declare const AGENT_BLOCK_LABEL = "[prompt.agent]";
+/**
+ * One place a declaration names a server function: the key, the tool's name
+ * for a tool, the path that makes the reference, and whether the reference
+ * needs the function's schemas (a tool's are its function's; a turn-context or
+ * history hook only needs the function to exist).
+ */
+export interface AgentFunctionReference {
+    key: string;
+    tool?: string;
+    path: string;
+    needsSchemas: boolean;
+}
 /**
  * The function keys a declaration references (tools, turn context, history),
  * each once, in declaration order. What a caller resolves into the
@@ -2712,6 +2724,39 @@ export declare const AGENT_BLOCK_LABEL = "[prompt.agent]";
  */
 export declare function parseAgentDeclarationBlock(agent: unknown): Record<string, unknown> | undefined;
 export declare function agentDeclarationFunctionKeys(agent: unknown): string[];
+/**
+ * Every function reference of a declaration (tools, turn context, history), in
+ * declaration order, with the path that makes it. `[]` for a block that is
+ * absent or does not parse. A declaration written as one JSON string is read
+ * as the object it encodes.
+ */
+export declare function agentDeclarationFunctionReferences(agent: unknown): AgentFunctionReference[];
+/**
+ * What a reference lacks: the function itself, or one of a tool's two schemas.
+ * One deficit per (reference, kind), so a comparison of two states can tell a
+ * schema restored from a schema removed without reading message text.
+ */
+export type AgentFunctionDeficitKind = "absent" | "inputSchemaMissing" | "outputSchemaMissing";
+/** One thing a function reference of a declaration lacks. */
+export interface AgentFunctionDeficit {
+    path: string;
+    tool?: string;
+    key: string;
+    kind: AgentFunctionDeficitKind;
+}
+/**
+ * Every deficit of a declaration's function references against `functions`:
+ * an absent function (`null`, or missing from the map), and for a tool a
+ * missing `inputSchema` and a missing `outputSchema`, each on its own. `[]` for
+ * a block that is absent or does not parse.
+ */
+export declare function agentFunctionDeficits(agent: unknown, functions: AgentFunctionFacts): AgentFunctionDeficit[];
+/**
+ * The refusals for a list of deficits: one `AGENT_TOOL_FUNCTION_MISSING` per
+ * absent reference, and one `AGENT_TOOL_FUNCTION_SCHEMA_MISSING` per tool
+ * reference naming every schema it lacks.
+ */
+export declare function agentFunctionDeficitRefusals(deficits: readonly AgentFunctionDeficit[]): AgentRefusal[];
 /**
  * The one rule: is this `[prompt.agent]` declaration (with the prompt's kind
  * and `outputSchema`) something the platform can run?
@@ -2872,6 +2917,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[];
+/**
+ * One schema an agent's model reads that a provider of a non-archived config
+ * cannot carry — or, for a server tool, a function schema that does not parse.
+ * The structured half of `agentSchemaTranslationRefusals`: its identity is
+ * (`subject`, `which`, `provider`, `schemaPath`, `keyword`), or (`subject`,
+ * `which`, `unparsable`), so two states can be compared without reading
+ * message text.
+ */
+export type AgentSchemaDeficit = {
+    /** `tool "propose"`, `tool "lookup" (function "ledger")` or `event "applied"`. */
+    subject: string;
+    /** `inputSchema`, `outputSchema` or `schema`. */
+    which: string;
+    provider: string;
+    /** The non-archived configs on `provider`. */
+    configNames: string[];
+    /** The dotted path from the schema root; `""` is the root. */
+    schemaPath: string;
+    keyword: string;
+    reason: string;
+} | {
+    subject: string;
+    which: string;
+    /** The function whose stored schema does not parse. */
+    unparsable: string;
+};
+/**
+ * Every deficit `agentSchemaTranslationRefusals` reports, in the same order,
+ * before it is rendered. One per (schema, path, keyword, provider), and one
+ * per server-tool schema that does not parse.
+ */
+export declare function agentSchemaTranslationDeficits(input: AgentSchemaTranslationInput): AgentSchemaDeficit[];
+/** The `AGENT_SCHEMA_NOT_TRANSLATABLE` refusal one deficit renders as. */
+export declare function agentSchemaDeficitRefusal(deficit: AgentSchemaDeficit): AgentRefusal;
+/**
+ * A change to a server function that an agent uses — issue #4441.
+ *
+ * An agent names server functions as its tools, its turn-context hook and its
+ * history hook. The agent's own writes are checked against those functions
+ * (`resolveAgentDeclaration`, `agentSchemaTranslationRefusals`), but a change
+ * to the FUNCTION — archiving it, deleting it, changing its schemas — used to
+ * be accepted and fail at the agent's next turn. This module is the rule for
+ * that change: given one agent's declaration and configs, and the functions it
+ * names before and after the change, which refusals does the change introduce?
+ *
+ * The admin function routes refuse such a change with `FUNCTION_USED_BY_AGENT`,
+ * and `config push`'s preflight runs the same rule through the vendored
+ * artifact, so the two cannot disagree.
+ *
+ * ONLY WHAT THE CHANGE INTRODUCES. Both states are reduced to structured
+ * deficits (`agentFunctionDeficits`, `agentSchemaTranslationDeficits`) and the
+ * ones already present before the change are dropped. An agent that is broken
+ * for another reason does not block an unrelated change, and a partial repair
+ * — restoring one of two missing schemas, removing one of two `$ref`s — is
+ * accepted. Messages are rendered only afterwards, by the sibling rules' own
+ * builders, so they read exactly as an agent write's refusals do.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/** The code a function route answers when an agent cannot take the change. */
+export declare const FUNCTION_USED_BY_AGENT = "FUNCTION_USED_BY_AGENT";
+/** One agent, and the functions it names before and after a change to them. */
+export interface AgentFunctionChangeInput {
+    /** `[prompt.agent]` as stored: a table, or one JSON string encoding one. */
+    declaration: unknown;
+    /** Every config of the agent's prompt. Archived ones are skipped. */
+    configs: ReadonlyArray<AgentSchemaConfigFact>;
+    /** What the app holds for each function the declaration names, now. */
+    before: AgentFunctionFacts;
+    /** The same, as the change would leave it. */
+    after: AgentFunctionFacts;
+}
+/**
+ * Every refusal the change introduces for this agent: a reference whose
+ * function goes away (`AGENT_TOOL_FUNCTION_MISSING`), a tool schema that goes
+ * away (`AGENT_TOOL_FUNCTION_SCHEMA_MISSING`), and a schema a non-archived
+ * config's provider cannot carry where the previous one could
+ * (`AGENT_SCHEMA_NOT_TRANSLATABLE`). `[]` when the agent can take the change,
+ * and for a declaration that does not parse (it names nothing).
+ */
+export declare function agentFunctionChangeRefusals(input: AgentFunctionChangeInput): AgentRefusal[];
+/**
+ * How an agent uses one function: each tool's name (or its path when the tool
+ * has none), and `turnContext.function` / `history.function` for a hook, in
+ * declaration order. `[]` when the declaration does not name the function.
+ */
+export declare function agentFunctionUses(declaration: unknown, functionKey: string): string[];
+/** What a function route was asked to do. */
+export type FunctionChangeKind = "archive" | "delete" | "schema";
+/** One agent a function change would break. */
+export interface FunctionUsedByAgent {
+    promptKey: string;
+    /** `agentFunctionUses` of the changed function. */
+    tools: string[];
+    /** The refusals the change introduces for this agent. */
+    refusals: ReadonlyArray<AgentRefusal>;
+}
+/**
+ * The sentence a function route refuses with: the function, then one sentence
+ * per agent naming its key and each use, then the remedy. A schema change also
+ * carries each agent's refusals, since the remedy depends on which schema broke.
+ */
+export declare function functionUsedByAgentMessage(functionKey: string, change: FunctionChangeKind, agents: ReadonlyArray<FunctionUsedByAgent>): string;
 /**
  * What an agent test case may say — issue #4262 (single-round prompt tests
  * from a seeded history; design-docs/agents.md §D1).

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

@@ -6255,35 +6255,82 @@ export function agentDeclarationFunctionKeys(agent) {
         return [];
     return [...new Set(agentFunctionReferences(parsed).map((ref) => ref.key))];
 }
-function agentFunctionRefusals(agent, functions) {
+/**
+ * Every function reference of a declaration (tools, turn context, history), in
+ * declaration order, with the path that makes it. `[]` for a block that is
+ * absent or does not parse. A declaration written as one JSON string is read
+ * as the object it encodes.
+ */
+export function agentDeclarationFunctionReferences(agent) {
+    const parsed = parseAgentBlock(agent);
+    return parsed ? agentFunctionReferences(parsed) : [];
+}
+/**
+ * Every deficit of a declaration's function references against `functions`:
+ * an absent function (`null`, or missing from the map), and for a tool a
+ * missing `inputSchema` and a missing `outputSchema`, each on its own. `[]` for
+ * a block that is absent or does not parse.
+ */
+export function agentFunctionDeficits(agent, functions) {
     const out = [];
-    for (const ref of agentFunctionReferences(agent)) {
-        const subject = ref.tool
-            ? `tool "${ref.tool}" (${ref.path})`
-            : ref.path;
+    for (const ref of agentDeclarationFunctionReferences(agent)) {
+        const at = {
+            path: ref.path,
+            ...(ref.tool !== undefined ? { tool: ref.tool } : {}),
+            key: ref.key,
+        };
         const facts = Object.prototype.hasOwnProperty.call(functions, ref.key)
             ? functions[ref.key]
             : null;
         if (!facts) {
-            out.push(agentRefusal("AGENT_TOOL_FUNCTION_MISSING", `${AGENT_BLOCK} ${subject} names function "${ref.key}", which this app ` +
-                "does not have. Push the function first, or include its file in " +
-                "this push"));
+            out.push({ ...at, kind: "absent" });
             continue;
         }
         if (!ref.needsSchemas)
             continue;
-        const missing = [
-            facts.hasInputSchema ? null : "inputSchema",
-            facts.hasOutputSchema ? null : "outputSchema",
-        ].filter((name) => name !== null);
+        if (!facts.hasInputSchema)
+            out.push({ ...at, kind: "inputSchemaMissing" });
+        if (!facts.hasOutputSchema)
+            out.push({ ...at, kind: "outputSchemaMissing" });
+    }
+    return out;
+}
+/**
+ * The refusals for a list of deficits: one `AGENT_TOOL_FUNCTION_MISSING` per
+ * absent reference, and one `AGENT_TOOL_FUNCTION_SCHEMA_MISSING` per tool
+ * reference naming every schema it lacks.
+ */
+export function agentFunctionDeficitRefusals(deficits) {
+    const out = [];
+    const byPath = new Map();
+    for (const deficit of deficits) {
+        const list = byPath.get(deficit.path);
+        if (list)
+            list.push(deficit);
+        else
+            byPath.set(deficit.path, [deficit]);
+    }
+    for (const list of byPath.values()) {
+        const { path, tool, key } = list[0];
+        const subject = tool ? `tool "${tool}" (${path})` : path;
+        if (list.some((deficit) => deficit.kind === "absent")) {
+            out.push(agentRefusal("AGENT_TOOL_FUNCTION_MISSING", `${AGENT_BLOCK} ${subject} names function "${key}", which this app ` +
+                "does not have. Push the function first, or include its file in " +
+                "this push"));
+            continue;
+        }
+        const missing = ["inputSchema", "outputSchema"].filter((name) => list.some((deficit) => deficit.kind === `${name}Missing`));
         if (missing.length > 0) {
-            out.push(agentRefusal("AGENT_TOOL_FUNCTION_SCHEMA_MISSING", `${AGENT_BLOCK} ${subject} names function "${ref.key}", which declares ` +
+            out.push(agentRefusal("AGENT_TOOL_FUNCTION_SCHEMA_MISSING", `${AGENT_BLOCK} ${subject} names function "${key}", which declares ` +
                 `no ${missing.join(" or ")}. A tool's schemas are its function's: ` +
-                `declare ${missing.join(" and ")} in functions/${ref.key}.toml`));
+                `declare ${missing.join(" and ")} in functions/${key}.toml`));
         }
     }
     return out;
 }
+function agentFunctionRefusals(agent, functions) {
+    return agentFunctionDeficitRefusals(agentFunctionDeficits(agent, functions));
+}
 /**
  * The one rule: is this `[prompt.agent]` declaration (with the prompt's kind
  * and `outputSchema`) something the platform can run?
@@ -7068,6 +7115,14 @@ function configList(configNames) {
  * A declaration with no tools and no events reads no function schema at all.
  */
 export function agentSchemaTranslationRefusals(input) {
+    return agentSchemaTranslationDeficits(input).map(agentSchemaDeficitRefusal);
+}
+/**
+ * Every deficit `agentSchemaTranslationRefusals` reports, in the same order,
+ * before it is rendered. One per (schema, path, keyword, provider), and one
+ * per server-tool schema that does not parse.
+ */
+export function agentSchemaTranslationDeficits(input) {
     const declaration = parseAgentDeclarationBlock(input.declaration);
     if (!declaration)
         return [];
@@ -7081,11 +7136,9 @@ export function agentSchemaTranslationRefusals(input) {
     for (const subject of subjects) {
         if (subject.unparsable !== undefined) {
             out.push({
-                code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
-                message: `${AGENT_BLOCK_LABEL} ${subject.subject} ${subject.which} is not a ` +
-                    `JSON Schema the platform can read, so it cannot be translated for ` +
-                    `any provider. Fix ${subject.which} in ` +
-                    `functions/${subject.unparsable}.toml`,
+                subject: subject.subject,
+                which: subject.which,
+                unparsable: subject.unparsable,
             });
             continue;
         }
@@ -7095,18 +7148,148 @@ export function agentSchemaTranslationRefusals(input) {
                 continue;
             for (const refusal of result.refusals) {
                 out.push({
-                    code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
-                    message: `${AGENT_BLOCK_LABEL} ${subject.subject} ${subject.which} at ` +
-                        `${schemaPathLabel(refusal.path)}: ${refusal.keyword} cannot be ` +
-                        `translated for ${provider} without losing meaning — ` +
-                        `${refusal.reason}. ${configList(configNames)} run on ${provider}; ` +
-                        `rewrite the schema, or archive every ${provider} config of this prompt`,
+                    subject: subject.subject,
+                    which: subject.which,
+                    provider,
+                    configNames,
+                    schemaPath: refusal.path,
+                    keyword: refusal.keyword,
+                    reason: refusal.reason,
                 });
             }
         }
     }
     return out;
 }
+/** The `AGENT_SCHEMA_NOT_TRANSLATABLE` refusal one deficit renders as. */
+export function agentSchemaDeficitRefusal(deficit) {
+    if ("unparsable" in deficit) {
+        return {
+            code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
+            message: `${AGENT_BLOCK_LABEL} ${deficit.subject} ${deficit.which} is not a ` +
+                `JSON Schema the platform can read, so it cannot be translated for ` +
+                `any provider. Fix ${deficit.which} in ` +
+                `functions/${deficit.unparsable}.toml`,
+        };
+    }
+    const { provider } = deficit;
+    return {
+        code: "AGENT_SCHEMA_NOT_TRANSLATABLE",
+        message: `${AGENT_BLOCK_LABEL} ${deficit.subject} ${deficit.which} at ` +
+            `${schemaPathLabel(deficit.schemaPath)}: ${deficit.keyword} cannot be ` +
+            `translated for ${provider} without losing meaning — ` +
+            `${deficit.reason}. ${configList(deficit.configNames)} run on ${provider}; ` +
+            `rewrite the schema, or archive every ${provider} config of this prompt`,
+    };
+}
+// ── src/config-surface/agent-function-change.ts ──────────────────────────
+/**
+ * A change to a server function that an agent uses — issue #4441.
+ *
+ * An agent names server functions as its tools, its turn-context hook and its
+ * history hook. The agent's own writes are checked against those functions
+ * (`resolveAgentDeclaration`, `agentSchemaTranslationRefusals`), but a change
+ * to the FUNCTION — archiving it, deleting it, changing its schemas — used to
+ * be accepted and fail at the agent's next turn. This module is the rule for
+ * that change: given one agent's declaration and configs, and the functions it
+ * names before and after the change, which refusals does the change introduce?
+ *
+ * The admin function routes refuse such a change with `FUNCTION_USED_BY_AGENT`,
+ * and `config push`'s preflight runs the same rule through the vendored
+ * artifact, so the two cannot disagree.
+ *
+ * ONLY WHAT THE CHANGE INTRODUCES. Both states are reduced to structured
+ * deficits (`agentFunctionDeficits`, `agentSchemaTranslationDeficits`) and the
+ * ones already present before the change are dropped. An agent that is broken
+ * for another reason does not block an unrelated change, and a partial repair
+ * — restoring one of two missing schemas, removing one of two `$ref`s — is
+ * accepted. Messages are rendered only afterwards, by the sibling rules' own
+ * builders, so they read exactly as an agent write's refusals do.
+ *
+ * Pure and dependency-free, like every module under `src/config-surface/`.
+ */
+/** The code a function route answers when an agent cannot take the change. */
+export const FUNCTION_USED_BY_AGENT = "FUNCTION_USED_BY_AGENT";
+function functionDeficitIdentity(deficit) {
+    return `${deficit.path}\u0000${deficit.kind}`;
+}
+function schemaDeficitIdentity(deficit) {
+    if ("unparsable" in deficit) {
+        return [deficit.subject, deficit.which, "unparsable", deficit.unparsable].join("\u0000");
+    }
+    return [
+        deficit.subject,
+        deficit.which,
+        deficit.provider,
+        deficit.schemaPath,
+        deficit.keyword,
+    ].join("\u0000");
+}
+/**
+ * Every refusal the change introduces for this agent: a reference whose
+ * function goes away (`AGENT_TOOL_FUNCTION_MISSING`), a tool schema that goes
+ * away (`AGENT_TOOL_FUNCTION_SCHEMA_MISSING`), and a schema a non-archived
+ * config's provider cannot carry where the previous one could
+ * (`AGENT_SCHEMA_NOT_TRANSLATABLE`). `[]` when the agent can take the change,
+ * and for a declaration that does not parse (it names nothing).
+ */
+export function agentFunctionChangeRefusals(input) {
+    const { declaration, configs, before, after } = input;
+    if (agentDeclarationFunctionReferences(declaration).length === 0)
+        return [];
+    const functionBefore = new Set(agentFunctionDeficits(declaration, before).map(functionDeficitIdentity));
+    const functionIntroduced = agentFunctionDeficits(declaration, after).filter((deficit) => !functionBefore.has(functionDeficitIdentity(deficit)));
+    const schemaBefore = new Set(agentSchemaTranslationDeficits({ declaration, functions: before, configs }).map(schemaDeficitIdentity));
+    const schemaIntroduced = agentSchemaTranslationDeficits({
+        declaration,
+        functions: after,
+        configs,
+    }).filter((deficit) => !schemaBefore.has(schemaDeficitIdentity(deficit)));
+    return [
+        ...agentFunctionDeficitRefusals(functionIntroduced),
+        ...schemaIntroduced.map(agentSchemaDeficitRefusal),
+    ];
+}
+/**
+ * How an agent uses one function: each tool's name (or its path when the tool
+ * has none), and `turnContext.function` / `history.function` for a hook, in
+ * declaration order. `[]` when the declaration does not name the function.
+ */
+export function agentFunctionUses(declaration, functionKey) {
+    return agentDeclarationFunctionReferences(declaration)
+        .filter((ref) => ref.key === functionKey)
+        .map((ref) => ref.tool ?? ref.path);
+}
+/** `tool "lookup"` for a tool's name, the path itself for a hook. */
+function useLabel(use) {
+    return use.includes(".") ? use : `tool "${use}"`;
+}
+/**
+ * The sentence a function route refuses with: the function, then one sentence
+ * per agent naming its key and each use, then the remedy. A schema change also
+ * carries each agent's refusals, since the remedy depends on which schema broke.
+ */
+export function functionUsedByAgentMessage(functionKey, change, agents) {
+    const verb = change === "archive"
+        ? "cannot be archived"
+        : change === "delete"
+            ? "cannot be deleted"
+            : "cannot take this schema change";
+    const uses = agents.map((agent) => {
+        const labels = agent.tools.map(useLabel).join(", ");
+        const why = change === "schema" && agent.refusals.length > 0
+            ? `: ${agent.refusals.map((refusal) => refusal.message).join("; ")}`
+            : "";
+        return `It is used by agent "${agent.promptKey}" as ${labels}${why}.`;
+    });
+    const files = agents.map((agent) => `prompts/${agent.promptKey}.toml`).join(", ");
+    const remedy = change === "schema"
+        ? `Change the agent in the same push (${files}) so it no longer needs ` +
+            "what this change removes, or retire the agent, then retry."
+        : `Remove the reference from [prompt.agent] in ${files} and push it, or ` +
+            "retire the agent, then retry.";
+    return `Function "${functionKey}" ${verb} while an agent uses it. ${uses.join(" ")} ${remedy}`;
+}
 // ── src/config-surface/agent-test-case.ts ────────────────────────────────
 /**
  * What an agent test case may say — issue #4262 (single-round prompt tests