@hellix-ai/cubes 0.1.3 → 0.1.5

package/README.md

@@ -28,6 +28,14 @@ Every key goes to the session, exactly as if Claude Code were running locally, e
 takes it back, the terminal says so and goes read-only; detach and attach again to reclaim it.
 `cubes attach --view` watches without taking it.
 
+**Your tab shows the session.** The terminal tab is titled after the session, with its state in front,
+the way Claude Code does it locally: a spinner while it works, `✳` when idle, `✋` when it is waiting
+for you. The moment it starts waiting, the terminal also gets a bell (most terminals mark the tab or
+bounce the dock) and a desktop notification with Claude's question (iTerm2, Ghostty, WezTerm, kitty and
+others). In Warp, the same events Warp's own Claude Code plugin sends drive its tab status and
+notifications instead. Muted sessions stay quiet. Your own title comes back when you detach.
+`--no-status` turns all of it off.
+
 A stopped or hibernated session is resumed before attaching (`--no-resume` to refuse), with the
 spinning Cubes mark on screen until it is up. A dropped connection reconnects on its own and replays
 the screen.
@@ -43,7 +51,7 @@ cubes logout
 cubes whoami
 cubes org [ALIAS]
 cubes ls [--mine] [--live] [--all] [--json]
-cubes attach [SESSION] [--view] [--no-resume]
+cubes attach [SESSION] [--view] [--no-resume] [--no-status]
 cubes upgrade [--check]
 ```
 

package/dist/attach.js

@@ -14,6 +14,7 @@
 // on a read-only tile. The writer also decides the pane's size, so the session re-fits to THIS window.
 import { ApiError } from "./api.js";
 import { InputFilter, PASTE_IMAGE_BYTE } from "./keys.js";
+import { StreamFilter, TermStatus, TITLE_POP, TITLE_PUSH } from "./termstatus.js";
 export const TTY_SUBPROTOCOL = "cube.tty.v1";
 const OPEN = 1;
 /** Close codes (server/src/engine/tty.ts, web/src/cubes/Terminal.tsx). */
@@ -59,6 +60,45 @@ export function attach(deps, session, opts = {}) {
         // an image paste is uploading (so what is typed after Ctrl-V lands after the path, not before).
         let pending = [];
         let pasting = false;
+        // Our own sequences (title, bell, notifications) wait here until the session's stream is between
+        // escape sequences - see termstatus.ts. A fresh filter per connection: a replay starts clean.
+        let stream = new StreamFilter();
+        let injections = [];
+        let status = null;
+        let pollTimer = null;
+        let spinTimer = null;
+        const inject = (seq) => {
+            if (stream.safe)
+                stdout.write(seq);
+            else
+                injections.push(seq);
+        };
+        const flushInjections = () => {
+            if (!injections.length || !stream.safe)
+                return;
+            stdout.write(injections.join(""));
+            injections = [];
+        };
+        const startStatus = () => {
+            if (opts.status === false || status)
+                return;
+            const cfg = opts.status ?? {};
+            stdout.write(TITLE_PUSH);
+            status = new TermStatus({ status: "running", ...session }, inject, cfg.env);
+            status.update({ status: "running", ...session });
+            let inFlight = false;
+            pollTimer = setInterval(() => {
+                if (inFlight || done)
+                    return;
+                inFlight = true;
+                api.get(`/sessions/${encodeURIComponent(session.id)}`)
+                    .then((row) => { if (!done)
+                    status?.update(row); })
+                    .catch(() => { })
+                    .finally(() => { inFlight = false; });
+            }, cfg.pollMs ?? 3000);
+            spinTimer = setInterval(() => { status?.tick(); flushInjections(); }, cfg.spinMs ?? 250);
+        };
         const note = (msg) => {
             stderr.write(entered ? `\r\n\x1b[2m[cubes] ${msg}\x1b[0m\r\n` : `[cubes] ${msg}\n`);
         };
@@ -69,6 +109,7 @@ export function attach(deps, session, opts = {}) {
             if (stdin.isTTY)
                 stdin.setRawMode?.(true);
             stdout.write(ENTER_ALT);
+            startStatus();
         };
         const finish = (code, message) => {
             if (done)
@@ -76,6 +117,10 @@ export function attach(deps, session, opts = {}) {
             done = true;
             if (timer)
                 clearTimeout(timer);
+            if (pollTimer)
+                clearInterval(pollTimer);
+            if (spinTimer)
+                clearInterval(spinTimer);
             stdin.off("data", onData);
             stdout.off("resize", onResize);
             const sock = ws;
@@ -89,7 +134,7 @@ export function attach(deps, session, opts = {}) {
                 catch { /* already gone */ }
             }
             if (entered) {
-                stdout.write(RESTORE_TERMINAL + LEAVE_ALT);
+                stdout.write(RESTORE_TERMINAL + (status ? TITLE_POP : "") + LEAVE_ALT);
                 if (stdin.isTTY)
                     stdin.setRawMode?.(false);
             }
@@ -247,6 +292,7 @@ export function attach(deps, session, opts = {}) {
             const sock = deps.openWs(wsUrlFor(deps.host, session.id), [TTY_SUBPROTOCOL, ticket]);
             sock.binaryType = "arraybuffer";
             ws = sock;
+            stream = new StreamFilter();
             askedTakeover = false;
             takeoverPending = false;
             sock.onopen = () => {
@@ -296,10 +342,12 @@ export function attach(deps, session, opts = {}) {
                     }
                     return;
                 }
-                if (data instanceof ArrayBuffer)
-                    stdout.write(new Uint8Array(data));
-                else if (ArrayBuffer.isView(data))
-                    stdout.write(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+                const bytes = data instanceof ArrayBuffer ? new Uint8Array(data)
+                    : ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : null;
+                if (!bytes)
+                    return;
+                stdout.write(stream.feed(bytes));
+                flushInjections();
             };
             sock.onclose = (ev) => { if (ws === sock)
                 onClose(ev.code, ev.reason); };

package/dist/cli.js

@@ -27,7 +27,8 @@ Usage:
   cubes org [ALIAS]                                       list your orgs, or switch the default
   cubes ls [--mine] [--live] [--all] [--json]             list sessions by group (--mine: you started them,
                                                           --live: running now, --all: include spawned ones)
-  cubes attach [SESSION] [--view] [--no-resume]           attach to a session
+  cubes attach [SESSION] [--view] [--no-resume] [--no-status]
+                                                          attach to a session
   cubes upgrade [--check]                                 install the newest cubes (--check only reports)
 
 SESSION is an id, the start of one (4+ characters), or part of its title. Left out, you pick from
@@ -40,6 +41,10 @@ While attached, every key goes to the session except:
 Attaching takes the keyboard from any browser tab on the same session (it becomes read-only) and
 fits the session to this window. --view watches without taking it.
 
+The tab is titled after the session, with its state: a spinner while it works, ✳ when idle, ✋ when it
+is waiting for you - and a bell plus a desktop notification the moment it starts waiting (in Warp, its
+own agent status instead). --no-status turns all of that off.
+
 Global: --org ALIAS overrides the default org for one command.
 Env:    CUBES_HOST + CUBES_TOKEN (+ CUBES_ORG) use a token instead of the stored login.
 Config: ${configPath()}
@@ -262,7 +267,7 @@ async function cmdAttach(a) {
         stdout: process.stdout,
         stderr: process.stderr,
         readClipboardImage: () => readClipboardImage(),
-    }, row, { view, signal: ac.signal });
+    }, row, { view, signal: ac.signal, status: a.flags.has("no-status") ? false : undefined });
     process.stderr.write(`[cubes] ${result.message}\n`);
     return result.code;
 }

package/dist/termstatus.js

@@ -0,0 +1,275 @@
+// 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:
+//     a spinner while working, ✳ when idle, ✋ when it is waiting for you.
+//   • 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 SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+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;
+    frame = 0;
+    shown = "";
+    row;
+    warp;
+    constructor(row, emit, env = process.env) {
+        this.emit = emit;
+        this.row = row;
+        this.warp = warpProtocol(env);
+    }
+    title() {
+        const glyph = this.state === "working" ? SPINNER[this.frame % SPINNER.length]
+            : 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`);
+    }
+    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(`\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\x1b]9;Cubes · ${clean(row.title || "session", 60)}: ${summary}\x07`);
+            }
+        }
+    }
+    /** Advance the working spinner. Returns false when there is nothing to animate. */
+    tick() {
+        if (this.state !== "working")
+            return false;
+        this.frame++;
+        this.setTitle();
+        return true;
+    }
+}

package/dist/upgrade.js

@@ -37,12 +37,19 @@ export function installerFor(scriptPath) {
         return "yarn";
     return "npm";
 }
+/**
+ * ⚠ FORCE A FRESH LOOK AT THE REGISTRY. npm keeps a local copy of a package's version list and trusts
+ * it for the registry's `max-age=300`, so within five minutes of any earlier install it does not know a
+ * release we just read from `/latest` exists: measured as `ETARGET No matching version found for
+ * @hellix-ai/cubes@0.1.3` four minutes after 0.1.3 was published. `--prefer-online` makes npm revalidate
+ * that copy; bun's `--no-cache` does the same for its manifest cache. pnpm and yarn revalidate already.
+ */
 export function installCommand(installer, spec) {
     switch (installer) {
         case "pnpm": return ["pnpm", "add", "-g", spec];
-        case "bun": return ["bun", "add", "-g", spec];
+        case "bun": return ["bun", "add", "-g", "--no-cache", spec];
         case "yarn": return ["yarn", "global", "add", spec];
-        default: return ["npm", "install", "-g", spec];
+        default: return ["npm", "install", "-g", "--prefer-online", spec];
     }
 }
 export async function latestVersion(pkg, fetchImpl = fetch) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellix-ai/cubes",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Attach to your Cubes sessions from your own terminal (Warp, iTerm, Ghostty, anything).",
   "type": "module",
   "bin": {