@bli-cockpit/cli 0.2.36 → 0.2.38

package/dist/commands/jarvis-attachment.js

@@ -0,0 +1,82 @@
+/**
+ * Reads a local file for `cockpit jarvis --image <path>` (BLI-3414), before
+ * anything is uploaded.
+ *
+ * The dashboard's `/api/jarvis/cli` route is the ONE authority on whether an
+ * attached image is acceptable — it runs the exact same
+ * `checkAttachedImage`/`attachedImageRefusalSentence` gate the JARVIS panel
+ * uses (`apps/dashboard/src/lib/jarvis/chat-v2/attached-image.ts`), and this
+ * package cannot import from `apps/dashboard` (separate workspace, no
+ * dependency edge). So this module only catches what is cheap and purely
+ * local to check BEFORE spending a network round trip: does the path exist
+ * and is it readable, and does its extension even look like an image. Byte
+ * size and decoded-dimension refusals still come from the server and are
+ * relayed to the terminal verbatim (`readReply`/`writeFailure` in
+ * `jarvis.ts`) — this module's `ATTACHED_IMAGE_MAX_BYTES` constant is a local
+ * courtesy check to avoid uploading something the server is certain to
+ * refuse, not a second source of truth; if the two ever drift, the server's
+ * check still wins.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { errorMessage } from "./cli-io.js";
+/** Mirrors `ATTACHED_IMAGE_MAX_BYTES` in `apps/dashboard/src/lib/jarvis/chat-v2/attached-image.ts`. */
+export const ATTACHED_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+const EXTENSION_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+};
+/** The sentence the terminal prints for a refusal caught locally, before any request goes out. */
+export function attachedFileRefusalSentence(refusal, filePath) {
+    switch (refusal) {
+        case "file_not_found":
+            return `I could not find that file: ${filePath}`;
+        case "file_unreadable":
+            return `I could not read that file: ${filePath}`;
+        case "unsupported_file_type":
+            // Same wording as the panel's own refusal for this case (BLI-3170).
+            return "That is not an image I can read — attach a PNG, JPEG, or WEBP.";
+        case "file_too_big":
+            // Same wording as the panel's own refusal for this case (BLI-3170).
+            return "That image is too big to attach — keep it under 10 MB.";
+    }
+}
+/**
+ * Reads and locally screens one attached file. Never throws — every failure
+ * mode comes back as a named refusal so the caller can print a plain
+ * sentence instead of a stack trace.
+ */
+export async function readAttachedImage(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    const mimeType = EXTENSION_MIME_TYPES[extension];
+    if (!mimeType) {
+        return { ok: false, refusal: "unsupported_file_type", detail: extension || "no_extension" };
+    }
+    let size;
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile()) {
+            return { ok: false, refusal: "file_unreadable", detail: "not_a_regular_file" };
+        }
+        size = info.size;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { ok: false, refusal: "file_not_found", detail: "enoent" };
+        return { ok: false, refusal: "file_unreadable", detail: errorMessage(error) };
+    }
+    if (size > ATTACHED_IMAGE_MAX_BYTES) {
+        return { ok: false, refusal: "file_too_big", detail: `byte_size_${size}` };
+    }
+    let bytes;
+    try {
+        bytes = await readFile(filePath);
+    }
+    catch (error) {
+        return { ok: false, refusal: "file_unreadable", detail: errorMessage(error) };
+    }
+    return { ok: true, bytes, mimeType, fileName: path.basename(filePath) };
+}

package/dist/commands/jarvis.js

@@ -5,12 +5,21 @@
  * existing paired device session, and every turn is executed by the dashboard
  * through the same JARVIS runtime used by web chat and Slack.
  */
-import { errorMessage, isInteractiveStdin, readLine, writeLine } from "./cli-io.js";
-import { getCollectorRuntimePaths, readLocalCollectorSessionFile, } from "../local-state.js";
+import { isInteractiveStdin, readLine, writeLine } from "./cli-io.js";
+import { attachedFileRefusalSentence, readAttachedImage, } from "./jarvis-attachment.js";
+import { loadPairedSession, towerFailureDetail, towerRequest, } from "../tower-client.js";
+import { readTowerTurn, streamFailureDetail, } from "../tower-stream.js";
 const TRACE_DIM = "\x1b[2m";
 const TRACE_RESET = "\x1b[0m";
+/**
+ * The dashboard route caps a turn at 120s (`maxDuration = 120`). The client
+ * waits slightly longer so the server's own named failure wins the race
+ * whenever it manages to send one; past that, the terminal names the timeout
+ * itself rather than sitting there.
+ */
+const TURN_DEADLINE_MS = 125_000;
 export async function runJarvis(command, io) {
-    const session = await loadPairedSession(command.homeDir);
+    const session = await loadPairedSession("jarvis", command.homeDir);
     const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
     const oneShotPrompt = await resolveOneShotPrompt(command, io);
     if (oneShotPrompt !== null) {
@@ -31,19 +40,6 @@ export async function runJarvis(command, io) {
             return exitCode;
     }
 }
-async function loadPairedSession(homeDir) {
-    const paths = getCollectorRuntimePaths(homeDir);
-    try {
-        const session = await readLocalCollectorSessionFile(paths);
-        if (session.session_state !== "valid") {
-            throw new Error(`session_${session.session_state}`);
-        }
-        return session;
-    }
-    catch (error) {
-        throw new Error(`JARVIS needs a valid paired Tower session. Run \`cockpit login\`, then try again (${errorMessage(error)}).`);
-    }
-}
 async function resolveOneShotPrompt(command, io) {
     if (command.prompt)
         return validatePrompt(command.prompt);
@@ -54,60 +50,143 @@ async function resolveOneShotPrompt(command, io) {
 }
 async function sendOneTurn(context, prompt, io) {
     const startedAt = Date.now();
-    let response;
-    try {
-        response = await io.fetch(`${context.dashboardUrl}/api/jarvis/cli`, {
-            method: "POST",
-            headers: {
-                authorization: `Bearer ${context.deviceToken}`,
-                "content-type": "application/json",
-            },
-            body: JSON.stringify({
+    // BLI-3414: an attached file is read and locally screened (exists,
+    // readable, a supported extension, under the byte ceiling) BEFORE any
+    // network call — a refusal here never reaches the dashboard and is
+    // terminal, same discipline as the panel's own attached-image gate.
+    let attachment = null;
+    if (context.command.imagePath) {
+        const read = await readAttachedImage(context.command.imagePath);
+        if (!read.ok) {
+            writeAttachmentRefusal(context.command, io, read.refusal, context.command.imagePath);
+            return 1;
+        }
+        attachment = read;
+    }
+    // BLI-3457: streaming is the default. A dashboard that has not shipped the
+    // NDJSON half yet answers `application/json`, which the reader takes as a
+    // single final event and names `stream_not_available` — so the terminal
+    // works against both server versions with no flag.
+    const wantsStream = context.command.stream !== false;
+    const log = (line) => writeLine(io.stderr, line);
+    const requested = await towerRequest({
+        dashboardUrl: context.dashboardUrl,
+        path: "/api/jarvis/cli",
+        deviceToken: context.deviceToken,
+        fetch: io.fetch,
+        label: "jarvis",
+        timeoutMs: TURN_DEADLINE_MS,
+        headers: wantsStream ? { accept: "application/x-ndjson" } : {},
+        body: attachment
+            ? buildAttachmentForm(context.command, prompt, attachment)
+            : {
                 question: prompt,
                 thread: context.command.thread,
                 subject: context.command.subject,
                 model: context.command.model,
-            }),
-        });
+            },
+        log,
+    });
+    if (!requested.ok) {
+        writeFailure(context.command, io, requested.reason, towerFailureDetail(requested.reason, requested.detail));
+        return 1;
     }
-    catch (error) {
-        writeFailure(context.command, io, "gateway_unreachable", errorMessage(error));
+    // Live trace lines go to a person as they land, never to a `--json`
+    // consumer: that contract is exactly one object on stdout, so the events are
+    // buffered and folded into the final payload instead.
+    let liveTraceLines = 0;
+    const turn = await readTowerTurn(requested.response, {
+        startedAt,
+        log,
+        onActivity: (event) => {
+            if (context.command.json)
+                return;
+            if (writeActivityLine(io, event))
+                liveTraceLines += 1;
+        },
+        onNote: (reason, detail) => {
+            log(`[jarvis cli] stream note ${JSON.stringify({
+                reason,
+                ...(detail && reason !== "ndjson_line_unparseable" ? { detail } : {}),
+            })}`);
+        },
+    });
+    if (!turn.ok) {
+        writeFailure(context.command, io, turn.reason, streamFailureDetail(turn.reason, turn.detail));
         return 1;
     }
-    const body = await readReply(response);
-    if (!response.ok || !body.ok || !body.reply) {
-        const reason = body.error ?? body.reply ?? `http_${response.status}`;
+    const body = turn.final;
+    const httpStatus = typeof turn.final.httpStatus === "number" ? turn.final.httpStatus : requested.response.status;
+    if (httpStatus >= 400 || !body.ok || !body.reply) {
+        const reason = body.error ?? body.reply ?? `http_${httpStatus}`;
         writeFailure(context.command, io, "turn_failed", reason);
         return 1;
     }
+    // A streaming server may leave the settled trace out of the final event
+    // because it already sent every step live; the activity we collected is that
+    // same trace, so `--json` still gets one.
+    const trace = body.trace ?? activityToTrace(turn.activity);
     if (context.command.json) {
         writeLine(io.stdout, JSON.stringify({
             ok: true,
             reply: body.reply,
             thread: body.thread ?? context.command.thread,
             model: body.model ?? null,
-            trace: body.trace ?? [],
+            trace,
             subject: body.subject ?? null,
         }));
     }
     else {
         const subject = body.subject?.displayName ? ` (${body.subject.displayName})` : "";
         writeLine(io.stdout, `jarvis${subject}> ${body.reply}`);
-        writeTraceBlock(io, body.trace);
+        // Only when nothing was drawn live — otherwise every tool would print twice.
+        if (liveTraceLines === 0)
+            writeTraceBlock(io, trace);
         writeModelReceipt(io, body.model);
     }
     writeLine(io.stderr, `[jarvis cli] answered ${JSON.stringify({
         prompt_length: prompt.length,
         reply_length: body.reply.length,
-        trace_steps: body.trace?.length ?? 0,
-        trace_failed: body.trace?.filter((step) => step.status === "failed").length ?? 0,
+        trace_steps: trace?.length ?? 0,
+        trace_failed: trace?.filter((step) => step.status === "failed").length ?? 0,
         model_requested: context.command.model ?? null,
         elapsed_ms: Date.now() - startedAt,
         thread: context.command.thread === "main" ? "default" : "named",
         subject: context.command.subject ? "selected" : "caller",
+        image_attached: attachment !== null,
+        image_byte_size: attachment?.bytes.byteLength ?? null,
+        streamed: turn.streamed,
+        live_trace_lines: liveTraceLines,
     })}`);
     return 0;
 }
+/**
+ * The multipart body `/api/jarvis/cli` reads when a file is attached
+ * (BLI-3414) — same field names the request handler parses, mirroring the
+ * JSON body's fields plus one `image` file field.
+ */
+function buildAttachmentForm(command, prompt, attachment) {
+    const form = new FormData();
+    form.set("question", prompt);
+    form.set("thread", command.thread);
+    if (command.subject)
+        form.set("subject", command.subject);
+    if (command.model)
+        form.set("model", command.model);
+    form.set("image", new File([attachment.bytes], attachment.fileName, { type: attachment.mimeType }));
+    return form;
+}
+/** A refusal caught locally, before any request went out — never a stack trace. */
+function writeAttachmentRefusal(command, io, refusal, filePath) {
+    const message = attachedFileRefusalSentence(refusal, filePath);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: refusal, detail: message }));
+    }
+    else {
+        writeLine(io.stderr, `JARVIS could not attach that file: ${message}`);
+    }
+    writeLine(io.stderr, `[jarvis cli] attachment refused ${JSON.stringify({ reason: refusal })}`);
+}
 /**
  * One dim line per tool the turn called (BLI-3381): what it was, how long it
  * took, and — for a failure — the reason, matching what the web thinking
@@ -117,11 +196,53 @@ async function sendOneTurn(context, prompt, io) {
 function writeTraceBlock(io, trace) {
     if (!trace || trace.length === 0)
         return;
-    for (const step of trace) {
-        const elapsed = typeof step.elapsedMs === "number" ? ` (${step.elapsedMs}ms)` : "";
-        const failure = step.status === "failed" ? ` — failed: ${step.detail ?? "no reason given"}` : "";
-        writeLine(io.stdout, `${TRACE_DIM}  ⏺ ${step.label}${elapsed}${failure}${TRACE_RESET}`);
+    for (const step of trace)
+        writeTraceLine(io, step);
+}
+/** The one dim trace line, drawn identically live (BLI-3457) and after the fact. */
+function writeTraceLine(io, step) {
+    const elapsed = typeof step.elapsedMs === "number" ? ` (${step.elapsedMs}ms)` : "";
+    const failure = step.status === "failed" ? ` — failed: ${step.detail ?? "no reason given"}` : "";
+    writeLine(io.stdout, `${TRACE_DIM}  ⏺ ${step.label}${elapsed}${failure}${TRACE_RESET}`);
+}
+/**
+ * Draws one streamed tool call, and says whether it drew anything.
+ *
+ * Only settled steps print: a `running` event is the same tool arriving a
+ * second time, and printing both would double every line in a terminal that
+ * cannot rewrite the one above it.
+ */
+function writeActivityLine(io, event) {
+    if (event.status !== "done" && event.status !== "failed")
+        return false;
+    const step = activityToStep(event);
+    if (!step)
+        return false;
+    writeTraceLine(io, step);
+    return true;
+}
+/** The settled steps of a streamed turn, in the shape `--json` already promises. */
+function activityToTrace(activity) {
+    const steps = [];
+    for (const event of activity) {
+        if (event.status !== "done" && event.status !== "failed")
+            continue;
+        const step = activityToStep(event);
+        if (step)
+            steps.push(step);
     }
+    return steps;
+}
+function activityToStep(event) {
+    if (event.status !== "done" && event.status !== "failed")
+        return null;
+    return {
+        tool: event.tool ?? "unknown_tool",
+        label: event.label ?? event.tool ?? "A tool ran",
+        status: event.status,
+        ...(typeof event.elapsedMs === "number" ? { elapsedMs: event.elapsedMs } : {}),
+        ...(event.detail ? { detail: event.detail } : {}),
+    };
 }
 /**
  * One line, only when the answer did not come from what was requested — a
@@ -138,21 +259,6 @@ function writeModelReceipt(io, model) {
         return;
     writeLine(io.stdout, `Model: ${answered ?? "an unknown model"} answered (${requested ?? "the requested model"} unavailable)`);
 }
-async function readReply(response) {
-    const text = await response.text();
-    if (!text)
-        return { ok: false, error: "empty_response" };
-    try {
-        const value = JSON.parse(text);
-        if (!value || typeof value !== "object") {
-            return { ok: false, error: "response_body_not_object" };
-        }
-        return value;
-    }
-    catch {
-        return { ok: false, error: "response_body_not_json" };
-    }
-}
 function writeFailure(command, io, reason, detail) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));

package/dist/commands/local-args.js

@@ -611,8 +611,19 @@ function parseAgentRulesHost(value) {
 }
 function parseJarvisArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--dashboard-url", "--prompt", "--as", "--thread", "--model", "--json"],
-        valueFlags: ["--home", "--dashboard-url", "--prompt", "--as", "--thread", "--model"],
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--prompt",
+            "--as",
+            "--thread",
+            "--model",
+            "--image",
+            "--file",
+            "--no-stream",
+            "--json",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--prompt", "--as", "--thread", "--model", "--image", "--file"],
     });
     const flaggedPrompt = optionalNonEmpty(values.flags.get("--prompt"));
     const positionalPrompt = optionalNonEmpty(values.positionals.join(" "));
@@ -623,6 +634,13 @@ function parseJarvisArgs(args) {
     if (!/^[A-Za-z0-9_-]{1,40}$/.test(thread)) {
         throw new Error("jarvis --thread must use 1 to 40 letters, numbers, underscores, or hyphens.");
     }
+    // BLI-3414: `--file` is a plain alias for `--image` — same flag, whichever
+    // word a person reaches for first.
+    const image = optionalNonEmpty(values.flags.get("--image"));
+    const file = optionalNonEmpty(values.flags.get("--file"));
+    if (image && file) {
+        throw new Error("jarvis accepts either --image or --file, not both — they are the same flag.");
+    }
     return {
         kind: "jarvis",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
@@ -633,6 +651,11 @@ function parseJarvisArgs(args) {
         // BLI-3381: no client-side allowlist — the dashboard forwards this key
         // to the inference server's own allowlist and relays its refusal.
         model: optionalNonEmpty(values.flags.get("--model")),
+        imagePath: image ?? file,
+        // BLI-3457: streaming is on unless a caller opts out. A dashboard that
+        // does not stream yet still answers plain JSON, so this flag is for
+        // callers that want the single-body shape on purpose, not a compat knob.
+        stream: !values.booleans.has("--no-stream"),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-help.js

@@ -46,7 +46,7 @@ export function localCommandHelp(command) {
         "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--dashboard-url <url>] [--json]",
+        "  cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
@@ -190,15 +190,18 @@ function localSubcommandHelp(command) {
         [
             "jarvis",
             [
-                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit jarvis [question] [--prompt <question>] [--as <person>] [--thread <name>] [--model <key>] [--image <path>|--file <path>] [--no-stream] [--dashboard-url <url>] [--json]",
                 "",
                 "Chats with the same JARVIS used by Tower web chat and the BLI Slack DM.",
                 "--as selects the existing website person space; it changes who the chat is about, never who is authenticated.",
                 "--model <key> requests one provider:model pair (e.g. openai:gpt-5.6-terra); an unrecognised key is refused by the dashboard, not this command.",
+                "--image <path> (alias --file) attaches one local PNG, JPEG, or WEBP under 10 MB with the question, the same one-image gate the JARVIS panel uses. A bad path, an unsupported type, or an oversized file is refused with its own plain sentence — never a stack trace.",
                 "Run with no question for an interactive terminal conversation.",
                 "Agents can pass --prompt, positional text, or pipe one question on stdin.",
                 "Each answer prints a per-tool trace line and, only on a fallback or model mismatch, one model receipt line.",
-                "--json writes one machine-readable response (including trace and model) to stdout; operational metadata stays on stderr.",
+                "Trace lines arrive live while JARVIS works; pass --no-stream to wait for the whole answer in one piece instead.",
+                "--json writes one machine-readable response (including trace and model) to stdout; operational metadata stays on stderr. A --json run never streams fragments, whichever mode it is in.",
+                "A turn that outlives the dashboard's own ceiling is reported as turn_timed_out — an incomplete answer is never printed as a finished one.",
                 "The command uses the existing paired device identity. It cannot override the caller, team, role, or person scope.",
                 "Run `cockpit login` first if this machine is not paired.",
             ],

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.36");
+    writeLine(io?.stdout ?? process.stdout, "0.2.38");
     return 0;
   }
 

package/dist/tower-client.js

@@ -0,0 +1,150 @@
+/**
+ * The one shared "call the dashboard as me" client (BLI-3457).
+ *
+ * Every command that speaks to Tower on the paired person's behalf — `jarvis`
+ * today, the rest of the CLI-parity surface next — needs the same three
+ * things: the paired device session, a request that carries its device token,
+ * and a failure that names itself instead of throwing a transport stack trace
+ * at a person. Before this module each command grew its own copy; the copies
+ * drifted (one normalised the dashboard URL, one did not) and only one of them
+ * ever named a reason.
+ *
+ * Contract:
+ * - Nothing here throws for a transport error. `towerRequest` returns
+ *   `{ ok: false, reason }` for every network-shaped failure, and the reason
+ *   label is the thing that travels to the operator.
+ * - `loadPairedSession` still throws, because "this machine is not paired" is
+ *   not a transport failure — it is a precondition the caller cannot proceed
+ *   past, and the command's top level turns it into one plain sentence.
+ * - The device token is attached to the request and never returned, logged, or
+ *   put in a reason. Log lines here carry metadata only.
+ *
+ * The HTTP vocabulary (`normalizeDashboardUrl`, `readResponseJson`,
+ * `responseErrorMessage`) is reused from `upload-http.ts` rather than copied —
+ * the upload path and the conversation path answer to the same rules.
+ */
+import { errorMessage } from "./commands/cli-io.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, } from "./local-state.js";
+import { normalizeDashboardUrl, readResponseJson, responseErrorMessage, } from "./upload-http.js";
+const defaultLog = (line) => {
+    console.error(line);
+};
+/**
+ * Loads the paired device session, or explains in one sentence why it cannot.
+ *
+ * `commandName` names the caller so the sentence reads as the command a person
+ * actually typed ("`cockpit jarvis` needs a valid paired Tower session"),
+ * rather than the JARVIS-specific wording this used to be hard-coded to.
+ */
+export async function loadPairedSession(commandName, homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    try {
+        const session = await readLocalCollectorSessionFile(paths);
+        if (session.session_state !== "valid") {
+            throw new Error(`session_${session.session_state}`);
+        }
+        return session;
+    }
+    catch (error) {
+        throw new Error(`\`cockpit ${commandName}\` needs a valid paired Tower session. ` +
+            `Run \`cockpit login\`, then try again (${errorMessage(error)}).`);
+    }
+}
+/**
+ * Makes one authenticated request to the dashboard. Never throws.
+ *
+ * A 4xx/5xx still comes back as `{ ok: true, response }` — the status is the
+ * caller's to interpret, because several routes put a readable refusal in a
+ * non-2xx body. Only a request that produced no response at all is a failure
+ * here, and it always carries a reason label.
+ */
+export async function towerRequest(options) {
+    const log = options.log ?? defaultLog;
+    const startedAt = Date.now();
+    const url = `${normalizeDashboardUrl(options.dashboardUrl)}${options.path}`;
+    const isForm = typeof FormData !== "undefined" && options.body instanceof FormData;
+    const headers = {
+        ...(options.headers ?? {}),
+        authorization: `Bearer ${options.deviceToken}`,
+    };
+    // fetch derives the multipart boundary from a FormData body; declaring the
+    // content-type by hand would strip it and the server would parse nothing.
+    if (options.body !== undefined && !isForm)
+        headers["content-type"] = "application/json";
+    const init = {
+        method: options.method ?? "POST",
+        headers,
+        ...(options.body === undefined
+            ? {}
+            : { body: (isForm ? options.body : JSON.stringify(options.body)) }),
+        ...(timeoutSignal(options.timeoutMs) ?? {}),
+    };
+    try {
+        const response = await options.fetch(url, init);
+        log(`[tower client] responded ${JSON.stringify({
+            request: options.label,
+            http_status: response.status,
+            content_type: response.headers.get("content-type") ?? "none",
+            streamed: (response.headers.get("content-type") ?? "").includes("application/x-ndjson"),
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return { ok: true, response };
+    }
+    catch (error) {
+        const reason = isAbortError(error)
+            ? "turn_timed_out"
+            : "gateway_unreachable";
+        log(`[tower client] request failed ${JSON.stringify({
+            request: options.label,
+            reason,
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return { ok: false, reason, detail: towerFailureDetail(reason, errorMessage(error)) };
+    }
+}
+/**
+ * `towerRequest` plus reading the body as JSON and turning a non-2xx into a
+ * named failure carrying the server's own words when it supplied any.
+ */
+export async function towerJsonRequest(options) {
+    const result = await towerRequest(options);
+    if (!result.ok)
+        return result;
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        return {
+            ok: false,
+            reason: "http_error",
+            httpStatus: result.response.status,
+            detail: responseErrorMessage(body, `http_${result.response.status}`),
+        };
+    }
+    return { ok: true, httpStatus: result.response.status, body };
+}
+/** One plain sentence per reason, so no caller has to invent its own wording. */
+export function towerFailureDetail(reason, detail) {
+    switch (reason) {
+        case "gateway_unreachable":
+            return `Tower could not be reached (${detail}).`;
+        case "turn_timed_out":
+            return "Tower did not finish in time, so the answer is incomplete. Ask again.";
+        case "http_error":
+            return detail;
+    }
+}
+export function isAbortError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const name = error.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/**
+ * A deadline when the runtime has one. `AbortSignal.timeout` exists on Node 18+
+ * on both supported host families; the guard is here so a stripped runtime
+ * loses the ceiling rather than the whole request.
+ */
+function timeoutSignal(timeoutMs) {
+    if (!timeoutMs || typeof AbortSignal?.timeout !== "function")
+        return null;
+    return { signal: AbortSignal.timeout(timeoutMs) };
+}

package/dist/tower-stream.js

@@ -0,0 +1,252 @@
+/**
+ * Reading a Tower turn as it happens (BLI-3457).
+ *
+ * The dashboard's conversation routes speak one JSON object per line
+ * (`application/x-ndjson`): `activity` events as tools start and settle, then
+ * exactly one `final` event carrying what the plain JSON response used to be.
+ * That is the same wire format the browser already reads
+ * (`apps/dashboard/src/lib/webchat/tool-trace.ts`); this is the terminal's
+ * reader for it.
+ *
+ * Three things it refuses to do:
+ * - Throw. A stream that dies mid-turn comes back as a named reason, never an
+ *   exception in the middle of a person's answer.
+ * - Present a truncated turn as a complete one. No `final` event means the
+ *   turn failed, and it says which way it failed
+ *   (`turn_timed_out` when the dashboard's own 120s ceiling is the likely
+ *   cause, `stream_ended_without_final` otherwise).
+ * - Require the stream. A dashboard that has not shipped streaming yet answers
+ *   `application/json`; that single object is read as the final event and the
+ *   fallback is named `stream_not_available` rather than passed off as a
+ *   stream that happened to be quiet.
+ *
+ * A malformed line is skipped, named `ndjson_line_unparseable`, and the lines
+ * after it still count — one bad byte cannot swallow an answer.
+ */
+import { errorMessage } from "./commands/cli-io.js";
+import { isAbortError } from "./tower-client.js";
+/**
+ * The dashboard caps a turn at 120s (`maxDuration = 120`). A stream that stops
+ * without a final event anywhere near that mark was almost certainly cut off by
+ * the platform, and saying `turn_timed_out` is the honest label; earlier than
+ * that, the stream broke for some other reason and gets its own.
+ */
+const CEILING_HINT_MS = 110_000;
+/**
+ * Yields every event on the response, then stops at the first `final`.
+ *
+ * Handles both wire shapes: real NDJSON, and a plain `application/json` body
+ * from a dashboard that does not stream yet (yielded as the final event, after
+ * a `stream_not_available` note).
+ */
+export async function* readTowerStream(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/x-ndjson")) {
+        yield* readPlainJsonBody(response);
+        return;
+    }
+    let buffer = "";
+    try {
+        for await (const chunk of iterateBody(response)) {
+            buffer += chunk;
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                const item = parseLine(line);
+                if (!item)
+                    continue;
+                yield item;
+                if (item.kind === "event" && item.event.type === "final")
+                    return;
+            }
+        }
+    }
+    catch (error) {
+        yield {
+            kind: "note",
+            reason: isAbortError(error) ? "turn_timed_out" : "stream_read_failed",
+            detail: errorMessage(error),
+        };
+        return;
+    }
+    // Whatever was still in flight when the body ended.
+    const tail = parseLine(buffer);
+    if (tail)
+        yield tail;
+}
+/**
+ * The whole turn in one call: renders activity as it arrives, buffers the
+ * final, and names any way the turn failed to produce one.
+ *
+ * `onActivity` is where a caller draws its live trace. `onNote` sees every
+ * named oddity (a skipped line, a non-streaming dashboard) so nothing is
+ * silently absorbed — the caller decides whether that is a log line or a
+ * sentence.
+ */
+export async function readTowerTurn(response, options = {}) {
+    const startedAt = options.startedAt ?? Date.now();
+    const activity = [];
+    const notes = [];
+    let streamed = true;
+    let final = null;
+    for await (const item of readTowerStream(response)) {
+        if (item.kind === "note") {
+            if (item.reason === "stream_not_available")
+                streamed = false;
+            notes.push({ reason: item.reason, detail: item.detail });
+            options.onNote?.(item.reason, item.detail);
+            continue;
+        }
+        if (item.event.type === "final") {
+            final = item.event;
+            break;
+        }
+        activity.push(item.event);
+        options.onActivity?.(item.event);
+    }
+    const elapsedMs = Date.now() - startedAt;
+    if (!final) {
+        // The last named note is the truest reason we have; absent one, a stream
+        // that simply stopped near the dashboard's ceiling is a timeout.
+        const terminal = notes.at(-1);
+        const reason = terminal && terminal.reason !== "stream_not_available"
+            ? terminal.reason
+            : elapsedMs >= CEILING_HINT_MS
+                ? "turn_timed_out"
+                : "stream_ended_without_final";
+        options.log?.(`[tower stream] turn incomplete ${JSON.stringify({
+            reason,
+            activity_events: activity.length,
+            notes: notes.length,
+            elapsed_ms: elapsedMs,
+        })}`);
+        return { ok: false, reason, detail: streamFailureDetail(reason, terminal?.detail) };
+    }
+    options.log?.(`[tower stream] turn complete ${JSON.stringify({
+        streamed,
+        activity_events: activity.length,
+        notes: notes.length,
+        elapsed_ms: elapsedMs,
+    })}`);
+    return { ok: true, final, activity, streamed };
+}
+/** One plain sentence per way a turn can end without an answer. */
+export function streamFailureDetail(reason, detail) {
+    switch (reason) {
+        case "turn_timed_out":
+            return "Tower ran out of time before finishing that turn, so the answer is incomplete. Ask again.";
+        case "stream_ended_without_final":
+            return "Tower stopped sending mid-answer, so the answer is incomplete. Ask again.";
+        case "stream_read_failed":
+            return `The connection to Tower broke mid-answer${detail ? ` (${detail})` : ""}. Ask again.`;
+        case "response_body_not_json":
+            return "Tower answered with something that was not JSON.";
+        case "response_body_empty":
+            return "Tower answered with an empty body.";
+        default:
+            return detail ?? reason;
+    }
+}
+/**
+ * A dashboard that does not stream yet. The whole body is one JSON object; it
+ * becomes the final event so every caller has exactly one code path.
+ */
+async function* readPlainJsonBody(response) {
+    yield {
+        kind: "note",
+        reason: "stream_not_available",
+        detail: response.headers.get("content-type") ?? "none",
+    };
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        yield {
+            kind: "note",
+            reason: isAbortError(error) ? "turn_timed_out" : "stream_read_failed",
+            detail: errorMessage(error),
+        };
+        return;
+    }
+    if (!text.trim()) {
+        yield { kind: "note", reason: "response_body_empty" };
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        yield { kind: "note", reason: "response_body_not_json" };
+        return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        yield { kind: "note", reason: "response_body_not_json" };
+        return;
+    }
+    yield {
+        kind: "event",
+        event: { ...parsed, type: "final" },
+    };
+}
+/** One NDJSON line: an event, a named skip, or nothing at all for blank lines. */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // The line text is never logged: it is conversation content.
+        return { kind: "note", reason: "ndjson_line_unparseable" };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { kind: "note", reason: "unexpected_event_type" };
+    }
+    const type = parsed.type;
+    if (type !== "activity" && type !== "final") {
+        return { kind: "note", reason: "unexpected_event_type" };
+    }
+    return { kind: "event", event: parsed };
+}
+/**
+ * Decoded text chunks from a response body.
+ *
+ * Node's web `ReadableStream` is async-iterable on both supported host
+ * families (macOS and Windows, Node 20+), and that is the fast path. The
+ * `getReader()` fallback is there because a test double or a polyfilled fetch
+ * may hand back a stream without the iterator, and losing the answer over an
+ * iteration protocol would be absurd.
+ */
+async function* iterateBody(response) {
+    const body = response.body;
+    if (!body) {
+        const text = await response.text();
+        if (text)
+            yield text;
+        return;
+    }
+    const decoder = new TextDecoder();
+    const asyncIterable = body;
+    if (typeof asyncIterable[Symbol.asyncIterator] === "function") {
+        for await (const chunk of asyncIterable) {
+            yield decoder.decode(chunk, { stream: true });
+        }
+    }
+    else {
+        const reader = body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                yield decoder.decode(value, { stream: true });
+        }
+    }
+    const rest = decoder.decode();
+    if (rest)
+        yield rest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "pretypecheck": "npm run build",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "npm run build",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
     "@bli-cockpit/telemetry-core": "0.1.25"