primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/functions.js

@@ -0,0 +1,1630 @@
+/**
+ * `primitive functions` — server functions' read and operational verbs
+ * (#3179, project `server-functions`).
+ *
+ * A server function is the SIXTH status-carrying type (`docs/cli-design.md`,
+ * §Object availability): it exposes a public endpoint, so it carries
+ * `active | inactive | archived`, the `enable`/`disable` pair, and the
+ * `archive` spelling of the delete flow. It carries no `create`, `update` or
+ * `delete` verb — the function is authored in `functions/<key>.toml` beside the
+ * TypeScript its `entry` names, applied with `config push`, and prune-by-push
+ * stays the only CLI hard-delete path.
+ *
+ * The rule worth stating loudly here, because a function IS code on a public
+ * endpoint: a `config push` to a DISABLED function updates the code and leaves
+ * it out of service. `status` has one writer pair and push is not one of them
+ * (#2803's resurrection guard) — otherwise shipping a fix would silently put
+ * an endpoint an operator had taken down back in service.
+ */
+import { existsSync, readdirSync } from "fs";
+import { join, relative as relativePath } from "path";
+import { ApiClient } from "../lib/api-client.js";
+import { resolveAppId } from "../lib/config.js";
+import { resolveSyncDir } from "../lib/sync-paths.js";
+import { FunctionSchemaCodegenError, functionSchemaSources, } from "../lib/function-schema-codegen.js";
+import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
+import { AGENT_CLIENT_FILE_SUFFIX, promptSchemaSources, treeDeclaresAgentPrompt, } from "../lib/prompt-schema-codegen.js";
+import { generateFunctionSwiftTypes } from "../lib/swift-codegen/functionGenerator.js";
+import { AGENT_SWIFT_FILE_SUFFIX } from "../lib/swift-codegen/agentGenerator.js";
+import { SwiftCodegenError } from "../lib/swift-codegen/schemaToSwift.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatDate, formatStatus, json, jsonLine, divider, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { FUNCTION_LOG_COLUMNS, functionLogCells, functionLogLine, } from "../lib/function-log-row.js";
+import { activatedLine, activationOutput, activationPrompt, activationRefusalLine, functionVersionRows, newerVersionLine, versionLine, } from "../lib/function-versions.js";
+import { parseStatusFilter } from "../lib/object-status-filter.js";
+import { renderStepRunTable } from "../lib/step-run-table.js";
+import { triggerKindsCell, triggerTableRows, } from "../lib/function-trigger-listing.js";
+import { renderRunLogs } from "../lib/function-log-lines.js";
+import { buildWorkflowStepEnvelope } from "../lib/log-inspection.js";
+import { followLoop } from "../lib/watch.js";
+import { buildLogFollowSource } from "../lib/function-log-tail.js";
+import { toFunctionLogInspectionRow } from "../lib/log-inspection.js";
+import { decidePageContinuation, describeIdentity, exitCodeForInvokeStatus, exitCodeForRunStatus, invokeIdLines, logsFlagConflict, refusalLines, renderIdLines, resolveRunFlags, runRuntimeCell, runSliceCells, runtimeForExecutionMode, resumeCommand, startIdLines, userTokenName, waitDelayMs, withMintedToken, EXIT_INTERRUPTED, EXIT_TIMED_OUT, USER_TOKEN_TTL, WAIT_DEFAULT_TIMEOUT_SECONDS, } from "../lib/function-run.js";
+import { wholeListEnvelope } from "../lib/paginate.js";
+/**
+ * How far back one `--follow` tick will page to meet its high-water mark.
+ *
+ * A bound on one CALL rather than "until you get there": the listing is
+ * newest-first, so an unbounded walk on a busy function would page through a
+ * whole window of history in one go. Ten pages at the default limit is 250
+ * invocations between polls — comfortably past what two seconds of an admitted
+ * caller can record. A tail that does fall behind carries its walk into the
+ * next call rather than skipping the gap (CR3287-017): the rows between the
+ * mark and now are all printed, in order, a bounded number of pages at a time.
+ */
+const FOLLOW_MAX_PAGES_PER_TICK = 10;
+/**
+ * Which cell each shared invocation column reads, and how it is rendered.
+ *
+ * The ORDER lives in `FUNCTION_LOG_COLUMNS` (#3462); this is only the mapping
+ * from a header to the cell `functionLogCells` builds for it, so adding a
+ * column is one edit in each place rather than three copies of the order.
+ */
+const LOG_COLUMN_KEYS = {
+    TIME: "startedAt",
+    STATUS: "status",
+    TRIGGER: "trigger",
+    RUNTIME: "runtime",
+    VERSION: "configId",
+    "RUN/INVOCATION ID": "runOrInvocation",
+    CODE: "errorCode",
+    ERROR: "firstError",
+};
+const LOG_COLUMN_FORMATS = {
+    TIME: formatDate,
+    STATUS: formatStatus,
+};
+export function registerFunctionsCommands(program) {
+    const functions = program
+        .command("functions")
+        .description("Inspect and operate server functions")
+        .addHelpText("after", `
+Examples:
+  $ primitive config create function greet   # then edit functions/greet.toml and: primitive config push
+  $ primitive functions list
+  $ primitive functions get 01HXY...
+  $ primitive functions disable 01HXY...     # out of service; pushes still land
+  $ primitive functions archive 01HXY...     # retire it (soft delete)
+`);
+    // Configuration is authored in TOML and applied with `config push` (#2645):
+    // this group carries no config-setting flags, and the code the function runs
+    // is the TypeScript beside its file rather than anything a verb can send.
+    functions.addHelpText("after", `
+Configuration lives in functions/<key>.toml, and the code beside it:
+  $ primitive config fields function        # the file's keys, types and defaults
+  $ primitive config create function <key>  # scaffold one locally
+  $ primitive config set function/<key> <path>=<value>
+  $ primitive config push --only function/<key>
+`);
+    functions
+        .command("list")
+        .description("List server functions and their triggers")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--status <status>", "Filter by status: active, inactive, archived")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const status = parseStatusFilter("functions", options.status, [
+                "active",
+                "inactive",
+                "archived",
+            ]);
+            // The admin listing drains `functionsByApp` server-side, so there is no
+            // cursor to follow and the filter is applied here.
+            const { items } = await client.listFunctions(resolvedAppId);
+            const filtered = status
+                ? (items || []).filter((f) => String(f.status ?? "active") === status)
+                : items || [];
+            if (options.json) {
+                json(wholeListEnvelope(filtered));
+                return;
+            }
+            if (filtered.length === 0) {
+                info("No functions found.");
+                return;
+            }
+            // #3690 — which functions a webhook or a schedule reaches, in one call.
+            // The standalone `webhooks list` and `cron-triggers list` hide the
+            // rows a function owns (#3181), so without this the only way to find
+            // an app's triggers was `functions get`, one function at a time.
+            console.log(formatTable(filtered.map((f) => ({
+                ...f,
+                triggersCell: triggerKindsCell(f.triggers),
+            })), [
+                { header: "KEY", key: "functionKey" },
+                { header: "ID", key: "functionId" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "TRIGGERS", key: "triggersCell" },
+                { header: "MODIFIED", key: "modifiedAt", format: formatDate },
+            ]));
+            const triggerRows = triggerTableRows(filtered);
+            if (triggerRows.length > 0) {
+                console.log("");
+                console.log(formatTable(triggerRows, [
+                    { header: "FUNCTION", key: "functionKey" },
+                    { header: "KIND", key: "kind" },
+                    { header: "NAME", key: "name" },
+                    { header: "SCHEDULE", key: "schedule" },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                    { header: "NEXT FIRE", key: "nextFireAt", format: formatDate },
+                    {
+                        header: "LAST FIRE",
+                        key: "lastFireAt",
+                        format: (value) => (value ? formatDate(value) : "never"),
+                    },
+                ]));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("get")
+        .description("Get a server function, and the version it currently runs")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const record = await client.getFunction(resolvedAppId, functionId);
+            // The versions are append-only and nameless; `activeConfigId` is the
+            // only thing that says which one runs, so a listing without it would
+            // report the newest rather than the live one.
+            //
+            // #3462 — a POINT READ, not a drained listing scanned for the id. Past
+            // 25 versions the listing is a page and the active version may not be
+            // on it at all; one read by id is both cheaper and correct.
+            let active = null;
+            if (record?.activeConfigId) {
+                // #3455 — this single read is also what carries
+                // `documentSchemaModels`: the models this version can seed are
+                // derived from the schema INSIDE the envelope rather than stored on
+                // the row, so the LISTING (one row per version, no R2 read) cannot
+                // carry them and only the point read can. Best-effort — an older
+                // server sends no such field, and the line then reads exactly as it
+                // does for a version pushed without a schema.
+                try {
+                    active = await client.getFunctionConfig(resolvedAppId, functionId, String(record.activeConfigId));
+                }
+                catch {
+                    active = null;
+                }
+            }
+            // #3462 — one row of the listing answers "is the active version the
+            // newest", which is what tells an operator this function is rolled back.
+            let newest = null;
+            try {
+                const page = await client.listFunctionConfigs(resolvedAppId, functionId, {
+                    limit: 1,
+                });
+                newest = (page.items || [])[0] ?? null;
+            }
+            catch {
+                newest = null;
+            }
+            const newer = newerVersionLine(newest, record?.activeConfigId, formatDate);
+            if (options.json) {
+                json({
+                    ...record,
+                    activeConfig: active,
+                    ...(newer ? { newerVersion: newest } : {}),
+                });
+                return;
+            }
+            printResult("Function ID", record.functionId);
+            printResult("Key", record.functionKey);
+            // #3462 — which code this function is running, beside its identity. The
+            // version was only reachable by reading the section below, or by asking
+            // the API; an operator answering "what is deployed" reads this line.
+            printResult("Version", versionLine({
+                activeConfigId: record.activeConfigId,
+                contentHash: active?.contentHash,
+            }));
+            printResult("Description", record.description || "-");
+            printResult("Status", formatStatus(record.status));
+            printResult("Access", record.access || "-");
+            printResult("Input Schema", record.inputSchema || "-");
+            printResult("Output Schema", record.outputSchema || "-");
+            divider();
+            info("Active version:");
+            if (!active) {
+                printResult("  Version", "none — no code has been pushed yet");
+            }
+            else {
+                printResult("  Config ID", active.configId);
+                printResult("  Entry", active.entry);
+                printResult("  Content Hash", active.contentHash || "-");
+                // #3482 — no Mode line. The config says nothing about how a
+                // function runs: `invoke` runs it inside the request, `start` runs
+                // it as a task, and every function takes both.
+                printResult("  Limits", active.limits || "-");
+                // #3182 — what this version declared: since #3279 the egress
+                // allowlist, the secrets that may enter the sandbox and the
+                // high-blast opt-ins. Shown here because `functions get` is where an
+                // operator asks what a deployed function is configured to reach.
+                const capabilities = Array.isArray(active.capabilities)
+                    ? active.capabilities
+                    : [];
+                printResult("  Capabilities", capabilities.length > 0 ? capabilities.join(", ") : "-");
+                // #3462 — who put this version live and when, from either door (a
+                // push or `functions activate`). A header written before that change
+                // carries neither field and reads `unknown` rather than naming an
+                // actor nobody recorded.
+                printResult("  Activated", activatedLine(record, formatDate));
+                if (newer) {
+                    printResult("  Newer version", newer);
+                }
+                // #3455 — the document models this version can SEED on a first
+                // write. An operator asking "why did the first write not seed
+                // `institution`" gets the answer here: either the model is in this
+                // list, or the version was pushed without a document schema at all.
+                // A server that predates the field sends nothing, which reads the
+                // same way as a version pushed without one.
+                const documentSchemaModels = Array.isArray(active.documentSchemaModels)
+                    ? active.documentSchemaModels
+                    : null;
+                printResult("  Document schema", documentSchemaModels === null
+                    ? "none — this version was pushed without one"
+                    : documentSchemaModels.length > 0
+                        ? documentSchemaModels.join(", ")
+                        : "declares no models");
+            }
+            // #3181 — the ONE surface a function's triggers are visible on. The
+            // hidden `AppWebhook` and `CronTrigger` rows are omitted from
+            // `webhooks list`, `cron-triggers list` and `config pull` by design, so
+            // without this an operator could not find the receiver URL a provider
+            // must be pointed at, or the schedule the platform actually holds.
+            divider();
+            info("Triggers:");
+            const triggers = record.triggers ?? { webhook: null, cron: [] };
+            const cronEntries = Array.isArray(triggers.cron)
+                ? triggers.cron
+                : [];
+            // #3483 — an OLDER server still answers a `databases` key, and this
+            // command ignores it rather than branching on it: the trigger it
+            // described was removed, so a section about it would tell an operator
+            // that a write runs this function when nothing does.
+            if (!triggers.webhook && cronEntries.length === 0) {
+                printResult("  Triggers", "none — this function is invoked over HTTP only");
+            }
+            if (triggers.webhook) {
+                printResult("  Webhook", triggers.webhook.webhookId);
+                printResult("    URL", triggers.webhook.url || "-");
+                printResult("    Scheme", triggers.webhook.verificationScheme || "-");
+                printResult("    Status", formatStatus(triggers.webhook.status));
+                printResult("    Signing Secret", triggers.webhook.signingSecret || "-");
+                printResult("    Last Triggered", triggers.webhook.lastTriggeredAt
+                    ? formatDate(triggers.webhook.lastTriggeredAt)
+                    : "never");
+            }
+            if (cronEntries.length > 0) {
+                console.log(formatTable(cronEntries, [
+                    { header: "NAME", key: "name" },
+                    { header: "ID", key: "triggerId" },
+                    { header: "CRON", key: "cron" },
+                    // #3454 — which runner this schedule's fires use. Always one of
+                    // the two words: an `any` function's entry names it, and a
+                    // locked one's takes its lock.
+                    { header: "TZ", key: "timezone" },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                    { header: "NEXT FIRE", key: "nextFireAt", format: formatDate },
+                    { header: "FIRED", key: "firedCount" },
+                    { header: "LAST RUN", key: "lastTriggeredRunId" },
+                ]));
+            }
+            // #3187 / #3279 — the ACTIVE version's manifest: what it registered
+            // and what it TOUCHES, from the push-time collection. Documentation,
+            // never authorization — function code acts as the system, and this
+            // is what lets an operator see what a version reaches without opening
+            // the bundle (principle 8). A server that predates the manifest block
+            // sends only `queries`.
+            divider();
+            info("Manifest (documentation, not authorization):");
+            const manifest = record.manifest && typeof record.manifest === "object"
+                ? record.manifest
+                : { queries: Array.isArray(record.queries) ? record.queries : [] };
+            const queries = Array.isArray(manifest.queries) ? manifest.queries : [];
+            const models = Array.isArray(manifest.models) ? manifest.models : [];
+            const families = Array.isArray(manifest.families)
+                ? manifest.families
+                : [];
+            if (!record.manifest) {
+                printResult("  Manifest", "none recorded — this version was pushed without a manifest");
+            }
+            else {
+                printResult("  Models", (models.length > 0 ? models.join(", ") : "none named") +
+                    // The marker is the difference between "names none" and "names
+                    // these, and possibly more" (D3279-006).
+                    (manifest.dynamicModels === true
+                        ? " (+ a model name resolved at run time)"
+                        : ""));
+                printResult("  Families", families.length > 0 ? families.join(", ") : "none reached");
+            }
+            if (queries.length === 0) {
+                if (record.manifest)
+                    printResult("  Queries", "none registered");
+            }
+            else {
+                console.log(formatTable(queries, [
+                    { header: "NAME", key: "name" },
+                    { header: "KIND", key: "kind" },
+                    {
+                        header: "MODELS",
+                        key: "models",
+                        format: (value) => Array.isArray(value) && value.length > 0 ? value.join(", ") : "-",
+                    },
+                    {
+                        header: "SCOPED",
+                        key: "callerScoped",
+                        format: (value) => (value ? "$caller" : "no"),
+                    },
+                    {
+                        header: "CACHE",
+                        key: "cache",
+                        format: (value) => (value ? `${value.ttlMs}ms` : "off"),
+                    },
+                ]));
+            }
+            divider();
+            printResult("Created", formatDate(record.createdAt));
+            printResult("Modified", formatDate(record.modifiedAt));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── #3462: a function's versions, and pointing it back at one ─────────
+    //
+    // Every changing push mints an immutable version and repoints the function at
+    // it. That was already true and already stored — and entirely invisible: an
+    // operator could not list a function's versions, and a bad push was undone by
+    // editing the tree and pushing again, with `disable` as the only immediate
+    // stop.
+    //
+    // Both are OPERATIONAL verbs on a configuration group in `docs/cli-design.md`'s
+    // sense: they author nothing. A function's versions are nameless, immutable
+    // and not in TOML — unlike a prompt's `[[configs]]` blocks, whose `active`
+    // marker is why `prompts configs activate` was retired — so there is no TOML
+    // spelling of activation to prefer to a verb.
+    functions
+        .command("configs")
+        .description("List a server function's versions, newest first")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Rows per page (default 25, max 100)")
+        .option("--cursor <cursor>", "Continue from a previous page")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            // Always a `limit`, so this pages. The server's no-parameter form
+            // drains every version and exists for a CLI installed before paging
+            // did — this one is not it.
+            const { items, nextCursor } = await client.listFunctionConfigs(resolvedAppId, functionId, {
+                limit: options.limit ? Number(options.limit) : 25,
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            });
+            if (options.json) {
+                // Full hashes, not the table's twelve characters: a consumer
+                // comparing versions needs the value the server stored.
+                json({ items, hasMore: !!nextCursor, ...(nextCursor ? { nextCursor } : {}) });
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No versions pushed yet.");
+                return;
+            }
+            console.log(formatTable(functionVersionRows(items), [
+                { header: "CONFIG ID", key: "configId" },
+                { header: "PUSHED", key: "createdAt", format: formatDate },
+                { header: "ACTIVE", key: "active" },
+                { header: "CONTENT", key: "content" },
+                { header: "ENVELOPE", key: "envelope" },
+                { header: "TRIGGERS", key: "triggers" },
+                { header: "BY", key: "by" },
+            ]));
+            if (nextCursor) {
+                info(`More versions: --cursor ${nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("activate")
+        .description("Point a server function at one of its own existing versions (roll back or forward)")
+        .argument("<function-id>", "Function ID")
+        .argument("<config-id>", "The version to activate (`functions configs`)")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+What activating a version does, and does not:
+  Request calls and trigger fires use it from the NEXT call, under that
+  version's own capabilities, limits and triggers.
+  A task run already in flight finishes on the version it started on — the
+  content hash pins its code.
+  No version is created. \`config push\` of the tree is still what makes the
+  tree's code the newest version.
+`)
+        .action(async (functionId, configId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(activationPrompt(String(functionId), String(configId)));
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const answer = await client.activateFunctionConfig(resolvedAppId, functionId, configId);
+            if (options.json) {
+                json(answer);
+                return;
+            }
+            const rendered = activationOutput(answer, formatDate);
+            if (!rendered.changed) {
+                info(rendered.headline);
+                return;
+            }
+            success(rendered.headline);
+            for (const [label, value] of rendered.lines)
+                printResult(label, value);
+        }
+        catch (err) {
+            // The server's own sentence and code: an archived function, an archived
+            // version, a held delete lease and a pointer another writer moved each
+            // owe the operator a different next move, and only the code says which
+            // one without reading English.
+            error(activationRefusalLine(err));
+            process.exit(1);
+        }
+    });
+    // #3181 — a trigger-fired invocation writes a run row, and a function run has
+    // no `workflowId`, so `primitive workflows runs` cannot see it. This verb is
+    // the only way to inspect what a webhook or a schedule actually did
+    // (principle 8).
+    const runs = functions
+        .command("runs")
+        .description("List a server function's runs, newest first")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Rows per page (default 25, max 100)")
+        .option("--cursor <cursor>", "Continue from a previous page")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items, nextCursor } = await client.listFunctionRuns(resolvedAppId, functionId, {
+                ...(options.limit ? { limit: Number(options.limit) } : {}),
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            });
+            // #3482, C-6 — the runtime this run used, derived BEFORE the output is
+            // chosen so the table and `--json` say the same thing about the same
+            // row. `--json` takes the word or `null`, never the table's blank: a
+            // reader parsing this needs "no runtime" to be a value rather than an
+            // empty string that sorts beside real ones.
+            const withRuntime = (items ?? []).map((run) => ({
+                ...run,
+                runtime: runtimeForExecutionMode(run?.executionMode),
+            }));
+            if (options.json) {
+                json({ items: withRuntime, nextCursor });
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No runs found for this function.");
+                return;
+            }
+            console.log(formatTable(
+            // #3381, #3566 — flatten the slice record's two counts onto the
+            // row for the REFRESHES and RESETS columns. One helper decides
+            // both, so a row with no record gets a blank cell in each and a
+            // record with no count gets `0`.
+            items.map((run) => ({
+                ...run,
+                // #3482 — which RUNTIME this run used, from the row's own
+                // `executionMode`. One pure mapping, so the word an operator
+                // reads here is the word `ctx.runtime` gave the code.
+                runtime: runRuntimeCell(run),
+                ...runSliceCells(run),
+            })), [
+                { header: "RUN ID", key: "runId" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "FIRED BY", key: "initiatorKind" },
+                // #3482 — the runtime this run used: `request` for a webhook
+                // delivery or a `workflow.call` leaf, `task` for everything the
+                // engine ran. Blank for a DSL row, which is not a function run.
+                { header: "RUNTIME", key: "runtime" },
+                // #3462 — WHICH version this run executed. The row has carried
+                // `configId` since #3181; nothing showed it, so an operator
+                // reading a failed run could not tell which code failed.
+                { header: "VERSION", key: "configId" },
+                // #3280 — FIRED BY already said `function`; this is the half that
+                // makes it actionable, so a failed page leads back to the
+                // orchestrator that started it. Blank for a root.
+                { header: "PARENT", key: "parentFunctionKey" },
+                // #3381 — how many times a task slice's token was refreshed
+                // through the gateway. Blank for a request run.
+                { header: "REFRESHES", key: "refreshes" },
+                // #3566 — how many of this run's slices a platform deploy (or an
+                // isolate eviction) tore down. The engine re-runs the interrupted
+                // step, so a run that reset and then COMPLETED carries no failure
+                // and no error code: this cell is the only place it shows.
+                { header: "RESETS", key: "resets" },
+                { header: "STARTED", key: "startedAt", format: formatDate },
+                { header: "ENDED", key: "endedAt", format: formatDate },
+                { header: "CODE", key: "errorCode" },
+            ]));
+            if (nextCursor) {
+                info(`More runs: --cursor ${nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3348 — the step-level view of a durable run.
+    //
+    // A durable function's handler calls named steps and the engine memoizes each
+    // completed one to replay it, but nothing exposed them: `workflows runs
+    // steps|status|step-detail` resolve their first argument to a workflow
+    // DEFINITION, which a function id and a function key alike miss, and
+    // `functions runs` above reports only the run row — status, start, end, one
+    // error string. For a run that did partial work there was no way to see which
+    // steps completed, how long each took, or where the time went.
+    //
+    // A SUBCOMMAND of `runs`, which keeps its own `<function-id>` argument form.
+    // Commander dispatches to a subcommand only when the first operand names one,
+    // and a function id is a ULID, so `functions runs <function-id>` is untouched.
+    runs
+        .command("steps")
+        .description("Show step-level details for a function run")
+        .argument("<function-id>", "Function ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, runId, _options, command) => {
+        // `optsWithGlobals`, not the action's own `options`. `runs` is a command
+        // with arguments AND subcommands, so commander parses ITS options out of
+        // the argv before it dispatches here — and `runs` declares `--app` and
+        // `--json` too, so both land on the parent and the subcommand's copies
+        // read empty. The merged view is what the flags an operator typed
+        // actually are.
+        const options = command.optsWithGlobals();
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.getFunctionStepRuns(resolvedAppId, functionId, runId);
+            if (options.json) {
+                // The same envelope `workflows runs steps --json` emits: one run's
+                // full trace under `items`, never a bare array and never a cursor.
+                json(buildWorkflowStepEnvelope(items));
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No step runs found.");
+                return;
+            }
+            console.log(renderStepRunTable(items));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3348 — end a run that will not settle.
+    //
+    // `client.functions.terminate` has existed in the SDK since #3186 and nothing
+    // reached it from an operator's side, so a run left `running` after its
+    // context document was deleted stayed `running` with nothing to do about it.
+    runs
+        .command("terminate")
+        .description("End a function run that will not settle")
+        .argument("<function-id>", "Function ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, runId, _options, command) => {
+        // See `runs steps` above: `runs` parses its own `--app`/`--json` out of
+        // the argv before dispatching here, so the merged view is the real one.
+        const options = command.optsWithGlobals();
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Terminate run ${runId}? Its work stops where it is.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.terminateFunctionRun(resolvedAppId, functionId, runId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            if (!result.terminated) {
+                // The run finished on its own. Reporting a kill would be a lie, and
+                // the status it settled at is the answer the operator wanted.
+                info(`Run ${result.runId} had already settled (${result.status}); nothing to terminate.`);
+                return;
+            }
+            success(`Run ${result.runId} terminated.`);
+            printResult("Status", formatStatus(result.status));
+            printResult("Ended", formatDate(result.endedAt));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3287 — the invocation logs. `runs` above answers what HAPPENED; this
+    // answers what the function PRINTED and what it threw, which is the thing
+    // an operator reaches for when a function is failing and the response says
+    // only that it did.
+    functions
+        .command("logs")
+        .description("List a server function's invocation logs, newest first")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Rows per page (default 25, max 100)")
+        .option("--cursor <cursor>", "Continue from a previous page")
+        .option("--follow", "Append new invocations as they are recorded (tail)")
+        .option("--interval <seconds>", "Poll interval for --follow (default 2)")
+        .option("--run <run-id>", "Only this run's records (#3448)")
+        .option("--invocation <invocation-id>", "One record, by the id an invoke answered with (#3448)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const limit = options.limit ? Number(options.limit) : undefined;
+        // A cursor names a page in the PAST and a tail starts from now: serving
+        // both would mean guessing which the caller meant.
+        if (options.follow && options.cursor) {
+            error("--follow and --cursor cannot be combined; --follow tails from now.");
+            process.exit(1);
+        }
+        // #3448 — `--invocation` names ONE record, so every flag that shapes a
+        // listing contradicts it, and `--run` is a filter a tail cannot honour.
+        const conflict = logsFlagConflict(options);
+        if (conflict) {
+            error(conflict);
+            process.exit(1);
+        }
+        try {
+            if (options.invocation) {
+                // The point read. A record that never existed, one of ANOTHER
+                // function, and one the seven-day TTL has expired all answer the
+                // same 404 — which is the listing's own filter, said out loud.
+                let record;
+                try {
+                    record = await client.getFunctionLog(resolvedAppId, functionId, String(options.invocation));
+                }
+                catch (err) {
+                    // An id nothing wrote, one of ANOTHER function, and one the
+                    // seven-day TTL has expired all answer the same 404 — so the
+                    // message names the retention rather than implying the platform
+                    // lost something (edge 37).
+                    if (err?.statusCode === 404) {
+                        error(`No invocation ${options.invocation} for this function. ` +
+                            `Invocation records are kept for seven days.`);
+                        process.exit(1);
+                    }
+                    throw err;
+                }
+                if (options.json) {
+                    json(toFunctionLogInspectionRow(record));
+                    return;
+                }
+                console.log(formatTable([functionLogCells(record)], FUNCTION_LOG_COLUMNS.map((header) => ({
+                    header,
+                    key: LOG_COLUMN_KEYS[header],
+                    ...(LOG_COLUMN_FORMATS[header]
+                        ? { format: LOG_COLUMN_FORMATS[header] }
+                        : {}),
+                }))));
+                return;
+            }
+            if (options.follow) {
+                const intervalSeconds = options.interval ? Number(options.interval) : 2;
+                if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+                    error("--interval must be a positive number of seconds.");
+                    process.exit(1);
+                }
+                const controller = new AbortController();
+                const onSigint = () => controller.abort();
+                process.on("SIGINT", onSigint);
+                try {
+                    // The high-water mark is the newest `invocationId` already seen.
+                    // It is a ULID, so string order IS creation order and "newer than
+                    // this" is a comparison rather than a set of ids to remember.
+                    // The route answers NEWEST first, so a tick walks BACKWARD until
+                    // it meets the mark rather than reading one page and hoping
+                    // (CR3287-007). The walk is `buildLogFollowSource`, where it can
+                    // be put to a test without a server.
+                    const source = buildLogFollowSource(({ cursor }) => client.listFunctionLogs(resolvedAppId, functionId, {
+                        ...(limit ? { limit } : {}),
+                        ...(cursor ? { cursor } : {}),
+                    }), {
+                        idOf: (row) => String(row.invocationId),
+                        maxPagesPerTick: FOLLOW_MAX_PAGES_PER_TICK,
+                    });
+                    if (!options.json) {
+                        info("Following invocations (Ctrl-C to stop)…");
+                    }
+                    await followLoop(source, {
+                        intervalMs: intervalSeconds * 1000,
+                        signal: controller.signal,
+                        render: (items) => {
+                            if (options.json) {
+                                // One JSON object per line — a tail has no closing bracket
+                                // to wait for — each in the SHARED inspection item shape,
+                                // the same items the one-shot envelope carries.
+                                for (const row of items)
+                                    jsonLine(toFunctionLogInspectionRow(row));
+                                return;
+                            }
+                            for (const row of items)
+                                console.log(functionLogLine(row));
+                        },
+                    });
+                }
+                finally {
+                    process.off("SIGINT", onSigint);
+                }
+                return;
+            }
+            // #3448 D3448-SO-006, the CLI half. A FILTERED page holding only
+            // other runs' records comes back EMPTY WITH A CURSOR, which is an
+            // intermediate page and not the end: returning on it — as this did —
+            // reports "no logs" for a run whose records are one page further down.
+            // The continuation is followed a bounded number of times, and if it is
+            // still holding nothing the empty state is printed WITH the cursor
+            // rather than as a bare "none".
+            let cursor = options.cursor;
+            let items = [];
+            let nextCursor;
+            let exhaustedCursor = null;
+            for (let followed = 0;; followed += 1) {
+                const page = await client.listFunctionLogs(resolvedAppId, functionId, {
+                    ...(limit ? { limit } : {}),
+                    ...(cursor ? { cursor } : {}),
+                    ...(options.run ? { runId: String(options.run) } : {}),
+                });
+                items = page.items;
+                nextCursor = page.nextCursor;
+                const decision = decidePageContinuation(page, followed);
+                if (decision.action === "continue") {
+                    cursor = decision.cursor;
+                    continue;
+                }
+                if (decision.action === "exhausted")
+                    exhaustedCursor = decision.cursor;
+                break;
+            }
+            if (options.json) {
+                // The shared envelope, whose items are the shared inspection shape:
+                // a consumer classifies and pivots on `outcome`, `nativeStatus` and
+                // `correlation` without knowing which store answered (DSO3287-007).
+                json({
+                    items: items.map((row) => toFunctionLogInspectionRow(row)),
+                    hasMore: !!nextCursor,
+                    ...(nextCursor ? { nextCursor } : {}),
+                });
+                return;
+            }
+            if (!items || items.length === 0) {
+                info(options.run
+                    ? `No invocation logs found for run ${options.run}.`
+                    : "No invocation logs found for this function.");
+                // Not the end: the scan's budget was spent with matching records
+                // possibly still below. Printing the cursor is what lets an operator
+                // continue rather than concluding there is nothing there.
+                if (exhaustedCursor)
+                    info(`More logs: --cursor ${exhaustedCursor}`);
+                return;
+            }
+            if (options.run) {
+                // #3453 — reading ONE run, which is a different question from
+                // listing a function's invocations. A table of one row per record
+                // answers "which invocations were there"; what an operator opened
+                // `--run` for is what the run PRINTED, and until now that was only
+                // reachable through `--json`. So: the step trace first, then each
+                // record oldest first with its own lines under it.
+                let trace = null;
+                let traceError = null;
+                try {
+                    const read = await client.getFunctionStepRuns(resolvedAppId, functionId, String(options.run));
+                    trace = read?.items ?? [];
+                }
+                catch (traceErr) {
+                    traceError = traceErr?.message ?? String(traceErr);
+                }
+                const rendered = renderRunLogs({ records: items, trace, traceError });
+                if (rendered.warning)
+                    warn(rendered.warning);
+                for (const line of rendered.lines)
+                    console.log(line);
+                if (nextCursor) {
+                    info(`More logs: --cursor ${nextCursor}`);
+                }
+                return;
+            }
+            console.log(formatTable(items.map((row) => functionLogCells(row)), FUNCTION_LOG_COLUMNS.map((header) => ({
+                header,
+                key: LOG_COLUMN_KEYS[header],
+                ...(LOG_COLUMN_FORMATS[header]
+                    ? { format: LOG_COLUMN_FORMATS[header] }
+                    : {}),
+            }))));
+            if (nextCursor) {
+                info(`More logs: --cursor ${nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3182 — the typed handle's generated files, and the freshness question a
+    // CI job has to be able to ASK. `config push` writes them and `config diff`
+    // names the stale ones, but a diff exits 0 whatever it found, so a job that
+    // meant to fail on stale types passed and a declaration that disagreed with
+    // its schema reached the author as types that quietly lie (F3182-004). The
+    // verb and the flag are the two `databases codegen` and `workflows codegen`
+    // already use for exactly this.
+    functions
+        .command("codegen")
+        .allowExcessArguments(false)
+        .description("Write the generated files into the config tree's functions/ directory: the database-type declaration, the primitive-functions declaration, the functions declaration (<Key>Input/<Key>Output from each function's schemas), the per-function client invokers under generated/, and the tsconfig that wires the declarations into your editor. `config push` does this too; this is the standalone form, with a --check mode for CI.")
+        .option("--check", "Exit non-zero if the generated files are out of date or the tsconfig no longer loads them (CI guard); does not write.")
+        .option("-o, --out <dir>", "Directory for the per-function client invokers (default: <tree>/functions/generated/)")
+        .option("--lang <lang>", "Target language for the generated per-key invokers: 'ts' (default) or 'swift'. Swift emits one <key>.generated.swift per function (<Key>Input/<Key>Output Codable types + a <Key>Function invoker) and writes no TypeScript artifact. Every invoker carries both verb sets in either language — invoke, start, getStatus, waitFor, terminate — because the caller picks the runtime at each call.", "ts")
+        .option("--json", "Output the result summary as JSON")
+        .action(async (options) => {
+        // `--lang` is validated FIRST, before a single file is read, so an
+        // unknown value fails naming the flag rather than reporting whatever the
+        // schema parser happened to meet on the way (#3344 behavior 8).
+        const lang = String(options.lang ?? "ts").toLowerCase();
+        if (lang !== "ts" && lang !== "swift") {
+            error(`Unknown --lang "${options.lang}". Use "ts" or "swift".`);
+            process.exit(1);
+        }
+        // A tree command: what it writes is the environment's own directory,
+        // which is the only directory it can be asked to write (#3154).
+        const configDir = resolveSyncDir();
+        if (!existsSync(configDir)) {
+            error(`Config directory not found: ${configDir}`);
+            process.exit(1);
+        }
+        if (!existsSync(join(configDir, "functions")) &&
+            !treeDeclaresAgentPrompt(configDir) &&
+            !holdsAgentArtifacts(options.out ? String(options.out) : join(configDir, "functions", "generated"))) {
+            // Nothing to type: the artifacts exist to serve function sources, and
+            // a tree with none needs no compiler wiring. Not a failure — a tree
+            // may legitimately have no functions. #3798 (DSO-3798-005) — unless
+            // it declares an agent, whose client-side types are generated with or
+            // without functions, or (CSO-3798-003) a removed agent's artifacts are
+            // still there to sweep and for `--check` to report.
+            if (options.json)
+                json({ ok: true, stale: [], problems: [] });
+            else
+                info(`No functions/ directory in ${configDir}; nothing to generate.`);
+            return;
+        }
+        // #3281 — the per-key client invokers go beside the declarations unless
+        // `-o` names another directory, the `workflows codegen` shape.
+        const artifactOptions = options.out ? { invokerDir: String(options.out) } : {};
+        // #3344 — the Swift half. It shares the default output directory with
+        // the TypeScript invokers (suffixes and ownership banners keep the two
+        // sweeps apart) and writes NO TypeScript artifact: a Swift app has no
+        // tsconfig to wire, so `problems` is always empty here.
+        if (lang === "swift") {
+            const outputDir = options.out
+                ? String(options.out)
+                : join(configDir, "functions", "generated");
+            // Tree-relative, so the paths a CI job prints read the way the author's
+            // repository does.
+            const relative = (filePath) => relativePath(configDir, filePath);
+            let outcome;
+            try {
+                outcome = await generateFunctionSwiftTypes({
+                    inputs: functionSchemaSources(configDir),
+                    // #3798 — each agent prompt's Swift types, in the same run.
+                    agentInputs: promptSchemaSources(configDir),
+                    outputDir,
+                    check: Boolean(options.check),
+                });
+            }
+            catch (err) {
+                // A malformed schema, a duplicate key, an un-typable schema or a
+                // collision with another generator's file: nothing is written, and
+                // the message names the file the author edits.
+                if (!(err instanceof FunctionSchemaCodegenError) &&
+                    !(err instanceof SwiftCodegenError)) {
+                    throw err;
+                }
+                if (options.json)
+                    json({ ok: false, stale: [], problems: [err.message] });
+                else
+                    error(err.message);
+                process.exit(1);
+            }
+            if (options.check) {
+                const stale = outcome.mismatches.map((m) => relative(m.filePath)).sort();
+                if (stale.length === 0) {
+                    if (options.json)
+                        json({ ok: true, stale: [], problems: [] });
+                    else
+                        success("Check passed: the generated Swift invokers are up to date.");
+                    return;
+                }
+                if (options.json) {
+                    json({ ok: false, stale, problems: [] });
+                }
+                else {
+                    error(`Check failed: ${stale.length} file(s) out of date.`);
+                    for (const mismatch of outcome.mismatches) {
+                        error(`  ${mismatch.reason}: ${relative(mismatch.filePath)}`);
+                    }
+                    const regenerate = ["primitive functions codegen --lang swift"];
+                    if (options.out)
+                        regenerate.push(`-o ${options.out}`);
+                    info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
+                }
+                process.exit(1);
+            }
+            const writtenRelative = outcome.writtenFiles.map(relative).sort();
+            const deletedRelative = outcome.deletedFiles.map(relative).sort();
+            if (options.json) {
+                json({ written: writtenRelative, deleted: deletedRelative, problems: [] });
+                return;
+            }
+            success(`Wrote ${writtenRelative.length} Swift file(s) into ${outputDir}.`);
+            for (const file of writtenRelative)
+                keyValue("  wrote", file);
+            for (const file of deletedRelative)
+                keyValue("  swept", file);
+            return;
+        }
+        // Wiring push cannot repair is checked alongside freshness: a tsconfig
+        // that carries comments is never rewritten, so it can be perfectly
+        // current and still load none of the declarations (CR3182-003).
+        let problems;
+        let stale = [];
+        try {
+            problems = functionTypeWiringProblems(configDir, artifactOptions);
+            if (options.check)
+                stale = staleFunctionTypeArtifacts(configDir, artifactOptions);
+        }
+        catch (err) {
+            // A malformed schema in a function file: nothing can be generated
+            // from it, and the message names the file.
+            if (!(err instanceof FunctionSchemaCodegenError))
+                throw err;
+            if (options.json)
+                json({ ok: false, stale: [], problems: [err.message] });
+            else
+                error(err.message);
+            process.exit(1);
+        }
+        if (options.check) {
+            if (stale.length === 0 && problems.length === 0) {
+                if (options.json)
+                    json({ ok: true, stale: [], problems: [] });
+                else
+                    success("Check passed: the function types are up to date.");
+                return;
+            }
+            if (options.json) {
+                json({ ok: false, stale, problems });
+            }
+            else {
+                error(`Check failed: ${stale.length} file(s) out of date` +
+                    (problems.length > 0
+                        ? `, ${problems.length} wiring problem(s).`
+                        : "."));
+                for (const relative of stale)
+                    error(`  out of date: ${relative}`);
+                for (const problem of problems) {
+                    error(`  functions/tsconfig.json: ${problem}`);
+                }
+                // Name the command that fixes what was just reported, keeping the
+                // options that decided WHERE it looked (#2911). The tree itself is
+                // no longer one of them (#3154) — only `-o` is left.
+                const regenerate = ["primitive functions codegen"];
+                if (options.out)
+                    regenerate.push(`-o ${options.out}`);
+                info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
+            }
+            process.exit(1);
+        }
+        const written = writeFunctionTypeArtifacts(configDir, undefined, artifactOptions);
+        if (options.json) {
+            json({ written, problems });
+            return;
+        }
+        success(`Wrote ${written.length} file(s) into ${configDir}/functions/.`);
+        for (const relative of written)
+            keyValue("  wrote", relative);
+        for (const problem of problems) {
+            warn(`functions/tsconfig.json: ${problem}`);
+        }
+    });
+    // #2803 — the operational verb pair, and the only writers of `status` besides
+    // the delete flow. `config push` is deliberately not one: see the module note.
+    functions
+        .command("disable")
+        .description("Take a server function out of service now. Invocations are refused; the committed configuration and code are unchanged.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.setFunctionAvailability(resolvedAppId, functionId, "disable");
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function disabled: ${result.functionKey || functionId}`);
+            info("Invocations are refused. `primitive config push` still updates the code and leaves it out of service — `primitive functions enable` puts it back.");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("enable")
+        .description("Put a server function back in service.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.setFunctionAvailability(resolvedAppId, functionId, "enable");
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function enabled: ${result.functionKey || functionId}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #2907 — the delete flow's CLI spelling. The plain `DELETE` the server has
+    // always answered by writing the tombstone; not a second writer of `status`.
+    functions
+        .command("archive")
+        .description("Retire a server function (soft delete). Delete-lifecycle, not `disable`: the row is kept, goes on holding its key, and there is no un-archive.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+What archiving a function costs:
+  Invocations are refused, as they are for a disabled function.
+  The archived row still holds its key in the app's SINGLE key namespace — no
+  new function, workflow, script or webhook may take that key while it stands —
+  and pushing code to an archived function is refused.
+  \`primitive functions enable\` refuses an archived function; there is no
+  un-archive.
+
+Reclaiming the key means hard-deleting the row:
+  $ rm functions/<key>.toml
+  $ primitive config push --prune     # confirmed; hard-deletes the row, its
+                                      # versions and their stored bundles
+  # or hard-delete it in the console, then re-add the file and push.
+`)
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Archive function ${functionId}? Invocations stop, the row keeps its ` +
+                    `key in the app's single key namespace, and there is no un-archive.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            // The soft delete: no `hard`, so the server writes the tombstone and
+            // keeps the reservation. Prune-by-push owns the hard path.
+            const result = await client.deleteFunction(resolvedAppId, functionId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function archived: ${functionId}`);
+            info("Invocations are refused and pushes to it are rejected. The row still holds its key — reclaim it by removing its file and running a confirmed `primitive config push --prune`.");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── #3448: running a function ───────────────────────────────────────
+    //
+    // `functions list|get|runs|logs` could INSPECT a function and nothing could
+    // run one: invoking a request function, starting a task and waiting for a
+    // run all needed a signed-in app client or a test harness, and stopping an
+    // experimental run needed SDK code (Compound developer feedback SF3).
+    //
+    // Two identities were missing with it. Every HTTP invocation ran as a
+    // caller, so a function fired by cron, a webhook or a database change —
+    // `ctx.user` null, the system principal — could not be exercised from
+    // outside without faking its trigger.
+    //
+    // Every decision these verbs make is in `cli/src/lib/function-run.ts`, where
+    // it is pinned without a server; what is here is the I/O and the rendering.
+    /**
+     * Key → the function's id.
+     *
+     * `invoke` and `start` take the KEY, because that is the public route's
+     * argument and what a developer wrote in their TOML — while `runs`, `logs`
+     * and `steps` keep the function id they have always taken. So the key has to
+     * be resolved, and the drained admin listing is what `functions list` reads.
+     *
+     * #3482 — the ACTIVE VERSION is no longer read. It was point-read for one
+     * reason: the mode pre-check, which refused the wrong verb before a round
+     * trip. There is no wrong verb any more — the caller picks the runtime and
+     * every function takes both — so the read and the pre-check go together.
+     */
+    async function resolveFunctionByKey(client, appId, functionKey) {
+        const { items } = await client.listFunctions(appId);
+        const wanted = functionKey.trim().toLowerCase();
+        const match = (items || []).find((item) => String(item.functionKey ?? "").toLowerCase() === wanted);
+        if (!match) {
+            throw new Error(`No function with key '${functionKey}' in this app. ` +
+                `List them with 'primitive functions list'.`);
+        }
+        return { functionId: String(match.functionId) };
+    }
+    /** The identity a call runs under, and the bearer it presents. */
+    async function planIdentity(client, appId, identity) {
+        if (identity.kind === "system") {
+            const me = await client.getAppProfile(appId);
+            return {
+                describe: describeIdentity({ kind: "system", byUserId: me.userId }),
+                actingUserId: null,
+                asSystem: true,
+            };
+        }
+        if (identity.kind === "user") {
+            return {
+                describe: describeIdentity({ kind: "user", userId: identity.userId }),
+                actingUserId: identity.userId,
+                asSystem: false,
+            };
+        }
+        const me = await client.getAppProfile(appId);
+        return {
+            describe: describeIdentity({
+                kind: "self",
+                userId: me.userId,
+                appRole: me.appRole,
+            }),
+            actingUserId: me.userId,
+            asSystem: false,
+        };
+    }
+    /** Print an envelope's ids, each followed by the command that takes it. */
+    function printIdLines(lines) {
+        for (const line of renderIdLines(lines))
+            console.log(line);
+    }
+    functions
+        .command("invoke")
+        .allowExcessArguments(false)
+        .description("Run a REQUEST function over the public route and print its result — the same call `client.functions.invoke` makes")
+        .argument("<key>", "Function key (as written in functions/<key>.toml)")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--input <json>", "The handler's input, as JSON (default {})")
+        .option("--context-doc-id <id>", "Context document for the invocation")
+        .option("--timeout <seconds>", "Wall-clock budget; the platform clamps at 30s")
+        .option("--user <user-id>", "Run as this app user (admin/owner only)")
+        .option("--as <principal>", "Run with no caller: --as system (admin/owner only)")
+        .option("--json", "Output as JSON")
+        .action(async (functionKey, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const flags = resolveRunFlags(options);
+        if (flags.ok === false) {
+            error(flags.error);
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        try {
+            const target = await resolveFunctionByKey(client, resolvedAppId, functionKey);
+            const identity = await planIdentity(client, resolvedAppId, flags.identity);
+            const body = {
+                rootInput: flags.input,
+                ...(options.contextDocId ? { contextDocId: options.contextDocId } : {}),
+                ...(flags.timeoutSeconds
+                    ? { timeoutMs: Math.round(flags.timeoutSeconds * 1000) }
+                    : {}),
+            };
+            const answer = await runAs(client, resolvedAppId, flags.identity, "invoke", functionKey, (bearer) => client.invokeFunction(resolvedAppId, functionKey, body, {
+                ...(bearer ? { bearer } : {}),
+                asSystem: identity.asSystem,
+                // #3482 — the ROUTE says which runtime this call means. The
+                // admin-only system door is one route for both, so the body still
+                // names it there and only there.
+                runtime: "request",
+                ...(identity.asSystem ? {} : {}),
+            }));
+            const envelope = answer.body ?? {};
+            if (options.json) {
+                json({
+                    functionId: target.functionId,
+                    functionKey,
+                    identity: identity.describe,
+                    httpStatus: answer.httpStatus,
+                    ...(answer.retryAfterSeconds !== null
+                        ? { retryAfterSeconds: answer.retryAfterSeconds }
+                        : {}),
+                    ...envelope,
+                });
+                process.exit(exitCodeForInvokeAnswer(answer));
+            }
+            if (answer.httpStatus >= 400) {
+                renderRefusal(answer);
+                // The ids, each with the command that takes it — the same rendering
+                // a success gets, because a refusal is when an operator most needs
+                // the next command (CR3448-004). A REFUSAL CAN CARRY AN INVOCATION
+                // ID: the two 500s the platform records answer one (edge 35), and
+                // printing the function id bare beside it left the record findable
+                // only by someone who already knew the flag.
+                printIdLines(invokeIdLines({
+                    functionId: target.functionId,
+                    invocationId: envelope.invocationId,
+                }));
+                process.exit(1);
+            }
+            printResult("Status", formatStatus(String(envelope.status ?? "")));
+            if (envelope.output !== undefined) {
+                console.log("Output");
+                console.log(JSON.stringify(envelope.output, null, 2));
+            }
+            if (envelope.error)
+                printResult("Error", String(envelope.error));
+            if (envelope.errorCode)
+                printResult("Code", String(envelope.errorCode));
+            if (envelope.limits) {
+                printResult("Limits", `cpuMs ${envelope.limits.cpuMs}, subRequests ${envelope.limits.subRequests}, ratePerMinute ${envelope.limits.ratePerMinute}`);
+            }
+            console.log(identity.describe);
+            printIdLines(invokeIdLines({
+                functionId: target.functionId,
+                invocationId: envelope.invocationId,
+            }));
+            process.exit(exitCodeForInvokeAnswer(answer));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("start")
+        .allowExcessArguments(false)
+        .description("Start a TASK function and print its run id")
+        .argument("<key>", "Function key (as written in functions/<key>.toml)")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--input <json>", "The handler's input, as JSON (default {})")
+        .option("--context-doc-id <id>", "Context document the run is keyed under")
+        .option("--run-key <key>", "Idempotency key; a repeat replays the existing run")
+        .option("--user <user-id>", "Run as this app user (admin/owner only)")
+        .option("--as <principal>", "Run with no caller: --as system (admin/owner only)")
+        .option("--wait", "Wait for the run to settle, then print its outcome")
+        .option("--timeout <seconds>", "Budget for --wait (default 900)")
+        .option("--json", "Output as JSON")
+        .action(async (functionKey, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const flags = resolveRunFlags(options);
+        if (flags.ok === false) {
+            error(flags.error);
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        try {
+            const target = await resolveFunctionByKey(client, resolvedAppId, functionKey);
+            const identity = await planIdentity(client, resolvedAppId, flags.identity);
+            // D3448-014 — the task path defaults the context to the acting user's
+            // `AppUser.rootDocId`, and the app user provisioned for an admin has
+            // none, so the advertised `functions start <key> --wait` would refuse
+            // `CONTEXT_DOC_REQUIRED` on a fresh app. The route that mints one is
+            // idempotent, so asking for it is free on the second call.
+            //
+            // `--as system` keeps the synthetic `fn:<functionId>` context and does
+            // NOT call the route: there is no app user to mint a document for.
+            let contextDocId = options.contextDocId;
+            if (!contextDocId && !identity.asSystem && identity.actingUserId) {
+                const root = await client.ensureUserRootDocument(resolvedAppId, identity.actingUserId);
+                contextDocId = root.rootDocId;
+            }
+            const body = {
+                rootInput: flags.input,
+                // #3482 — `--as system` is the ONE door that is a single route for
+                // both runtimes, so it keeps the deprecated body selector; every
+                // other call says it with the route.
+                ...(identity.asSystem ? { mode: "task" } : {}),
+                ...(contextDocId ? { contextDocId } : {}),
+                ...(options.runKey ? { runKey: options.runKey } : {}),
+            };
+            const answer = await runAs(client, resolvedAppId, flags.identity, "start", functionKey, (bearer) => client.invokeFunction(resolvedAppId, functionKey, body, {
+                ...(bearer ? { bearer } : {}),
+                asSystem: identity.asSystem,
+                runtime: "task",
+            }));
+            const envelope = answer.body ?? {};
+            if (answer.httpStatus >= 400) {
+                if (options.json) {
+                    json({
+                        functionId: target.functionId,
+                        functionKey,
+                        identity: identity.describe,
+                        httpStatus: answer.httpStatus,
+                        ...(answer.retryAfterSeconds !== null
+                            ? { retryAfterSeconds: answer.retryAfterSeconds }
+                            : {}),
+                        ...envelope,
+                    });
+                }
+                else {
+                    renderRefusal(answer);
+                }
+                process.exit(1);
+            }
+            const runId = String(envelope.runId ?? "");
+            if (!options.json) {
+                if (envelope.existing) {
+                    info(`Replayed the existing run for this run key (existing).`);
+                }
+                console.log(identity.describe);
+                printIdLines(startIdLines({ functionId: target.functionId, runId }));
+            }
+            if (!options.wait) {
+                if (options.json) {
+                    json({
+                        functionId: target.functionId,
+                        functionKey,
+                        identity: identity.describe,
+                        httpStatus: answer.httpStatus,
+                        ...envelope,
+                    });
+                }
+                process.exit(0);
+            }
+            // The run id is printed BEFORE the wait begins, so an operator who
+            // interrupts still holds the thing they need to resume.
+            const outcome = await waitForFunctionRun({
+                client,
+                appId: resolvedAppId,
+                functionId: target.functionId,
+                runId,
+                timeoutSeconds: flags.timeoutSeconds ?? WAIT_DEFAULT_TIMEOUT_SECONDS,
+                json: !!options.json,
+            });
+            process.exit(outcome);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    runs
+        .command("wait")
+        .allowExcessArguments(false)
+        .description("Poll a function run until it settles")
+        .argument("<function-id>", "Function ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--timeout <seconds>", "Give up after this many seconds (default 900)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, runId, _options, command) => {
+        // `optsWithGlobals`, for the reason `runs steps` records: `runs` declares
+        // `--app` and `--json` of its own, so both land on the parent.
+        const options = command.optsWithGlobals();
+        const resolvedAppId = resolveAppId(undefined, options);
+        const flags = resolveRunFlags({ timeout: options.timeout });
+        if (flags.ok === false) {
+            error(flags.error);
+            process.exit(1);
+        }
+        const client = new ApiClient();
+        try {
+            const outcome = await waitForFunctionRun({
+                client,
+                appId: resolvedAppId,
+                functionId,
+                runId,
+                timeoutSeconds: flags.timeoutSeconds ?? WAIT_DEFAULT_TIMEOUT_SECONDS,
+                json: !!options.json,
+            });
+            process.exit(outcome);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+}
+/**
+ * A refusal, rendered from the envelope the server sent — #3448.
+ *
+ * `ApiClient.invokeFunction` hands the answer back rather than throwing for
+ * exactly this: a 429 carries a `Retry-After` an operator needs and a 409 mode
+ * mismatch carries the version's real mode, and re-deriving either from an
+ * exception message would be re-deriving what the server already said.
+ */
+/**
+ * Whether a directory still holds an agent's generated artifact (either
+ * language) — #3798, CSO-3798-003: a tree whose last agent was removed has
+ * nothing left to generate, and those files still need sweeping (and
+ * reporting under `--check`).
+ */
+function holdsAgentArtifacts(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((file) => file.endsWith(AGENT_CLIENT_FILE_SUFFIX) || file.endsWith(AGENT_SWIFT_FILE_SUFFIX));
+    }
+    catch {
+        return false;
+    }
+}
+function renderRefusal(answer) {
+    const lines = refusalLines(answer);
+    error(lines.message);
+    for (const field of lines.fields)
+        printResult(field.label, field.value);
+    for (const detail of lines.details)
+        info(`  ${detail}`);
+}
+/** Exit 0 only for a completed invocation; every refusal and every terminal failure is 1. */
+function exitCodeForInvokeAnswer(answer) {
+    if (answer.httpStatus >= 400)
+        return 1;
+    return exitCodeForInvokeStatus(answer.body?.status);
+}
+/**
+ * Run a call under the operator's own identity, or under a ten-minute token
+ * minted for `--user` — D3448-009.
+ *
+ * The token is a REAL credential for another user, so it is revoked on every
+ * exit path including Ctrl-C (the wrapper's `finally`), and its value never
+ * reaches stdout, stderr or `--json`: `use` receives it and nothing else does.
+ */
+async function runAs(client, appId, identity, verb, functionKey, use) {
+    if (identity.kind !== "user")
+        return use(undefined);
+    return withMintedToken({
+        mint: async () => {
+            const minted = await client.createToken(appId, {
+                name: userTokenName(verb, functionKey),
+                ttl: USER_TOKEN_TTL,
+                userId: identity.userId,
+            });
+            return { token: minted.token, tokenId: minted.tokenId };
+        },
+        revoke: (tokenId) => client.revokeToken(appId, tokenId).then(() => undefined),
+        warn: (message) => warn(message),
+    }, (token) => use(token));
+}
+/**
+ * Poll one run until it settles, the budget is spent, or the operator
+ * interrupts — #3448 behavior 16.
+ *
+ * It polls the ADMIN single-run read, never the runs listing: that reports the
+ * STORED status, and a durable run's row stays `running` until something asks
+ * the engine, so a wait built on it would never settle.
+ *
+ * Ctrl-C exits 130 after printing the resume command, and a second one exits
+ * at once — the failures sweep's shape, and the workflows group's convention.
+ */
+async function waitForFunctionRun(args) {
+    const { client, appId, functionId, runId } = args;
+    const deadline = Date.now() + args.timeoutSeconds * 1000;
+    let interrupted = false;
+    let interruptCount = 0;
+    const onSigint = () => {
+        interruptCount += 1;
+        if (interruptCount > 1)
+            process.exit(EXIT_INTERRUPTED);
+        interrupted = true;
+    };
+    process.on("SIGINT", onSigint);
+    try {
+        let attempt = 0;
+        for (;;) {
+            const read = await client.getFunctionRun(appId, functionId, runId);
+            const status = String(read?.status?.status ?? "");
+            const settled = exitCodeForRunStatus(status);
+            if (settled !== null) {
+                if (args.json) {
+                    json({ functionId, runId, ...read });
+                    return settled;
+                }
+                printResult("Status", formatStatus(status));
+                if (read?.status?.output !== undefined) {
+                    console.log("Output");
+                    console.log(JSON.stringify(read.status.output, null, 2));
+                }
+                const failure = read?.status?.error;
+                if (failure) {
+                    printResult("Error", typeof failure === "string" ? failure : String(failure?.message ?? ""));
+                }
+                if (read?.run?.errorCode)
+                    printResult("Code", String(read.run.errorCode));
+                return settled;
+            }
+            if (interrupted) {
+                if (!args.json) {
+                    info(`Stopped waiting. The run is still going; resume with:`);
+                    info(`  ${resumeCommand(functionId, runId)}`);
+                }
+                return EXIT_INTERRUPTED;
+            }
+            if (Date.now() >= deadline) {
+                if (args.json) {
+                    json({ functionId, runId, timedOut: true, ...read });
+                }
+                else {
+                    warn(`Gave up after ${args.timeoutSeconds}s; the run is still ${status || "in flight"}. Resume with:`);
+                    info(`  ${resumeCommand(functionId, runId)}`);
+                }
+                return EXIT_TIMED_OUT;
+            }
+            const delay = Math.min(waitDelayMs(attempt), Math.max(0, deadline - Date.now()));
+            attempt += 1;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+    }
+}
+//# sourceMappingURL=functions.js.map