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

package/dist/src/commands/sync.d.ts

@@ -4,7 +4,8 @@ import { type PullWriteTally } from "../lib/pull-write.js";
 import { type PushMode } from "../lib/config-payload.js";
 import { type ConfigObjectSurface, type ConfigTable } from "../lib/generated-config-surfaces.js";
 import { type PromptKind } from "../lib/generated-config-surfaces.js";
-import { type AgentFunctionFacts } from "../lib/generated-config-surfaces.js";
+import { type AgentFunctionFact, type AgentFunctionFacts } from "../lib/generated-config-surfaces.js";
+import { type AgentSchemaConfigFact } from "../lib/generated-config-surfaces.js";
 import { type DocumentSchemaResolution } from "../lib/function-document-types.js";
 import { type PresenceOutcome, type TestBlockType } from "../lib/sync-resource-types.js";
 export { resolveSlugCollisions, slugifyTestCaseName, testCaseFileBasenames, } from "../lib/test-case-file-names.js";
@@ -324,6 +325,10 @@ export declare function validateWebhookCapForPush(localKeys: string[], remoteKey
  */
 export declare function validateVarsFile(parsedVars: Record<string, unknown>, options?: {
     onlyKeys?: ReadonlySet<string>;
+    /** The file the entries came from, for the messages (#4485). */
+    fileName?: string;
+    /** Skip the count cap — the caller measures it on a layered set (#4485). */
+    skipCountCap?: boolean;
 }): string[];
 /**
  * Plan the config-var writes a `config push` should make, detecting concurrent
@@ -428,7 +433,12 @@ export declare function countVarsAfterPush(remoteVars: Array<{
  * local value). Pure and side-effect-free so it's unit-testable without a live
  * server.
  */
-export declare function diffVars(localVars: Map<string, string>, remoteVars: Map<string, string>): Array<{
+export declare function diffVars(localVars: Map<string, string>, remoteVars: Map<string, string>, 
+/**
+ * The file `config pull` would write a server value into — a machine-local
+ * environment's override file (#4485). Defaults to `vars.toml`.
+ */
+pullTargetFile?: string): Array<{
     type: "var";
     key: string;
     status: string;
@@ -958,9 +968,18 @@ export declare function runConfigPushPreflight(input: {
      * tree's, never this app's, so it is out of the validated body.
      */
     localEnvironment?: boolean;
-    client: Pick<ApiClient, "listIntegrations" | "listFunctions">;
+    client: Pick<ApiClient, "listIntegrations" | "listFunctions" | "listPrompts" | "listPromptConfigs">;
+    /** #4485 — the environment's vars override file, layered over vars.toml. */
+    varsOverridePath?: string | null;
 }): Promise<{
     parsedVars: Record<string, unknown> | null;
+    /** #4441 — agent files to apply before the functions leg. */
+    agentFilesFirst: string[];
+    /** #4485 — which override keys replace or add, when an override was read. */
+    varsOverrideKeys: {
+        overridingKeys: string[];
+        addedKeys: string[];
+    } | null;
 }>;
 export declare function promptKindFileErrors(filePath: string, tomlData: any): string[];
 /**
@@ -990,6 +1009,90 @@ export declare function agentFunctionFactsForPush(input: {
     facts: AgentFunctionFacts;
     liveListed: boolean;
 };
+/**
+ * The functions the app holds now, as the agent rules read them — #3798. A
+ * live row that is archived is a tombstone, not a function, so it is absent.
+ */
+export declare function liveAgentFunctionFacts(live: ReadonlyArray<Record<string, unknown>> | null): Record<string, AgentFunctionFact>;
+/** A selected `functions/<file>` and the key push resolves it to. */
+export interface FunctionChangePreflightFile {
+    file: string;
+    key: string;
+}
+/** A prompt of the app's live listing, as `functionChangePreflight` reads it. */
+export interface FunctionChangePreflightPrompt {
+    promptId: string;
+    promptKey: string;
+    kind?: unknown;
+    status?: unknown;
+    /** `[prompt.agent]` as stored. */
+    agent?: unknown;
+}
+/** A selected agent prompt file. */
+export interface FunctionChangePreflightAgentFile {
+    /** The file name under `prompts/`. */
+    file: string;
+    promptKey: string;
+    /** The parsed file. */
+    tomlData: any;
+}
+/** What `functionChangePreflight` reads: everything the push already listed or parsed. */
+export interface FunctionChangePreflightInput {
+    /** The function files this push selects. */
+    selectedFunctionFiles: ReadonlyArray<FunctionChangePreflightFile>;
+    /** The functions the app holds now (`liveAgentFunctionFacts`). */
+    live: AgentFunctionFacts;
+    /** What this push believes: the live functions overlaid by the selected files. */
+    pushed: AgentFunctionFacts;
+    /** The app's prompts, or `null` when they could not be listed. */
+    prompts: ReadonlyArray<FunctionChangePreflightPrompt> | null;
+    /** Every config of each live agent that names a changed function, by `promptId`. */
+    configsOf: ReadonlyMap<string, ReadonlyArray<AgentSchemaConfigFact>>;
+    /** The agent prompt files this push selects. */
+    selectedAgentFiles: ReadonlyArray<FunctionChangePreflightAgentFile>;
+}
+/** The preflight errors, the warnings, and the agent files to apply first. */
+export interface FunctionChangePreflightResult {
+    errors: string[];
+    warnings: string[];
+    /** Agent files to apply before the server-functions leg (`partitionPromptFilesForPush`). */
+    agentFilesFirst: string[];
+}
+/**
+ * The selected function files that CHANGE a live function — #4441. A file
+ * whose function is not live creates it, which no agent can depend on yet.
+ * The push lists the app's prompts only when this is non-empty.
+ */
+export declare function functionChangePreflightKeys(selectedFunctionFiles: ReadonlyArray<FunctionChangePreflightFile>, live: AgentFunctionFacts): FunctionChangePreflightFile[];
+/**
+ * The live, non-archived agent prompts that name at least one of `keys`.
+ * Whose configs the push reads for `functionChangePreflight`.
+ */
+export declare function functionChangePreflightAgents(prompts: ReadonlyArray<FunctionChangePreflightPrompt>, keys: ReadonlyArray<string>): FunctionChangePreflightPrompt[];
+/**
+ * Would a function change this push makes break a live agent? — #4441.
+ *
+ * The same rule the function routes run (`agentFunctionChangeRefusals`), so a
+ * change the preflight lets through is one the server accepts, run for every
+ * selected file that changes a live function against every live non-archived
+ * agent that names it, with every config of that agent:
+ *
+ *  - an agent whose prompt file this push does NOT select would be broken by
+ *    the change: a preflight error naming the function file, the agent and its
+ *    uses, and the remedy (change the agent in the same push, or retire it);
+ *  - an agent whose file IS selected keeps the existing order (applied after
+ *    the functions leg) unless its LIVE declaration would be broken by the
+ *    change. Then the file must go first to release the reference, which it
+ *    can only do when it is valid against the functions the app holds NOW —
+ *    its references, the providers of its non-archived configs, and the
+ *    providers of the configs the server still holds at its prompt PATCH. When it
+ *    is, it joins `agentFilesFirst`; when it is not, the push cannot be
+ *    ordered in one run and the error names the sequence that can.
+ *
+ * `prompts: null` (the listing failed) checks nothing and says so once; the
+ * server's refusal remains.
+ */
+export declare function functionChangePreflight(input: FunctionChangePreflightInput): FunctionChangePreflightResult;
 /**
  * The function half of an agent's declaration — #3798: every tool, turn
  * context and history function that the functions this push believes
@@ -1007,9 +1110,10 @@ export declare function promptAgentFunctionErrors(filePath: string, tomlData: an
  * server functions that must exist when it is created, and the push applies
  * prompts before functions, so agent files go AFTER the server-functions leg;
  * every other file keeps its place. A file that does not parse stays first, so
- * the leg reports it where it always has.
+ * the leg reports it where it always has. #4441 — the agent files in
+ * `agentFilesFirst` (`functionChangePreflight`) go before the leg instead.
  */
-export declare function partitionPromptFilesForPush(promptsDir: string, files: readonly string[]): {
+export declare function partitionPromptFilesForPush(promptsDir: string, files: readonly string[], agentFilesFirst?: readonly string[]): {
     beforeFunctions: string[];
     afterFunctions: string[];
 };
@@ -1590,6 +1694,7 @@ export interface PushFieldDiff {
  */
 export type PushGateOutcome = {
     action: "live-unavailable";
+    transient?: boolean;
 } | {
     action: "create";
 } | {
@@ -2377,6 +2482,7 @@ export declare function listAllTestCases(client: ApiClient, appId: string, block
     items: any[];
 } | {
     ok: false;
+    error: unknown;
 }>;
 /**
  * Copy a block's prior `entities.testCases` records into the pull's fresh map
@@ -2460,11 +2566,17 @@ interface PushResolutionMaps {
     /** Whether a block is authored locally but not on the server yet. */
     isPlannedBlock?: (blockType: TestBlockType, blockKey: string) => boolean;
 }
-/** A failure row the push reports and exits nonzero on (`applyFailures`). */
+/**
+ * A failure row the push reports and exits nonzero on (`applyFailures`).
+ * `transient` is set where a request failed without an answer, or with a
+ * transient status: a push that failed only on such rows may succeed when run
+ * again (#4491).
+ */
 type ApplyFailure = {
     type: string;
     key: string;
     message: string;
+    transient?: boolean;
 };
 /** The attachment bookkeeping a test case's sync-state record carries. */
 type RecordedAttachments = {