@cargo-ai/cli 1.0.78 → 1.0.81

package/build/commands/ask/session.js

@@ -0,0 +1,965 @@
+import { randomUUID } from "node:crypto";
+import { isAbsolute, relative } from "node:path";
+import { determineIfIsFetcherError } from "@cargo-ai/api";
+import { isInteractive, selectOne } from "@cargo-ai/cdk/cli";
+import { getConfig } from "../../config.js";
+import { openPromptInput } from "../../utils/prompt.js";
+import { colors, ExitCodes, failWith, handleApiCall, outputJson, pollUntilFinished, startSpinner, } from "../runHandler.js";
+import { loadChatHistoryPreamble } from "./history.js";
+import { createLocalHarness, HarnessTurnStuck, } from "./localHarness.js";
+import { streamMessageTextDeltas } from "./messageStream.js";
+import { saveAskState } from "./persist.js";
+import { readAskLine } from "./prompt.js";
+import { parseSlash } from "./slash.js";
+import { ASK_STATE_VERSION } from "./state.js";
+function requireInteractive() {
+    if (isInteractive() === false || process.stdout.isTTY !== true) {
+        failWith("Ask needs a terminal. Re-run with --print for one JSON turn.", {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+}
+/** Sentinel for `/agent` → Local workspace (no agentUuid). */
+const LOCAL_WORKSPACE = "__local_workspace__";
+/**
+ * How long before a proxy token's stated expiry to stop trusting it. Covers
+ * the gap between deciding to reuse the harness and the first proxy call the
+ * turn makes.
+ */
+const TOKEN_REFRESH_MARGIN_MS = 5 * 60_000;
+/**
+ * When the proxy token baked into the running harness stops being safe to
+ * reuse.
+ *
+ * The server re-arms the token on every proxy call, so the clock runs from
+ * the last turn that reached Anthropic rather than from when it was minted.
+ * Anchoring it to mint time instead would tear down a conversation that is
+ * still going — a cold start, a replayed history preamble and the loss of
+ * Claude Code's in-session memory, for a token that had not expired.
+ *
+ * Exported for tests.
+ */
+export function proxyTokenDeadlineMs(input) {
+    const armedAtMs = input.lastUsedAtMs === undefined ? input.mintedAtMs : input.lastUsedAtMs;
+    return armedAtMs + input.ttlMs - TOKEN_REFRESH_MARGIN_MS;
+}
+const PRINT_POLL_INTERVAL_MS = 5_000;
+/**
+ * How long `--print` waits for a remote turn. Generous, because a multi-step
+ * agent legitimately runs for a while — but bounded, because `--print` is the
+ * path used by pipes and CI, where nobody is there to notice a wait that
+ * never ends.
+ */
+const PRINT_POLL_TIMEOUT_MS = 30 * 60_000;
+async function loadAgent(api, agentUuid) {
+    const result = await handleApiCall(() => api.ai.agent.get(agentUuid));
+    return result.agent;
+}
+/**
+ * No agent → local Claude Code on the host. Any agent streams remotely, like
+ * the webapp chat: what it runs — a tool loop or a harness against its bound
+ * repo — follows from its deployed release, which the API resolves itself.
+ *
+ * Exported for tests.
+ */
+export function modeForAgent(agent) {
+    return agent === undefined ? { kind: "local" } : { kind: "remote" };
+}
+/**
+ * Pick a workspace agent, or Local workspace (clears the agent).
+ * Returns undefined when the user chooses the local default.
+ */
+async function pickAgent(api, currentUuid) {
+    const { agents } = await handleApiCall(() => api.ai.agent.all());
+    const chosen = await selectOne({
+        message: "Agent for the next question",
+        recommended: currentUuid !== undefined ? currentUuid : LOCAL_WORKSPACE,
+        choices: [
+            {
+                value: LOCAL_WORKSPACE,
+                label: "Local workspace",
+                hint: "Claude Code on this machine (default)",
+                fallback: true,
+            },
+            ...agents.map((agent) => ({
+                value: agent.uuid,
+                label: agent.name,
+                hint: agent.uuid,
+            })),
+        ],
+    });
+    if (chosen === LOCAL_WORKSPACE) {
+        return undefined;
+    }
+    return chosen;
+}
+/**
+ * `harnessSlug` is deliberately not sent. On the API it is a chat-level
+ * override that outranks the agent's release for the life of the chat, so a
+ * chat stamped here would keep routing to a harness even after `/agent` picks
+ * something else — and a local chat's harness runs on this machine, where the
+ * API could not reach it anyway. Letting the release speak for itself keeps the
+ * chat reusable by any agent.
+ */
+async function ensureChat(input) {
+    if (input.created === true) {
+        return;
+    }
+    await handleApiCall(() => input.api.ai.chat.create({
+        uuid: input.chatUuid,
+        trigger: { type: "app" },
+        agentUuid: input.agentUuid,
+    }), { spinner: false });
+}
+function persistAskState(input) {
+    saveAskState({
+        version: ASK_STATE_VERSION,
+        chatUuid: input.chatUuid,
+        agentUuid: input.agentUuid,
+        updatedAt: new Date().toISOString(),
+    });
+}
+/**
+ * Take the chat for one local turn.
+ *
+ * Exported for tests.
+ */
+export async function claimChatTurn(api, chatUuid, ownerId) {
+    try {
+        await api.ai.chat.claimTurn(chatUuid, { ownerId });
+        return { outcome: "claimed" };
+    }
+    catch (error) {
+        if (determineIfIsFetcherError(error) === true &&
+            error.status === 409) {
+            return { outcome: "busy" };
+        }
+        // Handed back rather than reported from here. Reporting an API failure
+        // ends the process, and the interactive session has a Claude Code process
+        // to shut down first — `process.exit` does not run the `finally` that
+        // would have done it.
+        return { outcome: "unavailable", error };
+    }
+}
+/**
+ * Report an API failure the way every other call in the CLI does, and exit.
+ * Never returns: `handleApiCall` exits on a recognised API error, and anything
+ * else is rethrown for the top-level handler.
+ */
+async function reportApiFailure(error) {
+    await handleApiCall(async () => {
+        throw error;
+    }, { spinner: false });
+    throw error;
+}
+/**
+ * Hand the chat back after a turn.
+ *
+ * Recording the turn already does this, but a turn that spent nothing has
+ * nothing to record — a stall, an expired token, a workspace out of credits —
+ * and the claim would sit there until it expired, telling the next process the
+ * chat was busy.
+ *
+ * Best effort: the TTL is the backstop, and a reply the user has already read
+ * must not fail on the way out.
+ */
+async function releaseChatTurn(api, chatUuid, ownerId) {
+    try {
+        await api.ai.chat.releaseTurn(chatUuid, { ownerId });
+    }
+    catch {
+        // Nothing useful to say to the user about this one.
+    }
+}
+export async function doesChatExist(api, chatUuid) {
+    try {
+        await api.ai.chat.get(chatUuid);
+        return true;
+    }
+    catch (error) {
+        if (determineIfIsFetcherError(error) === true &&
+            error.status === 404) {
+            return false;
+        }
+        await handleApiCall(async () => {
+            throw error;
+        }, { spinner: false });
+        return false;
+    }
+}
+/**
+ * Body width under `◇  ` / `│  ` / `◆  `. Soft wrap without this drops the
+ * rail mid-line and the tree looks broken.
+ */
+function treeBodyWidth() {
+    const columns = process.stderr.columns === undefined ? 80 : process.stderr.columns;
+    // Marker + two spaces (`◇  `, `│  `, `◆  `).
+    return Math.max(24, columns - 3);
+}
+/**
+ * Greedy wrap on spaces. A word longer than the width keeps its own line
+ * rather than being cut mid-token.
+ */
+function wrapLine(text, width) {
+    const lines = [];
+    for (const word of text.split(/\s+/).filter((part) => part.length > 0)) {
+        const current = lines[lines.length - 1];
+        if (current === undefined || `${current} ${word}`.length > width) {
+            lines.push(word);
+            continue;
+        }
+        lines[lines.length - 1] = `${current} ${word}`;
+    }
+    return lines;
+}
+/** One line under the current ◆/◇, with the │ rail (same indent as clack). */
+function writeRail(body) {
+    process.stderr.write(`${colors.dim("│")}  ${body}\n`);
+}
+/** Word-wrap onto the │ rail so the terminal never soft-wraps mid-line. */
+function writeRailWrapped(body) {
+    // Keep the rail on blank paragraphs so the tree does not break mid-reply.
+    if (body === "") {
+        writeRail("");
+        return;
+    }
+    const lines = wrapLine(body, treeBodyWidth());
+    if (lines.length === 0) {
+        writeRail("");
+        return;
+    }
+    for (const line of lines) {
+        writeRail(line);
+    }
+}
+/**
+ * Light cleanup so model markdown does not fight the tree. Keeps the words;
+ * drops heading marks, bold markers, and horizontal rules.
+ */
+function forTerminal(text) {
+    return text
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/^---+$/gm, "");
+}
+/**
+ * One finished step: label on the diamond, body on the rail.
+ *
+ *   ◇  Agent
+ *   │  reply…
+ */
+function showStep(label, body) {
+    process.stderr.write(`${colors.dim("◇")}  ${label}\n`);
+    for (const paragraph of body.split("\n")) {
+        writeRailWrapped(paragraph);
+    }
+}
+/**
+ * Slash help / notes — finished step like the palette:
+ *   ◇  /help
+ *   │  …
+ */
+function showCard(body) {
+    const paragraphs = body.split("\n");
+    const title = paragraphs[0] === undefined ? "" : paragraphs[0];
+    const rest = paragraphs.slice(1).join("\n");
+    showStep(title, rest);
+}
+/**
+ * Finished user turn — message on the diamond, like the palette's
+ * `◇  ask hey --continue`. No "You" label.
+ */
+function showUserTurn(body) {
+    const lines = body === "" ? [""] : wrapLine(body, treeBodyWidth());
+    const first = lines.length === 0 ? "" : lines[0] === undefined ? "" : lines[0];
+    process.stderr.write(`${colors.dim("◇")}  ${first}\n`);
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line !== undefined) {
+            writeRail(line);
+        }
+    }
+}
+/**
+ * Display lines for an assistant body. First line is the brick header body;
+ * later lines sit on the │ rail. Blank paragraphs keep an empty rail.
+ */
+function assistantDisplayLines(body) {
+    const paragraphs = forTerminal(body).split("\n");
+    const lines = [];
+    for (let index = 0; index < paragraphs.length; index += 1) {
+        const paragraph = paragraphs[index];
+        if (paragraph === undefined) {
+            continue;
+        }
+        if (paragraph === "") {
+            lines.push("");
+            continue;
+        }
+        const wrapped = wrapLine(paragraph, treeBodyWidth());
+        if (wrapped.length === 0) {
+            lines.push("");
+            continue;
+        }
+        for (const line of wrapped) {
+            lines.push(line);
+        }
+    }
+    if (lines.length === 0) {
+        return [""];
+    }
+    return lines;
+}
+function writeAssistantLines(lines) {
+    const first = lines[0] === undefined ? "" : lines[0];
+    // One space after the brick: the emoji is already two columns, so `🧱 `
+    // lines up with `◇  ` / `│  `.
+    process.stderr.write(`🧱 ${first}\n`);
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line !== undefined) {
+            writeRail(line);
+        }
+    }
+}
+function clearPaintedLines(count) {
+    if (count <= 0 || process.stderr.isTTY !== true) {
+        return;
+    }
+    process.stderr.write(`\x1B[${String(count)}A\r\x1B[J`);
+}
+/** Rail gap, then an empty brick line ready for deltas. */
+function beginAssistantTurn() {
+    writeRail("");
+    process.stderr.write(`🧱 \n`);
+    return { buffer: "", paintedLines: 1 };
+}
+function appendAssistantDelta(live, delta) {
+    live.buffer += delta;
+    const lines = assistantDisplayLines(live.buffer);
+    clearPaintedLines(live.paintedLines);
+    writeAssistantLines(lines);
+    live.paintedLines = lines.length;
+}
+/** Trailing rail gap before the next user turn / ◆ prompt. */
+function endAssistantTurn(_live) {
+    writeRail("");
+}
+/**
+ * Finished assistant turn — same tree as a user step, but `🧱` instead of `◇`.
+ */
+function showAssistantTurn(body) {
+    const live = beginAssistantTurn();
+    appendAssistantDelta(live, body);
+    endAssistantTurn(live);
+}
+/**
+ * Ctrl-C during a turn cancels the turn, not the CLI: the harness interrupts
+ * Claude Code, the tree says so, and the ◆ prompt comes back. A second Ctrl-C
+ * while the first is still settling exits for real.
+ */
+function beginCancellableTurn(onCancel) {
+    const controller = new AbortController();
+    const state = { cancelled: false };
+    const handleInterrupt = () => {
+        if (state.cancelled === true) {
+            // 130 is the conventional "terminated by SIGINT" status.
+            process.exit(130);
+        }
+        state.cancelled = true;
+        onCancel();
+        controller.abort();
+    };
+    process.on("SIGINT", handleInterrupt);
+    return {
+        signal: controller.signal,
+        wasCancelled: () => state.cancelled,
+        release: () => {
+            process.removeListener("SIGINT", handleInterrupt);
+        },
+    };
+}
+/**
+ * Stop a remote turn the user walked away from.
+ *
+ * Best effort: the uuid is only known once the server has announced the
+ * message, and a failed cancel must not take the chat session down with it —
+ * the next turn reports `lastMessageNotFinished` if this did not land.
+ */
+async function cancelRemoteMessage(api, messageUuid) {
+    if (messageUuid === undefined) {
+        return;
+    }
+    try {
+        await api.ai.message.cancel({ uuids: [messageUuid] });
+    }
+    catch {
+        // Nothing useful to do here; surfacing it would bury the "Cancelled." card.
+    }
+}
+/** Common tool names arrive lowercase (`bash`); natives keep their case. */
+function toolLabel(toolName) {
+    if (toolName.length === 0) {
+        return "tool";
+    }
+    return `${toolName.slice(0, 1).toUpperCase()}${toolName.slice(1)}`;
+}
+const ACTIVITY_MAX_LENGTH = 72;
+function describeToolActivity(toolName, summary) {
+    const label = toolLabel(toolName);
+    if (summary === "") {
+        return label;
+    }
+    const line = `${label}: ${summary}`;
+    return line.length > ACTIVITY_MAX_LENGTH
+        ? `${line.slice(0, ACTIVITY_MAX_LENGTH - 1)}…`
+        : line;
+}
+/**
+ * A path inside the session directory reads better relative to it; anything
+ * outside stays absolute so it is obvious the turn left the project.
+ *
+ * Exported for tests.
+ */
+export function displayPath(path, dir) {
+    const relativePath = relative(dir, path);
+    return relativePath === "" ||
+        relativePath.startsWith("..") === true ||
+        isAbsolute(relativePath) === true
+        ? path
+        : relativePath;
+}
+/**
+ * Closing step for a turn that edited the working copy, so a reply that says
+ * "done" is backed by the list of files it touched.
+ */
+function showTouchedFiles(paths, dir) {
+    if (paths.size === 0) {
+        return;
+    }
+    const listed = [...paths].map((path) => displayPath(path, dir)).sort();
+    showStep(`${String(listed.length)} file${listed.length === 1 ? "" : "s"} changed`, listed.join("\n"));
+}
+/**
+ * Side notes from a turn — a chat-history save that failed, say. They are not
+ * part of the reply, so they land after it rather than inside it.
+ */
+function showNotices(notices) {
+    while (notices.length > 0) {
+        const notice = notices.shift();
+        if (notice !== undefined) {
+            showCard(notice);
+        }
+    }
+}
+/**
+ * Local Claude Code runs against the user's own working copy, so anything
+ * beyond a read is confirmed before it happens:
+ *
+ *   ◆  Run Bash: npm test?
+ *   │  ● Yes …
+ */
+async function askToolApproval(approval) {
+    const decision = await selectOne({
+        message: approval.summary === ""
+            ? `Run ${approval.toolName}?`
+            : `Run ${approval.toolName}: ${approval.summary}?`,
+        recommended: "yes",
+        // Escape here means "not that tool", not "leave the chat" — the turn
+        // continues and the model reports what it could not do.
+        cancelValue: "no",
+        choices: [
+            { value: "yes", label: "Yes", hint: "just this once" },
+            { value: "always", label: "Yes to everything", hint: "for this chat" },
+            { value: "no", label: "No", hint: "tell the model to skip it" },
+        ],
+    });
+    return decision === "always" ? "always" : decision === "no" ? "no" : "yes";
+}
+/**
+ * Live prompt: `◆  ` with an as-you-type suggestion menu for `/…` commands
+ * and path-like tokens. Empty Enter leaves. A first message from the palette
+ * is written as a finished user turn, then sent.
+ */
+async function readQuestion(firstMessage, dir) {
+    if (firstMessage !== undefined) {
+        showUserTurn(firstMessage);
+        return firstMessage;
+    }
+    const input = openPromptInput();
+    if (input === undefined) {
+        failWith("Ask needs a terminal. Re-run with --print for one JSON turn.", {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+    try {
+        const answer = await readAskLine(input.stream, dir);
+        if (answer === undefined) {
+            return undefined;
+        }
+        showUserTurn(answer);
+        return answer;
+    }
+    finally {
+        input.close();
+    }
+}
+/**
+ * Same tree grammar as the palette:
+ *   ◇  <your message>
+ *   🧱  reply…
+ *   ◆
+ * Empty Enter or /exit leaves to the parent palette.
+ */
+export async function runAskSession(options) {
+    requireInteractive();
+    const config = getConfig();
+    // An API token from CARGO_API_TOKEN is workspace-bound on the server, so
+    // config.workspaceUuid can be unset — same as whoami / every other command.
+    if (config.getAccessToken === undefined) {
+        failWith("Not authenticated. Run 'cargo-ai login --email <email>' or 'cargo-ai login --oauth'.", { code: ExitCodes.NotAuthenticated });
+    }
+    let agent = options.agentUuid !== undefined
+        ? await loadAgent(options.api, options.agentUuid)
+        : undefined;
+    let chatUuid = options.chatUuid !== undefined ? options.chatUuid : randomUUID();
+    let chatCreated = false;
+    let pendingFirst = options.message;
+    let local;
+    // The proxy token is fixed in the Claude Code process env at spawn, so the
+    // only way to refresh it is to rebuild the harness. These two say when that
+    // becomes necessary; see `proxyTokenDeadlineMs`.
+    let localTokenMintedAtMs = 0;
+    let localTokenTtlMs = 0;
+    // Identifies this process to the server's per-chat turn claim, so our own
+    // next turn renews it rather than colliding with it.
+    const sessionId = randomUUID();
+    // "Yes to everything" lasts until the chat is reset, never on disk.
+    let approveEveryTool = false;
+    if (options.continueChat === true && options.chatUuid !== undefined) {
+        chatCreated = await doesChatExist(options.api, options.chatUuid);
+    }
+    try {
+        for (;;) {
+            const mode = modeForAgent(agent);
+            const question = await readQuestion(pendingFirst, options.dir);
+            pendingFirst = undefined;
+            if (question === undefined) {
+                return "palette";
+            }
+            const slash = parseSlash(question);
+            if (slash !== undefined) {
+                if (slash.kind === "card") {
+                    showCard(slash.text);
+                    continue;
+                }
+                if (slash.action === "exit") {
+                    return "palette";
+                }
+                if (slash.action === "cancel") {
+                    showCard("Nothing is running — this prompt only appears between turns. Press Ctrl-C while a turn is in flight to stop it.");
+                    continue;
+                }
+                if (slash.action === "new" || slash.action === "clear") {
+                    if (local !== undefined) {
+                        await local.close();
+                        local = undefined;
+                    }
+                    // Fresh session returns to the local default (no agent).
+                    agent = undefined;
+                    chatUuid = randomUUID();
+                    chatCreated = false;
+                    approveEveryTool = false;
+                    showCard("Started a fresh chat.");
+                    continue;
+                }
+                if (slash.action === "pick-agent") {
+                    if (local !== undefined) {
+                        await local.close();
+                        local = undefined;
+                    }
+                    const nextUuid = await pickAgent(options.api, agent === undefined ? undefined : agent.uuid);
+                    agent =
+                        nextUuid === undefined
+                            ? undefined
+                            : await loadAgent(options.api, nextUuid);
+                    // A blanket "yes" was given to one agent's local session, not to
+                    // whatever the next one wants to run.
+                    approveEveryTool = false;
+                    continue;
+                }
+            }
+            if (mode.kind === "local") {
+                if (chatCreated === false) {
+                    await ensureChat({
+                        api: options.api,
+                        chatUuid,
+                        agentUuid: agent === undefined ? undefined : agent.uuid,
+                        created: false,
+                    });
+                    chatCreated = true;
+                }
+                // A session left at the prompt long enough for its token to lapse
+                // would send the next turn with a dead key, which surfaces as an
+                // authentication failure from the proxy rather than anything the user
+                // can act on. Rebuilding costs a cold start and a history replay, so
+                // it happens only once the token really is past saving.
+                if (local !== undefined &&
+                    Date.now() >=
+                        proxyTokenDeadlineMs({
+                            mintedAtMs: localTokenMintedAtMs,
+                            lastUsedAtMs: local.proxyLastUsedAtMs(),
+                            ttlMs: localTokenTtlMs,
+                        })) {
+                    await local.close();
+                    local = undefined;
+                }
+                if (local === undefined) {
+                    const minted = await handleApiCall(() => options.api.ai.chat.mintHarnessProxyToken(chatUuid), { spinner: false });
+                    localTokenMintedAtMs = Date.now();
+                    localTokenTtlMs = minted.expiresInSeconds * 1000;
+                    // A new Claude Code session knows nothing of this chat, whether it
+                    // is being continued from an earlier run or was reset by /agent.
+                    const history = await loadChatHistoryPreamble({
+                        api: options.api,
+                        chatUuid,
+                    });
+                    local = await createLocalHarness({
+                        api: options.api,
+                        apiBaseUrl: config.baseUrl,
+                        dir: options.dir,
+                        chatUuid,
+                        agentUuid: agent === undefined ? undefined : agent.uuid,
+                        proxyToken: minted.token,
+                        history,
+                        turnOwnerId: sessionId,
+                    });
+                }
+                // Nothing about a local turn is visible to the server until it is
+                // ingested, so the chat reads as idle while Claude Code works and a
+                // second session resuming it would spend alongside this one.
+                //
+                // Taken here rather than before the setup above: the claim is only
+                // released by a finished turn, so holding it across a mint or a
+                // harness build that then fails would block the chat for the whole
+                // TTL. Nothing in the setup needs protecting — mint hands back the
+                // token already in play rather than replacing it.
+                const claim = await claimChatTurn(options.api, chatUuid, sessionId);
+                if (claim.outcome === "busy") {
+                    showCard("Another session is already running a turn in this chat. Wait for it to finish, or /new to start a fresh one.");
+                    continue;
+                }
+                if (claim.outcome === "unavailable") {
+                    // Reporting this ends the process, and the harness is already
+                    // running — shut it down here, because `process.exit` skips the
+                    // `finally` below that would otherwise have done it. Left assigned
+                    // so the `finally` still closes it on the one path that unwinds
+                    // instead of exiting; closing twice is harmless.
+                    await local.close();
+                    await reportApiFailure(claim.error);
+                }
+                let spinner;
+                let live;
+                // A tool interrupting the narration closes the live block, so `live`
+                // alone cannot tell whether the turn ever said anything.
+                let saidSomething = false;
+                const touchedFiles = new Set();
+                const notices = [];
+                const stopSpinner = () => {
+                    if (spinner !== undefined) {
+                        spinner.stop();
+                        spinner = undefined;
+                    }
+                };
+                const showSpinner = (label) => {
+                    if (spinner === undefined) {
+                        spinner = startSpinner(label);
+                        return;
+                    }
+                    spinner.update(label);
+                };
+                // Registered before the spinner so our SIGINT handler runs first and
+                // clack's spinner is already stopped when its own handler fires —
+                // otherwise Ctrl-C prints its cancel line under ours.
+                const cancellation = beginCancellableTurn(stopSpinner);
+                spinner = startSpinner("Asking…");
+                try {
+                    await local.streamPrompt(question, {
+                        abortSignal: cancellation.signal,
+                        onTextDelta: (delta) => {
+                            if (live === undefined) {
+                                stopSpinner();
+                                live = beginAssistantTurn();
+                            }
+                            saidSomething = true;
+                            appendAssistantDelta(live, delta);
+                        },
+                        onActivity: (activity) => {
+                            // Tool work replaces the spinner text so a long Bash step is
+                            // not an unexplained pause. Claude Code narrates before it acts,
+                            // so a tool usually starts with live text on screen: close that
+                            // block first, and the next delta opens a new one.
+                            if (activity.kind === "end") {
+                                showSpinner("Asking…");
+                                return;
+                            }
+                            if (live !== undefined) {
+                                endAssistantTurn(live);
+                                live = undefined;
+                            }
+                            showSpinner(describeToolActivity(activity.toolName, activity.summary));
+                        },
+                        onFileTouched: (path) => {
+                            touchedFiles.add(path);
+                        },
+                        onNotice: (message) => {
+                            notices.push(message);
+                        },
+                        onApproval: async (approval) => {
+                            // Close whatever is on screen: the prompt owns the line next.
+                            if (live !== undefined) {
+                                endAssistantTurn(live);
+                                live = undefined;
+                            }
+                            stopSpinner();
+                            const decision = approveEveryTool === true
+                                ? "always"
+                                : await askToolApproval(approval);
+                            if (decision === "always") {
+                                approveEveryTool = true;
+                            }
+                            showSpinner("Asking…");
+                            return decision !== "no";
+                        },
+                    });
+                    stopSpinner();
+                    if (live !== undefined) {
+                        endAssistantTurn(live);
+                    }
+                    else if (saidSomething === false) {
+                        showAssistantTurn("");
+                    }
+                    showTouchedFiles(touchedFiles, options.dir);
+                    showNotices(notices);
+                }
+                catch (error) {
+                    stopSpinner();
+                    if (live !== undefined) {
+                        endAssistantTurn(live);
+                    }
+                    if (cancellation.wasCancelled() === true) {
+                        showTouchedFiles(touchedFiles, options.dir);
+                        showNotices(notices);
+                        showCard("Cancelled.");
+                        persistAskState({
+                            chatUuid,
+                            agentUuid: agent === undefined ? undefined : agent.uuid,
+                        });
+                        continue;
+                    }
+                    showNotices(notices);
+                    // The runtime could not be wound down, so this session will refuse
+                    // every question from here. Replace it rather than leaving the user
+                    // to guess that /new is the way out — the chat, its history and the
+                    // working copy all survive; only the Claude Code process is new.
+                    if (error instanceof HarnessTurnStuck) {
+                        await local.close();
+                        local = undefined;
+                        showCard("That coding session stopped responding, so it has been replaced. Ask again — the chat is unchanged.");
+                        continue;
+                    }
+                    throw error;
+                }
+                finally {
+                    cancellation.release();
+                    await releaseChatTurn(options.api, chatUuid, sessionId);
+                }
+                persistAskState({
+                    chatUuid,
+                    agentUuid: agent === undefined ? undefined : agent.uuid,
+                });
+                continue;
+            }
+            if (agent === undefined) {
+                failWith("Ask remote stream needs an agent.", {
+                    code: ExitCodes.GenericError,
+                });
+            }
+            if (chatCreated === false) {
+                await ensureChat({
+                    api: options.api,
+                    chatUuid,
+                    agentUuid: agent.uuid,
+                    created: false,
+                });
+                chatCreated = true;
+            }
+            if (config.getAccessToken === undefined) {
+                failWith("Not authenticated. Run 'cargo-ai login --email <email>' or 'cargo-ai login --oauth'.", { code: ExitCodes.NotAuthenticated });
+            }
+            let live;
+            let spinner;
+            const stopRemoteSpinner = () => {
+                if (spinner !== undefined) {
+                    spinner.stop();
+                    spinner = undefined;
+                }
+            };
+            // Registered before the spinner so our handler runs before clack's own
+            // — same ordering as the local turn.
+            const cancellation = beginCancellableTurn(stopRemoteSpinner);
+            spinner = startSpinner("Asking…");
+            let assistantMessageUuid;
+            try {
+                const deltas = streamMessageTextDeltas({
+                    baseUrl: config.baseUrl,
+                    getAccessToken: config.getAccessToken,
+                    workspaceUuid: config.workspaceUuid,
+                    chatUuid,
+                    messageUuid: randomUUID(),
+                    parts: [{ type: "text", text: question }],
+                    agentUuid: agent.uuid,
+                    onAssistantMessageUuid: (uuid) => {
+                        assistantMessageUuid = uuid;
+                    },
+                    abortSignal: cancellation.signal,
+                });
+                for await (const delta of deltas) {
+                    if (live === undefined) {
+                        stopRemoteSpinner();
+                        live = beginAssistantTurn();
+                    }
+                    appendAssistantDelta(live, delta);
+                }
+                if (live === undefined) {
+                    stopRemoteSpinner();
+                    showAssistantTurn("");
+                }
+                else {
+                    endAssistantTurn(live);
+                }
+            }
+            catch (error) {
+                stopRemoteSpinner();
+                if (live !== undefined) {
+                    endAssistantTurn(live);
+                }
+                // Ctrl-C only stops the CLI reading the stream, so the message has to
+                // be cancelled server-side too — an unfinished one makes the next
+                // question in this chat fail with lastMessageNotFinished.
+                if (cancellation.wasCancelled() === true) {
+                    await cancelRemoteMessage(options.api, assistantMessageUuid);
+                    showCard("Cancelled.");
+                    persistAskState({ chatUuid, agentUuid: agent.uuid });
+                    continue;
+                }
+                if (error instanceof Error) {
+                    failWith(error.message, { code: ExitCodes.GenericError });
+                }
+                throw error;
+            }
+            finally {
+                cancellation.release();
+            }
+            persistAskState({
+                chatUuid,
+                agentUuid: agent.uuid,
+            });
+        }
+    }
+    finally {
+        if (local !== undefined) {
+            await local.close();
+        }
+    }
+}
+export async function runAskPrint(input) {
+    const config = getConfig();
+    if (config.getAccessToken === undefined) {
+        failWith("Not authenticated. Run 'cargo-ai login --email <email>' or 'cargo-ai login --oauth'.", { code: ExitCodes.NotAuthenticated });
+    }
+    const agent = input.agentUuid !== undefined
+        ? await loadAgent(input.api, input.agentUuid)
+        : undefined;
+    const mode = modeForAgent(agent);
+    const chatUuid = input.chatUuid !== undefined ? input.chatUuid : randomUUID();
+    // Same lifecycle as the interactive session: a caller-supplied uuid may
+    // already be on the server (--chat-uuid, or --continue reopening the last
+    // thread), in which case creating it again would fail; a fresh one has to
+    // be created before the first message.
+    const chatCreated = input.chatUuid !== undefined
+        ? await doesChatExist(input.api, input.chatUuid)
+        : false;
+    if (mode.kind === "local") {
+        await ensureChat({
+            api: input.api,
+            chatUuid,
+            agentUuid: agent === undefined ? undefined : agent.uuid,
+            created: chatCreated,
+        });
+        const minted = await handleApiCall(() => input.api.ai.chat.mintHarnessProxyToken(chatUuid), { spinner: false });
+        const history = await loadChatHistoryPreamble({
+            api: input.api,
+            chatUuid,
+        });
+        const ownerId = randomUUID();
+        // Before the harness is built, because both exits below end the process
+        // and `process.exit` does not run `finally` blocks — either one below a
+        // live harness would leave Claude Code and its bridge running.
+        const claim = await claimChatTurn(input.api, chatUuid, ownerId);
+        if (claim.outcome === "busy") {
+            failWith("Another session is already running a turn in this chat. Wait for it to finish, or pass --chat-uuid for a different one.", { code: ExitCodes.GenericError });
+        }
+        if (claim.outcome === "unavailable") {
+            await reportApiFailure(claim.error);
+        }
+        let local;
+        try {
+            local = await createLocalHarness({
+                api: input.api,
+                apiBaseUrl: config.baseUrl,
+                dir: input.dir,
+                chatUuid,
+                agentUuid: agent === undefined ? undefined : agent.uuid,
+                proxyToken: minted.token,
+                history,
+                turnOwnerId: ownerId,
+            });
+            const text = await local.streamPrompt(input.message);
+            persistAskState({
+                chatUuid,
+                agentUuid: agent === undefined ? undefined : agent.uuid,
+            });
+            outputJson({ chatUuid, text });
+        }
+        finally {
+            // Covers the build as well as the turn: a turn that errored spent
+            // nothing and so recorded nothing, and a build that failed never got as
+            // far as a turn. Either would leave the chat claimed until the TTL.
+            await releaseChatTurn(input.api, chatUuid, ownerId);
+            if (local !== undefined) {
+                await local.close();
+            }
+        }
+        return;
+    }
+    if (agent === undefined) {
+        failWith("Ask remote print needs an agent.", {
+            code: ExitCodes.GenericError,
+        });
+    }
+    await ensureChat({
+        api: input.api,
+        chatUuid,
+        agentUuid: agent.uuid,
+        created: chatCreated,
+    });
+    const result = await handleApiCall(() => input.api.ai.message.create({
+        chatUuid,
+        agentUuid: agent.uuid,
+        parts: [{ type: "text", text: input.message }],
+    }));
+    const finalResult = await pollUntilFinished(() => input.api.ai.message.get(result.assistantMessage.uuid), (row) => row.message.finishedAt, PRINT_POLL_INTERVAL_MS, PRINT_POLL_TIMEOUT_MS);
+    persistAskState({ chatUuid, agentUuid: agent.uuid });
+    outputJson(finalResult);
+}