@illuminis/comprism 0.1.2 → 0.1.4

package/out/agent/session.js

@@ -60,10 +60,32 @@ exports.TerminalSession = void 0;
  * front. Both are the same session; the difference is who answers.
  */
 const gateway_1 = require("../lib/gateway");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
 const executor_1 = require("../executor");
+const project_1 = require("../lib/project");
 const ui = __importStar(require("./render"));
+const jobs_1 = require("../commands/jobs");
+/** The actions that change a file, whose change is shown as it is made. */
+const CHANGES = new Set(["edit_file", "multi_edit", "write_file"]);
+/** Files with changes in Git as the job starts: the person's, not the agent's. */
+function dirtyFiles(root) {
+    try {
+        const { spawnSync } = require("child_process");
+        const r = spawnSync("git", ["status", "--porcelain", "-uall"], { cwd: root, encoding: "utf8", timeout: 5000 });
+        if (r.status !== 0)
+            return [];
+        return String(r.stdout).split("\n").filter(Boolean).map((l) => l.slice(3).split(" -> ").pop() ?? "")
+            .filter(Boolean).slice(0, 500);
+    }
+    catch {
+        return [];
+    }
+}
 class TerminalSession {
+    /** The VS Code window this terminal is inside, when there is one (VS Code manual 9.12). */
+    editor = null;
     socket = null;
     executor;
     opts;
@@ -80,12 +102,13 @@ class TerminalSession {
         this.out = write;
         this.executor = new executor_1.NativeExecutor({
             root: opts.root,
+            added: opts.project?.added ?? [],
             // Streamed straight through while a command runs. A build that takes two
             // minutes must not look like a hang, and the output is the only thing
             // that proves it is not.
             onOutput: (chunk) => {
                 if (!opts.headless)
-                    this.out(ui.gray(chunk));
+                    this.stream(chunk);
             },
         });
     }
@@ -126,8 +149,18 @@ class TerminalSession {
             // include coding and an allowance that has been spent have different
             // fixes, and a caller told only "refused" looks in the wrong place.
             this.refusal = reply.message || "your workspace could not be reached";
+            // The reason word, for the exit number (Appendix B): the service's own
+            // when it answered, else what the missing answer means.
+            this.refusalReason = reply.reason
+                ?? (reply.httpStatus === 401 ? "signed_out"
+                    : reply.ok || reply.httpStatus ? "incomplete" : "unreachable");
+            this.refusalResult = reply.result ?? undefined;
+            this.refusalTable = reply.exit_status ?? undefined;
             return null;
         }
+        this.jobId = reply.job.job_id;
+        if (process.env.COMPRISM_JOB_LOG && this.jobId)
+            (0, jobs_1.notePointer)(this.jobId, process.env.COMPRISM_JOB_LOG);
         return { ticket: reply.job.ticket, jobId: reply.job.job_id };
     }
     /** Where the stream lives, derived from the workspace URL.
@@ -154,8 +187,13 @@ class TerminalSession {
     project() {
         return this.opts.root.split("/").filter(Boolean).pop() || this.opts.root;
     }
+    /** Connections lost during this job, so reconnecting gives up in the end. */
+    drops = 0;
     /** Why the one service would not start this job, in its own words. */
     refusal = null;
+    refusalReason;
+    refusalResult;
+    refusalTable;
     /** The workspace does not carry the permission question yet, so fall back. */
     olderWorkspace = false;
     /** Set while one is actually running, so two never overlap. */
@@ -237,7 +275,7 @@ class TerminalSession {
     async run(request) {
         const result = {
             outcome: "failed", steps: 0, actions: 0, totalUsd: 0, savedUsd: null,
-            receipt: "", models: [], text: "",
+            receipt: "", models: [], text: "", todos: [], lateNotes: [],
         };
         // ── the map of this project, brought up to date first ──────────────────
         //
@@ -286,6 +324,17 @@ class TerminalSession {
         // Permission first, from the one service. The stream opens only once the
         // job has been authorized there, so this socket carries no decision of its
         // own and the workspace credential is no longer the thing that opens it.
+        // Joined to VS Code when run in its terminal (VS Code manual 9.12): the
+        // window's selection goes with the request, and proposed changes open in
+        // its diff view. CompletionPrism's own connection; no other tool's.
+        if (!this.opts.headless) {
+            const { findEditor, selectionText } = await Promise.resolve().then(() => __importStar(require("../lib/ide")));
+            this.editor = findEditor(this.opts.root);
+            if (this.editor) {
+                this.out(ui.dim("  Connected to VS Code\n"));
+                request += selectionText(await this.editor.context());
+            }
+        }
         const granted = await this.pass(request);
         if (this.olderWorkspace) {
             // Straight on to the stream with the credential, silently. A person does
@@ -298,181 +347,632 @@ class TerminalSession {
             // service's own wording, because a plan that does not include coding and
             // an allowance that has been spent have different fixes.
             result.detail = this.refusal;
+            result.refusalReason = this.refusalReason;
+            if (this.refusalResult)
+                result.result = this.refusalResult;
+            if (this.refusalTable)
+                result.exitStatus = this.refusalTable;
+            this.out(ui.red(`  ${this.refusal}\n`));
             return result;
         }
+        // What this machine did for the job, by action id: received, then done
+        // with its result. Sent back after a dropped connection so the service can
+        // match it, which is how nothing is ever done twice (manual 8.9).
+        const journal = new Map();
+        let finished = false;
         await new Promise((resolve, reject) => {
-            const socket = new WebSocket(this.socketUrl(granted?.ticket));
-            this.socket = socket;
-            let ready = false;
-            socket.onopen = () => {
-                socket.send(JSON.stringify({
-                    type: "hello",
-                    client: this.opts.headless ? "cli-headless" : "cli",
-                    capabilities: this.executor.capabilities,
-                }));
-            };
-            socket.onmessage = async (event) => {
-                let frame;
-                try {
-                    frame = JSON.parse(String(event.data));
-                }
-                catch {
-                    return;
-                }
-                if (frame.type === "ready" && !ready) {
-                    ready = true;
-                    this.announce(frame);
+            const open = (ticket, first) => {
+                const socket = new WebSocket(this.socketUrl(ticket));
+                this.socket = socket;
+                let ready = false;
+                socket.onopen = () => {
                     socket.send(JSON.stringify({
-                        type: this.opts.resumeJobId ? "resume" : "run",
-                        job_id: this.opts.resumeJobId,
-                        continues_job: this.opts.continuesJob,
-                        request,
-                        workspace: this.opts.root.split("/").pop(),
-                        workspace_source: "local",
-                        workspace_root: this.opts.root,
+                        type: "hello",
                         client: this.opts.headless ? "cli-headless" : "cli",
-                        permission_mode: this.opts.permissionMode ?? "approve_writes",
-                        plan_only: Boolean(this.opts.planOnly),
-                        plan_approved: Boolean(this.opts.planApproved),
-                        model: this.opts.model,
-                        pin_model: Boolean(this.opts.pinModel),
-                        max_spend_usd: this.opts.maxSpendUsd,
-                        approved_commands: this.opts.approvedCommands ?? [],
-                        attachments: this.opts.attachmentIds ?? [],
-                        without_graph: Boolean(this.opts.withoutMap),
+                        // `ask_user` says a person is here to answer questions (manual
+                        // 4.3). Unattended, it is left out and the service tells the agent to
+                        // choose the safest option instead.
+                        // `reattach`: this tool reconnects after a drop, so the service
+                        // holds the job for it rather than ending it (manual 8.9).
+                        capabilities: this.opts.headless
+                            ? [...this.executor.capabilities, "reattach"]
+                            : [...this.executor.capabilities, "ask_user", "reattach"],
                     }));
-                    return;
-                }
-                if (frame.type === "tool_call") {
-                    const r = await this.executor.execute(String(frame.name), frame.input ?? {});
-                    // THE MAP IS CAUGHT UP BEFORE THE RESULT GOES BACK.
+                };
+                socket.onmessage = async (event) => {
+                    let frame;
+                    try {
+                        frame = JSON.parse(String(event.data));
+                    }
+                    catch {
+                        return;
+                    }
+                    if (frame.type === "ready" && !ready) {
+                        ready = true;
+                        if (!first) {
+                            // Back after a drop: what this machine did, for the service to match.
+                            socket.send(JSON.stringify({
+                                type: "reattach", job_id: this.jobId, journal: [...journal.values()],
+                            }));
+                            return;
+                        }
+                        this.announce(frame);
+                        socket.send(JSON.stringify({
+                            type: this.opts.resumeJobId ? "resume" : "run",
+                            job_id: this.opts.resumeJobId,
+                            continues_job: this.opts.continuesJob,
+                            conversation_id: this.opts.conversationId,
+                            request,
+                            workspace: this.opts.root.split("/").pop(),
+                            workspace_source: "local",
+                            workspace_root: this.opts.root,
+                            ...(this.opts.project ? (0, project_1.asWire)(this.opts.project) : {}),
+                            client: process.env.COMPRISM_BACKGROUND === "1" ? "cli-background"
+                                : this.opts.headless ? "cli-headless" : "cli",
+                            // Absent when not chosen: the service takes it from the settings.
+                            permission_mode: this.opts.permissionMode,
+                            plan_only: Boolean(this.opts.planOnly),
+                            plan_approved: Boolean(this.opts.planApproved),
+                            model: this.opts.model,
+                            pin_model: Boolean(this.opts.pinModel),
+                            max_spend_usd: this.opts.maxSpendUsd,
+                            ...(this.opts.maxSteps ? { max_steps: this.opts.maxSteps } : {}),
+                            ...(this.opts.maxMinutes ? { max_minutes: this.opts.maxMinutes } : {}),
+                            ...(this.opts.effort ? { effort: this.opts.effort } : {}),
+                            sandbox: Boolean(this.opts.sandbox),
+                            // Which sandbox this machine can offer, so the service can turn it
+                            // on from settings too, or refuse when it cannot (manual 4.12).
+                            sandbox_system: this.sandboxSystem(),
+                            command_timeout_s: this.opts.commandTimeoutS,
+                            ...(this.opts.issue ? { issue: this.opts.issue } : {}),
+                            ...(this.opts.team ? { team: this.opts.team } : {}),
+                            ...(this.opts.review ? { review: this.opts.review } : {}),
+                            approved_commands: this.opts.approvedCommands ?? [],
+                            attachments: this.opts.attachmentIds ?? [],
+                            left_out: this.opts.leftOut ?? [],
+                            without_graph: Boolean(this.opts.withoutMap),
+                            ...(this.opts.answerSchema ? { answer_schema: this.opts.answerSchema } : {}),
+                            ...(this.opts.settingsConfig ? { settings_config: this.opts.settingsConfig } : {}),
+                            ...(this.opts.noPersonal ? { no_personal: true } : {}),
+                            ...(this.opts.queuedJob ? { queued_job: this.opts.queuedJob } : {}),
+                            // Files already changed before the job, so they are never counted
+                            // as the agent's (manual 7.1).
+                            dirty_files: dirtyFiles(this.opts.root),
+                            // Which system runs the commands, so the agent writes for its shell
+                            // (manual 1.2): PowerShell on Windows.
+                            machine_os: process.platform,
+                        }));
+                        return;
+                    }
+                    if (frame.type === "tool_call") {
+                        const id = String(frame.id);
+                        const seen = journal.get(id);
+                        if (seen?.state === "done") {
+                            // Sent again after a drop, but already carried out here: the
+                            // result is sent, the action is not repeated.
+                            this.socket?.send(JSON.stringify({ type: "tool_result", id, ...seen.result }));
+                            return;
+                        }
+                        if (seen)
+                            return;
+                        const input = frame.input ?? {};
+                        const target = String(input.path ?? input.file_path ?? input.command ?? "");
+                        // An approved action is checked against what the person approved
+                        // immediately before it runs: the same action, the same arguments,
+                        // the same folder (manual 4.8). Anything changed does not run.
+                        const approved = this.approvedCalls.get(id);
+                        if (approved !== undefined && approved !== this.fingerprint(String(frame.name), input)) {
+                            const refused = {
+                                content: "This action changed after it was approved (a different command, "
+                                    + "argument or folder), so it did not run. Ask again for the new one.",
+                                is_error: true, summary: "changed after approval; not run",
+                            };
+                            this.socket?.send(JSON.stringify({ type: "tool_result", id, ...refused }));
+                            return;
+                        }
+                        journal.set(id, { id, name: String(frame.name), target, state: "running" });
+                        // The hooks the service named for this action (manual 10.9).
+                        const plan = frame.hooks && typeof frame.hooks === "object"
+                            ? frame.hooks : undefined;
+                        const r = await this.executor.execute(String(frame.name), input, plan);
+                        // THE MAP IS CAUGHT UP BEFORE THE RESULT GOES BACK.
+                        //
+                        // Before, not after, and that ordering is the whole of it. The server
+                        // runs a step's actions one after another, so an agent that writes a
+                        // file and then asks the map about it does both inside one step. A
+                        // refresh started after this result is sent has not finished when the
+                        // question runs, and the agent is told the thing it just wrote does
+                        // not exist. Measured on a real job before this line existed.
+                        if (!r.isError)
+                            await this.noteChanged(String(frame.name), frame.input);
+                        const answer = {
+                            content: r.content, is_error: Boolean(r.isError), summary: r.summary,
+                            facts: r.facts,
+                        };
+                        journal.set(id, { id, name: String(frame.name), target, state: "done", result: answer });
+                        // On whichever connection is open now. If none is, the journal holds
+                        // the result until the service asks for it.
+                        if (this.socket?.readyState === WebSocket.OPEN) {
+                            this.socket.send(JSON.stringify({ type: "tool_result", id, ...answer }));
+                        }
+                        return;
+                    }
+                    if (frame.type === "approval_ask") {
+                        const callId = String(frame.call_id ?? frame.action_id ?? "");
+                        this.asked.add(callId);
+                        const input = frame.input ?? {};
+                        // Answered in the browser while this terminal waits (web manual 6.15):
+                        // the service already has the answer, so none is sent from here.
+                        const remote = new Promise((resolve) => {
+                            this.answeredElsewhere.set(String(frame.id), () => resolve("remote"));
+                        });
+                        if (this.editor && ["write_file", "edit_file", "multi_edit"].includes(String(frame.name))) {
+                            void this.editor.diff(String(frame.name), input);
+                        }
+                        const local = this.ask(String(frame.name), input, String(frame.prompt ?? ""));
+                        const first = await Promise.race([local, remote]);
+                        this.answeredElsewhere.delete(String(frame.id));
+                        if (first === "remote")
+                            return;
+                        const answer = first;
+                        // The words go to the service, which decides what they mean (4.7 to
+                        // 4.9). `granted` is kept for a service that reads only yes or no.
+                        const word = (answer ?? "").trim().toLowerCase();
+                        const granted = word === "y" || word === "yes" || word === "a";
+                        if (granted)
+                            this.approvedCalls.set(callId, this.fingerprint(String(frame.name), input));
+                        this.socket?.send(JSON.stringify(answer === null
+                            ? { type: "approval_reply", id: frame.id, granted: false, cancelled: true } // american-english-allowed: the service's field name
+                            : { type: "approval_reply", id: frame.id, granted, answer,
+                                // Nobody at the keyboard: the service records it as an approval
+                                // nobody could give (manual 10.1, exit 4).
+                                ...(this.opts.headless ? { unattended: true } : {}) }));
+                        if (answer === null)
+                            this.cancel();
+                        return;
+                    }
+                    if (frame.type === "question") {
+                        const answer = await this.question(frame);
+                        this.socket?.send(JSON.stringify(answer === null
+                            ? { type: "question_reply", id: frame.id, cancelled: true } // american-english-allowed: the service's field name
+                            : { type: "question_reply", id: frame.id, answer }));
+                        if (answer === null)
+                            this.cancel();
+                        return;
+                    }
+                    if (frame.type === "event" && frame.kind === "approval_answered") {
+                        const done = this.answeredElsewhere.get(String(frame.id));
+                        if (done) {
+                            this.out(ui.dim(`\n  ${String(frame.line ?? "answered in the browser")}\n`));
+                            done();
+                        }
+                        return;
+                    }
+                    if (frame.type === "event" && frame.kind === "sandbox") {
+                        // The service turned the sandbox on for this job: every command from
+                        // here runs inside it, with its allowed addresses (manual 4.12).
+                        const { Sandbox } = await Promise.resolve().then(() => __importStar(require("../executor/sandbox")));
+                        const system = this.sandboxSystem();
+                        if (system) {
+                            const box = new Sandbox(system, this.opts.root, this.opts.project?.added ?? []);
+                            box.setAllowed(Array.isArray(frame.allow) ? frame.allow : []);
+                            await box.start();
+                            this.executor.sandbox = box;
+                        }
+                        this.out(ui.yellow(`  ${String(frame.line ?? "")}`) + "\n");
+                        return;
+                    }
+                    if (frame.type === "event") {
+                        // The published stream lines the service attached (manual 10.4).
+                        if (this.opts.onStream && Array.isArray(frame.stream) && frame.stream.length) {
+                            this.opts.onStream(frame.stream);
+                        }
+                        // The session's name, pushed by the service as soon as it exists, is
+                        // shown as the terminal window's title, where it never interrupts
+                        // the answer being printed.
+                        if (frame.kind === "session_named" && typeof frame.title === "string"
+                            && frame.title && process.stdout.isTTY) {
+                            process.stdout.write(`\x1b]0;${frame.title.replace(/[\x00-\x1f\x7f]/g, "")}\x07`);
+                        }
+                        if (frame.kind === "job_opened" && frame.job_id) {
+                            this.jobId = String(frame.job_id);
+                            // A background job notes where its log is, for `jobs attach` (5.14).
+                            if (process.env.COMPRISM_JOB_LOG)
+                                (0, jobs_1.notePointer)(this.jobId, process.env.COMPRISM_JOB_LOG);
+                        }
+                        // The service recorded this action, so it is settled either way.
+                        if (frame.kind === "action_finished" && frame.id) {
+                            const j = journal.get(String(frame.id));
+                            if (j)
+                                j.confirmed = true;
+                        }
+                        if (frame.kind === "reconciled") {
+                            // The service's own report of what was matched (manual 8.9).
+                            for (const line of frame.lines ?? []) {
+                                this.out(`  ${line}\n`);
+                            }
+                            this.out("\n");
+                            return;
+                        }
+                        this.narrate(frame);
+                        return;
+                    }
+                    if (frame.type === "done") {
+                        finished = true;
+                        if (this.opts.onStream && Array.isArray(frame.stream)) {
+                            this.opts.onStream(frame.stream);
+                        }
+                        result.outcome = String(frame.outcome ?? "failed");
+                        result.detail = frame.detail ?? null;
+                        result.jobId = frame.job_id;
+                        result.steps = Number(frame.steps ?? 0);
+                        result.actions = Number(frame.actions ?? 0);
+                        result.totalUsd = Number(frame.total_usd ?? 0);
+                        // The saving is the server's arithmetic, taken as it is sent. A
+                        // client that subtracted its own would disagree with the stored
+                        // receipt within a release, and the stored one is the record.
+                        {
+                            const economics = frame.economics;
+                            const saved = economics?.saved_usd;
+                            result.savedUsd = typeof saved === "number" ? saved : null;
+                            const rows = economics?.models;
+                            result.models = Array.isArray(rows) ? rows : [];
+                        }
+                        // The sentence the server wrote. Everything a reader is told about
+                        // cost and saving comes from here.
+                        result.receipt = String(frame.receipt ?? "");
+                        result.reusedPct = ui.reusePct(0, frame.cached_tokens, Math.max(0, Number(frame.context_tokens ?? 0) - Number(frame.cached_tokens ?? 0)));
+                        result.text = String(frame.text ?? "");
+                        result.why = this.lastWhy;
+                        result.todos = Array.isArray(frame.todos)
+                            ? frame.todos : [];
+                        if (frame.result && typeof frame.result === "object") {
+                            result.result = frame.result;
+                        }
+                        if (frame.exit_status && typeof frame.exit_status === "object") {
+                            result.exitStatus = frame.exit_status;
+                        }
+                        result.lateNotes = Array.isArray(frame.late_notes)
+                            ? frame.late_notes.map(String) : [];
+                        {
+                            const ending = frame.ending;
+                            if (ending && typeof ending === "object") {
+                                result.ending = {
+                                    line: typeof ending.line === "string" ? ending.line : null,
+                                    proof: Array.isArray(ending.proof) ? ending.proof.map(String) : [],
+                                    exit: typeof ending.exit === "number" ? ending.exit : null,
+                                    ...(typeof ending.reason === "string" ? { reason: ending.reason } : {}),
+                                };
+                                result.testsPassed = typeof ending.tests_passed === "boolean"
+                                    ? ending.tests_passed : undefined;
+                            }
+                            else {
+                                result.testsPassed = this.executor.lastTestsPassed;
+                            }
+                        }
+                        // What the agent itself changed goes back into the map before the
+                        // next job asks anything. Without this the second job of a session
+                        // works from a picture of the code as it was before the first job
+                        // edited it, which is the exact failure the freshness rule exists to
+                        // prevent, and the most likely one: the agent that made the map stale
+                        // is the agent about to trust it.
+                        void this.remap();
+                        socket.close();
+                        return;
+                    }
+                    if (frame.type === "error") {
+                        this.out(ui.red(`\n  ${String(frame.message ?? "Something went wrong.")}\n`));
+                    }
+                };
+                socket.onerror = () => {
+                    // Say what actually failed.
                     //
-                    // Before, not after, and that ordering is the whole of it. The server
-                    // runs a step's actions one after another, so an agent that writes a
-                    // file and then asks the map about it does both inside one step. A
-                    // refresh started after this result is sent has not finished when the
-                    // question runs, and the agent is told the thing it just wrote does
-                    // not exist. Measured on a real job before this line existed.
-                    if (!r.isError)
-                        await this.noteChanged(String(frame.name), frame.input);
-                    socket.send(JSON.stringify({
-                        type: "tool_result", id: frame.id,
-                        content: r.content, is_error: Boolean(r.isError), summary: r.summary,
-                    }));
-                    return;
-                }
-                if (frame.type === "approval_ask") {
-                    const granted = await this.ask(String(frame.name), frame.input ?? {});
-                    socket.send(JSON.stringify({ type: "approval_reply", id: frame.id, granted }));
-                    return;
-                }
-                if (frame.type === "event") {
-                    this.narrate(frame);
-                    return;
-                }
-                if (frame.type === "done") {
-                    result.outcome = String(frame.outcome ?? "failed");
-                    result.detail = frame.detail ?? null;
-                    result.jobId = frame.job_id;
-                    result.steps = Number(frame.steps ?? 0);
-                    result.actions = Number(frame.actions ?? 0);
-                    result.totalUsd = Number(frame.total_usd ?? 0);
-                    // The saving is the server's arithmetic, taken as it is sent. A
-                    // client that subtracted its own would disagree with the stored
-                    // receipt within a release, and the stored one is the record.
-                    {
-                        const economics = frame.economics;
-                        const saved = economics?.saved_usd;
-                        result.savedUsd = typeof saved === "number" ? saved : null;
-                        const rows = economics?.models;
-                        result.models = Array.isArray(rows) ? rows : [];
+                    // This used to read "Check you are signed in", on a screen that had
+                    // just printed the person's own email, their company and their plan,
+                    // all of which came from the very server it claimed it could not reach.
+                    // Being told to do the one thing you have visibly already done sends
+                    // somebody to sign in again, which fixes nothing and costs an evening.
+                    //
+                    // By the time this fires the credential has already been accepted: the
+                    // job was authorized and the server issued a pass for it. What failed
+                    // is the live connection that carries the work, and the wording names
+                    // that instead.
+                    if (!ready && first) {
+                        reject(new Error("The live connection to your workspace could not be opened. "
+                            + "You are signed in; the work stream is what failed."));
                     }
-                    // The sentence the server wrote. Everything a reader is told about
-                    // cost and saving comes from here.
-                    result.receipt = String(frame.receipt ?? "");
-                    result.reusedPct = ui.reusePct(0, frame.cached_tokens, Math.max(0, Number(frame.context_tokens ?? 0) - Number(frame.cached_tokens ?? 0)));
-                    result.text = String(frame.text ?? "");
-                    result.testsPassed = this.executor.lastTestsPassed;
-                    // What the agent itself changed goes back into the map before the
-                    // next job asks anything. Without this the second job of a session
-                    // works from a picture of the code as it was before the first job
-                    // edited it, which is the exact failure the freshness rule exists to
-                    // prevent, and the most likely one: the agent that made the map stale
-                    // is the agent about to trust it.
-                    void this.remap();
-                    socket.close();
-                    return;
-                }
-                if (frame.type === "error") {
-                    this.out(ui.red(`\n  ${String(frame.message ?? "Something went wrong.")}\n`));
-                }
-            };
-            socket.onerror = () => {
-                // Say what actually failed.
-                //
-                // This used to read "Check you are signed in", on a screen that had
-                // just printed the person's own email, their company and their plan,
-                // all of which came from the very server it claimed it could not reach.
-                // Being told to do the one thing you have visibly already done sends
-                // somebody to sign in again, which fixes nothing and costs an evening.
-                //
-                // By the time this fires the credential has already been accepted: the
-                // job was authorized and the server issued a pass for it. What failed
-                // is the live connection that carries the work, and the wording names
-                // that instead.
-                if (!ready) {
-                    reject(new Error("The live connection to your workspace could not be opened. "
-                        + "You are signed in; the work stream is what failed."));
-                }
-            };
-            socket.onclose = () => {
-                (0, executor_1.stopEverything)();
-                resolve();
+                };
+                socket.onclose = () => {
+                    if (socket !== this.socket)
+                        return;
+                    if (finished || this.canceled || !this.jobId) {
+                        // One job on its own is its session, so what it started ends with it
+                        // and is listed (manual 5.13). Inside a session they carry on.
+                        if (!this.opts.keepProcesses)
+                            this.out(ui.stoppedLines((0, executor_1.stopEverything)()));
+                        // The job's browser closes with it (manual 10.16).
+                        this.executor.close();
+                        // Tool servers on this machine end with the job (manual 9.10).
+                        this.executor.toolServers.stopAll();
+                        resolve();
+                        return;
+                    }
+                    // Dropped mid job. Nothing running here is stopped: an action already
+                    // under way finishes and its result waits in the journal.
+                    this.drops += 1;
+                    if (first || ready)
+                        this.out(ui.yellow("\n  The connection dropped. Reconnecting...\n"));
+                    void (this.drops > 6 ? Promise.resolve(null) : this.reconnect()).then((ticket) => {
+                        if (ticket !== null) {
+                            open(ticket, false);
+                            return;
+                        }
+                        // The service could not be reached again. What this machine knows,
+                        // said plainly; nothing is repeated (manual 8.9, exit 7).
+                        this.out("  The connection dropped and could not be restored.\n");
+                        for (const j of [...journal.values()].filter((e) => !e.confirmed)) {
+                            this.out(j.state === "done"
+                                ? `  done       ${j.name} ${j.target} (done here; the service has not confirmed it)\n`
+                                : `  unknown    ${j.name} ${j.target} (it may or may not have finished)\n`);
+                        }
+                        this.out("  Not repeated. Check the result, then tell the agent what happened.\n");
+                        result.outcome = "unknown";
+                        result.jobId = this.jobId;
+                        // Nobody can receive a result now, so a command still running here
+                        // is stopped rather than left to finish unseen.
+                        (0, executor_1.stopForeground)();
+                        (0, executor_1.stopEverything)();
+                        this.executor.toolServers.stopAll();
+                        resolve();
+                    });
+                };
             };
+            open(granted?.ticket, true);
         });
         this.report(result);
         return result;
     }
-    /** Stop the running job. Takes effect mid action, not at the end of the run. */
+    /**
+     * A pass to rejoin this job after a dropped connection, trying for about
+     * half a minute, inside the service's window (manual 8.9). Null when the
+     * service could not be reached again, or refused.
+     */
+    async reconnect() {
+        for (const wait of [1000, 2000, 3000, 5000, 8000, 10000]) {
+            await new Promise((r) => setTimeout(r, wait));
+            if (this.canceled)
+                return null;
+            const reply = await (0, gateway_1.ask)({ intent: "job_start", prompt: "", resumeJobId: this.jobId });
+            if (reply.served === false)
+                return undefined;
+            if (reply.ok && reply.job?.ticket)
+                return reply.job.ticket;
+            if (reply.ok && reply.granted === false)
+                return null;
+        }
+        return null;
+    }
+    /** Stop the running job. Takes effect mid action, not at the end of the run:
+     *  a command already running on this machine is stopped too (manual 6.7). */
     cancel() {
         if (this.canceled)
             return;
         this.canceled = true;
+        this.paused = false;
         this.out(ui.yellow("\n  stopping...\n"));
         this.socket?.send(JSON.stringify({ type: "cancel" }));
+        (0, executor_1.stopForeground)();
     }
-    /** Something typed while it works. Joins the conversation at the next step. */
+    /** Something typed while it works. Joins the conversation at the next step;
+     *  the service says so in the `note` event it sends back (6.8). */
     steer(text) {
         this.socket?.send(JSON.stringify({ type: "steer", text }));
-        this.out(ui.dim("  noted, it will pick that up on the next step\n"));
     }
+    /** Esc: finish the current action, then wait (manual 6.7). */
+    pause() {
+        if (this.canceled || this.paused)
+            return;
+        this.paused = true;
+        this.socket?.send(JSON.stringify({ type: "pause" }));
+    }
+    /** Carry on after Esc, with a correction or without one. */
+    carryOn(text) {
+        this.paused = false;
+        this.socket?.send(JSON.stringify({ type: "carry_on", text }));
+    }
+    /** This job's id, once the service has issued it (`transcript`, 6.9). */
+    jobId;
+    /** Set from Esc until the job carries on or stops. */
+    paused = false;
+    /** Helpers running now, from the service's own events (manual 5.25). */
+    helpers = new Map();
+    /** `stop h2` (5.25): the service stops that one helper. */
+    stopHelper(id) {
+        this.socket?.send(JSON.stringify({ type: "stop_helper", helper: id }));
+    }
+    /** `queue` and `queue clear` (6.8): the service answers with the notes. */
+    queue(clear) {
+        this.socket?.send(JSON.stringify({ type: clear ? "queue_clear" : "queue" }));
+    }
+    /** Ctrl+O: each action's full input and output, or the short line (6.9). */
+    full = false;
     announce(frame) {
         const allowance = frame.allowance;
-        const tools = frame.tools ?? [];
-        this.out(ui.dim(`  ${this.opts.root}  ${tools.length} actions available\n`));
+        // The project, company and mode are the service's first line, printed when
+        // it arrives (manual 2.2). The allowance follows it.
         if (allowance && allowance.included && !allowance.unlimited) {
-            this.out(ui.dim(`  coding allowance left this month: ${ui.money(Number(allowance.remaining_usd))}\n`));
+            this.allowanceLine = ui.dim(`  coding allowance left this month: ${ui.money(Number(allowance.remaining_usd))}\n`);
+        }
+    }
+    /** The allowance and plan notes, printed under the first line so it stays first. */
+    allowanceLine = "";
+    /** A running command's output on screen (manual 5.12): the first lines as
+     *  they arrive, then held, and at the end either the rest or the last lines
+     *  with a count of what was left out. How many is the service's number. */
+    screen = { limit: 0, edge: 0, shown: 0, held: [], partial: "" };
+    stream(chunk) {
+        const sc = this.screen;
+        if (!sc.limit) {
+            this.out(ui.gray(chunk));
+            return;
+        }
+        const parts = (sc.partial + chunk).split("\n");
+        sc.partial = parts.pop() ?? "";
+        for (const line of parts) {
+            if (sc.shown < sc.edge) {
+                this.out(ui.gray(`${line}\n`));
+                sc.shown += 1;
+            }
+            else
+                sc.held.push(line);
+        }
+    }
+    flushScreen() {
+        const sc = this.screen;
+        if (!sc.limit)
+            return;
+        if (sc.partial) {
+            sc.held.push(sc.partial);
+            sc.partial = "";
+        }
+        const room = sc.limit - sc.edge;
+        const show = sc.held.length <= room ? sc.held : sc.held.slice(-sc.edge);
+        const left = sc.held.length - show.length;
+        if (left > 0)
+            this.out(ui.dim(`  ... ${left.toLocaleString()} lines not shown ...\n`));
+        for (const line of show)
+            this.out(ui.gray(`${line}\n`));
+        this.screen = { limit: 0, edge: 0, shown: 0, held: [], partial: "" };
+    }
+    /** Changes already put in front of the person to approve, so they are not
+     *  shown twice. Every other change is shown as it is made (5.6 to 5.8). */
+    asked = new Set();
+    /** The sandbox this machine offers, worked out once (manual 4.12). */
+    sandboxChecked;
+    sandboxSystem() {
+        if (this.sandboxChecked === undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { availability } = require("../executor/sandbox");
+            this.sandboxChecked = availability().system;
         }
-        if (this.opts.planOnly)
-            this.out(ui.yellow("  plan only: nothing will be changed\n"));
-        if (this.opts.planApproved) {
-            this.out(ui.dim("  plan approved: file changes will not be asked about one at a time\n"));
+        return (this.sandboxChecked ?? null);
+    }
+    /** The full reason for the last step, as the service wrote it (4.16). */
+    lastWhy = [];
+    /** An unattended run refused an action that needed approval (Appendix B, 4). */
+    refusedUnattended = false;
+    /** Approved actions by call, and what exactly was approved (manual 4.8). */
+    approvedCalls = new Map();
+    /** Approvals waiting here that the browser may answer first (web manual 6.15). */
+    answeredElsewhere = new Map();
+    /** An action as approved: its name, its arguments and the real folder it
+     *  runs in, so a changed argument or a moved folder is caught. */
+    fingerprint(name, input) {
+        const pathMod = path;
+        const fsMod = fs;
+        let folder = this.opts.root;
+        if (typeof input.cwd === "string" && input.cwd)
+            folder = pathMod.resolve(this.opts.root, input.cwd);
+        try {
+            folder = fsMod.realpathSync(folder);
         }
+        catch { /* the folder is gone: still compared */ }
+        const sorted = (v) => (v && typeof v === "object" && !Array.isArray(v)
+            ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])]))
+            : v);
+        return JSON.stringify([name, sorted(input), folder]);
     }
     narrate(frame) {
         switch (frame.kind) {
+            // Helpers, in the service's words (manual 5.23, 5.25).
+            case "helper_started":
+                this.helpers.set(String(frame.id), {
+                    id: String(frame.id), question: String(frame.question ?? ""),
+                    agent: frame.agent ?? null,
+                });
+                this.out(`  ${ui.bold(String(frame.id))}  ${String(frame.line ?? "")}\n`);
+                break;
+            case "helper_finished":
+                this.helpers.delete(String(frame.id));
+                this.out(ui.dim(`    ${String(frame.line ?? "")}\n`));
+                if (frame.used_line)
+                    this.out(ui.dim(`    ${String(frame.used_line)}\n`));
+                break;
+            // A skill the job follows, in the service's words (manual 9.2, 9.5).
+            case "skill_used":
+            case "skill_file":
+                if (frame.line)
+                    this.out((frame.ok === false ? ui.red : ui.dim)(`  ${String(frame.line)}\n`));
+                break;
+            case "team":
+                this.out((frame.ok === false ? ui.red : ui.bold)(`  ${String(frame.line ?? "")}`) + "\n");
+                break;
+            case "helper_conflict":
+                this.out(ui.red(`  ${String(frame.line ?? "")}\n`));
+                if (frame.diff)
+                    this.out(ui.dim(String(frame.diff).split("\n").map((l) => `    ${l}`).join("\n") + "\n"));
+                break;
+            case "helper_stopping":
+                this.out(ui.dim(`  ${String(frame.line ?? "")}\n`));
+                break;
+            case "action_started":
+                this.flushScreen();
+                if (typeof frame.screen_lines === "number" && typeof frame.screen_edge === "number") {
+                    this.screen = { limit: frame.screen_lines, edge: frame.screen_edge, shown: 0, held: [], partial: "" };
+                }
+                break;
+            // The first line of the job, exactly as the service wrote it.
+            case "project_line":
+                this.out(`${ui.bold(String(frame.line ?? ""))}\n`);
+                if (this.allowanceLine)
+                    this.out(this.allowanceLine);
+                this.allowanceLine = "";
+                break;
+            // Planning and plan approval, in the service's words (manual 4.1, 4.2).
+            case "planning":
+                this.out(ui.yellow(`  ${String(frame.line ?? "")}`) + "\n");
+                break;
+            // A warning the service wants on screen, in its words (manual 4.13).
+            case "notice":
+                this.out(ui.yellow(`  ${String(frame.line ?? "")}`) + "\n");
+                break;
+            case "plan_approved":
+                this.out(ui.dim(`  ${String(frame.reason ?? "")}\n`));
+                break;
             case "step_finished": {
-                this.out(ui.step(Number(frame.index ?? 0), String(frame.model ?? ""), frame.usd, frame.latency_ms, ui.reusePct(frame.tokens_in, frame.cache_read_tokens, frame.cache_write_tokens)) + "\n");
+                this.out(ui.step(Number(frame.index ?? 0), String(frame.model ?? ""), frame.usd, frame.latency_ms, ui.reusePct(frame.tokens_in, frame.cache_read_tokens, frame.cache_write_tokens), String(frame.reason ?? "")) + "\n");
+                if (Array.isArray(frame.why_lines))
+                    this.lastWhy = frame.why_lines;
                 const said = String(frame.text ?? "").trim();
                 // Markdown is for a browser. A terminal shows the asterisks.
                 if (said) {
-                    this.out(`\n${ui.plain(said)}\n`);
+                    // The plan is titled so it reads as the plan (manual 4.1).
+                    const plain = ui.plain(said).replace(/^\s*plan\s*\n/i, "");
+                    this.out(frame.plan ? `  ${ui.bold("Plan")}\n${plain}\n` : `\n${ui.plain(said)}\n`);
                     this.lastSaid = said;
                 }
                 break;
             }
             case "action_finished":
+                this.flushScreen();
                 this.out(ui.action(String(frame.name ?? ""), this.targetOf(frame), frame.ok !== false, frame.latency_ms) + "\n");
+                // The change itself, as it is made, unless it was just shown for
+                // approval (manual 5.6 to 5.8). A change that changed nothing has
+                // nothing to show.
+                if (frame.ok !== false && !this.full && CHANGES.has(String(frame.name))
+                    && !this.asked.has(String(frame.id)) && !/  no change$/.test(String(frame.target ?? ""))) {
+                    this.out(ui.diff(String(frame.name), frame.input ?? {}, false));
+                }
+                // The full view: exactly what went in and what came back (6.9).
+                if (this.full) {
+                    this.out(ui.dim(`       input  ${JSON.stringify(frame.input ?? {})}\n`));
+                    const got = String(frame.output ?? frame.summary ?? "");
+                    this.out(ui.dim(`       output\n${got.split("\n").map((l) => `         ${l}`).join("\n")}\n`));
+                }
+                // A refused or failed action says why, with the path (manual 2.4).
+                if (frame.ok === false && frame.summary) {
+                    this.out(ui.dim(`       ${String(frame.summary).split("\n")[0]}\n`));
+                }
                 break;
             case "action_refused":
                 this.out(ui.red(`  refused  ${String(frame.name ?? "")}`)
@@ -503,13 +1003,34 @@ class TerminalSession {
             case "compacting":
                 this.out(ui.dim("  summarizing the conversation so far to keep it affordable\n"));
                 break;
+            // Notes, pausing and the queue, in the service's words (6.7, 6.8).
             case "steered":
+            case "note":
+            case "pausing":
+            case "paused":
+            case "resumed":
+            case "queue":
+            case "queue_clear":
+                if (frame.kind === "paused")
+                    this.paused = true;
+                if (frame.kind === "resumed")
+                    this.paused = false;
+                if (frame.line)
+                    this.out(ui.dim(`  ${String(frame.line)}\n`));
+                if (frame.kind === "queue" && Array.isArray(frame.notes)) {
+                    for (const n of frame.notes)
+                        this.out(ui.dim(`    ${String(n.text ?? "")}\n`));
+                }
                 break;
             default:
                 break;
         }
     }
     targetOf(frame) {
+        // The service's words when it sent them (manual 5.2 to 5.4); an older
+        // service sends none and the path or pattern is shown as before.
+        if (typeof frame.target === "string")
+            return frame.target;
         const input = frame.input ?? {};
         return String(input.path ?? input.pattern ?? input.command ?? input.to ?? "");
     }
@@ -524,7 +1045,7 @@ class TerminalSession {
      *  nobody ever saw, which is the opposite of what a permission mode is for:
      *  a script that needs to change files says so by choosing a mode that allows
      *  it, up front. */
-    async ask(name, input) {
+    async ask(name, input, prompt = "") {
         if (this.opts.headless) {
             // Name what was refused. A refusal that does not say WHICH command it
             // turned down cannot be acted on: the operator's only remedy is to
@@ -535,22 +1056,73 @@ class TerminalSession {
             this.out(ui.yellow(`  ${name} needs approval and nobody is watching, so it was refused. `)
                 + (what ? ui.dim(`Refused: ${what}\n  `) : "")
                 + ui.dim("Re-run with --allow \"<that exact command>\", or choose a permission mode that allows it.\n"));
-            return false;
+            this.refusedUnattended = true;
+            return "n";
         }
         this.out(ui.diff(name, input));
-        if (this.opts.confirm) {
-            const granted = await this.opts.confirm(`${ui.bold("Apply this?")} ${ui.dim("[y/N]")}`);
-            this.out(granted ? ui.green("  applied\n") : ui.dim("  skipped\n"));
-            return granted;
+        // A command shows the folder it will run in (manual 4.7).
+        if (typeof input.command === "string") {
+            const pathMod = path;
+            const folder = typeof input.cwd === "string" && input.cwd
+                ? pathMod.resolve(this.opts.root, input.cwd) : this.opts.root;
+            const home = process.env.HOME || process.env.USERPROFILE || "";
+            this.out(ui.dim(`  in ${home && folder.startsWith(home) ? `~${folder.slice(home.length)}` : folder}\n`));
+        }
+        const question = prompt ? ui.bold(prompt) : `${ui.bold("Apply this?")} ${ui.dim("[y/N]")}`;
+        let answer;
+        if (this.opts.prompt) {
+            answer = await this.opts.prompt(question);
         }
+        else if (this.opts.confirm) {
+            answer = (await this.opts.confirm(question)) ? "y" : "n";
+        }
+        else {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                answer = await new Promise((resolve) => {
+                    rl.on("SIGINT", () => { this.out("\n"); resolve(null); });
+                    rl.question(`  ${question} `, (a) => resolve(a));
+                });
+            }
+            finally {
+                rl.close();
+            }
+        }
+        const word = (answer ?? "").trim().toLowerCase();
+        if (answer === null)
+            return null;
+        if (word === "y" || word === "yes")
+            this.out(ui.green("  applied\n"));
+        else if (word === "a")
+            this.out(ui.green("  applied, and yes to exactly this for the rest of the session\n"));
+        else if (word === "" || word === "n" || word === "no")
+            this.out(ui.dim("  skipped\n"));
+        else
+            this.out(ui.dim("  not applied; your words go to the agent\n"));
+        return answer;
+    }
+    /** The plan question or one of the agent's questions (manual 4.2, 4.3).
+     *  Returns what the person typed, or null for Ctrl+C. The meaning of the
+     *  answer (y, n, a number, words) is decided by the service. */
+    async question(frame) {
+        const kind = String(frame.kind ?? "question");
+        const options = Array.isArray(frame.options) ? frame.options : [];
+        // The trust question lists the project's allow rules as they are (4.10).
+        if (kind === "trust")
+            this.out(`\n  ${String(frame.question ?? "").split("\n").join("\n  ")}\n`);
+        else if (kind !== "plan")
+            this.out(ui.question(String(frame.question ?? ""), options));
+        const label = String(frame.prompt ?? "");
+        const shown = kind === "plan" ? `${ui.bold(label)}` : label;
+        if (this.opts.prompt)
+            return this.opts.prompt(shown);
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         try {
-            const answer = await new Promise((resolve) => {
-                rl.question(`  ${ui.bold("Apply this?")} ${ui.dim("[y/N]")} `, resolve);
+            return await new Promise((resolve) => {
+                // Ctrl+C at a question stops the job, as it does anywhere else.
+                rl.on("SIGINT", () => { this.out("\n"); resolve(null); });
+                rl.question(`  ${shown} `, (a) => resolve(a));
             });
-            const granted = /^y(es)?$/i.test(answer.trim());
-            this.out(granted ? ui.green("  applied\n") : ui.dim("  skipped\n"));
-            return granted;
         }
         finally {
             rl.close();
@@ -561,8 +1133,22 @@ class TerminalSession {
         // IS the step's text, and printing it again read as a stutter.
         if (r.text && r.text.trim() !== this.lastSaid)
             this.out(`\n${ui.plain(r.text)}\n`);
-        this.out(ui.outcome(r.outcome, r.detail));
-        this.out(ui.receipt(r.receipt, r.models, r.testsPassed));
+        // An item the agent could not finish stays on screen, unticked (4.4).
+        if (r.todos.some((t) => t.status !== "completed"))
+            this.out(ui.todos(r.todos));
+        if (r.ending?.line) {
+            // The service's own words, decided from what ran (manual 5.15).
+            this.out(ui.ending(r.ending.line, r.detail));
+            for (const line of r.ending.proof)
+                this.out(ui.dim(`  ${line}\n`));
+            this.out(ui.receipt(r.receipt, r.models));
+        }
+        else {
+            this.out(ui.outcome(r.outcome, r.detail));
+            for (const line of r.ending?.proof ?? [])
+                this.out(ui.dim(`  ${line}\n`));
+            this.out(ui.receipt(r.receipt, r.models, r.ending ? undefined : r.testsPassed));
+        }
         if (r.jobId) {
             // The job's own reference, so a person can quote it. The link to the
             // account sits in the receipt above, where the server put it.