primitive-admin 1.1.0-alpha.80 → 1.1.0-alpha.82

package/dist/src/commands/functions.js

@@ -17,19 +17,24 @@
  * an endpoint an operator had taken down back in service.
  */
 import { existsSync } from "fs";
-import { join } from "path";
+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 { activeVersionMode } from "../lib/function-sync.js";
-import { FunctionSchemaCodegenError } from "../lib/function-schema-codegen.js";
+import { FunctionSchemaCodegenError, functionSchemaSources, } from "../lib/function-schema-codegen.js";
 import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
+import { generateFunctionSwiftTypes } from "../lib/swift-codegen/functionGenerator.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 { parseStatusFilter } from "../lib/object-status-filter.js";
+import { renderStepRunTable } from "../lib/step-run-table.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, modeFor, precheckMode, refusalLines, renderIdLines, resolveRunFlags, resumeCommand, startIdLines, userTokenName, waitDelayMs, withMintedToken, EXIT_INTERRUPTED, EXIT_TIMED_OUT, USER_TOKEN_TTL, WAIT_DEFAULT_TIMEOUT_SECONDS, } from "../lib/function-run.js";
 /**
  * How far back one `--follow` tick will page to meet its high-water mark.
  *
@@ -166,9 +171,11 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 printResult("  Config ID", active.configId);
                 printResult("  Entry", active.entry);
                 printResult("  Content Hash", active.contentHash || "-");
-                // #3281 — the mode words. A server that predates `mode` serializes
-                // only the `durable` column, which reads the same way.
-                printResult("  Mode", activeVersionMode(active));
+                // #3281 — the mode words, widened by #3454. A server that predates
+                // `mode` serializes only the `durable` column, which reads the same
+                // way. `any` names no runner, so the line says which verbs it takes.
+                const activeMode = activeVersionMode(active);
+                printResult("  Mode", activeMode === "any" ? "any (invoke or start)" : activeMode);
                 printResult("  Limits", active.limits || "-");
                 // #3182 — what this version declared: since #3279 the egress
                 // allowlist, the secrets that may enter the sandbox and the
@@ -218,6 +225,10 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                     { 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: "RUNNER", key: "runner" },
                     { header: "TZ", key: "timezone" },
                     { header: "STATUS", key: "status", format: formatStatus },
                     { header: "NEXT FIRE", key: "nextFireAt", format: formatDate },
@@ -300,7 +311,7 @@ Configuration lives in functions/<key>.toml, and the code beside it:
     // 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).
-    functions
+    const runs = functions
         .command("runs")
         .description("List a server function's runs, newest first")
         .argument("<function-id>", "Function ID")
@@ -324,7 +335,16 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 info("No runs found for this function.");
                 return;
             }
-            console.log(formatTable(items, [
+            console.log(formatTable(
+            // #3381 — flatten the slice's refresh count onto the row for the
+            // REFRESHES column. Blank for a run with no slice record (a run
+            // started before this child, or a request invocation).
+            items.map((run) => ({
+                ...run,
+                refreshes: run.slice && Number.isFinite(run.slice.refreshCount)
+                    ? String(run.slice.refreshCount)
+                    : "",
+            })), [
                 { header: "RUN ID", key: "runId" },
                 { header: "STATUS", key: "status", format: formatStatus },
                 { header: "FIRED BY", key: "initiatorKind" },
@@ -332,6 +352,9 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 // 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" },
                 { header: "STARTED", key: "startedAt", format: formatDate },
                 { header: "ENDED", key: "endedAt", format: formatDate },
                 { header: "CODE", key: "errorCode" },
@@ -345,6 +368,109 @@ Configuration lives in functions/<key>.toml, and the code beside it:
             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
@@ -358,6 +484,8 @@ Configuration lives in functions/<key>.toml, and the code beside it:
         .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);
@@ -369,7 +497,57 @@ Configuration lives in functions/<key>.toml, and the code beside it:
             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([
+                    {
+                        startedAt: record.startedAt,
+                        status: record.status,
+                        trigger: record.trigger?.kind ?? "",
+                        runOrInvocation: record.runId || record.invocationId,
+                        errorCode: record.errorCode ?? "",
+                        firstError: firstErrorLine(record),
+                    },
+                ], [
+                    { header: "TIME", key: "startedAt", format: formatDate },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                    { header: "TRIGGER", key: "trigger" },
+                    { header: "RUN/INVOCATION ID", key: "runOrInvocation" },
+                    { header: "CODE", key: "errorCode" },
+                    { header: "ERROR", key: "firstError" },
+                ]));
+                return;
+            }
             if (options.follow) {
                 const intervalSeconds = options.interval ? Number(options.interval) : 2;
                 if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
@@ -419,10 +597,34 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 }
                 return;
             }
-            const { items, nextCursor } = await client.listFunctionLogs(resolvedAppId, functionId, {
-                ...(limit ? { limit } : {}),
-                ...(options.cursor ? { cursor: options.cursor } : {}),
-            });
+            // #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
@@ -435,7 +637,14 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 return;
             }
             if (!items || items.length === 0) {
-                info("No invocation logs found for this function.");
+                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;
             }
             console.log(formatTable(items.map((row) => ({
@@ -477,8 +686,17 @@ Configuration lives in functions/<key>.toml, and the code beside it:
         .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 mode-fixed <Key>Function invoker) and writes no TypeScript artifact.", "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();
@@ -499,6 +717,76 @@ Configuration lives in functions/<key>.toml, and the code beside it:
         // #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),
+                    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).
@@ -668,5 +956,441 @@ Reclaiming the key means hard-deleting the row:
             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 and the mode its ACTIVE version runs in.
+     *
+     * `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.
+     */
+    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'.`);
+        }
+        const functionId = String(match.functionId);
+        // A function with no pushed version has no mode to disagree with, and the
+        // server's `FUNCTION_NOT_PUSHED` is the honest answer (edge 30).
+        let mode = null;
+        try {
+            const { items: configs } = await client.listFunctionConfigs(appId, functionId);
+            const active = (configs || []).find((config) => String(config.configId) === String(match.activeConfigId));
+            if (active)
+                mode = activeVersionMode(active);
+        }
+        catch {
+            // A version list this operator cannot read is not a reason to refuse the
+            // call: the pre-check is a courtesy and the server is the authority.
+            mode = null;
+        }
+        return { functionId, mode };
+    }
+    /** 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 precheck = precheckMode("invoke", target.mode, functionKey);
+            if (precheck.ok === false) {
+                error(precheck.error);
+                process.exit(1);
+            }
+            const identity = await planIdentity(client, resolvedAppId, flags.identity);
+            const body = {
+                rootInput: flags.input,
+                mode: modeFor("invoke"),
+                ...(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,
+            }));
+            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 precheck = precheckMode("start", target.mode, functionKey);
+            if (precheck.ok === false) {
+                error(precheck.error);
+                process.exit(1);
+            }
+            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,
+                mode: modeFor("start"),
+                ...(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,
+            }));
+            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.
+ */
+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