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

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

@@ -5875,6 +5875,9 @@ export const AGENT_ERROR_CODES = [
     // #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",
+    // #4549 — a presentation call whose `references` name a number that is not
+    // an earlier call of the turn with a result.
+    "AGENT_PRESENTATION_REFERENCE_INVALID",
 ];
 /**
  * The platform maximums. An agent may lower `maxSteps`, `waitLimitSeconds`
@@ -5900,14 +5903,20 @@ 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.
+ * Where a tool without a `function` runs: `client` is answered by a member's
+ * client; `presentation` is data the model hands the client with its final
+ * answer, which no client executes (#4549).
+ */
+export const AGENT_TOOL_RUNS = ["client", "presentation"];
+/**
+ * The result the platform records for a presentation call: 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. */
+/** The schema of `AGENT_TERMINAL_CALL_OUTPUT`, the result a presentation call is recorded with. */
 export const AGENT_TERMINAL_CALL_OUTPUT_SCHEMA = Object.freeze({
     type: "object",
     properties: { delivered: { type: "boolean" } },
@@ -5935,6 +5944,7 @@ const AGENT_TOOL_KEYS = [
     "statusText",
     "historyScope",
     "endsTurn",
+    "references",
     "inputSchema",
     "outputSchema",
 ];
@@ -6030,6 +6040,71 @@ function checkAgentName(value, path, seen, what, out) {
     }
     seen.add(value);
 }
+/** Whether a property schema holds one integer, or a list of integers. */
+function agentIsReferenceProperty(schema) {
+    if (!agentIsPlainObject(schema))
+        return false;
+    if (schema.type === "integer")
+        return true;
+    return (schema.type === "array" &&
+        agentIsPlainObject(schema.items) &&
+        schema.items.type === "integer");
+}
+/**
+ * A presentation (#4549): its `inputSchema` is required, the keys of a call
+ * that runs or pauses are refused, and each `references` entry names a
+ * top-level input property declared as an integer or a list of integers.
+ */
+function checkAgentPresentation(tool, path, out) {
+    const notDeclared = [
+        ["outputSchema", "the platform records a presentation call's result"],
+        ["approval", "a presentation call never pauses"],
+        ["endsTurn", "a presentation call always ends the turn"],
+    ];
+    for (const [key, why] of notDeclared) {
+        if (tool[key] !== undefined) {
+            out.push(agentInvalid(`${path}.${key}`, `is not declared on a presentation: ${why} — remove it`));
+        }
+    }
+    const schemaPath = `${path}.inputSchema`;
+    if (tool.inputSchema === undefined) {
+        out.push(agentInvalid(schemaPath, "is required on a presentation"));
+    }
+    else {
+        const error = agentSchemaError(tool.inputSchema, schemaPath);
+        if (error)
+            out.push(error);
+    }
+    if (tool.references === undefined)
+        return;
+    const referencesPath = `${path}.references`;
+    const references = tool.references;
+    if (!Array.isArray(references) ||
+        references.length === 0 ||
+        !references.every((name) => agentIsNonEmptyString(name))) {
+        out.push(agentInvalid(referencesPath, "must be a non-empty list of input property names, each holding an " +
+            "integer or a list of integers"));
+        return;
+    }
+    const seen = new Set();
+    const properties = agentIsPlainObject(tool.inputSchema) && agentIsPlainObject(tool.inputSchema.properties)
+        ? tool.inputSchema.properties
+        : {};
+    for (const name of references) {
+        if (seen.has(name)) {
+            out.push(agentInvalid(referencesPath, `repeats "${name}"; each property is named once`));
+            continue;
+        }
+        seen.add(name);
+        if (!Object.prototype.hasOwnProperty.call(properties, name)) {
+            out.push(agentInvalid(referencesPath, `names "${name}", which inputSchema.properties does not declare`));
+        }
+        else if (!agentIsReferenceProperty(properties[name])) {
+            out.push(agentInvalid(referencesPath, `names "${name}", which must be declared as { type = "integer" } or ` +
+                'a list of them ({ type = "array", items = { type = "integer" } })'));
+        }
+    }
+}
 function checkAgentTool(tool, index, names, out) {
     const path = `tools[${index}]`;
     if (!agentIsPlainObject(tool)) {
@@ -6045,52 +6120,61 @@ function checkAgentTool(tool, index, names, out) {
     const hasRuns = tool.runs !== undefined;
     if (hasFunction === hasRuns) {
         out.push(agentInvalid(path, hasFunction
-            ? 'sets both function and runs; a tool is a server tool (function = "<key>") or a client tool (runs = "client"), not both'
-            : 'needs function = "<key>" (a server tool) or runs = "client" (a client tool)'));
+            ? 'sets both function and runs; a tool is a server tool (function = "<key>"), a client tool (runs = "client") or a presentation (runs = "presentation"), not more than one'
+            : 'needs function = "<key>" (a server tool), runs = "client" (a client tool) or runs = "presentation" (a presentation)'));
     }
-    if (hasRuns && tool.runs !== "client") {
-        out.push(agentInvalid(`${path}.runs`, `must be "client"; found ${JSON.stringify(tool.runs)}`));
+    if (hasRuns && !AGENT_TOOL_RUNS.includes(tool.runs)) {
+        out.push(agentInvalid(`${path}.runs`, `must be ${AGENT_TOOL_RUNS.map((runs) => JSON.stringify(runs)).join(" or ")}; found ${JSON.stringify(tool.runs)}`));
     }
     if (hasFunction && !agentIsNonEmptyString(tool.function)) {
         out.push(agentInvalid(`${path}.function`, "must name a server function by key"));
     }
-    const isClient = hasRuns && !hasFunction;
+    const isClient = hasRuns && !hasFunction && tool.runs === "client";
+    const isPresentation = hasRuns && !hasFunction && tool.runs === "presentation";
     if (tool.invoke !== undefined) {
-        if (isClient) {
-            out.push(agentInvalid(`${path}.invoke`, "is for server tools; a client tool is answered by a member's client"));
+        if (isClient || isPresentation) {
+            out.push(agentInvalid(`${path}.invoke`, isClient
+                ? "is for server tools; a client tool is answered by a member's client"
+                : "is for server tools; a presentation is never executed"));
         }
         else if (!AGENT_TOOL_INVOKE.includes(tool.invoke)) {
             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"));
+    if (isPresentation) {
+        checkAgentPresentation(tool, path, out);
     }
-    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"));
+    else {
+        const terminal = tool.endsTurn === true;
+        if (tool.endsTurn !== undefined && typeof tool.endsTurn !== "boolean") {
+            out.push(agentInvalid(`${path}.endsTurn`, "must be true or false"));
+        }
+        else if (isClient && terminal) {
+            out.push(agentInvalid(`${path}.endsTurn`, "cannot be set on a client tool: a client tool is answered by a " +
+                "member's client; for data the model hands the client with its " +
+                'answer, declare runs = "presentation"'));
+        }
+        else if (terminal && tool.approval === true) {
+            out.push(agentInvalid(`${path}.endsTurn`, "cannot be set with approval = true: a terminal call never pauses"));
+        }
+        if (tool.references !== undefined) {
+            out.push(agentInvalid(`${path}.references`, 'is declared only on a presentation (runs = "presentation")'));
+        }
+        for (const key of ["inputSchema", "outputSchema"]) {
+            const schemaPath = `${path}.${key}`;
+            if (isClient) {
+                if (tool[key] === undefined) {
+                    out.push(agentInvalid(schemaPath, "is required on a client tool"));
+                    continue;
+                }
+                const error = agentSchemaError(tool[key], schemaPath);
+                if (error)
+                    out.push(error);
             }
-            continue;
-        }
-        if (isClient) {
-            if (tool[key] === undefined) {
-                out.push(agentInvalid(schemaPath, "is required on a client tool"));
-                continue;
+            else if (hasFunction && tool[key] !== undefined) {
+                out.push(agentInvalid(schemaPath, "is not declared on a server tool; its function's schemas are the " +
+                    "tool's (one source of truth) — remove it"));
             }
-            const error = agentSchemaError(tool[key], schemaPath);
-            if (error)
-                out.push(error);
-        }
-        else if (hasFunction && tool[key] !== undefined) {
-            out.push(agentInvalid(schemaPath, "is not declared on a server tool; its function's schemas are the " +
-                "tool's (one source of truth) — remove it"));
         }
     }
     if (tool.approval !== undefined && typeof tool.approval !== "boolean") {
@@ -6409,6 +6493,39 @@ 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");
 }
+/** The integers a call's argument holds under one referencing property. */
+function referencedNumbers(value) {
+    const values = Array.isArray(value) ? value : [value];
+    return values.filter((v) => typeof v === "number" && Number.isInteger(v));
+}
+/**
+ * The refusal of a presentation call whose `references` name a number that
+ * is not an earlier call of the turn with a result — a refused call, a number
+ * the turn never gave, or a call of the same response — or `null`. `earlier`
+ * is the turn's calls committed before this call's response. The message
+ * lists the offending values by property and the numbers that may be
+ * referenced, with their tools, so the model can correct itself next round.
+ */
+export function presentationReferenceRefusal(tool, args, earlier) {
+    if (!tool.references?.length || !agentIsPlainObject(args))
+        return null;
+    const valid = earlier.filter((call) => call.state === "output-available");
+    const validNumbers = new Set(valid.map((call) => call.callNumber));
+    const offending = [];
+    for (const property of tool.references) {
+        const bad = [...new Set(referencedNumbers(args[property]).filter((n) => !validNumbers.has(n)))];
+        if (bad.length > 0)
+            offending.push(`${property}: ${bad.join(", ")}`);
+    }
+    if (offending.length === 0)
+        return null;
+    const choices = valid.length > 0
+        ? `Reference one of: ${valid.map((call) => `${call.callNumber} (${call.toolName})`).join(", ")}`
+        : "No earlier call of this turn has a result to reference";
+    return agentRefusal("AGENT_PRESENTATION_REFERENCE_INVALID", `The call to "${tool.name}" references calls this turn has no result for ` +
+        `(${offending.join("; ")}). A reference is the \`call\` number of an ` +
+        `earlier tool result of this turn. ${choices}`);
+}
 /** A deep copy, so a reader's defaults never reach the caller's value. */
 function agentCopy(value) {
     return value === undefined ? value : JSON.parse(JSON.stringify(value));
@@ -6416,7 +6533,8 @@ 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`, `historyScope = "session"` and `endsTurn = false`.
+ * tools), `approval = false`, `historyScope = "session"` and `endsTurn = false`
+ * — `endsTurn = true` for a presentation, whose call always ends the turn.
  *
  * The ONLY accessor for defaults — the stored value never carries them
  * (DSO-3798-001). Takes a value `resolveAgentDeclaration` accepted (or `null`)
@@ -6433,10 +6551,10 @@ export function normalizeAgentDeclaration(declaration) {
         history: source.history ?? null,
         tools: (source.tools ?? []).map((tool) => ({
             ...tool,
-            ...(tool.runs === "client" ? {} : { invoke: tool.invoke ?? "request" }),
+            ...(tool.runs === undefined ? { invoke: tool.invoke ?? "request" } : {}),
             approval: tool.approval ?? false,
             historyScope: tool.historyScope ?? "session",
-            endsTurn: tool.endsTurn ?? false,
+            endsTurn: tool.runs === "presentation" ? true : (tool.endsTurn ?? false),
         })),
         events: source.events ?? [],
     };
@@ -10564,8 +10682,10 @@ export const TEST_CASE_SURFACE = {
  * explicit classification the secret-adjacent rule requires — the guard fails
  * on a bare omission, not on a stated reference-only contract.
  *
- * As of #2891 nothing here is writable-but-unauthorable. `notExposed` carries
- * no `deprecated` entry and no withheld-on-read field: the five superseded keys
+ * As of #2891 nothing here is writable-but-unauthorable but one key: the
+ * `protected` boolean (#3886) the protection level replaced in #4564 is a
+ * `deprecated` entry, still accepted on write and never emitted, until its
+ * scheduled retirement. There is no withheld-on-read field: the five superseded keys
  * (`googleClientId`, `googleClientSecret`, `redirectUris`, `passkeyRpId`,
  * `passkeyRpName`) stay DECLARED in `models.yaml` so a row's storage can still
  * be read, but no write path accepts them and no serializer emits them, which
@@ -10668,21 +10788,29 @@ export const APP_SETTINGS_SURFACE = {
                     validation: handledBy(SETTINGS_HANDLER, "SettingsController", "apply"),
                 },
                 {
-                    field: "protected",
-                    tomlKey: "protected",
-                    type: "boolean",
-                    // Always: a pulled file states whether the app is live with real
-                    // users, rather than leaving it to the absence of a key (#3886).
+                    field: "protection",
+                    tomlKey: "protection",
+                    type: "string",
+                    // Always: a pulled file states the app's protection level, rather
+                    // than leaving it to the absence of a key (#4564).
                     emit: "always",
                     writableOn: UPDATE_ONLY,
-                    // Strict boolean, and only the app's console owner or a super-admin
-                    // may CHANGE it; a body carrying the stored value is a no-op for
-                    // anyone the route admits (`resolveProtectedFlagWrite`,
+                    // One of `default`, `protected` and `internal`, and only the app's
+                    // console owner or a super-admin may CHANGE it; a body carrying the
+                    // stored level is a no-op for anyone the route admits, and a child's
+                    // level is fixed at `internal` (`resolveProtectionWrite`,
                     // `src/services/protected-app.ts`).
                     validation: handledBy(SETTINGS_HANDLER, "SettingsController", "apply"),
                 },
             ],
             notExposed: {
+                protected: {
+                    kind: "deprecated",
+                    note: "The boolean the protection level replaced (#3886, #4564). Still " +
+                        "accepted on write, where `true` reads as `protection = \"protected\"` " +
+                        "and `false` as not protected, and kept in step with every level " +
+                        "write; never emitted. Use `[app].protection`.",
+                },
                 appId: {
                     kind: "server-owned",
                     note: "The app's id; taken from the route, never authored.",
@@ -11173,6 +11301,7 @@ export const GENERATED_CONFIG_MODEL_FIELDS = {
         "memberInvitationLimit",
         "largeDocumentWindowDays",
         "rootDocumentFormat",
+        "protection",
         "protected",
         "parentAppId",
         "childSlug",