primitive-admin 1.1.0-alpha.81 → 1.1.0-alpha.83

package/dist/src/commands/functions.js

@@ -21,17 +21,22 @@ 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, 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 { 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 { 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";
 /**
  * How far back one `--follow` tick will page to meet its high-water mark.
  *
@@ -45,25 +50,26 @@ import { toFunctionLogInspectionRow } from "../lib/log-inspection.js";
  */
 const FOLLOW_MAX_PAGES_PER_TICK = 10;
 /**
- * One invocation, as a human reads it in the table — #3287.
+ * Which cell each shared invocation column reads, and how it is rendered.
  *
- * The FIRST error line only: a stack is eight kilobytes and a table row is
- * one line, so the row says what happened and `--json` carries the rest.
+ * 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.
  */
-function firstErrorLine(row) {
-    const message = String(row?.errorMessage ?? "").trim();
-    if (message)
-        return message.split("\n")[0];
-    const stderr = Array.isArray(row?.stderr) ? row.stderr : [];
-    return stderr.length > 0 ? String(stderr[0].line ?? "") : "";
-}
-/** The same row, for the follow tail's one-line-per-invocation output. */
-function logRow(row) {
-    const when = row?.startedAt ? String(row.startedAt) : "";
-    const code = row?.errorCode ? `  ${row.errorCode}` : "";
-    const detail = firstErrorLine(row);
-    return `${when}  ${row?.status ?? ""}  ${row?.trigger?.kind ?? ""}  ${row?.runId || row?.invocationId || ""}${code}${detail ? `  ${detail}` : ""}`;
-}
+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")
@@ -142,18 +148,56 @@ Configuration lives in functions/<key>.toml, and the code beside it:
             // 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) {
-                const { items } = await client.listFunctionConfigs(resolvedAppId, functionId);
-                active =
-                    (items || []).find((c) => String(c.configId) === String(record.activeConfigId)) ?? null;
+                // #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 });
+                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 || "-");
@@ -168,9 +212,9 @@ 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));
+                // #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
@@ -180,6 +224,28 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                     ? 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
@@ -192,17 +258,11 @@ Configuration lives in functions/<key>.toml, and the code beside it:
             const cronEntries = Array.isArray(triggers.cron)
                 ? triggers.cron
                 : [];
-            // #3184 — the database types this function watches. A change trigger
-            // has no standalone surface at all (there is no `database-triggers
-            // list`), so this is the only place an operator can see that a write
-            // to a type runs this function. A server that predates #3184 sends no
-            // `databases` key, which reads as none.
-            const databaseEntries = Array.isArray(triggers.databases)
-                ? triggers.databases
-                : [];
-            if (!triggers.webhook &&
-                cronEntries.length === 0 &&
-                databaseEntries.length === 0) {
+            // #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) {
@@ -220,6 +280,9 @@ 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: "TZ", key: "timezone" },
                     { header: "STATUS", key: "status", format: formatStatus },
                     { header: "NEXT FIRE", key: "nextFireAt", format: formatDate },
@@ -227,15 +290,6 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                     { header: "LAST RUN", key: "lastTriggeredRunId" },
                 ]));
             }
-            if (databaseEntries.length > 0) {
-                printResult("  Database changes", "a committed write to one of these types runs this function");
-                // A fire carries the rows of every change of the type (the intent's
-                // 2026-09-09 decision), so the row says which type and no more —
-                // the READ GRANTS column retired with the grant grammar (#3279).
-                console.log(formatTable(databaseEntries, [
-                    { header: "DATABASE TYPE", key: "databaseType" },
-                ]));
-            }
             // #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
@@ -298,11 +352,129 @@ Configuration lives in functions/<key>.toml, and the code beside it:
             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).
-    functions
+    const runs = functions
         .command("runs")
         .description("List a server function's runs, newest first")
         .argument("<function-id>", "Function ID")
@@ -318,8 +490,17 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 ...(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, nextCursor });
+                json({ items: withRuntime, nextCursor });
                 return;
             }
             if (!items || items.length === 0) {
@@ -327,18 +508,29 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 return;
             }
             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).
+            // #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,
-                refreshes: run.slice && Number.isFinite(run.slice.refreshCount)
-                    ? String(run.slice.refreshCount)
-                    : "",
+                // #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.
@@ -346,6 +538,11 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 // #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" },
@@ -359,6 +556,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
@@ -372,6 +672,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);
@@ -383,7 +685,47 @@ 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([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) {
@@ -424,7 +766,7 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                                 return;
                             }
                             for (const row of items)
-                                console.log(logRow(row));
+                                console.log(functionLogLine(row));
                         },
                     });
                 }
@@ -433,10 +775,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
@@ -449,26 +815,49 @@ 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) => ({
-                startedAt: row.startedAt,
-                status: row.status,
-                trigger: row.trigger?.kind ?? "",
-                // A trigger fire and a task run name their run; a request
-                // invocation's key is its own id.
-                runOrInvocation: row.runId || row.invocationId,
-                errorCode: row.errorCode ?? "",
-                firstError: firstErrorLine(row),
-            })), [
-                { 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" },
-            ]));
+            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}`);
             }
@@ -761,5 +1150,429 @@ 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.
+     *
+     * `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.
+ */
+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