nebula-notebook 0.1.1 → 0.2.1

package/node_modules/nebula-autocomplete/dist/server/fastify.d.ts

@@ -0,0 +1,40 @@
+import type { AutocompleteEngine } from "../core/engine.js";
+import type { CompletionRequest } from "../types.js";
+/**
+ * Minimal structural types so this plugin works with Fastify 4/5 without a
+ * hard dependency on the fastify package.
+ */
+interface FastifyLikeRequest {
+    body: unknown;
+}
+interface FastifyLikeReply {
+    raw: {
+        writeHead(status: number, headers: Record<string, string>): void;
+        write(chunk: string): void;
+        end(): void;
+        on(event: "close", cb: () => void): void;
+        writableEnded: boolean;
+    };
+    hijack?: () => void;
+}
+interface FastifyLikeInstance {
+    post(path: string, handler: (req: FastifyLikeRequest, reply: FastifyLikeReply) => Promise<void>): void;
+}
+export interface AutocompleteRouteOptions {
+    /** Route path. Default "/autocomplete". */
+    path?: string;
+}
+export type EngineResolver = (req: CompletionRequest) => AutocompleteEngine;
+/**
+ * Register `POST <path>` streaming completions as SSE.
+ *
+ * Request body: CompletionRequest (JSON).
+ * Response events: {type:"chunk",text} then {type:"done",...CompletionResult},
+ * or {type:"error",message}.
+ *
+ * Usage in nebula-notebook's node-server:
+ *   const engine = new AutocompleteEngine({ backend: new ClaudeBackend() });
+ *   app.register(async (f) => registerAutocompleteRoute(f, engine), { prefix: "/api" });
+ */
+export declare function registerAutocompleteRoute(fastify: FastifyLikeInstance, engine: AutocompleteEngine | EngineResolver, options?: AutocompleteRouteOptions): void;
+export {};

package/node_modules/nebula-autocomplete/dist/server/fastify.js

@@ -0,0 +1,52 @@
+/**
+ * Register `POST <path>` streaming completions as SSE.
+ *
+ * Request body: CompletionRequest (JSON).
+ * Response events: {type:"chunk",text} then {type:"done",...CompletionResult},
+ * or {type:"error",message}.
+ *
+ * Usage in nebula-notebook's node-server:
+ *   const engine = new AutocompleteEngine({ backend: new ClaudeBackend() });
+ *   app.register(async (f) => registerAutocompleteRoute(f, engine), { prefix: "/api" });
+ */
+export function registerAutocompleteRoute(fastify, engine, options = {}) {
+    const path = options.path ?? "/autocomplete";
+    const resolve = typeof engine === "function" ? engine : () => engine;
+    fastify.post(path, async (req, reply) => {
+        reply.hijack?.(); // take over the raw socket for SSE (Fastify 4/5)
+        const res = reply.raw;
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+        });
+        const send = (obj) => res.write(`data: ${JSON.stringify(obj)}\n\n`);
+        const abort = new AbortController();
+        // Detect client disconnect via the RESPONSE stream closing before we
+        // ended it. (The request's "close" fires as soon as its body is fully
+        // consumed on modern Node — listening there aborts every request.)
+        res.on("close", () => {
+            if (!res.writableEnded)
+                abort.abort(new Error("client disconnected"));
+        });
+        try {
+            const body = req.body;
+            if (!body || typeof body.prefix !== "string") {
+                send({ type: "error", message: "prefix (string) is required" });
+                res.end();
+                return;
+            }
+            const result = await resolve(body).complete(body, {
+                signal: abort.signal,
+                onChunk: (text) => send({ type: "chunk", text }),
+            });
+            send({ type: "done", ...result });
+        }
+        catch (e) {
+            if (!abort.signal.aborted) {
+                send({ type: "error", message: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        res.end();
+    });
+}

package/node_modules/nebula-autocomplete/dist/transport.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Process transport for backends: run a provider CLI either LOCALLY (same host
+ * as this process) or OVER SSH on a remote host.
+ *
+ * The over-ssh case powers "remote Nebula, local agent": the Nebula server runs
+ * on a cluster, but autocomplete should drive the user's OWN claude/codex on
+ * their laptop — reached over the reverse SSH tunnel the user already has. The
+ * CLI's stream-json stdio flows transparently over the ssh channel; a persistent
+ * warm worker keeps one ssh connection open (handshake paid once, not per turn),
+ * and ControlMaster makes any reconnect ~free. See the validated latency probe:
+ * per-turn overhead ≈ one network RTT (~50ms), negligible vs ~2s model latency.
+ */
+export interface SshTransport {
+    kind: 'ssh';
+    /** Host to ssh to — typically 'localhost' (the reverse-tunnel endpoint). */
+    host: string;
+    /** Reverse-tunnel port on this (server) host that forwards to the user's sshd. */
+    port: number;
+    /** Username on the user's machine. */
+    user: string;
+    /** Absolute path to the provider binary ON THE USER'S machine (PATH isn't set
+     *  for a non-interactive ssh, so this must be absolute). */
+    remoteBin: string;
+    /** ControlMaster socket path, so warm workers + reconnects reuse one connection. */
+    controlPath?: string;
+    /** Working dir on the remote side (created if absent). Keep it empty of any
+     *  CLAUDE.md so the agent harness stays minimal. */
+    remoteCwd?: string;
+}
+export type Transport = {
+    kind: 'local';
+} | SshTransport;
+export interface SpawnPlan {
+    command: string;
+    args: string[];
+    /** Options to pass to child_process.spawn (env/cwd). For ssh these are empty
+     *  because env/cwd are embedded in the remote command line. */
+    options: {
+        env?: NodeJS.ProcessEnv;
+        cwd?: string;
+    };
+}
+/** POSIX single-quote a string so it survives the remote shell verbatim. */
+export declare function shellQuote(s: string): string;
+/**
+ * Plan how to spawn `bin argv` with `env` in `cwd`, honoring the transport.
+ * - local: spawn the binary directly; env/cwd go to spawn().
+ * - ssh: spawn `ssh …host <remoteCmd>` where remoteCmd re-establishes cwd + env
+ *   on the far side (via `cd` and `env K=V …`) and execs the binary. `cwd`/`env`
+ *   passed here are interpreted on the REMOTE side.
+ */
+export declare function planSpawn(transport: Transport, bin: string, argv: string[], env: Record<string, string>, cwd: string): SpawnPlan;
+/** Best-effort remote cleanup (e.g. wipe an ephemeral config dir) over the same
+ *  ssh path. Returns the command+args for a fire-and-forget spawn. */
+export declare function planRemoteCleanup(transport: SshTransport, remotePath: string): SpawnPlan;

package/node_modules/nebula-autocomplete/dist/transport.js

@@ -0,0 +1,66 @@
+/**
+ * Process transport for backends: run a provider CLI either LOCALLY (same host
+ * as this process) or OVER SSH on a remote host.
+ *
+ * The over-ssh case powers "remote Nebula, local agent": the Nebula server runs
+ * on a cluster, but autocomplete should drive the user's OWN claude/codex on
+ * their laptop — reached over the reverse SSH tunnel the user already has. The
+ * CLI's stream-json stdio flows transparently over the ssh channel; a persistent
+ * warm worker keeps one ssh connection open (handshake paid once, not per turn),
+ * and ControlMaster makes any reconnect ~free. See the validated latency probe:
+ * per-turn overhead ≈ one network RTT (~50ms), negligible vs ~2s model latency.
+ */
+/** POSIX single-quote a string so it survives the remote shell verbatim. */
+export function shellQuote(s) {
+    return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+const SSH_BASE_OPTS = [
+    '-o', 'ProxyCommand=none',
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'BatchMode=yes',
+    '-o', 'ServerAliveInterval=30',
+];
+/**
+ * Plan how to spawn `bin argv` with `env` in `cwd`, honoring the transport.
+ * - local: spawn the binary directly; env/cwd go to spawn().
+ * - ssh: spawn `ssh …host <remoteCmd>` where remoteCmd re-establishes cwd + env
+ *   on the far side (via `cd` and `env K=V …`) and execs the binary. `cwd`/`env`
+ *   passed here are interpreted on the REMOTE side.
+ */
+export function planSpawn(transport, bin, argv, env, cwd) {
+    if (transport.kind === 'local') {
+        return { command: bin, args: argv, options: { env: { ...process.env, ...env }, cwd } };
+    }
+    const sshOpts = [...SSH_BASE_OPTS, '-p', String(transport.port)];
+    if (transport.controlPath) {
+        // ControlPersist 1h (was 120s): the master handshake is the expensive part
+        // over the reverse tunnel, and a 2-minute persist meant any idle gap made
+        // the next worker spawn pay it again — part of the "autocomplete lags
+        // after I come back" cold start. An idle master on a localhost tunnel
+        // costs one file descriptor; keep it warm for the whole work session.
+        sshOpts.push('-o', 'ControlMaster=auto', '-o', `ControlPath=${transport.controlPath}`, '-o', 'ControlPersist=3600');
+    }
+    const remoteCwd = transport.remoteCwd ?? cwd;
+    const envPrefix = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`).join(' ');
+    // mkdir+cd so the remote agent runs in a clean, CLAUDE.md-free dir; `exec env …`
+    // sets the child env on the far side (the local process.env doesn't reach it).
+    const remoteCmd = `mkdir -p ${shellQuote(remoteCwd)} 2>/dev/null; cd ${shellQuote(remoteCwd)} 2>/dev/null; ` +
+        `exec env ${envPrefix} ${shellQuote(transport.remoteBin)} ${argv.map(shellQuote).join(' ')}`;
+    return {
+        command: 'ssh',
+        args: [...sshOpts, `${transport.user}@${transport.host}`, remoteCmd],
+        options: {},
+    };
+}
+/** Best-effort remote cleanup (e.g. wipe an ephemeral config dir) over the same
+ *  ssh path. Returns the command+args for a fire-and-forget spawn. */
+export function planRemoteCleanup(transport, remotePath) {
+    const sshOpts = [...SSH_BASE_OPTS, '-p', String(transport.port)];
+    if (transport.controlPath)
+        sshOpts.push('-o', `ControlPath=${transport.controlPath}`);
+    return {
+        command: 'ssh',
+        args: [...sshOpts, `${transport.user}@${transport.host}`, `rm -rf ${shellQuote(remotePath)}`],
+        options: {},
+    };
+}

package/node_modules/nebula-autocomplete/dist/types.d.ts

@@ -0,0 +1,103 @@
+export interface NotebookCellContext {
+    type: "code" | "markdown";
+    content: string;
+}
+export interface CompletionRequest {
+    /** Text before the cursor in the active cell. Required. */
+    prefix: string;
+    /** Text after the cursor in the active cell. */
+    suffix?: string;
+    /** Explicit language, if known. Usually omitted — prefer the hints below and
+     *  let the model infer the language from the code + kernel/filename. */
+    language?: string;
+    /** Active kernel name/spec (e.g. "python3", "ir", "julia-1.9"). A hint. */
+    kernelName?: string;
+    /** Notebook filename (e.g. "analysis.ipynb"). A hint. */
+    filename?: string;
+    /** All notebook cells, in order, for cross-cell context. */
+    cells?: NotebookCellContext[];
+    /** Index of the active cell within `cells`. */
+    activeCellIndex?: number;
+    /**
+     * Requests sharing a sessionKey supersede each other: issuing a new one
+     * aborts the previous in-flight request. Use the cell id.
+     */
+    sessionKey?: string;
+    /** Model override (e.g. "haiku" | "sonnet"). Engines are pooled per model. */
+    model?: string;
+    /** Per-request cross-cell context budget in chars (clamped server-side).
+     *  More context grounds suggestions in the notebook (fewer hallucinated
+     *  names) at the cost of a bigger prompt. */
+    contextBudget?: number;
+    /** Per-request cap on suggested lines (clamped server-side). */
+    maxLines?: number;
+    /** Backend selector, for servers hosting more than one engine. */
+    backend?: string;
+}
+export interface CompletionResult {
+    text: string;
+    backend: string;
+    fromCache: boolean;
+    ttfbMs: number;
+    totalMs: number;
+    /** Per-request engine/worker diagnostics (see CompletionDiag). */
+    diag?: CompletionDiag;
+}
+/**
+ * Where a completion's latency went — filled by the backend, forwarded in the
+ * SSE done event so the browser console can show the breakdown.
+ */
+export interface CompletionDiag {
+    /** Transport the worker ran on. */
+    transport?: string;
+    /** ms spent queued behind an earlier in-flight turn for the same session
+     *  (single-flight per cell — typing bursts wait for the previous turn
+     *  instead of fanning out across workers; see engine.complete). */
+    queueWaitMs?: number;
+    /** ms from request start until the turn was dispatched to a warm worker
+     *  (pool scan + possible spawn + warmup wait). The silent part of TTFB. */
+    workerWaitMs?: number;
+    /** A fresh worker process had to be spawned for this request. */
+    coldSpawn?: boolean;
+    /** The turn was retried on a fresh worker after the first one died. */
+    retried?: boolean;
+    /** How many turns this worker had already served (conversation history
+     *  grows with each turn, inflating time-to-first-byte). */
+    workerTurn?: number;
+    /** Accumulated prompt chars in this worker's history before this turn —
+     *  the actual TTFB-drag driver (recycled past maxHistoryCharsPerWorker). */
+    workerHistoryChars?: number;
+    /** Busy workers / pool size at request time (busy=size → cold spawn). */
+    poolBusy?: number;
+    poolSize?: number;
+    /** Characters in the assembled prompt. */
+    promptChars?: number;
+    /** Characters in the RAW model reply, before tag/fence/overlap trimming —
+     *  rawChars>0 with empty final text means post-processing removed it. */
+    rawChars?: number;
+}
+export interface CompleteOptions {
+    signal?: AbortSignal;
+    /** Called with each streamed text chunk (claude backend streams; codex emits once). */
+    onChunk?: (text: string) => void;
+}
+/** A completion backend: turns a prompt into text. */
+export interface CompletionBackend {
+    readonly name: string;
+    complete(prompt: string, opts: {
+        signal?: AbortSignal;
+        onChunk?: (text: string) => void;
+        diag?: CompletionDiag;
+    }): Promise<string>;
+    /** Release child processes. */
+    dispose(): void;
+}
+export interface EngineOptions {
+    backend: CompletionBackend;
+    /** Max completions cached (keyed on context). Default 128. 0 disables. */
+    cacheSize?: number;
+    /** Character budget for cross-cell context in the prompt. Default 6000. */
+    contextBudget?: number;
+    /** Max lines the model is asked to produce. Default 5. */
+    maxLines?: number;
+}

package/node_modules/nebula-autocomplete/dist/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/nebula-autocomplete/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "nebula-autocomplete",
+  "version": "0.1.0",
+  "description": "LLM code autocomplete engine backed by Claude Code / Codex CLI subscriptions, with a Fastify plugin and CodeMirror 6 ghost-text extension.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/fastify.d.ts",
+      "default": "./dist/server/fastify.js"
+    },
+    "./client": {
+      "types": "./dist/client/fetcher.d.ts",
+      "default": "./dist/client/fetcher.js"
+    },
+    "./codemirror": {
+      "types": "./dist/codemirror/ghostText.d.ts",
+      "default": "./dist/codemirror/ghostText.js"
+    }
+  },
+  "files": [
+    "dist",
+    "server.js",
+    "server.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "node scripts/prepare.cjs",
+    "test": "vitest run",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "peerDependencies": {
+    "@codemirror/state": "^6.0.0",
+    "@codemirror/view": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@codemirror/state": {
+      "optional": true
+    },
+    "@codemirror/view": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@codemirror/state": "^6.5.0",
+    "@codemirror/view": "^6.36.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}

package/node_modules/nebula-autocomplete/server.d.ts

@@ -0,0 +1,3 @@
+// Type shim for consumers on classic (node10) module resolution, which cannot
+// read the "exports" map. Runtime resolution still goes through "exports".
+export * from "./dist/server/fastify.js";

package/node_modules/nebula-autocomplete/server.js

@@ -0,0 +1,3 @@
+// Runtime shim mirroring server.d.ts (only used by resolvers that bypass the
+// "exports" map).
+export * from "./dist/server/fastify.js";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "nebula-notebook",
-  "version": "0.1.1",
-  "description": "AI-native notebook computing environment \u2014 real Jupyter kernels, real filesystem, built to be driven by agents (Claude Code / Codex) via MCP",
+  "version": "0.2.1",
+  "description": "AI-native notebook computing environment — real Jupyter kernels, real filesystem, built to be driven by agents (Claude Code / Codex) via MCP",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jzthree/nebula-notebook.git"
+    "url": "https://github.com/jzhoulab/nebula-notebook.git"
   },
   "keywords": [
     "notebook",
@@ -27,6 +27,9 @@
     "node-server/package.json",
     "scripts/postinstall.cjs"
   ],
+  "bundledDependencies": [
+    "nebula-autocomplete"
+  ],
   "engines": {
     "node": ">=20"
   },
@@ -42,10 +45,12 @@
     "mcp": "npm --prefix packages/mcp run mcp",
     "mcp:build": "npm --prefix packages/mcp run build",
     "mcp:test": "npm --prefix packages/mcp test",
+    "autocomplete:test": "npm --prefix packages/autocomplete test",
     "setup-mcp": "npm --prefix packages/mcp run setup-mcp",
     "setup": "node setup.cjs",
     "postinstall": "node scripts/postinstall.cjs",
-    "prepublishOnly": "npm run build && npm run node-server:build",
+    "autocomplete:build": "npm --prefix packages/autocomplete run build",
+    "prepack": "npm --prefix packages/autocomplete install && npm run autocomplete:build && npm run build && npm run node-server:build",
     "stop": "lsof -ti:3000,3001,8000 | xargs kill -9 2>/dev/null; echo 'Servers stopped'",
     "test": "vitest",
     "test:run": "vitest run"
@@ -56,18 +61,23 @@
     "@fastify/static": "^9.0.0",
     "@fastify/websocket": "^11.2.0",
     "@homebridge/node-pty-prebuilt-multiarch": "^0.14.0",
+    "@xterm/addon-clipboard": "^0.2.0",
+    "@xterm/addon-webgl": "^0.19.0",
     "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",
     "ws": "^8.16.0",
+    "yaml": "^2.9.0",
     "zeromq": "^6.4.2"
   },
   "devDependencies": {
     "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/lang-python": "^6.2.1",
+    "@jupyter-widgets/html-manager": "^1.0.14",
     "@playwright/test": "^1.57.0",
     "@tailwindcss/vite": "^4.2.1",
     "@testing-library/jest-dom": "^6.9.1",
@@ -92,5 +102,8 @@
     "typescript": "~5.8.2",
     "vite": "^6.2.0",
     "vitest": "^4.0.16"
-  }
+  },
+  "bundleDependencies": [
+    "nebula-autocomplete"
+  ]
 }

package/scripts/postinstall.cjs

@@ -1,10 +1,13 @@
 /**
- * Repo-checkout convenience: install the node-server and packages/mcp
- * subpackage dependencies after a root `npm install`.
+ * Repo-checkout convenience: install the packages/autocomplete, node-server,
+ * and packages/mcp subpackage dependencies after a root `npm install`.
+ * packages/autocomplete is listed first so its `prepare` step builds dist/
+ * before node-server (which links to it via file:) is set up.
  *
  * Skipped entirely when nebula-notebook is installed from npm as a
  * dependency — the published package is self-contained (server runtime
- * deps live in the root package.json; dist artifacts are prebuilt).
+ * deps live in the root package.json; nebula-autocomplete is a bundled
+ * dependency; dist artifacts are prebuilt).
  */
 const path = require('path');
 const fs = require('fs');
@@ -15,12 +18,29 @@ if (__dirname.split(path.sep).includes('node_modules')) {
 }
 
 const root = path.join(__dirname, '..');
-for (const dir of ['node-server', path.join('packages', 'mcp')]) {
+for (const dir of [path.join('packages', 'autocomplete'), 'node-server', path.join('packages', 'mcp')]) {
   const pkg = path.join(root, dir, 'package.json');
   if (!fs.existsSync(pkg)) continue;
   try {
-    execSync('npm install', { cwd: path.join(root, dir), stdio: 'inherit' });
+    // --include=dev: the subpackage builds (tsc) need their devDependencies
+    // even when the environment forces production installs (NODE_ENV=production
+    // in server shells, npm production config) — without it, tsc is missing
+    // and the prepare builds are skipped.
+    execSync('npm install --include=dev', { cwd: path.join(root, dir), stdio: 'inherit' });
   } catch {
     console.warn(`⚠️  postinstall: npm install failed in ${dir}`);
   }
 }
+
+// The autocomplete build is load-bearing (the root depends on its dist/ via
+// file:). Its prepare skips quietly when typescript is absent, so verify the
+// artifact exists and fall back to an explicit build.
+const autocompleteDir = path.join(root, 'packages', 'autocomplete');
+if (fs.existsSync(path.join(autocompleteDir, 'package.json')) &&
+    !fs.existsSync(path.join(autocompleteDir, 'dist', 'index.js'))) {
+  try {
+    execSync('npm run build', { cwd: autocompleteDir, stdio: 'inherit' });
+  } catch {
+    console.warn('⚠️  postinstall: nebula-autocomplete build failed — run "npm install --include=dev && npm run build" in packages/autocomplete');
+  }
+}