@bli-cockpit/cli 0.2.54 → 0.2.56

package/dist/commands/jarvis-turn.js

@@ -0,0 +1,305 @@
+/**
+ * The turn engine, including `jarvis-turn`'s own turn: `sendOneTurn` (attach,
+ * request, stream, settle, print, log) and `readHistory` (`--threads` /
+ * `--thread <name> --history` — the same class of act with no model call,
+ * reading back what was already said). Everything each needs before the
+ * request or to draw the outcome lives in the render sibling —
+ * `jarvis-render.ts` — imported one direction only.
+ */
+import { colorEnabled, dim, writeLine } from "./cli-io.js";
+import { readAttachedImage } from "./jarvis-attachment.js";
+import { rememberTurnTrace } from "./jarvis-trace.js";
+import { towerFailureDetail, towerJsonRequest, towerRequest } from "../tower-client.js";
+import { readTowerTurn, streamFailureDetail } from "../tower-stream.js";
+import { activityToTrace, ANSWER_UPDATING_LINE, buildAttachmentForm, clientTimingFields, createLiveAnswer, latencyFields, latencyLogFields, TURN_DEADLINE_MS, writeActivityLine, writeAttachmentRefusal, writeFailure, writeModelReceipt, writeRevision, writeTraceBlock, } from "./jarvis-render.js";
+export async function sendOneTurn(context, prompt, io) {
+    const startedAt = Date.now();
+    // 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 { exitCode: 1, reply: null };
+        }
+        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);
+    // BLI-3591: everything this turn did before the question left the machine.
+    // There is no self-update probe, no floor check and no settings fetch on
+    // this path — the ONLY awaits between the command starting and the POST are
+    // the paired-session read, the piped-prompt read and an attached image, and
+    // all three are named. If this number is ever large, the step that made it
+    // large is on the same line.
+    const preRequestMs = Date.now() - startedAt;
+    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,
+                // BLI-3484: which day's page this turn is about. Sent verbatim — the
+                // dashboard decides what counts as a date and whose day it is.
+                date: context.command.date,
+                // BLI-3567: the answer this session last printed, so a correction can
+                // rewrite the paragraph it contradicts. Absent on a one-shot turn and
+                // on the first turn of a session, which is how the dashboard knows
+                // there is nothing above to revise.
+                previousAnswer: context.previous?.answer,
+                previousQuestion: context.previous?.question,
+            },
+        log,
+    });
+    if (!requested.ok) {
+        writeFailure(context.command, io, requested.reason, towerFailureDetail(requested.reason, requested.detail));
+        return { exitCode: 1, reply: null };
+    }
+    // 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. The same rule governs
+    // the answer's own words (BLI-3517): `--json` stays exactly one object.
+    let liveTraceLines = 0;
+    const live = createLiveAnswer(context.command, io);
+    const turn = await readTowerTurn(requested.response, {
+        startedAt,
+        log,
+        onActivity: (event) => {
+            if (context.command.json)
+                return;
+            // A trace row must never land in the middle of a half-written sentence.
+            live.interrupt();
+            if (writeActivityLine(io, event))
+                liveTraceLines += 1;
+        },
+        onToken: (event) => live.token(event),
+        // BLI-3567: the paragraph being rewritten says so while it happens. The
+        // terminal cannot mark the paragraph itself — it printed it turns ago — so
+        // the pending state is one dim line, in the same words the browsers use.
+        onRevision: (event) => {
+            if (context.command.json)
+                return;
+            if (event.revision?.status !== "pending")
+                return;
+            live.interrupt();
+            writeLine(io.stdout, dim(`  ${ANSWER_UPDATING_LINE}`, colorEnabled(io)));
+        },
+        onNote: (reason, detail) => {
+            log(`[jarvis cli] stream note ${JSON.stringify({
+                reason,
+                ...(detail && reason !== "ndjson_line_unparseable" ? { detail } : {}),
+            })}`);
+        },
+    });
+    if (!turn.ok) {
+        live.abandon();
+        writeFailure(context.command, io, turn.reason, streamFailureDetail(turn.reason, turn.detail));
+        return { exitCode: 1, reply: null };
+    }
+    const body = turn.final;
+    const httpStatus = typeof turn.final.httpStatus === "number" ? turn.final.httpStatus : requested.response.status;
+    if (httpStatus >= 400 || !body.ok || !body.reply) {
+        live.abandon();
+        const reason = body.error ?? body.reply ?? `http_${httpStatus}`;
+        writeFailure(context.command, io, "turn_failed", reason);
+        return { exitCode: 1, reply: null };
+    }
+    // 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);
+    // BLI-3560: bookmark this turn so `cockpit jarvis --trace last` can open its
+    // step tree. Written before the reply is printed for no reason other than
+    // keeping the failure — which is only ever a stderr line — above the answer
+    // rather than after it.
+    await rememberTurnTrace({ traceId: body.traceId ?? null, threadId: body.traceThread ?? null }, io, context.command.homeDir);
+    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,
+            subject: body.subject ?? null,
+            // BLI-3582: the server's own split of the wait. `null` from a
+            // dashboard that does not measure it yet.
+            latency: latencyFields(body.latency),
+            // BLI-3591: this side's own half of the same wait, so a consumer can
+            // put the whole journey together without a stopwatch of its own.
+            clientLatency: {
+                bootMs: context.boot.bootMs,
+                sessionMs: context.boot.sessionMs,
+                promptMs: context.boot.promptMs,
+                preRequestMs,
+                respondedMs: requested.respondedMs,
+                firstByteMs: turn.timing.firstByteMs,
+                firstFrameMs: turn.timing.firstFrameMs,
+                firstTokenMs: turn.timing.firstTokenMs,
+                elapsedMs: Date.now() - startedAt,
+            },
+            ...(body.traceId ? { traceId: body.traceId } : {}),
+        }));
+    }
+    else {
+        const subject = body.subject?.displayName ? ` (${body.subject.displayName})` : "";
+        // BLI-3517: when the answer streamed, `settle` prints only what the live
+        // words did not already say — and says so out loud when the grounding gate
+        // took some of them back. When nothing streamed it prints the whole reply
+        // through `writeReply`, which is byte-for-byte what this command printed
+        // before, BLI-3570's dim link line included.
+        live.settle(body.reply, subject, body.revised === true);
+        // BLI-3567: what the correction did to the answer above, printed under
+        // this turn's reply because that is the only place a terminal has.
+        if (body.revision)
+            writeRevision(context.command, io, body.revision);
+        // 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: 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,
+        // BLI-3517: whether the words arrived live, and whether the settled
+        // answer superseded them. `streamed_chars: 0` against a streaming
+        // dashboard means the answer landed all at once.
+        streamed_chars: turn.draft.length,
+        revised: body.revised === true,
+        // BLI-3567: whether this turn was told there was an answer above it, and
+        // what the correction did to it. `sent_previous_answer: false` is a
+        // one-shot turn; a status with no revision at all is a dashboard that
+        // predates the step.
+        sent_previous_answer: Boolean(context.previous),
+        revision: body.revision?.status ?? null,
+        revision_reason: body.revision?.reason ?? null,
+        // BLI-3582: `elapsed_ms` above is the whole wait as this side felt it;
+        // these three say which part of it was the dashboard's prep, which was
+        // the model's first token, and how long the socket stayed silent before
+        // the first byte. All null against a dashboard that does not send them.
+        ...latencyLogFields(body.latency),
+        // BLI-3591: the terminal's own half, on the same line, so the gap
+        // between the dashboard's first token and the first character a person
+        // sees stops being a mystery with nobody's name on it. `boot_ms` and
+        // `session_ms` are process facts (identical on every turn of an
+        // interactive session); the rest are this turn's, measured from the
+        // moment the turn started.
+        ...clientTimingFields(context.boot, {
+            preRequestMs,
+            respondedMs: requested.respondedMs,
+            timing: turn.timing,
+        }),
+    })}`);
+    return { exitCode: 0, reply: body.reply };
+}
+/**
+ * `--threads` and `--thread <name> --history`.
+ *
+ * The whole conversation lives on the server; nothing is cached locally, so a
+ * person who moves between machines sees the same history on both. The server
+ * scopes it to the device holder's own account — this command cannot ask for
+ * anybody else's, and there is no flag that would let it.
+ */
+export async function readHistory(context, io) {
+    const { command } = context;
+    const params = new URLSearchParams();
+    if (command.history) {
+        params.set("thread", command.thread);
+        if (command.limit)
+            params.set("limit", String(command.limit));
+    }
+    else {
+        params.set("threads", "1");
+    }
+    const result = await towerJsonRequest({
+        dashboardUrl: context.dashboardUrl,
+        path: `/api/jarvis/cli?${params.toString()}`,
+        deviceToken: context.deviceToken,
+        fetch: io.fetch,
+        method: "GET",
+        label: command.history ? "jarvis:thread" : "jarvis:threads",
+        timeoutMs: 30_000,
+        log: (line) => writeLine(io.stderr, line),
+    });
+    if (!result.ok) {
+        writeFailure(command, io, result.reason, result.detail);
+        return 1;
+    }
+    const body = result.body;
+    if (body.ok === false) {
+        writeFailure(command, io, "history_unavailable", body.reply ?? "Tower had nothing to show.");
+        return 1;
+    }
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(body));
+    }
+    else if (command.history) {
+        writeThreadHistory(io, body);
+    }
+    else {
+        writeThreadList(io, body.threads ?? []);
+    }
+    writeLine(io.stderr, `[jarvis cli] history read ${JSON.stringify({
+        mode: command.history ? "thread" : "threads",
+        thread_count: body.threads?.length ?? null,
+        message_count: body.messages?.length ?? null,
+        truncated: body.truncated ?? null,
+    })}`);
+    return 0;
+}
+function writeThreadList(io, threads) {
+    if (threads.length === 0) {
+        // A real answer, not a blank. Nothing here means nothing was ever asked
+        // from this terminal, which is worth saying rather than implying.
+        writeLine(io.stdout, "No terminal conversations yet. Ask something with `cockpit jarvis`.");
+        return;
+    }
+    const styled = colorEnabled(io);
+    for (const thread of threads) {
+        const turns = thread.turnCount === 1 ? "1 turn" : `${thread.turnCount ?? 0} turns`;
+        writeLine(io.stdout, `${thread.name}  ${dim(`${turns} · ${thread.lastAt ?? "unknown"}`, styled)}`);
+        if (thread.preview)
+            writeLine(io.stdout, dim(`  ${thread.preview}`, styled));
+    }
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, dim("Replay one with `cockpit jarvis --thread <name> --history`.", styled));
+}
+function writeThreadHistory(io, body) {
+    const messages = body.messages ?? [];
+    if (messages.length === 0) {
+        writeLine(io.stdout, `Nothing has been said in “${body.thread ?? "that thread"}” yet.`);
+        return;
+    }
+    if (body.truncated) {
+        writeLine(io.stdout, dim(`Showing the most recent ${messages.length}; there is more before this (\`--limit\`).`, colorEnabled(io)));
+    }
+    for (const message of messages) {
+        const speaker = message.role === "you" ? "you" : "jarvis";
+        writeLine(io.stdout, `${speaker}> ${message.text ?? ""}`);
+    }
+}