nebula-notebook 0.2.0 → 0.2.2

package/node-server/dist/terminal/binding-store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Terminal Bindings
+ *
+ * A notebook has exactly one binding per plane (shell / agent) that decides
+ * which named pty its panel attaches to — attach is always deterministic and
+ * duplicates are impossible by construction (get-or-create on the name).
+ *
+ * Scopes:
+ *   server   → the per-server shared terminal (well-known name `srv-main`)
+ *   project  → shared by all notebooks in the same directory (`proj-<hash>-<dir>`)
+ *   notebook → private to the notebook (`nb-<hash>-<plane>-<slug>` — the exact
+ *              scheme the panel has always used, so pre-binding ptys with live
+ *              jobs are grandfathered in, not orphaned)
+ *   named    → a user-chosen name (normalized like every pty name)
+ *
+ * Persisted as JSON at ~/.nebula/terminal-bindings.json so a notebook's
+ * binding follows it across browsers (same pattern as the agent registry).
+ */
+export type TerminalPlane = 'shell' | 'agent';
+export type TerminalBindingScope = 'server' | 'project' | 'notebook' | 'named';
+export interface TerminalBinding {
+    filePath: string;
+    plane: TerminalPlane;
+    scope: TerminalBindingScope;
+    /** Resolved pty name the panel attaches to (get-or-create). Null for
+     *  agent/project bindings — the client derives it from the chosen workdir. */
+    name: string | null;
+    /** The raw user-supplied name for scope 'named'. */
+    customName?: string;
+    updatedAt: number;
+}
+/** Well-known name of the per-server shared shell. */
+export declare const SHARED_SHELL_NAME = "srv-main";
+/** Well-known name of the per-server shared AGENT terminal. */
+export declare const SHARED_AGENT_NAME = "agent-srv";
+/**
+ * Resolve a (plane, scope) to the pty name it binds to. Pure — no I/O.
+ *
+ * Agent-plane specifics: names double as agent-record keys. `project` returns
+ * null — the workdir is a client-side choice (workdir chip), so the client
+ * derives the legacy `agent-<hash>-<slug>` name from it (which is also why
+ * every pre-binding record keeps working). Named agents get an `agent-`
+ * prefix so they can never collide with a shell terminal of the same name.
+ */
+export declare function resolveBindingName(plane: TerminalPlane, scope: TerminalBindingScope, filePath: string, customName?: string): string | null;
+export declare class TerminalBindingStore {
+    private file;
+    private bindings;
+    constructor(file?: string);
+    private key;
+    private load;
+    private persist;
+    get(filePath: string, plane: TerminalPlane): TerminalBinding | null;
+    set(filePath: string, plane: TerminalPlane, scope: TerminalBindingScope, customName?: string): TerminalBinding;
+    delete(filePath: string, plane: TerminalPlane): void;
+}
+export declare const terminalBindings: TerminalBindingStore;

package/node-server/dist/terminal/pty-manager.d.ts

@@ -13,8 +13,9 @@ interface TerminalSession {
     created: number;
     lastActivity: number;
     outputBuffer: string;
-    onData: ((data: string) => void) | null;
-    onExit: ((code: number) => void) | null;
+    activeModes: Set<number>;
+    dataListeners: Set<(data: string) => void>;
+    exitListeners: Set<(code: number) => void>;
 }
 export declare class PtyManager {
     private sessions;
@@ -48,6 +49,13 @@ export declare class PtyManager {
      * Get a terminal session by ID
      */
     get(id: string): TerminalSession | undefined;
+    /**
+     * Whether the pty's shell has any child process — i.e. something (an agent
+     * CLI, an ssh hop, a user command) is actually running in it. `false` means
+     * a bare idle shell with certainty; `null` means unknown (no such pty, or
+     * pgrep unavailable) and callers must not conclude anything from it.
+     */
+    hasLiveChild(id: string): Promise<boolean | null>;
     /**
      * Get terminal info by ID
      */
@@ -80,17 +88,26 @@ export declare class PtyManager {
      */
     kill(id: string): boolean;
     /**
-     * Set data listener for a terminal (for WebSocket connection)
+     * Subscribe to a terminal's output. Returns an unsubscribe function
+     * (no-op if the terminal is gone).
      */
-    setOnData(id: string, callback: ((data: string) => void) | null): void;
+    addDataListener(id: string, callback: (data: string) => void): () => void;
     /**
-     * Set exit listener for a terminal
+     * Subscribe to a terminal's exit. Returns an unsubscribe function.
      */
-    setOnExit(id: string, callback: ((code: number) => void) | null): void;
+    addExitListener(id: string, callback: (code: number) => void): () => void;
     /**
      * Get buffered output for reconnection
      */
     getOutputBuffer(id: string): string;
+    /**
+     * Sequences that reassert the sticky input modes (see TRACKED_INPUT_MODES) to
+     * the authoritative state observed on the full pty stream. Appended after the
+     * replay buffer so a reconnect never leaves mouse/focus reporting dangling on
+     * at the shell: the 100 KB buffer trim can drop or split the app's own
+     * mode-reset, and this puts it back deterministically.
+     */
+    getModeReset(id: string): string;
     /**
      * Kill all terminal sessions (for cleanup)
      */

package/node-server/dist/terminal/pty-manager.js

@@ -38,9 +38,23 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ptyManager = exports.PtyManager = void 0;
 const path = __importStar(require("path"));
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
 const pty = __importStar(require("@homebridge/node-pty-prebuilt-multiarch"));
 const uuid_1 = require("uuid");
 const types_1 = require("./types");
+// Sticky DEC private modes that turn mouse moves / focus changes into garbage
+// *input* when left enabled at a shell prompt (the classic "reconnected terminal
+// spews <b;x;yM sequences"). Tracked from the raw pty stream so a reconnect can
+// restore the AUTHORITATIVE state even when the enabling/disabling sequence has
+// scrolled out of — or been split by — the 100 KB buffer trim. 1000 click /
+// 1002 button-drag / 1003 any-motion mouse · 1004 focus events · 1006 SGR
+// encoding. (Bracketed paste 2004 is intentionally excluded — the shell prompt
+// toggles it itself, so forcing it would fight the shell.)
+const TRACKED_INPUT_MODES = [1000, 1002, 1003, 1004, 1006];
+// DECSET (…h) / DECRST (…l); params may be ;-separated, e.g. \x1b[?1000;1006h
+// eslint-disable-next-line no-control-regex
+const DEC_PRIVATE_MODE_RE = /\x1b\[\?([0-9;]+)([hl])/g;
 class PtyManager {
     sessions = new Map();
     /**
@@ -82,8 +96,15 @@ class PtyManager {
         // client the MCP uses (packages/mcp) — agents in the built-in terminal
         // can drive notebooks without any MCP registration.
         const nebulaCliBinDir = path.resolve(__dirname, '..', '..', '..', 'packages', 'mcp', 'bin');
-        // Spawn PTY process
-        const ptyProcess = pty.spawn(shell, [], {
+        // Spawn as a LOGIN shell (-l): Nebula terminals must see the same
+        // environment as the user's ssh sessions. Non-login shells skip
+        // .zprofile/.bash_profile, so env set there (agent auth tokens like
+        // CLAUDE_CODE_OAUTH_TOKEN, module inits, PATH) silently vanished from
+        // server-side agent launches — Claude then fell back to its stored OAuth
+        // session and demanded /login whenever that had expired. Windows shells
+        // don't take -l; posix only.
+        const shellArgs = process.platform === 'win32' ? [] : ['-l'];
+        const ptyProcess = pty.spawn(shell, shellArgs, {
             name: 'xterm-256color',
             cols,
             rows,
@@ -106,27 +127,50 @@ class PtyManager {
             created: Date.now(),
             lastActivity: Date.now(),
             outputBuffer: '',
-            onData: null,
-            onExit: null,
+            activeModes: new Set(),
+            dataListeners: new Set(),
+            exitListeners: new Set(),
         };
         // Handle PTY output
         ptyProcess.onData((data) => {
             session.lastActivity = Date.now();
             // Append to output buffer for reconnection
             session.outputBuffer += data;
+            // Track sticky input-mode transitions from the RAW stream (before the
+            // trim below can drop or split them) so replay can reassert the true state.
+            DEC_PRIVATE_MODE_RE.lastIndex = 0;
+            let modeMatch;
+            while ((modeMatch = DEC_PRIVATE_MODE_RE.exec(data)) !== null) {
+                const enable = modeMatch[2] === 'h';
+                for (const p of modeMatch[1].split(';')) {
+                    const n = Number(p);
+                    if (TRACKED_INPUT_MODES.includes(n)) {
+                        if (enable)
+                            session.activeModes.add(n);
+                        else
+                            session.activeModes.delete(n);
+                    }
+                }
+            }
             // Trim buffer if too large
             if (session.outputBuffer.length > types_1.OUTPUT_BUFFER_MAX_SIZE) {
                 session.outputBuffer = session.outputBuffer.slice(-types_1.OUTPUT_BUFFER_TRIM_SIZE);
             }
-            // Forward to listener if connected
-            if (session.onData) {
-                session.onData(data);
+            // Forward to all listeners (websocket clients, watchers)
+            for (const cb of session.dataListeners) {
+                try {
+                    cb(data);
+                }
+                catch { /* one bad listener must not break the rest */ }
             }
         });
         // Handle PTY exit
         ptyProcess.onExit(({ exitCode }) => {
-            if (session.onExit) {
-                session.onExit(exitCode);
+            for (const cb of session.exitListeners) {
+                try {
+                    cb(exitCode);
+                }
+                catch { /* see above */ }
             }
             this.sessions.delete(id);
         });
@@ -154,6 +198,36 @@ class PtyManager {
     get(id) {
         return this.sessions.get(id);
     }
+    /**
+     * Whether the pty's shell has any child process — i.e. something (an agent
+     * CLI, an ssh hop, a user command) is actually running in it. `false` means
+     * a bare idle shell with certainty; `null` means unknown (no such pty, or
+     * pgrep unavailable) and callers must not conclude anything from it.
+     */
+    async hasLiveChild(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return null;
+        const pid = session.pty.pid;
+        // Fast path (Linux): the kernel lists a process's children directly —
+        // an O(1) ~3ms read, vs pgrep's O(all processes) table scan (~50ms on a
+        // busy shared login node with 1300+ processes). Absent on macOS and on
+        // kernels without CONFIG_PROC_CHILDREN — fall back to pgrep there.
+        try {
+            const children = await fs_1.promises.readFile(`/proc/${pid}/task/${pid}/children`, 'utf-8');
+            return children.trim().length > 0;
+        }
+        catch { /* not Linux (or file gone with the process) — pgrep decides */ }
+        return new Promise((resolve) => {
+            (0, child_process_1.execFile)('pgrep', ['-P', String(pid)], (error) => {
+                if (!error)
+                    return resolve(true); // exit 0: at least one child
+                // pgrep exits 1 for "no processes matched" — that's a definitive no.
+                const code = error.code;
+                resolve(code === 1 ? false : null);
+            });
+        });
+    }
     /**
      * Get terminal info by ID
      */
@@ -185,6 +259,12 @@ class PtyManager {
         const session = this.sessions.get(id);
         if (!session)
             return false;
+        // Skip no-op resizes: TIOCSWINSZ raises SIGWINCH even when the size is
+        // unchanged, forcing a full-screen repaint from any running TUI. On a
+        // reconnect several resize messages arrive with the SAME dimensions, and
+        // that repaint burst is what stalls input after a refresh.
+        if (session.cols === cols && session.rows === rows)
+            return true;
         session.pty.resize(cols, rows);
         session.cols = cols;
         session.rows = rows;
@@ -216,22 +296,25 @@ class PtyManager {
         return true;
     }
     /**
-     * Set data listener for a terminal (for WebSocket connection)
+     * Subscribe to a terminal's output. Returns an unsubscribe function
+     * (no-op if the terminal is gone).
      */
-    setOnData(id, callback) {
+    addDataListener(id, callback) {
         const session = this.sessions.get(id);
-        if (session) {
-            session.onData = callback;
-        }
+        if (!session)
+            return () => { };
+        session.dataListeners.add(callback);
+        return () => { this.sessions.get(id)?.dataListeners.delete(callback); };
     }
     /**
-     * Set exit listener for a terminal
+     * Subscribe to a terminal's exit. Returns an unsubscribe function.
      */
-    setOnExit(id, callback) {
+    addExitListener(id, callback) {
         const session = this.sessions.get(id);
-        if (session) {
-            session.onExit = callback;
-        }
+        if (!session)
+            return () => { };
+        session.exitListeners.add(callback);
+        return () => { this.sessions.get(id)?.exitListeners.delete(callback); };
     }
     /**
      * Get buffered output for reconnection
@@ -240,6 +323,34 @@ class PtyManager {
         const session = this.sessions.get(id);
         return session?.outputBuffer || '';
     }
+    /**
+     * Sequences that reassert the sticky input modes (see TRACKED_INPUT_MODES) to
+     * the authoritative state observed on the full pty stream. Appended after the
+     * replay buffer so a reconnect never leaves mouse/focus reporting dangling on
+     * at the shell: the 100 KB buffer trim can drop or split the app's own
+     * mode-reset, and this puts it back deterministically.
+     */
+    getModeReset(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return '';
+        // If the pty's FOREGROUND process is a plain shell, no TUI can be holding
+        // the sticky input modes — any tracked "on" state is stale (a TUI died
+        // without its teardown bytes reaching the pty, e.g. an agent riding a
+        // collapsed reverse tunnel, or a SIGKILL). Reasserting it would turn the
+        // user's mouse movements into SGR garbage typed at the prompt, so reset
+        // everything OFF instead.
+        try {
+            const fg = (session.pty.process || '').split('/').pop() || '';
+            if (/^-?(bash|zsh|sh|dash|fish|tcsh|ksh)$/.test(fg)) {
+                session.activeModes.clear();
+            }
+        }
+        catch { /* can't inspect foreground — keep tracked state */ }
+        return TRACKED_INPUT_MODES
+            .map((n) => `\x1b[?${n}${session.activeModes.has(n) ? 'h' : 'l'}`)
+            .join('');
+    }
     /**
      * Kill all terminal sessions (for cleanup)
      */

package/node-server/dist/terminal/server.js

@@ -44,6 +44,8 @@ const net = __importStar(require("net"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const pty_manager_1 = require("./pty-manager");
+const agent_registry_1 = require("./agent-registry");
+const binding_store_1 = require("./binding-store");
 const fs_service_1 = require("../fs/fs-service");
 // Get configured root directory for terminals
 function getDefaultCwd() {
@@ -105,6 +107,38 @@ async function setupTerminalRoutes(fastify) {
         return reply.send({ up: result.up, ssh: result.ssh });
     });
     // List all terminals
+    // ---- Agent registry: project-scoped agent sessions (see agent-registry.ts) ----
+    fastify.get('/api/agents', async (_request, reply) => {
+        return reply.send({ agents: await agent_registry_1.agentRegistry.listEnriched() });
+    });
+    fastify.post('/api/agents/register', async (request, reply) => {
+        const b = (request.body ?? {});
+        if (!b.terminalId || !b.kind || !b.workdir) {
+            return reply.code(400).send({ error: 'terminalId, kind, workdir required' });
+        }
+        const record = agent_registry_1.agentRegistry.register({
+            terminalId: b.terminalId,
+            kind: b.kind === 'codex' ? 'codex' : 'claude',
+            workdir: b.workdir,
+            location: b.location === 'remote' ? 'remote' : 'server',
+            sessionId: b.sessionId,
+            launchedFrom: b.launchedFrom,
+            mirrorSlug: b.mirrorSlug,
+        });
+        return reply.send(record);
+    });
+    fastify.post('/api/agents/:id/hibernate', async (request, reply) => {
+        const { id } = request.params;
+        if (!agent_registry_1.agentRegistry.hibernate(id))
+            return reply.code(404).send({ error: 'unknown agent' });
+        return reply.send({ ok: true });
+    });
+    fastify.delete('/api/agents/:id', async (request, reply) => {
+        const { id } = request.params;
+        if (!agent_registry_1.agentRegistry.remove(id))
+            return reply.code(404).send({ error: 'unknown agent' });
+        return reply.send({ ok: true });
+    });
     fastify.get('/api/terminals', async (_request, reply) => {
         return reply.send(pty_manager_1.ptyManager.list());
     });
@@ -145,6 +179,63 @@ async function setupTerminalRoutes(fastify) {
             });
         }
     });
+    // --- Terminal bindings: which named pty a notebook's panel attaches to ---
+    // GET returns the stored binding, or the plane default when none is stored
+    // (shell → server-shared srv-main; agent → project scope, name resolved
+    // client-side from the chosen workdir).
+    fastify.get('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane } = request.query;
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        const stored = binding_store_1.terminalBindings.get(file_path, plane);
+        if (stored) {
+            return reply.send({
+                plane, scope: stored.scope, name: stored.name,
+                custom_name: stored.customName ?? null, stored: true,
+            });
+        }
+        if (plane === 'shell') {
+            return reply.send({ plane, scope: 'server', name: binding_store_1.SHARED_SHELL_NAME, custom_name: null, stored: false });
+        }
+        return reply.send({ plane, scope: 'project', name: null, custom_name: null, stored: false });
+    });
+    fastify.put('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane, scope, name } = request.body || {};
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        if (!['server', 'project', 'notebook', 'named'].includes(scope || '')) {
+            return reply.code(400).send({ detail: 'scope must be server|project|notebook|named' });
+        }
+        try {
+            const binding = binding_store_1.terminalBindings.set(file_path, plane, scope, name);
+            return reply.send({
+                plane, scope: binding.scope, name: binding.name,
+                custom_name: binding.customName ?? null, stored: true,
+            });
+        }
+        catch (e) {
+            return reply.code(400).send({ detail: e instanceof Error ? e.message : 'Invalid binding' });
+        }
+    });
+    fastify.delete('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane } = request.query;
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        binding_store_1.terminalBindings.delete(file_path, plane);
+        return reply.send({ ok: true });
+    });
+    // Process-table probe: does this pty's shell have a live child? Clients MUST
+    // check this before typing a launch command into an existing pty — records
+    // can mis-score liveness (a hand-resumed agent never re-registers), and a
+    // launch line typed into a live TUI becomes a chat prompt (lab report).
+    // busy:null = unknown (pty gone / pgrep unavailable) — claim nothing.
+    fastify.get('/api/terminals/:id/busy', async (request, reply) => {
+        const busy = await pty_manager_1.ptyManager.hasLiveChild(request.params.id);
+        return reply.send({ busy });
+    });
     // Get terminal info
     fastify.get('/api/terminals/:id', async (request, reply) => {
         const terminal = pty_manager_1.ptyManager.getTerminalInfo(request.params.id);
@@ -225,28 +316,28 @@ function setupTerminalWebSocket(server) {
         // Send buffered output for reconnection
         const buffer = pty_manager_1.ptyManager.getOutputBuffer(terminalId);
         if (buffer) {
-            const replayMsg = { type: 'replay', data: buffer };
+            // Append an authoritative reassert of the sticky input modes so a
+            // reconnect never leaves mouse/focus reporting dangling on at the shell
+            // (the buffer trim can drop or split the app's own mode-reset).
+            const info = pty_manager_1.ptyManager.getTerminalInfo(terminalId);
+            const replayMsg = {
+                type: 'replay',
+                data: buffer + pty_manager_1.ptyManager.getModeReset(terminalId),
+                cols: info?.cols,
+                rows: info?.rows,
+            };
             ws.send(JSON.stringify(replayMsg));
         }
-        // Collaborative mode: broadcast output to ALL connected clients
-        const broadcastOutput = (data) => {
-            const msg = { type: 'output', data };
-            const msgStr = JSON.stringify(msg);
-            for (const conn of connections) {
-                if (conn.readyState === ws_1.WebSocket.OPEN) {
-                    conn.send(msgStr);
-                }
+        // One subscription per websocket, sending only to ITS socket — the pty
+        // layer now multicasts, so no shared-closure broadcast trickery needed.
+        const unsubData = pty_manager_1.ptyManager.addDataListener(terminalId, (data) => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: 'output', data }));
             }
-        };
-        pty_manager_1.ptyManager.setOnData(terminalId, broadcastOutput);
-        // Set up exit listener - broadcast to all connections
-        pty_manager_1.ptyManager.setOnExit(terminalId, (code) => {
-            const msg = { type: 'exit', code };
-            const msgStr = JSON.stringify(msg);
-            for (const conn of connections) {
-                if (conn.readyState === ws_1.WebSocket.OPEN) {
-                    conn.send(msgStr);
-                }
+        });
+        const unsubExit = pty_manager_1.ptyManager.addExitListener(terminalId, (code) => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: 'exit', code }));
             }
         });
         // Handle incoming messages
@@ -271,13 +362,13 @@ function setupTerminalWebSocket(server) {
         // Handle disconnection
         ws.on('close', () => {
             console.log(`[Terminal] WebSocket disconnected from terminal ${terminalId}`);
+            unsubData();
+            unsubExit();
             const connections = wsConnections.get(terminalId);
             if (connections) {
                 connections.delete(ws);
                 if (connections.size === 0) {
                     wsConnections.delete(terminalId);
-                    // Clear the data listener when no connections
-                    pty_manager_1.ptyManager.setOnData(terminalId, null);
                 }
             }
         });

package/node-server/dist/terminal/types.d.ts

@@ -35,6 +35,8 @@ export type ServerMessage = {
 } | {
     type: 'replay';
     data: string;
+    cols?: number;
+    rows?: number;
 } | {
     type: 'exit';
     code: number;

package/node-server/package.json

@@ -20,6 +20,7 @@
     "better-sqlite3": "^11.0.0",
     "fastify": "^5.8.2",
     "jsonwebtoken": "^9.0.2",
+    "nebula-autocomplete": "file:../packages/autocomplete",
     "otplib": "^12.0.1",
     "qrcode-terminal": "^0.12.0",
     "uuid": "^9.0.1",