@usenaive-sdk/cli 0.14.0 → 0.15.1

package/dist/commands/agents.js

@@ -0,0 +1,916 @@
+import { Command } from "commander";
+import { apiRequest, handleApiError, scopePathToUser, activeUserId, activeProjectId } from "../client.js";
+import { loadConfig, getApiKey } from "../config.js";
+import { agentOutput, agentOutputExit, agentError, humanMode } from "../output.js";
+import { parseSse, highestSeq, redactFrame } from "../lib/stream-frames.js";
+/** micro-USD → a dollar string. The only arithmetic in this file, and it is on
+ *  a CAP (a configuration integer we set), never on the money ledger — every
+ *  spent figure stays the decimal string the API sent. */
+function usd(microUsd) {
+    return microUsd === undefined ? "—" : `$${(microUsd / 1_000_000).toFixed(2)}`;
+}
+function short(id) {
+    return id ? id.slice(0, 8) : "—";
+}
+/**
+ * Every `next_steps` command is DERIVED from the response the API just
+ * returned, so the id in a suggestion is the id the API echoed rather than an
+ * `<id>` placeholder, and a hint restates a field it actually sent. Neither can
+ * drift from what the platform did.
+ */
+function agentSteps(a, extra = []) {
+    const id = a?.id;
+    if (!id)
+        return extra;
+    return [
+        { command: `naive agents run ${id} "…"`, description: "Send work and stream it" },
+        { command: `naive agents tasks ${id}`, description: "The task board" },
+        { command: `naive agents spend ${id}`, description: "Spend against the cap" },
+        ...extra,
+    ];
+}
+/** Hints echoed off what the API returned — restated, never asserted. */
+function agentHints(a) {
+    if (!a)
+        return [];
+    const out = [];
+    if (a.status)
+        out.push(`Status: ${a.status}${a.blocked_reason ? ` (${a.blocked_reason})` : ""}`);
+    // 🔴 The idle-cost claim, rendered. An agent showing nothing is the NORMAL
+    // state of a long-horizon agent, so "nothing scheduled" has to be legible as
+    // a fact rather than as an absence.
+    if (a.status === "idle") {
+        out.push(a.next_wake_at ? `Next wake: ${a.next_wake_at}` : "No alarm armed — this agent costs storage only.");
+    }
+    if (a.attention)
+        out.push("Needs attention.");
+    if (a.budget?.cap_micro_usd !== undefined) {
+        out.push(`Cap: ${usd(a.budget.cap_micro_usd)} per ${a.budget.period ?? "period"} (per task ${usd(a.budget.max_task_micro_usd)})`);
+    }
+    if (a.harness_sha256 === null)
+        out.push("harness_sha256 is null — this agent has not run yet.");
+    return out;
+}
+function agentOf(data) {
+    const d = (data ?? {});
+    return d.agent;
+}
+/** `--budget-usd 50` is what an operator types; micro-USD is what the API takes. */
+function microFromUsd(v, field) {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n <= 0) {
+        agentError({
+            action: "agents.invalid",
+            error: { code: "invalid_input", message: `${field} must be a positive number of US dollars.` },
+            recovery_steps: [{ command: "naive agents create --help", description: "Show the flags" }],
+        });
+    }
+    return Math.round(n * 1_000_000);
+}
+function body(opts) {
+    const out = {};
+    if (opts.name)
+        out.name = opts.name;
+    if (opts.instructions)
+        out.instructions = opts.instructions;
+    if (opts.model)
+        out.model = opts.model;
+    if (opts.window)
+        out.completion_window = opts.window;
+    if (opts.delegateModel)
+        out.delegate_models = opts.delegateModel;
+    if (opts.secret)
+        out.secrets = opts.secret;
+    if (opts.connection)
+        out.connections = opts.connection;
+    if (opts.paused !== undefined)
+        out.paused = opts.paused;
+    const cap = microFromUsd(opts.budgetUsd, "--budget-usd");
+    const perTask = microFromUsd(opts.maxTaskUsd, "--max-task-usd");
+    if (cap !== undefined || perTask !== undefined) {
+        out.budget = {
+            cap_micro_usd: cap,
+            // Defaulting the per-task ceiling to a tenth of the cap is a choice, and
+            // it is the safe direction: an operator who never thinks about it still
+            // cannot lose the whole budget to one runaway task.
+            max_task_micro_usd: perTask ?? (cap !== undefined ? Math.max(1, Math.round(cap / 10)) : undefined),
+            period: opts.budgetPeriod ?? "month",
+        };
+    }
+    const tools = {};
+    for (const k of ["webSearch", "browser", "storage", "delegation", "connections"]) {
+        if (opts[k] !== undefined)
+            tools[k === "webSearch" ? "web_search" : k] = opts[k];
+    }
+    if (opts.sandbox !== undefined)
+        tools.sandbox = opts.sandbox;
+    if (Object.keys(tools).length)
+        out.tools = tools;
+    if (opts.cron) {
+        out.schedule = opts.cron.map((spec) => {
+            // `--cron "0 3 * * *=Triage last night's issues"` — the work is required,
+            // because a schedule with no work is a bug that fires forever.
+            const eq = spec.indexOf("=");
+            if (eq === -1) {
+                agentError({
+                    action: "agents.invalid",
+                    error: {
+                        code: "invalid_input",
+                        message: `--cron must be "<5-field cron>=<the work to send>", got "${spec}".`,
+                    },
+                    recovery_steps: [{ command: `naive agents create --cron "0 3 * * *=Triage last night's issues"`, description: "The shape" }],
+                });
+            }
+            return { cron: spec.slice(0, eq).trim(), text: spec.slice(eq + 1), tz: opts.tz ?? "UTC" };
+        });
+    }
+    const limits = {};
+    if (opts.wakeMs)
+        limits.sliceWallMs = Number(opts.wakeMs);
+    if (opts.maxTurns)
+        limits.maxTurnsPerTask = Number(opts.maxTurns);
+    if (opts.maxToolCalls)
+        limits.maxToolCallsPerTurn = Number(opts.maxToolCalls);
+    if (Object.keys(limits).length)
+        out.limits = limits;
+    return out;
+}
+export const agentsCmd = new Command("agents")
+    .description("Agents (Vetta) — long-horizon agents that run on a schedule, spend a budget, and deliver")
+    .addHelpText("after", `
+Subcommands:
+  naive agents status                              Configured, reachable, roster, harness hash
+  naive agents create --name n --model m …         Create an agent (a budget is REQUIRED)
+  naive agents list                                Roster with status, next wake and cap
+  naive agents show <id>                           One agent, materialised config included
+  naive agents update <id> [flags]                 Any create flag, plus --paused / --no-paused
+  naive agents rm <id>                             Delete (confirm required; --yes in a pipe)
+  naive agents run <id> <text...>                  Send work and stream it
+  naive agents job <id> <text...>                  Send work and return the task
+  naive agents tasks <id>                          The task board — which IS the job queue
+  naive agents task <id> <task-id>                 One unit of work
+  naive agents cancel <id> <task-id>               Cooperative cancel (never aborts mid-tool)
+  naive agents reply <id> <task-id> <text...>      Answer a task parked on needs_input
+  naive agents logs <id> [--follow]                The event trace; --follow tails it live
+  naive agents spend <id>                          Spend against the cap, by component or task
+  naive agents deliverables <id>                   Artifact manifests; --id fetches one
+
+The model:
+  A turn is bounded; a task is not. The agent wakes on an alarm, does one turn,
+  commits, and sleeps. While it sleeps it costs storage and nothing else — which
+  is what "idle · no alarm armed" means in \`list\`.
+
+Money:
+  A budget is REQUIRED at create. An agent with no cap is not creatable, because
+  a null cap means no cap AND no per-agent spend record at all. --budget-usd is
+  the cap; --max-task-usd is the per-task ceiling and defaults to a tenth of it.
+
+Exit codes:
+  0 ok · 1 error · 3 success, but the terminal state is not success.
+
+Examples:
+  $ naive agents create --name nightly-triage --model anthropic/claude-sonnet-4 \\
+      --budget-usd 50 --cron "0 3 * * *=Triage last night's Sentry issues"
+  $ naive agents run <id> "What changed in main today?"
+  $ naive agents logs <id> --follow --human
+  $ naive agents spend <id> --human
+`);
+/* ── 1. status ───────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("status")
+    .description("Primitive status: configured, reachable, roster, deployed harness hash")
+    .action(async () => {
+    const resp = await apiRequest("GET", "/v1/agents/status");
+    handleApiError("agents.status", resp);
+    const s = (resp.data ?? {});
+    agentOutput({
+        action: "agents.status",
+        result: resp.data,
+        next_steps: s.configured
+            ? [{ command: "naive agents list", description: "The roster" }]
+            : [{ command: "naive agents create --help", description: "What creating one needs" }],
+        hints: [
+            `Configured: ${s.configured ? "yes" : "no"} · reachable: ${s.reachable ? "yes" : "no"}`,
+            `Agents: ${s.agents ?? 0}`,
+            // A hash the deployment reported, not one this CLI computed. A CLI that
+            // computed it would be attesting to a build it has never seen.
+            s.harness_sha256 ? `Harness: ${s.harness_sha256}` : "Harness hash unavailable — the runtime did not report one.",
+            ...(s.error ? [`Runtime error: ${s.error}`] : []),
+        ],
+    });
+});
+/* ── 2. create ───────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("create")
+    .description("Create an agent. A pinned model and a budget are required.")
+    .requiredOption("--name <name>", "1–64 chars of [a-zA-Z0-9 _-]")
+    .requiredOption("--model <slug>", "A PINNED slug, e.g. anthropic/claude-sonnet-4. Never a family or an alias.")
+    .requiredOption("--budget-usd <usd>", "Hard spend cap in US dollars. Required — an uncapped agent is not creatable.")
+    .option("--max-task-usd <usd>", "Per-task ceiling. Defaults to a tenth of the cap.")
+    .option("--budget-period <p>", "total | day | week | month | year", "month")
+    .option("--instructions <text>", "What this agent is for")
+    // THREE, not two. The flag always FORWARDED `standard` — it is a free string
+    // and the CLI never validated it — so the capability shipped and only
+    // `--help` was wrong. asap is dearest and fastest, flex cheapest and slowest,
+    // standard the middle that makes it a curve. The server does the refusing:
+    // a non-`asap` window on a model that does not declare one comes back
+    // `window_unavailable` rather than being quietly served as `asap`.
+    .option("--window <w>", "asap (default) | standard | flex — the SCHEDULING TIER, never the model. Tasks inherit it.")
+    .option("--delegate-model <slug...>", "Models a sub-agent may run. Empty = delegation off.")
+    .option("--cron <spec...>", 'A schedule: "<5-field cron>=<the work to send>"')
+    .option("--tz <iana>", "Timezone for --cron", "UTC")
+    .option("--web-search", "Allow web search")
+    .option("--browser", "Allow the browser")
+    .option("--sandbox <mode>", "none | auto | <workspace id>")
+    .option("--storage", "Allow writing deliverables to storage")
+    .option("--secret <name...>", "Vault entry NAMES to expose. NEVER values.")
+    .option("--connection <id...>", "Connection ids to attach")
+    .option("--wake-ms <ms>", "Wall budget per wake (30000–840000)")
+    .option("--max-turns <n>", "Turns per task")
+    .option("--max-tool-calls <n>", "Tool calls per turn (1–32)")
+    .action(async (opts) => {
+    const resp = await apiRequest("POST", "/v1/agents", body(opts));
+    handleApiError("agents.create", resp);
+    const a = agentOf(resp.data);
+    agentOutput({
+        action: "agents.create",
+        result: resp.data,
+        next_steps: agentSteps(a),
+        hints: [
+            ...agentHints(a),
+            // Said once, at the only moment it changes what someone does next.
+            "Creating an agent queues no work. Send some with `naive agents job`.",
+        ],
+    });
+});
+/* ── 3. list ─────────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("list")
+    .description("The roster: status, next wake, cap")
+    .option("--status <s>", "idle | running | blocked | braked | stopped")
+    .option("--limit <n>", "Page size (default 50, max 200)")
+    .option("--cursor <c>", "Keyset cursor from a previous page")
+    .action(async (opts) => {
+    const q = new URLSearchParams();
+    for (const k of ["status", "limit", "cursor"])
+        if (opts[k])
+            q.set(k, opts[k]);
+    const qs = q.toString();
+    const resp = await apiRequest("GET", `/v1/agents${qs ? `?${qs}` : ""}`);
+    handleApiError("agents.list", resp);
+    const items = (resp.data ?? {}).items ?? [];
+    if (humanMode()) {
+        if (!items.length) {
+            process.stdout.write("no agents\n");
+        }
+        for (const a of items) {
+            const wake = a.status === "idle" && !a.next_wake_at ? "no alarm armed" : (a.next_wake_at ?? "—");
+            process.stdout.write(`${short(a.id).padEnd(9)}${(a.name ?? "").padEnd(24)}${(a.status ?? "").padEnd(9)}` +
+                `${(a.model ?? "").padEnd(34)}cap ${usd(a.budget?.cap_micro_usd).padEnd(9)}${wake}\n`);
+        }
+    }
+    agentOutput({
+        action: "agents.list",
+        result: resp.data,
+        next_steps: items[0]?.id ? [{ command: `naive agents show ${items[0].id}`, description: "One agent" }] : [],
+        hints: [`${items.length} agent${items.length === 1 ? "" : "s"}`],
+    });
+});
+/* ── 4. show ─────────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("show <id>")
+    .description("One agent, with its MATERIALISED limits (the numbers it will actually run with)")
+    .action(async (id) => {
+    const resp = await apiRequest("GET", `/v1/agents/${id}`);
+    handleApiError("agents.show", resp);
+    const a = agentOf(resp.data);
+    agentOutput({ action: "agents.show", result: resp.data, next_steps: agentSteps(a), hints: agentHints(a) });
+});
+/* ── 5. update ───────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("update <id>")
+    .description("Change any create field. `limits` and `tools` merge field by field.")
+    .option("--name <name>")
+    .option("--instructions <text>")
+    .option("--model <slug>")
+    .option("--window <w>", "asap | standard | flex — the agent's tier; its tasks inherit it")
+    .option("--budget-usd <usd>", "Raise or lower the cap. Raising it un-brakes a braked agent.")
+    .option("--max-task-usd <usd>")
+    .option("--budget-period <p>")
+    .option("--delegate-model <slug...>")
+    .option("--secret <name...>")
+    .option("--connection <id...>")
+    .option("--cron <spec...>")
+    .option("--tz <iana>")
+    .option("--wake-ms <ms>")
+    .option("--max-turns <n>")
+    .option("--max-tool-calls <n>")
+    /* A HOLD ON EXECUTION, and the help text says both halves because the
+     * missing half is what an operator gets wrong. It arms no wake and fires no
+     * cron; it does NOT refuse work, and it does not abort a running slice —
+     * `naive agents cancel` is that, cooperatively. */
+    .option("--paused", "Hold execution: arm no wake and fire no cron. Work sent meanwhile is queued, not refused")
+    .option("--no-paused", "Resume, and run whatever was held")
+    .action(async (id, opts) => {
+    const resp = await apiRequest("PATCH", `/v1/agents/${id}`, body(opts));
+    handleApiError("agents.update", resp);
+    const a = agentOf(resp.data);
+    agentOutput({ action: "agents.update", result: resp.data, next_steps: agentSteps(a), hints: agentHints(a) });
+});
+/* ── 6. rm ───────────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("rm <id>")
+    .description("Delete an agent: cancel queued work, stop the alarm chain. THE SPEND LEDGER IS KEPT.")
+    .option("--yes", "Skip the confirmation (required in a pipe)")
+    .action(async (id, opts) => {
+    if (!opts.yes) {
+        // Refuse rather than prompt. A prompt in a pipe either hangs or is
+        // answered by whatever byte arrives next, and this verb stops an agent
+        // mid-task.
+        agentError({
+            action: "agents.rm",
+            error: {
+                code: "invalid_input",
+                message: "Deleting an agent cancels its queued work and stops its alarm chain. Pass --yes to confirm.",
+            },
+            recovery_steps: [
+                { command: `naive agents tasks ${id}`, description: "See what is queued first" },
+                { command: `naive agents rm ${id} --yes`, description: "Delete it" },
+            ],
+        });
+        return;
+    }
+    const resp = await apiRequest("DELETE", `/v1/agents/${id}`);
+    handleApiError("agents.rm", resp);
+    agentOutput({
+        action: "agents.rm",
+        result: resp.data,
+        next_steps: [{ command: "naive agents list", description: "The remaining roster" }],
+        hints: ["The spend ledger is kept — deleting an agent does not change what it cost."],
+    });
+});
+/* ── 7–8. send work ──────────────────────────────────────────────────────── */
+function taskFlags(cmd) {
+    return cmd
+        .option("--mode <m>", "act (default, every granted tool) | ask (read-only)")
+        // Shared by `job` and `run`. `taskBody` OMITS the field when the flag is
+        // absent, and an omitted window is what the runtime resolves against the
+        // agent's `completion_window` — so leaving the flag off INHERITS the agent.
+        // It stopped meaning `asap` when the edge stopped resolving the default and
+        // started forwarding `undefined`, leaving one component holding it.
+        .option("--window <w>", "asap | standard | flex — this task only; omitted inherits the agent")
+        .option("--priority <p>", "normal | low")
+        .option("--not-before <iso>", "Do not start before this ISO-8601 instant")
+        .option("--idempotency-key <k>", "A PERMANENT business key: the same key returns the same task, forever");
+}
+function taskBody(text, opts) {
+    return {
+        text: text.join(" "),
+        mode: opts.mode,
+        window: opts.window,
+        priority: opts.priority,
+        not_before: opts.notBefore,
+        idempotency_key: opts.idempotencyKey,
+    };
+}
+taskFlags(agentsCmd.command("job <id> <text...>").description("Send work and return the task record"))
+    .action(async (id, text, opts) => {
+    const resp = await apiRequest("POST", `/v1/agents/${id}/tasks`, taskBody(text, opts));
+    handleApiError("agents.job", resp);
+    const t = (resp.data ?? {}).task;
+    agentOutput({
+        action: "agents.job",
+        result: resp.data,
+        next_steps: t?.id
+            ? [
+                { command: `naive agents logs ${id} --task ${t.id} --follow`, description: "Watch it" },
+                { command: `naive agents task ${id} ${t.id}`, description: "Check on it later" },
+            ]
+            : [],
+        // 202 is a fact worth restating: the row is committed and the alarm is
+        // armed before this returned. Nothing is sitting in a client-side queue.
+        hints: [`Status: ${t?.status ?? "queued"} — durably queued, alarm armed.`],
+    });
+});
+taskFlags(agentsCmd.command("run <id> <text...>").description("Send work and stream it (NDJSON, or --human)"))
+    .action(async (id, text, opts) => {
+    // 🔴 `flex` IS NOT REFUSED HERE, and the deletion is the point.
+    //
+    // The refusal was written when `flex` meant submit-then-poll, which has no
+    // tokens to stream. Every window now produces a real token stream, so
+    // `POST /:id/tasks` accepts and streams all three.
+    //
+    // The SDK dropped its identical client-side throw for the reason that
+    // applies twice as hard to a CLI: a client-side refusal is the worst place
+    // for a rule that has stopped being true, because a deploy cannot relax it
+    // — only a new install can. This copy outlived the rule by a release, and
+    // `naive agents run --window flex` refused a request the route serves.
+    //
+    // A window the platform cannot serve is still refused — server-side, at the
+    // gate, as `window_unavailable`, before a provider is chosen and before
+    // anything is spent. That is the right place for it.
+    await streamEvents("agents.run", `/v1/agents/${id}/tasks`, "POST", taskBody(text, opts), { follow: false });
+});
+/* ── 9–12. the board ─────────────────────────────────────────────────────── */
+agentsCmd
+    .command("tasks <id>")
+    .description("The task board — which IS the job queue. One noun, one table.")
+    .option("--status <s>", "queued | running | waiting | done | failed | cancelled | braked")
+    .option("--source <s>", "api | schedule | webhook | agent | self")
+    .option("--since <t>", "ISO-8601")
+    .option("--limit <n>")
+    .option("--cursor <c>")
+    .action(async (id, opts) => {
+    const q = new URLSearchParams();
+    for (const k of ["status", "source", "since", "limit", "cursor"])
+        if (opts[k])
+            q.set(k, opts[k]);
+    const qs = q.toString();
+    const resp = await apiRequest("GET", `/v1/agents/${id}/tasks${qs ? `?${qs}` : ""}`);
+    handleApiError("agents.tasks", resp);
+    const items = (resp.data ?? {}).items ?? [];
+    if (humanMode()) {
+        for (const t of items) {
+            process.stdout.write(`${short(t.id).padEnd(9)}${String(t.status ?? "").padEnd(11)}` +
+                `${String(t.window ?? "").padEnd(6)}t${String(t.turns ?? 0).padEnd(5)}` +
+                `${String(t.title ?? t.text ?? "").slice(0, 60)}\n`);
+        }
+    }
+    agentOutput({
+        action: "agents.tasks",
+        result: resp.data,
+        next_steps: items[0]?.id ? [{ command: `naive agents task ${id} ${items[0].id}`, description: "One task" }] : [],
+        hints: [`${items.length} task${items.length === 1 ? "" : "s"}`],
+    });
+});
+agentsCmd
+    .command("task <id> <task-id>")
+    .description("One unit of work. Exits 3 when its terminal state is not success.")
+    .action(async (id, taskId) => {
+    const resp = await apiRequest("GET", `/v1/agents/${id}/tasks/${taskId}`);
+    handleApiError("agents.task", resp);
+    const t = (resp.data ?? {}).task ?? {};
+    const status = String(t.status ?? "");
+    agentOutputExit({
+        action: "agents.task",
+        result: resp.data,
+        next_steps: [
+            { command: `naive agents logs ${id} --task ${taskId}`, description: "The event trace" },
+            { command: `naive agents spend ${id} --task ${taskId}`, description: "The authoritative cost" },
+        ],
+        hints: [
+            // 🔴 `spent_micro_usd` is the runtime's own synchronous counter, which
+            // the pre-call budget gate needs. `spend --task` prices from the ledger.
+            // The two are never printed in one column, and the `~` says which is
+            // which without the reader having to know.
+            `Spent (running counter): ~${usd(t.spent_micro_usd)} — authoritative: naive agents spend ${id} --task ${taskId}`,
+            ...(t.cancel_requested_at ? [`Cancelling since ${t.cancel_requested_at} — cancel never aborts mid-tool.`] : []),
+            ...(t.blocked_reason ? [`Blocked: ${t.blocked_reason}`] : []),
+        ],
+        // Exit 3, not 1: the command did what it said, and the WORK did not
+        // succeed. A CI script reading 0 as "the work is done" would otherwise
+        // count a failed task as a pass.
+        exitCode: ["failed", "cancelled", "braked"].includes(status) ? 3 : 0,
+    });
+});
+agentsCmd
+    .command("cancel <id> <task-id>")
+    .description("Cooperative cancel — it never aborts mid-tool, so it can take as long as the current tool")
+    .action(async (id, taskId) => {
+    const resp = await apiRequest("POST", `/v1/agents/${id}/tasks/${taskId}/cancel`, {});
+    handleApiError("agents.cancel", resp);
+    const t = (resp.data ?? {}).task ?? {};
+    agentOutput({
+        action: "agents.cancel",
+        result: resp.data,
+        next_steps: [{ command: `naive agents task ${id} ${taskId}`, description: "Watch it wind down" }],
+        hints: [
+            "Cancel is cooperative: the task ends after its current tool, and that tool is billed.",
+            ...(t.cancel_requested_at ? [`Requested at ${t.cancel_requested_at}`] : []),
+        ],
+    });
+});
+agentsCmd
+    .command("reply <id> <task-id> <text...>")
+    .description("Answer a task parked on needs_input. Without this the task is unrecoverable.")
+    .action(async (id, taskId, text) => {
+    const resp = await apiRequest("POST", `/v1/agents/${id}/tasks/${taskId}/reply`, { text: text.join(" ") });
+    handleApiError("agents.reply", resp);
+    agentOutput({
+        action: "agents.reply",
+        result: resp.data,
+        next_steps: [{ command: `naive agents logs ${id} --task ${taskId} --follow`, description: "Watch it resume" }],
+        hints: ["The alarm is re-armed; the task resumes on its next wake."],
+    });
+});
+/* ── 13. logs ────────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("logs <id>")
+    .description("The event trace. --follow tails it live; --after resumes from a position.")
+    .option("--task <task-id>", "Only this task")
+    .option("--kind <k>", "Only this event kind")
+    .option("--after <seq>", "Resume strictly after this seq. A POSITION, never a time.")
+    .option("--limit <n>", "Page size (paged mode only)")
+    .option("--follow", "Tail the live stream instead of reading a page")
+    .option("--show-args", "Print tool arguments instead of a digest (interactive terminals only)")
+    .action(async (id, opts) => {
+    const q = new URLSearchParams();
+    for (const [flag, key] of [["task", "task"], ["kind", "kind"], ["after", "after"], ["limit", "limit"]]) {
+        if (opts[flag])
+            q.set(key, String(opts[flag]));
+    }
+    if (!opts.follow) {
+        const qs = q.toString();
+        const resp = await apiRequest("GET", `/v1/agents/${id}/events${qs ? `?${qs}` : ""}`);
+        handleApiError("agents.logs", resp);
+        const page = (resp.data ?? {});
+        agentOutput({
+            action: "agents.logs",
+            result: resp.data,
+            next_steps: [{ command: `naive agents logs ${id} --follow`, description: "Tail it live" }],
+            hints: [
+                `${page.items?.length ?? 0} events`,
+                // 🔴 A truncated replay is a FACT ABOUT RETENTION, not a failure — but
+                // it must never be silent. The log is the source of truth, so a gap in
+                // it that nobody was told about is worse than a loud one.
+                ...(page.truncated
+                    ? [`⚠ replay truncated — earliest retained seq ${page.earliest_seq} (20,000-row cap); starting there`]
+                    : []),
+            ],
+        });
+        return;
+    }
+    await streamEvents("agents.logs", `/v1/agents/${id}/events?${q.toString()}`, "GET", undefined, {
+        follow: true,
+        showArgs: opts.showArgs === true,
+        after: opts.after === undefined ? undefined : Number(opts.after),
+    });
+});
+/* ── 14. spend ───────────────────────────────────────────────────────────── */
+agentsCmd
+    .command("spend <id>")
+    .description("Spend against the cap. Every paid component prints, INCLUDING the zeros.")
+    .option("--by <b>", "component (default) | task")
+    .option("--task <task-id>", "The authoritative per-task figure")
+    .action(async (id, opts) => {
+    const q = new URLSearchParams();
+    if (opts.by)
+        q.set("by", opts.by);
+    if (opts.task)
+        q.set("task", opts.task);
+    const qs = q.toString();
+    const resp = await apiRequest("GET", `/v1/agents/${id}/spend${qs ? `?${qs}` : ""}`);
+    handleApiError("agents.spend", resp);
+    const s = (resp.data ?? {});
+    if (humanMode()) {
+        process.stdout.write(`  cap ${usd(s.cap_micro_usd)} per ${s.period ?? "period"}${s.hard ? " (hard)" : ""}\n`);
+        for (const g of s.groups ?? []) {
+            // A component with a zero is printed WITH its zero. A paid tool absent
+            // from this view is exactly the hole that lets one bill unnoticed.
+            const why = g.rate_configured === false ? "  (rate not configured)" : g.calls === 0 ? "  (0 calls)" : "";
+            process.stdout.write(`  ${g.key.padEnd(14)}${g.credits.padStart(12)} cr${why}\n`);
+        }
+        process.stdout.write(`  ${"total".padEnd(14)}${(s.spent_credits ?? "0.0000").padStart(12)} cr\n`);
+        /* 🔴 THE SECOND TOTAL, PRINTED UNDER THE FIRST AND NEVER ADDED TO IT.
+         * `total` is what the agent's model calls COST, from the runtime's meter;
+         * `billed` is what the credit ledger holds. They differ today because an
+         * agent's inference writes no ledger row at all — which is why this view
+         * read `0.0000` for agents with real spend before it learned to read the
+         * meter. An operator seeing one number would have no way to know which. */
+        if (s.billed_credits !== undefined) {
+            process.stdout.write(`  ${"billed".padEnd(14)}${s.billed_credits.padStart(12)} cr  (credit ledger)\n`);
+        }
+        if (s.metered?.available === false) {
+            process.stdout.write("  no agents runtime on this deployment — the ledger is the only figure\n");
+        }
+        else if ((s.metered?.unpriced_calls ?? 0) > 0) {
+            // Counted, and costing nothing, because nobody priced them. Silence
+            // here would make an unpriced call indistinguishable from a free one.
+            process.stdout.write(`  ${s.metered.unpriced_calls} metered call(s) carry no price and add nothing above\n`);
+        }
+    }
+    agentOutput({
+        action: "agents.spend",
+        result: resp.data,
+        next_steps: [
+            { command: `naive agents update ${id} --budget-usd <usd>`, description: "Raise the cap (this un-brakes a braked agent)" },
+        ],
+        // The CLI NEVER computes money: every figure here is the string the API
+        // sent. The only number this file derives is the cap, which is a
+        // configuration integer, not a ledger sum.
+        hints: [
+            `Spent ${s.spent_credits ?? "0.0000"} credits against a cap of ${usd(s.cap_micro_usd)}.`,
+            ...(s.billed_credits === undefined
+                ? []
+                : [
+                    `Metered by the agent's runtime. The credit ledger holds ${s.billed_credits} — model calls are not billed through it. Do not add the two.`,
+                ]),
+        ],
+    });
+});
+/* ── 15. deliverables ────────────────────────────────────────────────────── */
+agentsCmd
+    .command("deliverables <id>")
+    .description("Artifact manifests. --id fetches one with a fresh download url and inline text.")
+    .option("--task <task-id>", "Only this task")
+    .option("--id <deliverable-id>", "Fetch one")
+    .option("--limit <n>")
+    .action(async (id, opts) => {
+    if (opts.id) {
+        const resp = await apiRequest("GET", `/v1/agents/${id}/deliverables/${opts.id}`);
+        handleApiError("agents.deliverables", resp);
+        const d = (resp.data ?? {});
+        agentOutput({
+            action: "agents.deliverables",
+            result: resp.data,
+            next_steps: [],
+            hints: [
+                // 🔴 Both halves are honest. A null url is a real state — the
+                // deployment may have no storage sink, and then the inline text is
+                // the whole artifact. Printing a url that 403s would be worse.
+                d.download_url
+                    ? "download_url expires in about an hour and is unauthenticated once issued — fetch it again rather than caching it."
+                    : "No download url on this deployment; `content` carries the artifact inline.",
+                ...(d.content === null && !d.download_url ? ["This deliverable carries no bytes — check `no_artifact_reason`."] : []),
+            ],
+        });
+        return;
+    }
+    const q = new URLSearchParams();
+    for (const k of ["task", "limit"])
+        if (opts[k])
+            q.set(k, opts[k]);
+    const qs = q.toString();
+    const resp = await apiRequest("GET", `/v1/agents/${id}/deliverables${qs ? `?${qs}` : ""}`);
+    handleApiError("agents.deliverables", resp);
+    const items = (resp.data ?? {}).items ?? [];
+    agentOutput({
+        action: "agents.deliverables",
+        result: resp.data,
+        next_steps: items[0]?.id
+            ? [{ command: `naive agents deliverables ${id} --id ${items[0].id}`, description: "Fetch it" }]
+            : [],
+        hints: [`${items.length} deliverable${items.length === 1 ? "" : "s"}`],
+    });
+});
+/* ── 16–18. inbound webhooks ─────────────────────────────────────────────── */
+/** 🔴 THE SECRET PRINTS ONCE, AND THE HUMAN LINE SAYS SO. It stays in the JSON
+ *  envelope — a CLI that hides a value from `--json` is a CLI you cannot script
+ *  — but a secret scrolled past unremarked is a secret nobody stored, and the
+ *  next event is a support request for a value that exists nowhere. */
+agentsCmd
+    .command("webhook-add <id>")
+    .description("Mint an inbound URL for this agent. A signed POST to it wakes the agent.")
+    .option("--name <name>", "Label it — which provider is on the other end")
+    .action(async (id, opts) => {
+    const resp = await apiRequest("POST", `/v1/agents/${id}/webhooks`, opts.name ? { name: opts.name } : {});
+    handleApiError("agents.webhook-add", resp);
+    const w_ = (resp.data ?? {});
+    if (humanMode()) {
+        process.stdout.write(`  url     ${w_.url ?? ""}\n`);
+        process.stdout.write(`  secret  ${w_.secret ?? ""}\n`);
+        process.stdout.write("  ⚠ the secret prints once. Store it now; rotate if you lose it.\n");
+    }
+    agentOutput({
+        action: "agents.webhook-add",
+        result: resp.data,
+        next_steps: [
+            { command: `naive agents webhooks ${id}`, description: "List this agent's URLs (never the secrets)" },
+            { command: `naive agents logs ${id} --follow`, description: "Watch the agent wake when the first event lands" },
+        ],
+        hints: [
+            "Sign `${unix_seconds}.${raw_body}` with HMAC-SHA256; hex digest in X-Naive-Signature, the same seconds in " +
+                "X-Naive-Timestamp. The timestamp is inside the signed content on purpose — that is what bounds a replay to 5m.",
+        ],
+    });
+});
+agentsCmd
+    .command("webhooks <id>")
+    .description("The inbound URLs bound to this agent. Secrets are never returned.")
+    .action(async (id) => {
+    const resp = await apiRequest("GET", `/v1/agents/${id}/webhooks`);
+    handleApiError("agents.webhooks", resp);
+    const hooks = (resp.data ?? {}).webhooks ?? [];
+    if (humanMode()) {
+        if (hooks.length === 0)
+            process.stdout.write("  no inbound URLs. `naive agents webhook-add <id>` mints one.\n");
+        // `never fired` separates "the provider never called" from "we called and
+        // dropped" — the first question when someone reports a dead webhook.
+        for (const h of hooks) {
+            const seen = h.last_event_at ? String(h.last_event_at) : "never fired";
+            process.stdout.write(`  ${String(h.id ?? "")}  ${String(h.url ?? "")}  ${h.active ? "active" : "inactive"}  ${seen}\n`);
+        }
+    }
+    agentOutput({
+        action: "agents.webhooks",
+        result: resp.data,
+        next_steps: hooks[0]?.id
+            ? [{ command: `naive agents webhook-rm ${id} ${String(hooks[0].id)}`, description: "Take it down" }]
+            : [{ command: `naive agents webhook-add ${id}`, description: "Mint one" }],
+        hints: [`${hooks.length} inbound URL${hooks.length === 1 ? "" : "s"}`],
+    });
+});
+agentsCmd
+    .command("webhook-rm <id> <hook-id>")
+    .description("Take an inbound URL down. Refuses if it removed nothing.")
+    .action(async (id, hookId) => {
+    const resp = await apiRequest("DELETE", `/v1/agents/${id}/webhooks/${hookId}`);
+    // 404 here is the honest answer, not a nuisance: "the URL is dead" and "the
+    // URL is still live and I no longer control it" must not share a response.
+    handleApiError("agents.webhook-rm", resp);
+    agentOutput({
+        action: "agents.webhook-rm",
+        result: resp.data,
+        next_steps: [{ command: `naive agents webhooks ${id}`, description: "Confirm it is gone" }],
+        hints: ["The URL now 404s. Anything still posting to it is told nothing exists there."],
+    });
+});
+/* ── the stream ──────────────────────────────────────────────────────────── */
+/**
+ * One streaming implementation for `run` and `logs --follow`.
+ *
+ * NDJSON, one object per line, terminated by an end frame with a reason and a
+ * status — never a JSON array, because a stream has no closing bracket, and
+ * never `[DONE]`, which belongs to the OpenAI-compatible lane.
+ *
+ * The SSE parsing and the redaction are `lib/stream-frames.ts`, unchanged: a
+ * second parser in one binary is a second place for a chunk boundary to lose an
+ * event, and the redactor already knows both secret shapes that can appear
+ * inside an arbitrary tool argument.
+ */
+async function streamEvents(action, path, method, payload, opts) {
+    // `--show-args` requires an interactive terminal, so a pipe or a CI job
+    // cannot turn it on — the same rule `naive teams watch` applies, and for the
+    // same reason: tool arguments are the one place an unaudited value arrives.
+    const showArgs = opts.showArgs === true && process.stdout.isTTY === true;
+    const config = loadConfig();
+    const headers = {
+        Authorization: `Bearer ${getApiKey()}`,
+        Accept: "text/event-stream",
+        ...(method === "POST" ? { "Content-Type": "application/json" } : {}),
+    };
+    /**
+     * 🔴 THE SUBJECT, WHICH THIS FUNCTION USED TO DROP ON THE FLOOR.
+     *
+     * Every other agents command goes through `apiRequest`, which rewrites
+     * `/v1/agents/...` to `/v1/users/<subject>/agents/...` and attaches the
+     * subject and project headers. `streamEvents` calls `fetch` directly, and it
+     * did neither — so `naive agents run` and `naive agents logs --follow`, the
+     * two commands an operator uses to WATCH an agent, were the only two that
+     * reached the COMPANY mount.
+     *
+     * That is not a cosmetic difference. On the company mount `subjectUserId` is
+     * empty, so the second half of `scopedAgent`'s predicate —
+     * `if (scope.tenantUserId && row.vetta.tenantUserId !== scope.tenantUserId)
+     * throw notFound()` — is INERT, and a company-wide key tails any agent in the
+     * company, including another team's. The event log carries the transcript.
+     * R25 exists precisely to stop that, and these two commands walked around it.
+     *
+     * It could not be seen from `agents-command.test.ts`, which mocks
+     * `apiRequest` — the very function that does the rewrite — and never reaches
+     * this code path at all.
+     */
+    const subject = activeUserId();
+    if (subject)
+        headers["X-Naive-User-Id"] = subject;
+    const project = activeProjectId();
+    if (project)
+        headers["X-Naive-Project-Id"] = project;
+    const scopedPath = scopePathToUser(path, subject);
+    // A POSITION, never a time. The server replays strictly greater.
+    if (opts.after !== undefined)
+        headers["Last-Event-ID"] = String(opts.after);
+    let response;
+    try {
+        response = await fetch(`${config.base_url}${scopedPath}`, {
+            method,
+            headers,
+            body: payload ? JSON.stringify(payload) : undefined,
+        });
+    }
+    catch (error) {
+        agentError({
+            action,
+            error: { code: "upstream_error", message: error instanceof Error ? error.message : String(error) },
+            recovery_steps: [{ command: "naive agents status", description: "Is the runtime reachable?" }],
+        });
+        return;
+    }
+    if (!response.ok || !response.body) {
+        let data = {};
+        try {
+            data = JSON.parse(await response.text());
+        }
+        catch {
+            /* a non-JSON body falls through to the generic branch */
+        }
+        handleApiError(action, { status: response.status, data });
+        return;
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let cursor = opts.after;
+    let finalStatus;
+    let ended = false;
+    for await (const chunk of response.body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        const { events, rest } = parseSse(buffer);
+        buffer = rest;
+        for (const ev of events) {
+            let frame;
+            try {
+                frame = JSON.parse(ev.data);
+            }
+            catch {
+                continue; // a keep-alive or a comment, not a frame
+            }
+            cursor = highestSeq(cursor, frame);
+            const f = frame;
+            if (f.kind === "task_finished") {
+                finalStatus = f.data?.status ?? finalStatus;
+                ended = true;
+            }
+            if (humanMode())
+                renderHumanEvent(frame, showArgs);
+            else
+                process.stdout.write(`${JSON.stringify(redactFrame(frame, { showArgs }))}\n`);
+            // Without --follow the command stops at the terminal frame. With it, the
+            // caller has asked to keep watching past this task — which is the right
+            // default for something left open on a second monitor, because an agent's
+            // NORMAL state is silence between wakes.
+            if (ended && !opts.follow)
+                break;
+        }
+        if (ended && !opts.follow)
+            break;
+    }
+    // Anything still in `buffer` is a partial event that never got its blank
+    // line. Half a JSON object is worse than none, so it is dropped deliberately.
+    if (!humanMode()) {
+        process.stdout.write(`${JSON.stringify({ type: "end", reason: ended ? "task_terminal" : "stream_closed", status: finalStatus ?? null, seq: cursor ?? null })}\n`);
+    }
+    // Exit 3 on a terminal state that is not success — the work is what the
+    // caller cares about, and exit 0 would report a failed task as a pass.
+    if (finalStatus && ["failed", "cancelled", "braked"].includes(finalStatus))
+        process.exitCode = 3;
+}
+/**
+ * The human renderer. Append-only, no spinner and no cursor movement, so
+ * `| tee` and scrollback both work.
+ */
+function renderHumanEvent(frame, showArgs) {
+    const f = redactFrame(frame, { showArgs });
+    const t = (f.at ?? "").slice(11, 19) || "--:--:--";
+    const d = f.data ?? {};
+    const w = process.stdout.write.bind(process.stdout);
+    switch (f.kind) {
+        case "text_delta":
+            w(String(d.text ?? ""));
+            return;
+        case "tool_call":
+            // `initiator` is printed and NEVER totalled against the other kind.
+            // Summing agent-chosen and harness-fired calls is what once let a null
+            // (zero agent-chosen calls) read as a positive.
+            w(`\n${t}  ▸ ${String(d.name ?? "").padEnd(12)}${String(d.argsPreview ?? "")} (${String(d.initiator ?? "?")})\n`);
+            return;
+        case "tool_result":
+            w(`${t}    ${String(d.status ?? "")}  ${String(d.preview ?? "").slice(0, 100)}\n`);
+            return;
+        case "turn_started":
+            w(`${t}  turn ${String(d.turn ?? "")} · ${String(d.model ?? "")}${Number(d.depth ?? 0) > 0 ? ` · depth ${d.depth}` : ""}\n`);
+            return;
+        case "usage": {
+            // 🔴 A NULL TIER RENDERS AS `—`, NEVER AS 0. Null means NOT MEASURED, and
+            // a column containing one must never be summed.
+            const tier = (k) => (d[k] === null || d[k] === undefined ? "—" : String(d[k]));
+            w(`${t}  in ${tier("input")} · cache_read ${tier("cacheRead")} · cw5m ${tier("cacheWrite5m")} · cw1h ${tier("cacheWrite1h")} · out ${tier("output")} · ${String(d.window ?? "")}\n`);
+            return;
+        }
+        case "budget": {
+            // `create` prints the per-task ceiling, so the stream prints what that
+            // ceiling has left. Printed only when one is declared (`0` ⇒ none), so an
+            // agent without one reads exactly as this line did before.
+            const ceiling = Number(d.maxTaskMicroUsd ?? 0);
+            const perTask = ceiling > 0 ? ` · this task ${usd(Number(d.taskMicroUsd ?? 0))} of ${usd(ceiling)}` : "";
+            w(`${t}  budget ${usd(Number(d.spentMicroUsd ?? 0))} of ${usd(Number(d.capMicroUsd ?? 0))}${perTask}\n`);
+            return;
+        }
+        case "delivered":
+            w(`${t}  ✓ delivered${d.final ? " (final)" : ""} · ${String(d.summary ?? "")}\n`);
+            return;
+        case "tools_offered":
+            w(`${t}  tools offered: ${d.tools?.length ?? 0} · ${String(d.totalChars ?? "")} chars\n`);
+            return;
+        case "task_finished":
+            w(`${t}  ■ ${String(d.status ?? "")}\n`);
+            return;
+        case "error":
+            w(`${t}  ✗ ${String(d.message ?? "")}${d.retryable ? " (retryable)" : ""}\n`);
+            return;
+        default:
+            w(`${t}  ${f.kind ?? "?"}\n`);
+    }
+}
+//# sourceMappingURL=agents.js.map