@usenaive-sdk/cli 0.15.1 → 1.0.1

package/dist/commands/agents.js

@@ -1,916 +0,0 @@
-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