primitive-admin 1.1.0-alpha.9 → 1.2.0-alpha.0

package/dist/src/lib/project-config.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Project-scoped configuration (primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the committed `primitive/` directory at the project root.
+ * The config defines named environments (dev, prod, staging, etc.) with their
+ * API URLs and app IDs.
+ *
+ * Design:
+ *   - Config file: primitive/config.json (or any ancestor directory)
+ *   - `primitive/` is committed — the config plus each environment's TOML;
+ *     `.primitive/` is machine-local state and is gitignored whole (#3153).
+ *   - Format: JSON
+ *   - Schema is versioned (currently 1). Future versions use semver-ish
+ *     caret range compatibility: we accept any config where major version
+ *     matches CURRENT_CONFIG_VERSION.
+ *   - Invalid configs throw — we do NOT silently ignore malformed files.
+ */
+/**
+ * Current schema version. Increment the major version when making
+ * backward-incompatible changes. Older configs will be rejected.
+ */
+export declare const CURRENT_CONFIG_VERSION = 1;
+/**
+ * The one set of layout constants, owned by the resolver core so the CLI, the
+ * Vite plugin and the Swift script cannot disagree about where the tree is
+ * (#3153). Re-exported here because most of the CLI imports its config
+ * vocabulary from this module.
+ */
+export { PROJECT_TREE_DIR, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+export interface ProjectEnvironment {
+    apiUrl: string;
+    /**
+     * The one app this environment names (#3152). Required: selecting an
+     * environment selects exactly one app, which is what lets the CLI drop its
+     * second, per-machine notion of "the current app".
+     */
+    appId: string;
+    appName?: string;
+    /**
+     * The app's web counterpart for this environment, as a normalized origin
+     * (`https://app.example.com`) — the deployment whose `/oauth/callback` the
+     * emailed sign-in link points at, and the origin an incoming universal link
+     * is trusted from (#2982). Per environment, because that deployment has to
+     * talk to the same backend and app as this entry.
+     */
+    webUrl?: string;
+    /**
+     * The iOS client's Apple app identifier for this environment —
+     * `<Application Identifier Prefix>.<bundle id>`, the prefix usually being the
+     * Team ID (#3081). Per environment, because an app with alpha and production
+     * has one bundle id each; declared beside `webUrl`, because the two halves
+     * name one cross-client link and the Vue template's deploy generates the
+     * `apple-app-site-association` document from the pair.
+     */
+    iosAppId?: string;
+    /** Optional notes about this environment. */
+    description?: string;
+}
+export interface ProjectConfig {
+    /** Schema version (currently 1). */
+    version: number;
+    /**
+     * Default environment name to use when --env is not specified and
+     * PRIMITIVE_ENV is unset.
+     */
+    defaultEnvironment?: string;
+    /**
+     * Named environments keyed by short name (e.g. "dev", "prod", "staging").
+     */
+    environments: Record<string, ProjectEnvironment>;
+}
+export declare class ProjectConfigError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+/**
+ * Walks upward from `startDir` looking for a `primitive/config.json` file.
+ * Returns the absolute path to the config file, or null if not found.
+ *
+ * Allows running `primitive` commands from subdirectories of a project,
+ * much like `git` walks up to find `.git`.
+ *
+ * One walk, not two: this delegates to the resolver core (#3153) so the CLI
+ * and every other reader refuse the pre-move layout identically — a second
+ * copy of the walk here is exactly how the stale-layout refusal would come to
+ * mean two different things.
+ */
+export declare function findProjectConfigPath(startDir?: string): string | null;
+/**
+ * Returns the project root directory (the parent of `primitive/`, which holds
+ * `primitive/config.json`), or null if no project config is found.
+ *
+ * When the PRIMITIVE_PROJECT_CONFIG env var override is active, the config
+ * file may not live inside a `primitive/` directory (e.g. in tests), and then
+ * the root is simply the containing directory.
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Validates a raw parsed object against the ProjectConfig schema.
+ * Throws ProjectConfigError with a helpful message on any problem.
+ */
+export declare function validateProjectConfig(raw: unknown, sourcePath?: string): ProjectConfig;
+/**
+ * Loads and validates the project config from a specific file path.
+ * Throws ProjectConfigError on I/O errors, JSON parse errors, or schema
+ * validation failures — we deliberately do NOT swallow these, because a
+ * broken config should be noisy so the user can fix it.
+ */
+export declare function loadProjectConfigFromPath(path: string): ProjectConfig;
+/**
+ * Loads the project config by searching upward from the current directory.
+ * Returns null (not an error) if no primitive/config.json is found anywhere.
+ * Still throws ProjectConfigError if a config IS found but is invalid.
+ */
+export declare function loadProjectConfig(startDir?: string): ProjectConfig | null;
+/**
+ * Writes a project config to disk as pretty-printed JSON. Callers are
+ * responsible for ensuring the parent directory exists — this function
+ * does not try to be clever about location.
+ */
+export declare function saveProjectConfig(path: string, config: ProjectConfig): void;

package/dist/src/lib/project-config.js

@@ -0,0 +1,244 @@
+/**
+ * Project-scoped configuration (primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the committed `primitive/` directory at the project root.
+ * The config defines named environments (dev, prod, staging, etc.) with their
+ * API URLs and app IDs.
+ *
+ * Design:
+ *   - Config file: primitive/config.json (or any ancestor directory)
+ *   - `primitive/` is committed — the config plus each environment's TOML;
+ *     `.primitive/` is machine-local state and is gitignored whole (#3153).
+ *   - Format: JSON
+ *   - Schema is versioned (currently 1). Future versions use semver-ish
+ *     caret range compatibility: we accept any config where major version
+ *     matches CURRENT_CONFIG_VERSION.
+ *   - Invalid configs throw — we do NOT silently ignore malformed files.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { detectInstall, installCommand, upgradeCommand, PRIMITIVE_CLI_PACKAGE, } from "./package-manager.js";
+import { findPrimitiveConfigPath, missingAppIdMessage, projectRootForConfigPath, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+import { normalizeIosAppId, validateIosAppId } from "./ios-app-id.js";
+import { validateServerUrl } from "./server-url.js";
+import { normalizeWebUrl, validateWebUrl } from "./web-url.js";
+/**
+ * The command that upgrades the running CLI. Falls back to the first-time
+ * install command when the running copy can't be upgraded by a package
+ * manager (a source checkout).
+ */
+function cliUpgradeCommand() {
+    return (upgradeCommand(detectInstall(), PRIMITIVE_CLI_PACKAGE, "latest") ??
+        installCommand(PRIMITIVE_CLI_PACKAGE));
+}
+/**
+ * Current schema version. Increment the major version when making
+ * backward-incompatible changes. Older configs will be rejected.
+ */
+export const CURRENT_CONFIG_VERSION = 1;
+/**
+ * The one set of layout constants, owned by the resolver core so the CLI, the
+ * Vite plugin and the Swift script cannot disagree about where the tree is
+ * (#3153). Re-exported here because most of the CLI imports its config
+ * vocabulary from this module.
+ */
+export { PROJECT_TREE_DIR, PROJECT_LOCAL_STATE_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, } from "./env-resolver-core.js";
+export class ProjectConfigError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = "ProjectConfigError";
+    }
+}
+/**
+ * Walks upward from `startDir` looking for a `primitive/config.json` file.
+ * Returns the absolute path to the config file, or null if not found.
+ *
+ * Allows running `primitive` commands from subdirectories of a project,
+ * much like `git` walks up to find `.git`.
+ *
+ * One walk, not two: this delegates to the resolver core (#3153) so the CLI
+ * and every other reader refuse the pre-move layout identically — a second
+ * copy of the walk here is exactly how the stale-layout refusal would come to
+ * mean two different things.
+ */
+export function findProjectConfigPath(startDir = process.cwd()) {
+    return findPrimitiveConfigPath({ cwd: startDir });
+}
+/**
+ * Returns the project root directory (the parent of `primitive/`, which holds
+ * `primitive/config.json`), or null if no project config is found.
+ *
+ * When the PRIMITIVE_PROJECT_CONFIG env var override is active, the config
+ * file may not live inside a `primitive/` directory (e.g. in tests), and then
+ * the root is simply the containing directory.
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    const path = findProjectConfigPath(startDir);
+    if (!path)
+        return null;
+    return projectRootForConfigPath(path);
+}
+/**
+ * Validates a raw parsed object against the ProjectConfig schema.
+ * Throws ProjectConfigError with a helpful message on any problem.
+ */
+export function validateProjectConfig(raw, sourcePath) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} must contain a JSON object at the top level.`, sourcePath);
+    }
+    const obj = raw;
+    // Version is required.
+    if (typeof obj.version !== "number" || !Number.isInteger(obj.version)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} is missing required integer field "version".`, sourcePath);
+    }
+    const version = obj.version;
+    // Caret-range compatibility: accept any config whose major version matches.
+    // For version 1.x this is simply version === 1; when we ship v2 we'll
+    // reject v1 configs and tell the user to migrate.
+    if (version !== CURRENT_CONFIG_VERSION) {
+        if (version > CURRENT_CONFIG_VERSION) {
+            throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has version ${version}, but this CLI only understands version ${CURRENT_CONFIG_VERSION}. Please upgrade the CLI: ${cliUpgradeCommand()}`, sourcePath);
+        }
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has unsupported version ${version}. This CLI expects version ${CURRENT_CONFIG_VERSION}.`, sourcePath);
+    }
+    // environments is required.
+    if (!obj.environments || typeof obj.environments !== "object" || Array.isArray(obj.environments)) {
+        throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} is missing required "environments" object.`, sourcePath);
+    }
+    const environments = {};
+    for (const [name, envRaw] of Object.entries(obj.environments)) {
+        if (!name.match(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)) {
+            throw new ProjectConfigError(`Invalid environment name "${name}" in ${PROJECT_CONFIG_DISPLAY_NAME}. Names must be alphanumeric with optional dashes/underscores.`, sourcePath);
+        }
+        if (!envRaw || typeof envRaw !== "object" || Array.isArray(envRaw)) {
+            throw new ProjectConfigError(`Environment "${name}" must be an object in ${PROJECT_CONFIG_DISPLAY_NAME}.`, sourcePath);
+        }
+        const envObj = envRaw;
+        if (typeof envObj.apiUrl !== "string" || !envObj.apiUrl) {
+            throw new ProjectConfigError(`Environment "${name}" must have a non-empty "apiUrl" string in ${PROJECT_CONFIG_DISPLAY_NAME}.`, sourcePath);
+        }
+        if (validateServerUrl(envObj.apiUrl) !== true) {
+            throw new ProjectConfigError(`Environment "${name}" has invalid apiUrl: ${envObj.apiUrl}`, sourcePath);
+        }
+        // Every environment names exactly one app (#3152) — for EVERY environment
+        // in the file, not just the one this invocation resolves, because the file
+        // is what the criterion is about and because the Vite plugin, cf-deploy
+        // and the Swift pre-build script may each select a different one.
+        // Non-string and blank-after-trim are the same failure as absent: an app id
+        // no consumer could use.
+        const appId = typeof envObj.appId === "string" ? envObj.appId.trim() : "";
+        if (!appId) {
+            throw new ProjectConfigError(missingAppIdMessage(name, sourcePath), sourcePath);
+        }
+        if (envObj.appName !== undefined && typeof envObj.appName !== "string") {
+            throw new ProjectConfigError(`Environment "${name}": "appName" must be a string if set.`, sourcePath);
+        }
+        if (envObj.description !== undefined && typeof envObj.description !== "string") {
+            throw new ProjectConfigError(`Environment "${name}": "description" must be a string if set.`, sourcePath);
+        }
+        // An origin, not any URL: the emailed sign-in link is built from it, so a
+        // value the server's allow-list would refuse — or one whose callback path
+        // neither the web app nor the AASA component names — is a 400 or a dead
+        // link later rather than an error here (#2982).
+        if (envObj.webUrl !== undefined) {
+            if (typeof envObj.webUrl !== "string") {
+                throw new ProjectConfigError(`Environment "${name}": "webUrl" must be a string if set.`, sourcePath);
+            }
+            const problem = validateWebUrl(envObj.webUrl);
+            if (problem !== true) {
+                throw new ProjectConfigError(`Environment "${name}" has invalid webUrl: ${problem}`, sourcePath);
+            }
+        }
+        // The iOS half of the same cross-client link (#3081). Both or neither for
+        // an environment with an iOS client: an app id with no origin names an app
+        // for a domain this config does not know, and no deploy could serve the
+        // association document that pairs them.
+        if (envObj.iosAppId !== undefined) {
+            if (typeof envObj.iosAppId !== "string") {
+                throw new ProjectConfigError(`Environment "${name}": "iosAppId" must be a string if set.`, sourcePath);
+            }
+            const problem = validateIosAppId(envObj.iosAppId);
+            if (problem !== true) {
+                throw new ProjectConfigError(`Environment "${name}" has invalid iosAppId: ${problem}`, sourcePath);
+            }
+            if (envObj.webUrl === undefined) {
+                throw new ProjectConfigError(`Environment "${name}" sets "iosAppId" but no "webUrl". The association document that vouches for that app is served by the web app, so set "webUrl" to its origin — or drop "iosAppId" if this environment has no iOS client.`, sourcePath);
+            }
+        }
+        environments[name] = {
+            apiUrl: envObj.apiUrl.replace(/\/$/, ""),
+            appId,
+            appName: envObj.appName,
+            webUrl: envObj.webUrl === undefined
+                ? undefined
+                : normalizeWebUrl(envObj.webUrl),
+            iosAppId: envObj.iosAppId === undefined
+                ? undefined
+                : normalizeIosAppId(envObj.iosAppId),
+            description: envObj.description,
+        };
+    }
+    // defaultEnvironment is optional but must refer to a real environment.
+    let defaultEnvironment;
+    if (obj.defaultEnvironment !== undefined) {
+        if (typeof obj.defaultEnvironment !== "string") {
+            throw new ProjectConfigError(`"defaultEnvironment" must be a string if set.`, sourcePath);
+        }
+        if (obj.defaultEnvironment && !environments[obj.defaultEnvironment]) {
+            throw new ProjectConfigError(`"defaultEnvironment" is set to "${obj.defaultEnvironment}" but no such environment is defined.`, sourcePath);
+        }
+        defaultEnvironment = obj.defaultEnvironment || undefined;
+    }
+    return { version, defaultEnvironment, environments };
+}
+/**
+ * Loads and validates the project config from a specific file path.
+ * Throws ProjectConfigError on I/O errors, JSON parse errors, or schema
+ * validation failures — we deliberately do NOT swallow these, because a
+ * broken config should be noisy so the user can fix it.
+ */
+export function loadProjectConfigFromPath(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        throw new ProjectConfigError(`Failed to read ${PROJECT_CONFIG_DISPLAY_NAME}: ${err.message}`, path);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ProjectConfigError(`Failed to parse ${PROJECT_CONFIG_DISPLAY_NAME}: ${err.message}`, path);
+    }
+    return validateProjectConfig(parsed, path);
+}
+/**
+ * Loads the project config by searching upward from the current directory.
+ * Returns null (not an error) if no primitive/config.json is found anywhere.
+ * Still throws ProjectConfigError if a config IS found but is invalid.
+ */
+export function loadProjectConfig(startDir = process.cwd()) {
+    const path = findProjectConfigPath(startDir);
+    if (!path)
+        return null;
+    return loadProjectConfigFromPath(path);
+}
+/**
+ * Writes a project config to disk as pretty-printed JSON. Callers are
+ * responsible for ensuring the parent directory exists — this function
+ * does not try to be clever about location.
+ */
+export function saveProjectConfig(path, config) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const serialized = JSON.stringify(config, null, 2) + "\n";
+    writeFileSync(path, serialized);
+}
+//# sourceMappingURL=project-config.js.map

package/dist/src/lib/project-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../../../src/lib/project-config.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/prompt-cost-format.d.ts

@@ -0,0 +1,11 @@
+/** What a row of the top-prompts response offers these cells. */
+export type PromptCostRow = {
+    executions: number;
+    executionsWithCost?: number;
+    totalCost?: number | null;
+    avgCost?: number | null;
+};
+/** The same USD thresholds the Admin Console renders (`web-admin/src/lib/promptCost.ts`). */
+export declare function formatUsd(cost: number): string;
+export declare function formatCostCell(row: PromptCostRow): string;
+export declare function formatAvgCostCell(row: PromptCostRow): string;

package/dist/src/lib/prompt-cost-format.js

@@ -0,0 +1,41 @@
+/**
+ * The `analytics prompts` table's cost cells — #3787.
+ *
+ * `analytics/prompts/top` answers `executionsWithCost`, `totalCost` and
+ * `avgCost` per prompt, and how they render follows from what a missing cost
+ * means: `null` is UNKNOWN, not zero. Today only a decisions run reports a
+ * price, so a chat prompt has no number to show, and `$0.00` would tell an
+ * owner comparing models that it was free. The placeholder is the dim `-` the
+ * other formatters in `output.ts` already use for an absent value.
+ *
+ * A total covering part of the window carries an ` (n/m)` suffix, because five
+ * priced runs of eight are not the prompt's whole spend. The average needs no
+ * suffix: it is already an average over the priced runs alone.
+ */
+import chalk from "chalk";
+/** The same USD thresholds the Admin Console renders (`web-admin/src/lib/promptCost.ts`). */
+export function formatUsd(cost) {
+    if (cost < 0.0001)
+        return `$${cost.toExponential(2)}`;
+    if (cost < 0.01)
+        return `$${cost.toFixed(6)}`;
+    if (cost < 1)
+        return `$${cost.toFixed(4)}`;
+    return `$${cost.toFixed(2)}`;
+}
+const costed = (row) => row.executionsWithCost ?? 0;
+export function formatCostCell(row) {
+    const total = row.totalCost ?? null;
+    const withCost = costed(row);
+    if (withCost <= 0 || total === null)
+        return chalk.dim("-");
+    const suffix = withCost < (row.executions ?? 0) ? ` (${withCost}/${row.executions})` : "";
+    return `${formatUsd(total)}${suffix}`;
+}
+export function formatAvgCostCell(row) {
+    const avg = row.avgCost ?? null;
+    if (costed(row) <= 0 || avg === null)
+        return chalk.dim("-");
+    return formatUsd(avg);
+}
+//# sourceMappingURL=prompt-cost-format.js.map

package/dist/src/lib/prompt-cost-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-cost-format.js","sourceRoot":"","sources":["../../../src/lib/prompt-cost-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAU1B,6FAA6F;AAC7F,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,IAAI,GAAG,MAAM;QAAE,OAAO,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,MAAM,GAAG,CAAC,GAAkB,EAAU,EAAE,CAAC,GAAG,CAAC,kBAAkB,IAAI,CAAC,CAAC;AAE3E,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;IACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,QAAQ,IAAI,CAAC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3D,MAAM,MAAM,GACV,QAAQ,GAAG,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAkB;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;IAChC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5D,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/dist/src/lib/prompt-schema-codegen.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The prompt declaration — #3330, project `server-functions` phase 4.
+ *
+ * A prompt's `[prompt.outputSchema]` already says what its answer looks like,
+ * and `config pull`/`push` already round-trip it. Until now nothing turned it
+ * into a type, so a function calling the prompt restated the shape by hand at
+ * the call site with nothing checking it — the same complaint the function
+ * input/output contract answered, one surface over.
+ *
+ * `functions/primitive-prompt-types.d.ts` is rendered from `prompts/*.toml`
+ * beside the other declarations and regenerated by `config push`,
+ * `config pull` and `primitive functions codegen`:
+ *
+ *   - `<Key>PromptOutput` for every prompt that declares an `outputSchema`,
+ *     through the SAME renderer `primitive-function-types.d.ts` uses, over the
+ *     same vendored descriptor, so what compiles is what the route validates.
+ *   - `PrimitivePromptSchemas`, keyed by prompt key, and the
+ *     `declare module "primitive-functions"` augmentation — the
+ *     `DatabaseSchemas`/`FunctionSchemas`/`DocumentSchemas` shape. Empty keeps
+ *     `PromptKeys` open (`string`); a pushed tree narrows it, so an undeclared
+ *     key is a compile error.
+ *
+ * A prompt that declares NO schema is `{}` under its key, not an entry with an
+ * `unknown` output. That is deliberate: `{}` does not extend `{ output: … }`,
+ * so the SDK's `PromptRunResult` falls to its open shape and `parsed` stays
+ * optional and `unknown` — and REMOVING a schema therefore turns a handler
+ * reading `parsed.field` into a compile error on the next push rather than a
+ * runtime `undefined`.
+ *
+ * ── The suffix ───────────────────────────────────────────────────────────
+ *
+ * `<Key>PromptOutput`, not `<Key>Output`. A function and the prompt it calls
+ * commonly share a key — the issue's own `categorize` — and `<Key>Output`
+ * already names the FUNCTION's output in the declaration beside this one.
+ *
+ * ── Identity is push's ───────────────────────────────────────────────────
+ *
+ * `config push` resolves a prompt file as
+ * `tomlData.prompt?.key || basename(file, ".toml")`, so `local.toml` carrying
+ * `key = "categorize"` is deployed as `categorize`. Reading the stem alone
+ * would type it under a key the platform never hears about, refuse the call
+ * the deployed prompt answers, and attach the schema to the wrong key. Same
+ * rule and same reason as `resolveFunctionKey` (CR3281-001) and
+ * `databaseTypeSources` (SO3182-003): the generator reads the key the platform
+ * will hear about, never the file name alone.
+ *
+ * ── Agents (#3798) ───────────────────────────────────────────────────────
+ *
+ * A `kind = "agent"` prompt is never run single-shot, so it has no `output`.
+ * Its entry is `{ agent: { variables; clientTools; events } }` instead —
+ * `<Key>AgentVariables` from `inputSchema` (the session's variables),
+ * `<Key>Tool<Name>Input`/`Output` for each CLIENT tool (a server tool's
+ * schemas are its function's, typed in the functions declaration) and
+ * `<Key>Event<Name>` for each event kind — and the SDK's `PromptKeys` excludes
+ * it, so `ctx.prompts.run("<agent>")` is a compile error. The same types go to
+ * the client side as `functions/generated/<key>.agent.generated.ts`
+ * (`renderAgentClientFiles`), which an app's web code imports. The
+ * declaration is read through `normalizeAgentDeclaration`, the one reader
+ * that applies an agent's defaults.
+ */
+import { type AgentSchema } from "./generated-config-surfaces.js";
+/** The client-side artifact an agent prompt gets, beside the invokers (#3798). */
+export declare const AGENT_CLIENT_FILE_SUFFIX = ".agent.generated.ts";
+/** The regenerated declaration beside `primitive-function-types.d.ts`. */
+export declare const PROMPT_TYPES_DECLARATION_FILE = "primitive-prompt-types.d.ts";
+export interface PromptSchemaSource {
+    /**
+     * The file stem, which is the key push uses when the file declares none.
+     * An authored `[prompt] key` wins over it — see {@link resolvePromptKey}.
+     */
+    key: string;
+    tomlPath: string;
+    tomlContent: string;
+}
+/** What the renderer needs from one `prompts/<key>.toml`. */
+export interface PromptSchemaIR {
+    key: string;
+    /** The tree-relative file this came from, for a message an author acts on. */
+    fileLabel: string;
+    /** The declared `[prompt].outputSchema`, or undefined when there is none. */
+    outputSchema: unknown;
+    /** `<Key>` — the PascalCase base of the type name. */
+    typeBaseName: string;
+    /** `<Key>PromptOutput`. */
+    outputTypeName: string;
+    /** #3798 — the agent's typed contract; `null` for a chat or decisions prompt. */
+    agent: AgentTypesIR | null;
+}
+/** One named type an agent's contract declares: its name and its schema. */
+export interface AgentNamedType {
+    /** The declared name — a tool or event name, as authored. */
+    name: string;
+    typeName: string;
+    schema: AgentSchema;
+}
+/** What an agent prompt contributes to the declarations (#3798). */
+export interface AgentTypesIR {
+    /** `<Key>AgentVariables`, from `[prompt].inputSchema` (`unknown` when none). */
+    variablesTypeName: string;
+    inputSchema: unknown;
+    clientTools: Array<{
+        name: string;
+        input: AgentNamedType;
+        output: AgentNamedType;
+    }>;
+    events: AgentNamedType[];
+}
+/**
+ * Every `prompts/*.toml` in a tree, read once.
+ *
+ * `withFileTypes` rather than a name filter alone: a `prompts/<key>.tests/`
+ * sidecar directory and anything that is not a regular `.toml` file are not
+ * prompt sources, and a directory read as one fails in the parser with a
+ * message about TOML instead of being ignored.
+ */
+export declare function promptSchemaSources(configDir: string): PromptSchemaSource[];
+/**
+ * Parse one file into the data the renderer needs.
+ *
+ * Throws a `FunctionSchemaCodegenError` naming the file for malformed TOML or
+ * malformed schema JSON — the honest "declares nothing" is for an ABSENT
+ * schema, never a broken one, because typing a broken schema as anything at
+ * all is a declaration that lies.
+ */
+export declare function describePromptSchema(source: PromptSchemaSource): PromptSchemaIR;
+/**
+ * The declaration for a whole tree's prompts. Sorted by key so the bytes
+ * depend on the files and not on the order they were read in. The
+ * augmentation is emitted even for a tree with no prompt: an empty
+ * `PromptSchemas` keeps `PromptKeys` open (`string`), so nothing breaks.
+ */
+export declare function renderPromptSchemasDeclaration(sources: readonly PromptSchemaSource[]): string;
+/** Whether a tree declares any agent prompt — the codegen gate (DSO-3798-005). */
+export declare function treeDeclaresAgentPrompt(configDir: string): boolean;
+/**
+ * The client-side artifact of each agent prompt — #3798:
+ * `<key>.agent.generated.ts`, carrying the agent's variables, client-tool and
+ * event types, the `<Key>AgentClientTools` / `<Key>AgentEvents` maps an app's
+ * session view is typed by, and `<Key>Agent.key`. Written beside the function
+ * invokers and owned by the same plan, so the invoker sweep keeps it; a
+ * Prettier fixed point, like them (#1565).
+ */
+export declare function renderAgentClientFiles(sources: readonly PromptSchemaSource[]): Array<{
+    key: string;
+    fileName: string;
+    content: string;
+}>;