@illuminis/comprism 0.1.0

package/out/agent/session.js

@@ -0,0 +1,573 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerminalSession = void 0;
+/**
+ * A coding job, run from a terminal.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items A6 (interactive), A7 (scriptable), A10 and H6 (one job, any client),
+ * C14 (resume) and D40 (a terminal the human can watch).
+ *
+ * ## What this file is, and what it is not
+ *
+ * It is the wire between a terminal and the loop, plus the rendering. **The loop
+ * is not here.** Which model takes each step, what an action costs, whether an
+ * action is allowed and what gets written down are all decided on the server,
+ * exactly as they are for the browser. This connects, performs what it is asked,
+ * prints what happened, and asks the person when the server says to.
+ *
+ * That is deliberate and it is the whole reason a terminal agent was cheap to
+ * build at all: the second client reuses everything except the drawing.
+ *
+ * ## Two ways to run
+ *
+ * Interactive, with a person at the keyboard who can approve, interrupt and
+ * steer. And headless, driven by a script with nobody present, where an
+ * approval has no one to ask and the permission mode decides everything up
+ * front. Both are the same session; the difference is who answers.
+ */
+const gateway_1 = require("../lib/gateway");
+const readline = __importStar(require("readline"));
+const executor_1 = require("../executor");
+const ui = __importStar(require("./render"));
+class TerminalSession {
+    socket = null;
+    executor;
+    opts;
+    out;
+    lastTodos = "";
+    /** The last thing it said on screen, so the ending does not say it twice.
+     *  Every step prints what the model said, and the closing frame carries the
+     *  final text again, so the answer to a one step job appeared twice in a row
+     *  with nothing between the copies. */
+    lastSaid = "";
+    canceled = false;
+    constructor(opts, write = (s) => process.stdout.write(s)) {
+        this.opts = opts;
+        this.out = write;
+        this.executor = new executor_1.NativeExecutor({
+            root: opts.root,
+            // 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));
+            },
+        });
+    }
+    /** Where the socket lives, derived from the workspace URL.
+     *
+     *  Derived rather than configured: a second setting for the socket address is
+     *  a second thing that can point at the wrong server, and the failure would be
+     *  a job running against somebody else's workspace. */
+    /**
+     * A pass for this job's stream, from the one service.
+     *
+     * The job is authorized THERE, where everything else in the product is
+     * authorized, and this returns only permission to open the stream. Null when
+     * the service refused or could not be reached, and the caller then reports
+     * the service's own words rather than guessing at them.
+     */
+    async pass(request) {
+        const reply = await (0, gateway_1.ask)({
+            intent: "job_start",
+            prompt: request,
+            ...(this.opts.resumeJobId ? { resumeJobId: this.opts.resumeJobId } : {}),
+        });
+        // An OLDER WORKSPACE that has never heard of this question is not a
+        // refusal. Its own credential path is alive and works, so the job falls
+        // back to it rather than stopping. This is the one place in the design
+        // where a second path is permitted, it is temporary, and it is deleted in
+        // the release after every workspace is known to be current.
+        if (reply.served === false) {
+            // Not a refusal. The workspace's own credential path is alive and works,
+            // so the job proceeds on it rather than stopping. This is the one place
+            // in the design where a second path is permitted, it is temporary, and it
+            // goes in the release after every workspace is known to be current.
+            this.olderWorkspace = true;
+            return null;
+        }
+        if (!reply.ok || !reply.job?.ticket) {
+            // A real refusal, in the service's own words: a plan that does not
+            // 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";
+            return null;
+        }
+        return { ticket: reply.job.ticket, jobId: reply.job.job_id };
+    }
+    /** Where the stream lives, derived from the workspace URL.
+     *
+     *  Derived rather than configured: a second setting for the stream address is
+     *  a second thing that can point at the wrong server, and the failure would be
+     *  a job running against somebody else's workspace.
+     *
+     *  The credential still travels because the pass is redeemed against the
+     *  tenant it was issued in, and the pass is what actually authorizes the job.
+     *  Without a pass this falls back to the old behavior, which is what a
+     *  workspace running an older build still understands. */
+    socketUrl(ticket) {
+        const url = new URL(this.opts.baseUrl);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        url.pathname = "/api/v1/agent/ws";
+        url.search = `?token=${encodeURIComponent(this.opts.credential)}`
+            + (ticket ? `&ticket=${encodeURIComponent(ticket)}` : "");
+        return url.toString();
+    }
+    /** The name the map is held under: the folder's own, which is exactly what
+     *  the run frame already sends as the workspace. One expression, so the map
+     *  and the job record can never be about two different projects. */
+    project() {
+        return this.opts.root.split("/").filter(Boolean).pop() || this.opts.root;
+    }
+    /** Why the one service would not start this job, in its own words. */
+    refusal = null;
+    /** The workspace does not carry the permission question yet, so fall back. */
+    olderWorkspace = false;
+    /** Set while one is actually running, so two never overlap. */
+    remapping = false;
+    /**
+     * The agent just changed something on disk. Bring the map back in step.
+     *
+     * Only for actions that can change a file. A read or a search leaves the
+     * project exactly as it was, and re-reading it would be a round trip bought
+     * for nothing on the most common actions there are.
+     *
+     * The refresh itself is the ordinary one: it compares the files against what
+     * the service holds and sends back only what moved, which after one edit is
+     * one file. Debounced by a short wait, because an agent that writes four
+     * files in one step should pay for one update, not four.
+     */
+    async noteChanged(tool, input) {
+        if (this.opts.withoutMap)
+            return;
+        // A named file changed, so exactly that file is put back into the map and
+        // the result waits for it. One round trip, and the agent can ask about what
+        // it just wrote in the very same step.
+        const NAMES_ITS_FILE = new Set([
+            "write_file", "edit_file", "multi_edit", "delete_file", "move_file",
+            "write_bytes", "create_dir",
+        ]);
+        if (NAMES_ITS_FILE.has(tool)) {
+            const a = (input ?? {});
+            const paths = [a.path, a.file_path, a.from, a.to, a.destination]
+                .filter((p) => typeof p === "string" && p.length > 0);
+            const edits = Array.isArray(a.edits) ? a.edits : [];
+            for (const e of edits) {
+                const one = e?.path;
+                if (typeof one === "string")
+                    paths.push(one);
+            }
+            if (paths.length) {
+                const { pushFile } = await Promise.resolve().then(() => __importStar(require("../graph/sync")));
+                await pushFile(this.opts.root, this.project(), [...new Set(paths)]);
+                return;
+            }
+        }
+        // A command, a patch or an install can change anything: a formatter, a code
+        // generator, a package manager writing a lockfile. Nothing here knows what
+        // it touched, so the whole project is re-checked rather than one file. That
+        // is the comparison that costs milliseconds, and only the files that
+        // actually moved are read.
+        const CHANGES_SOMETHING = new Set([
+            "apply_patch", "run_command", "run_background", "install_dependency",
+            "run_tests", "git_branch", "git_commit",
+        ]);
+        if (CHANGES_SOMETHING.has(tool))
+            await this.remap();
+    }
+    /**
+     * Put the files this job changed back into the map.
+     *
+     * Runs after the job, without being waited on: the person has their answer
+     * and a re-read of three files must not hold up their prompt. A failure here
+     * costs nothing, because the next job checks the files anyway and would read
+     * them then.
+     */
+    async remap() {
+        if (this.opts.withoutMap || this.remapping)
+            return;
+        this.remapping = true;
+        try {
+            const { refresh } = await Promise.resolve().then(() => __importStar(require("../graph/sync")));
+            await refresh(this.opts.root, this.project());
+        }
+        catch {
+            /* the next check picks the files up anyway */
+        }
+        finally {
+            this.remapping = false;
+        }
+    }
+    /** Run one request to its end. Resolves with how it went. */
+    async run(request) {
+        const result = {
+            outcome: "failed", steps: 0, actions: 0, totalUsd: 0, savedUsd: null,
+            receipt: "", models: [], text: "",
+        };
+        // ── the map of this project, brought up to date first ──────────────────
+        //
+        // Before the job, not after it, because the whole saving is the agent
+        // knowing the shape of the codebase instead of reading forty files to work
+        // it out. A map read afterwards would have cost the money it exists to
+        // save.
+        //
+        // Only what MOVED is read. An unchanged project costs about ten
+        // milliseconds here, which is the check itself; a few changed files cost a
+        // fraction of a second. Nothing about this can stop the job: a service that
+        // cannot be reached, a company that has switched the map off, and a machine
+        // with no parser all end the same way, with the agent reading files the
+        // way every other coding tool does all of the time.
+        if (!this.opts.withoutMap) {
+            try {
+                const { refresh, status } = await Promise.resolve().then(() => __importStar(require("../graph/sync")));
+                const now = await status(this.opts.root, this.project());
+                if (now.enabled && !now.hasMap) {
+                    // FIRST TIME IN THIS PROJECT: read it, but do not make anybody wait.
+                    //
+                    // A first read of a large project is minutes, because every file has
+                    // to be parsed and its structure sent. Waiting for that before the
+                    // job starts would make somebody's first experience of the product a
+                    // long pause for a feature they did not ask for, to save money on a
+                    // job they have not started. So the job runs now, reading files the
+                    // ordinary way, and the second job in this project has the map.
+                    this.out(ui.dim("  reading a map of this project in the background;"
+                        + " your next job here will use it\n"));
+                    void refresh(this.opts.root, this.project()).catch(() => undefined);
+                }
+                else if (now.enabled && !now.fresh) {
+                    // A map already exists and some files moved. Only those are read,
+                    // which is a fraction of a second, and it is worth waiting for:
+                    // answering this job from a map that is behind the files is the one
+                    // failure this whole feature has to avoid.
+                    const done = await refresh(this.opts.root, this.project());
+                    if (done.filesRead)
+                        this.out(ui.dim(`  code map: ${done.message}\n`));
+                }
+            }
+            catch {
+                /* the map is an optimization; never a reason a job does not start */
+            }
+        }
+        // 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.
+        const granted = await this.pass(request);
+        if (this.olderWorkspace) {
+            // Straight on to the stream with the credential, silently. A person does
+            // not need to be told their workspace is a release behind when the thing
+            // they asked for is about to happen anyway.
+            this.refusal = null;
+        }
+        else if (!granted && this.refusal) {
+            // A refusal is an ANSWER, not a failure to connect. It carries the
+            // 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;
+            return result;
+        }
+        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);
+                    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,
+                        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),
+                    }));
+                    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.
+                    //
+                    // 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 : [];
+                    }
+                    // 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();
+            };
+        });
+        this.report(result);
+        return result;
+    }
+    /** Stop the running job. Takes effect mid action, not at the end of the run. */
+    cancel() {
+        if (this.canceled)
+            return;
+        this.canceled = true;
+        this.out(ui.yellow("\n  stopping...\n"));
+        this.socket?.send(JSON.stringify({ type: "cancel" }));
+    }
+    /** Something typed while it works. Joins the conversation at the next step. */
+    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"));
+    }
+    announce(frame) {
+        const allowance = frame.allowance;
+        const tools = frame.tools ?? [];
+        this.out(ui.dim(`  ${this.opts.root}  ${tools.length} actions available\n`));
+        if (allowance && allowance.included && !allowance.unlimited) {
+            this.out(ui.dim(`  coding allowance left this month: ${ui.money(Number(allowance.remaining_usd))}\n`));
+        }
+        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"));
+        }
+    }
+    narrate(frame) {
+        switch (frame.kind) {
+            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");
+                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`);
+                    this.lastSaid = said;
+                }
+                break;
+            }
+            case "action_finished":
+                this.out(ui.action(String(frame.name ?? ""), this.targetOf(frame), frame.ok !== false, frame.latency_ms) + "\n");
+                break;
+            case "action_refused":
+                this.out(ui.red(`  refused  ${String(frame.name ?? "")}`)
+                    + ui.dim(`  ${String(frame.reason ?? "")}\n`));
+                break;
+            case "todos": {
+                const rendered = ui.todos(frame.todos ?? []);
+                // Only when it has actually changed. A plan reprinted identically after
+                // every step is noise that buries the run.
+                if (rendered !== this.lastTodos) {
+                    this.out(rendered);
+                    this.lastTodos = rendered;
+                }
+                break;
+            }
+            // A file the agent produced, and where it went. Said here rather than
+            // left to the model's sentence: a terminal has no timeline to look at, and
+            // "ready to download" in a terminal is the same as producing nothing.
+            case "document_made": {
+                const saved = frame.saved_to ? String(frame.saved_to) : "";
+                const bytes = Number(frame.bytes ?? 0).toLocaleString();
+                this.out(saved
+                    ? ui.green(`  saved  ${saved}`) + ui.dim(`  ${bytes} bytes\n`)
+                    : ui.yellow(`  made  ${String(frame.filename ?? "a file")}`)
+                        + ui.dim(`  ${bytes} bytes, not saved here\n`));
+                break;
+            }
+            case "compacting":
+                this.out(ui.dim("  summarizing the conversation so far to keep it affordable\n"));
+                break;
+            case "steered":
+                break;
+            default:
+                break;
+        }
+    }
+    targetOf(frame) {
+        const input = frame.input ?? {};
+        return String(input.path ?? input.pattern ?? input.command ?? input.to ?? "");
+    }
+    /** Put a change in front of the person and wait.
+     *
+     *  Three cases, in order. A caller that owns the keyboard lent us one, so the
+     *  question goes there. Nobody lent one and somebody is watching, so we open
+     *  our own reader. Nobody is watching, so it is refused.
+     *
+     *  In headless mode there is nobody to ask, so it is refused rather than
+     *  assumed. Treating silence as consent would let a script approve changes
+     *  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) {
+        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
+            // pre-approve it with --allow, and they cannot approve a string they were
+            // never shown. Found while running the same job unattended five ways and
+            // watching every arm stall on a command none of them would name.
+            const what = this.targetOf({ input });
+            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.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;
+        }
+        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);
+            });
+            const granted = /^y(es)?$/i.test(answer.trim());
+            this.out(granted ? ui.green("  applied\n") : ui.dim("  skipped\n"));
+            return granted;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    report(r) {
+        // Only if it has not already been said. On a one step job the closing text
+        // 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));
+        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.
+            this.out(ui.dim(`  job ${r.jobId}\n`));
+        }
+    }
+}
+exports.TerminalSession = TerminalSession;

package/out/commands/ask.d.ts

@@ -0,0 +1 @@
+export declare function cmdAsk(args: string[]): Promise<void>;