@hellix-ai/cubes 0.1.4 → 0.2.0

package/dist/termstatus.js

@@ -0,0 +1,276 @@
+// Telling YOUR terminal what the attached session is doing: the tab title, a "needs you" signal, and
+// Warp's per-tab agent status.
+//
+// Running Claude Code locally, a terminal tab shows its title and whether it is working or waiting.
+// Attached through `cubes`, the program on the other end is tmux in a pod, which says nothing about
+// either. So the CLI says it, from the server's own activity signal (the hooks every session reports:
+// working / ready / waiting-with-a-reason), in the three dialects terminals understand:
+//
+//   • OSC 0 TITLE - every terminal. `<glyph> <session title>`, the convention Claude Code itself uses:
+//     ● while working, ✳ when idle, ✋ when it is waiting for you. Static: an animated glyph churns the tab.
+//   • BEL + OSC 9 - the generic "this tab wants you": a bell marks the tab / bounces the dock almost
+//     everywhere, and OSC 9 raises a desktop notification in iTerm2, Ghostty, WezTerm, kitty, Warp.
+//   • OSC 777 `warp://cli-agent` - Warp's structured agent protocol, the same events and payload as
+//     warpdotdev/claude-code-warp sends from Claude Code's hooks (the remote program IS Claude Code).
+//     Gated exactly as that plugin gates it, and used INSTEAD of BEL+OSC 9 there, not as well.
+//
+// ⚠ NOTHING HERE MAY BE WRITTEN MID-SEQUENCE. The session's output arrives in arbitrary chunks, so a
+// chunk can end halfway through an escape sequence or a UTF-8 character; a title written into that gap
+// would corrupt both. `StreamFilter` tracks where the stream is, and the caller only writes ours when
+// the stream is between sequences.
+export const WARP_PLUGIN_COMPAT = "2.3.0"; // the claude-code-warp release whose event set this mirrors
+const WORKING = "●";
+const IDLE = "✳";
+const WAITING = "✋";
+/** Title push / pop (xterm window ops): our title is set on top of yours and yours comes back after. */
+export const TITLE_PUSH = "\x1b[22;0t";
+export const TITLE_POP = "\x1b]0;\x07\x1b[23;0t"; // clear first, for terminals with no title stack
+/** Nothing the server hands us may reach the terminal as a control character. */
+export function clean(s, max = 120) {
+    const t = s.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
+    return t.length > max ? t.slice(0, max - 1) + "…" : t;
+}
+/**
+ * Passes the session's output through, minus the two things that would fight us for the title -
+ * OSC 0/1/2 (set title) and CSI 22/23 t (title push/pop, which the session's tmux sends on attach and
+ * exit and which would unbalance our own push/pop) - and knows at every chunk boundary whether it is
+ * safe to write a sequence of our own.
+ */
+export class StreamFilter {
+    st = "ground";
+    seq = []; // the CSI or OSC-prefix being decided
+    utf8Left = 0;
+    oscEsc = false; // saw ESC inside a string, waiting for '\'
+    get safe() {
+        return this.st === "ground" && this.utf8Left === 0;
+    }
+    feed(chunk) {
+        const out = [];
+        for (const b of chunk) {
+            switch (this.st) {
+                case "ground":
+                    if (b === 0x1b) {
+                        this.st = "esc";
+                        this.seq = [b];
+                        break;
+                    }
+                    if (this.utf8Left > 0 && (b & 0xc0) === 0x80)
+                        this.utf8Left--;
+                    else if ((b & 0xe0) === 0xc0)
+                        this.utf8Left = 1;
+                    else if ((b & 0xf0) === 0xe0)
+                        this.utf8Left = 2;
+                    else if ((b & 0xf8) === 0xf0)
+                        this.utf8Left = 3;
+                    else
+                        this.utf8Left = 0;
+                    out.push(b);
+                    break;
+                case "esc":
+                    if (b === 0x1b) {
+                        out.push(0x1b);
+                        this.seq = [b];
+                        break;
+                    } // a bare ESC, then a new sequence
+                    this.seq.push(b);
+                    if (b === 0x5b) {
+                        this.st = "csi";
+                        break;
+                    } // [
+                    if (b === 0x5d) {
+                        this.st = "osc";
+                        break;
+                    } // ]
+                    if (b === 0x50 || b === 0x58 || b === 0x5e || b === 0x5f) { // P X ^ _ : DCS SOS PM APC
+                        out.push(...this.seq);
+                        this.st = "str";
+                        this.oscEsc = false;
+                        break;
+                    }
+                    if (b >= 0x20 && b <= 0x2f)
+                        break; // intermediate bytes, the final follows
+                    out.push(...this.seq);
+                    this.st = "ground";
+                    break;
+                case "csi":
+                    this.seq.push(b);
+                    if (b >= 0x40 && b <= 0x7e) {
+                        const body = String.fromCharCode(...this.seq.slice(2, -1));
+                        const drop = b === 0x74 && /^2[23](;|$)/.test(body); // CSI 22/23 ... t
+                        if (!drop)
+                            out.push(...this.seq);
+                        this.st = "ground";
+                    }
+                    else if (this.seq.length > 64) { // not a CSI anyone sends; stop holding it
+                        out.push(...this.seq);
+                        this.st = "ground";
+                    }
+                    break;
+                case "osc": {
+                    // Hold only until the number is known: 0/1/2 is a title and is dropped, anything else
+                    // (hyperlinks, clipboard, notifications) streams through untouched.
+                    const ends = b === 0x07 || b === 0x1b;
+                    if (b === 0x3b || ends || this.seq.length > 8) {
+                        const num = String.fromCharCode(...this.seq.slice(2));
+                        const title = /^[012]$/.test(num);
+                        if (!title)
+                            out.push(...this.seq);
+                        this.seq = [];
+                        if (ends) {
+                            if (b === 0x07) {
+                                if (!title)
+                                    out.push(b);
+                                this.st = "ground";
+                            }
+                            else {
+                                if (!title)
+                                    out.push(b);
+                                this.st = title ? "oscDrop" : "str";
+                                this.oscEsc = true;
+                            }
+                        }
+                        else {
+                            if (!title)
+                                out.push(b);
+                            this.st = title ? "oscDrop" : "str";
+                            this.oscEsc = false;
+                        }
+                    }
+                    else {
+                        this.seq.push(b);
+                    }
+                    break;
+                }
+                case "oscDrop":
+                case "str": {
+                    const keep = this.st === "str";
+                    if (keep)
+                        out.push(b);
+                    if (this.oscEsc && b === 0x5c) {
+                        this.st = "ground";
+                        this.oscEsc = false;
+                        break;
+                    } // ST = ESC \
+                    this.oscEsc = b === 0x1b;
+                    if (b === 0x07 && !this.oscEsc)
+                        this.st = "ground"; // BEL ends an OSC (and is harmless in DCS)
+                    break;
+                }
+            }
+        }
+        return Uint8Array.from(out);
+    }
+}
+function stateOf(r) {
+    if (r.status !== "running")
+        return "idle";
+    if (r.activity_status === "working")
+        return "working";
+    if (r.activity_status === "waiting")
+        return "waiting";
+    return "idle";
+}
+/** Warp's structured notifications, exactly as warpdotdev/claude-code-warp decides it may use them. */
+export function warpProtocol(env) {
+    const v = Number.parseInt(env.WARP_CLI_AGENT_PROTOCOL_VERSION ?? "", 10);
+    if (!Number.isFinite(v) || v < 1)
+        return null;
+    const client = env.WARP_CLIENT_VERSION ?? "";
+    if (!client)
+        return null;
+    // Builds that advertised the protocol before they could render it.
+    const broken = client.includes("stable") ? "v0.2026.03.25.08.24.stable_05"
+        : client.includes("preview") ? "v0.2026.03.25.08.24.preview_05" : "";
+    if (broken && !(client > broken))
+        return null;
+    return Math.min(1, v);
+}
+/**
+ * Turns successive reads of the session row into terminal sequences. `emit` must deliver them only at
+ * a safe point in the stream (see StreamFilter); this class only decides WHAT to say and WHEN.
+ */
+export class TermStatus {
+    emit;
+    state = null;
+    shown = "";
+    row;
+    warp;
+    inTmux;
+    constructor(row, emit, env = process.env) {
+        this.emit = emit;
+        this.row = row;
+        this.warp = warpProtocol(env);
+        this.inTmux = !!env.TMUX;
+    }
+    title() {
+        const glyph = this.state === "working" ? WORKING : this.state === "waiting" ? WAITING : IDLE;
+        return `${glyph} ${clean(this.row.title || "Cubes session", 80)}`;
+    }
+    /** Only when it changed: the activity is re-read every few seconds, and most reads change nothing. */
+    setTitle() {
+        const t = this.title();
+        if (t === this.shown)
+            return;
+        this.shown = t;
+        this.emit(`\x1b]0;${t}\x07`);
+    }
+    /**
+     * Notifications (OSC 9, OSC 777) are for the terminal the PERSON sees. Inside tmux - the split view
+     * runs everything in one - tmux would swallow them, so they travel as tmux's DCS passthrough (every
+     * ESC doubled), which reaches the outer terminal when `allow-passthrough` is on (the split view turns
+     * it on). The bell needs none of this: tmux forwards a bell by itself.
+     */
+    outward(seq) {
+        return this.inTmux ? `\x1bPtmux;${seq.replace(/\x1b/g, "\x1b\x1b")}\x1b\\` : seq;
+    }
+    warpEvent(event, extra = {}) {
+        if (this.warp === null)
+            return;
+        const body = JSON.stringify({
+            v: this.warp, agent: "claude", event, session_id: this.row.id, cwd: "",
+            project: clean(this.row.title || "cubes", 60), ...extra,
+        });
+        this.emit(this.outward(`\x1b]777;notify;warp://cli-agent;${body}\x07`));
+    }
+    /** Feed the latest row. The first call only establishes the state - nobody needs to be told that a
+     *  session they are attaching to right now is waiting for them. */
+    update(row) {
+        this.row = row;
+        const next = stateOf(row);
+        const first = this.state === null;
+        const prev = this.state;
+        // Only the step INTO waiting. Claude Code reports one wait in several hook events (measured: the
+        // question itself, then "Claude needs your permission" for the same question a moment later), and
+        // each moves activity_at, so keying on it rang twice for one thing to answer.
+        const newWait = next === "waiting" && prev !== "waiting";
+        this.state = next;
+        this.setTitle();
+        if (first) {
+            this.warpEvent("session_start", { plugin_version: WARP_PLUGIN_COMPAT });
+            if (next === "working")
+                this.warpEvent("prompt_submit", { query: "" });
+            return;
+        }
+        if (next === "working" && prev !== "working")
+            this.warpEvent("prompt_submit", { query: "" });
+        if (next === "idle" && prev === "working") {
+            this.warpEvent("stop", { query: "", response: clean(row.activity_message ?? "", 200), transcript_path: "" });
+        }
+        if (newWait) {
+            const summary = clean(row.activity_message || "Waiting for you", 120);
+            if (this.warp !== null) {
+                if (row.activity_reason === "permission") {
+                    this.warpEvent("permission_request", { summary, tool_name: "", tool_input: {} });
+                }
+                else {
+                    this.warpEvent("idle_prompt", { summary });
+                }
+            }
+            else if (!row.muted_at) {
+                // Bell first (marks the tab nearly everywhere), then the desktop notification where supported.
+                // "Cubes" leads the text so it can never be read as ConEmu's numeric OSC 9 sub-commands.
+                this.emit(`\x07${this.outward(`\x1b]9;Cubes · ${clean(row.title || "session", 60)}: ${summary}\x07`)}`);
+            }
+        }
+    }
+}

package/dist/tui/launch.js

@@ -0,0 +1,98 @@
+// `cubes` with no arguments: the split view. A local tmux on its own socket holds two panes - the
+// session list on the left, the session on the right - so layout, resizing, mouse focus and the
+// terminal emulation of the right pane are tmux's, which is the battle-tested part. Our two processes
+// (`cubes _list`, `cubes _pane`) only draw and talk to the API.
+//
+// Run it again and you are back where you were: the tmux outlives the terminal that opened it.
+import { spawnSync } from "node:child_process";
+import { CliError, currentSession } from "../auth.js";
+import { selfCommand, SESSION, SOCKET, tmux, tmuxVersion } from "./tmux.js";
+const MIN_TMUX = 3.2;
+/** Every option is set on OUR socket only, so none of this reaches a tmux the person already uses. */
+const OPTIONS = [
+    ["mouse", "on"],
+    ["status", "off"],
+    // ⚠ NO PREFIX. tmux's Ctrl-B is Claude Code's "run in background", and the session's own tmux (the
+    // one in the pod) has none either, so nothing here may eat a keystroke. Focus moves by mouse, by
+    // Ctrl-] from the session pane, and by Enter/Tab from the list.
+    ["prefix", "None"],
+    ["prefix2", "None"],
+    // Escape must reach Claude Code at once: tmux's default 500 ms makes every Esc feel broken.
+    ["escape-time", "10"],
+    ["focus-events", "on"],
+    ["pane-border-status", "top"],
+    ["pane-border-format", " #{?#{@cubes_header},#{@cubes_header},#{pane_title}} "],
+    ["pane-border-style", "fg=colour238"],
+    ["pane-active-border-style", "fg=colour62"],
+    // The outer terminal's tab follows the session on the right, whichever pane has focus.
+    ["set-titles", "on"],
+    ["set-titles-string", "#{?#{@cubes_tab},#{@cubes_tab},Cubes}"],
+    // So a session's bell and notifications reach the terminal the person is looking at.
+    ["bell-action", "any"],
+    ["visual-bell", "off"],
+    ["allow-passthrough", "on"],
+];
+function attachClient() {
+    const env = { ...process.env };
+    delete env.TMUX; // inside the person's own tmux: nest on purpose rather than refuse
+    const r = spawnSync("tmux", ["-L", SOCKET, "attach-session", "-t", SESSION], { stdio: "inherit", env });
+    return r.status ?? 0;
+}
+function build(org) {
+    const cols = process.stdout.columns ?? 160;
+    const rows = process.stdout.rows ?? 48;
+    const env = org ? ["-e", `CUBES_ORG=${org}`] : [];
+    const created = tmux(["new-session", "-d", "-s", SESSION, "-x", String(cols), "-y", String(rows), ...env,
+        "-P", "-F", "#{pane_id}", selfCommand(["_list"])]);
+    if (created.code !== 0)
+        throw new CliError(`could not start tmux: ${created.err || created.code}`);
+    const left = created.out;
+    for (const [k, v] of OPTIONS)
+        tmux(["set-option", "-g", "-q", k, v]);
+    // ⚠ The same fix the session's own tmux carries (server Tmux.clientDefaults): without `ech`, tmux
+    // draws gaps as real spaces. Warp left stale letters in every gap drawn with ECH. A SERVER option,
+    // read when a client attaches, so it is set before ours does.
+    tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]);
+    tmux(["set-option", "-w", "-t", SESSION, "-q", "remain-on-exit", "on"]);
+    // The list gets about a third, within reason: enough for a title, never most of the screen.
+    const listW = Math.max(32, Math.min(56, Math.round(cols * 0.3)));
+    const right = tmux(["split-window", "-h", "-t", left, "-l", String(Math.max(20, cols - listW - 1)), ...env,
+        "-P", "-F", "#{pane_id}", selfCommand(["_pane"])]);
+    if (right.code !== 0)
+        throw new CliError(`could not split the window: ${right.err || right.code}`);
+    tmux(["set-option", "-t", SESSION, "@cubes_left", left]);
+    tmux(["set-option", "-t", SESSION, "@cubes_right", right.out]);
+    tmux(["select-pane", "-t", left]);
+}
+/**
+ * Bring a dead pane back. `remain-on-exit` keeps a crashed pane on screen (with what it printed)
+ * instead of letting the layout collapse; reopening `cubes` restarts whichever of the two died.
+ */
+function heal() {
+    const panes = tmux(["list-panes", "-t", SESSION, "-F", "#{pane_id} #{pane_dead}"]).out.split("\n");
+    const left = tmux(["show-options", "-v", "-q", "-t", SESSION, "@cubes_left"]).out;
+    for (const line of panes) {
+        const [id, dead] = line.split(" ");
+        if (dead !== "1" || !id)
+            continue;
+        tmux(["respawn-pane", "-k", "-t", id, selfCommand(id === left ? ["_list"] : ["_pane"])]);
+    }
+}
+export async function launchTui(opts) {
+    const v = tmuxVersion();
+    if (v === null) {
+        throw new CliError("the split view runs inside tmux, which is not installed - `brew install tmux` (macOS) or "
+            + "`apt install tmux`. `cubes attach` works without it.");
+    }
+    if (v < MIN_TMUX)
+        throw new CliError(`the split view needs tmux ${MIN_TMUX} or newer (this is ${v}) - upgrade it, or use \`cubes attach\``);
+    // Fail here, with a sentence, rather than in two panes at once.
+    await currentSession({ org: opts.org }).token();
+    if (tmux(["has-session", "-t", SESSION]).code === 0) {
+        heal();
+        tmux(["set-option", "-s", "terminal-overrides[90]", "*:ech@"]); // a layout built by an older cubes
+    }
+    else
+        build(opts.org);
+    return attachClient();
+}