nebula-notebook 0.2.0 → 0.2.2

package/node-server/dist/kernel/kernel-service.js

@@ -40,6 +40,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.kernelService = exports.KernelService = exports.IOPUB_QUEUE_TIMEOUT = exports.IOPUB_QUEUE_CLOSED = void 0;
+exports.rewriteShellLines = rewriteShellLines;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -53,7 +54,10 @@ const types_1 = require("./types");
 const display_data_1 = require("../output/display-data");
 const output_limits_1 = require("../config/output-limits");
 const session_store_1 = require("./session-store");
+const private_tmp_1 = require("../private-tmp");
 const kernelspec_1 = require("./kernelspec");
+const discovery_service_1 = require("../discovery/discovery-service");
+const types_2 = require("../discovery/types");
 /** Resolved by BoundedAsyncQueue.next() when the queue has been closed. */
 exports.IOPUB_QUEUE_CLOSED = Symbol('iopub-queue-closed');
 /** Resolved by BoundedAsyncQueue.next(timeoutMs) when the wait timed out. */
@@ -139,6 +143,41 @@ class BoundedAsyncQueue {
         }
     }
 }
+/**
+ * Polyfill IPython-style `!command` lines for kernels whose language lacks
+ * them, by rewriting each such line into the language's own shell-call idiom
+ * before the code reaches the kernel. Because the rewritten code still runs
+ * in the kernel process, cwd, environment (conda env, loaded modules), and
+ * machine (allocation node) are all the kernel's — the same guarantees
+ * IPython's native `!` gives Python users.
+ *
+ * Python kernels are deliberately untouched: IPython's `!` is richer than a
+ * plain shell call (output capture `x = !ls`, `{var}` interpolation,
+ * streaming output) and a rewrite would break it.
+ *
+ * Only whole lines that start with `!` are rewritten. Known limits (v1):
+ * a line inside a multi-line string that happens to start with `!` would be
+ * rewritten too, and R's intern=TRUE buffers output until the command exits.
+ */
+function rewriteShellLines(code, language) {
+    const lang = (language || '').toLowerCase();
+    if (lang !== 'r')
+        return code; // python: native support; others: no safe idiom mapped yet
+    if (!/^[ \t]*!/m.test(code))
+        return code;
+    return code
+        .split('\n')
+        .map((line) => {
+        const m = line.match(/^([ \t]*)!(.+)$/);
+        if (!m)
+            return line;
+        // Merge stderr at the shell level — intern=TRUE captures only stdout.
+        const cmd = `${m[2].trim()} 2>&1`;
+        const rString = cmd.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        return `${m[1]}cat(system("${rString}", intern = TRUE), sep = "\\n")`;
+    })
+        .join('\n');
+}
 class KernelService {
     sessions = new Map();
     fileToSession = new Map();
@@ -573,8 +612,9 @@ class KernelService {
             hbPort,
         };
         // Write connection file
-        const connDir = path.join(os.tmpdir(), 'nebula-kernels');
-        fs.mkdirSync(connDir, { recursive: true });
+        // Per-user private dir (0700): connection files carry the HMAC key —
+        // world-readable means arbitrary code execution as this user.
+        const connDir = (0, private_tmp_1.privateTmpDir)('kernels');
         const connFile = path.join(connDir, `kernel-${sessionId}.json`);
         const connData = {
             ip: config.ip,
@@ -587,7 +627,7 @@ class KernelService {
             iopub_port: config.iopubPort,
             hb_port: config.hbPort,
         };
-        fs.writeFileSync(connFile, JSON.stringify(connData, null, 2));
+        fs.writeFileSync(connFile, JSON.stringify(connData, null, 2), { mode: 0o600 });
         return { config, filePath: connFile };
     }
     /**
@@ -595,7 +635,27 @@ class KernelService {
      */
     async startKernel(options = {}) {
         const kernelName = options.kernelName || 'python3';
-        const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+        // env:<pythonPath> kernels raw-launch a Python environment directly
+        // (VSCode-style) — no kernelspec registration involved. Preflight here so
+        // callers get a crisp, coded error instead of a spawn failure + ready
+        // timeout: python_not_found for a dead path, needs_ipykernel (with an
+        // ecosystem-appropriate install hint) when the env can't host a kernel yet.
+        const envPython = (0, kernelspec_1.envKernelPythonPath)(kernelName);
+        let spec;
+        if (envPython) {
+            if (!fs.existsSync(envPython)) {
+                throw new types_2.KernelProvisionError(`Python not found: ${envPython}`, 'python_not_found');
+            }
+            const probe = await discovery_service_1.pythonDiscovery.probeForKernel(envPython);
+            if (!probe.hasIpykernel) {
+                throw new types_2.KernelProvisionError(`ipykernel is not installed in ${envPython}`, 'needs_ipykernel', probe.installHint || undefined);
+            }
+            const cached = discovery_service_1.pythonDiscovery.getFromCache()?.[envPython];
+            spec = (0, kernelspec_1.makeEnvKernelSpec)(envPython, cached?.displayName);
+        }
+        else {
+            spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+        }
         if (!spec) {
             throw new Error(`Kernel '${kernelName}' not found`);
         }
@@ -1349,6 +1409,14 @@ class KernelService {
      * Execute code in a kernel session
      */
     async executeCode(sessionId, code, onOutput, onQueueInfo, cellId) {
+        // Polyfill `!command` lines for kernels whose language lacks them (see
+        // rewriteShellLines) — rewritten code still runs IN the kernel process,
+        // so cwd/env/node are the kernel's, exactly like IPython's native `!`.
+        {
+            const kernelName = this.sessions.get(sessionId)?.kernelName;
+            const spec = kernelName ? (0, kernelspec_1.getKernelSpec)(kernelName) : null;
+            code = rewriteShellLines(code, spec?.language);
+        }
         const queueInfo = this.reserveExecutionSlot(sessionId);
         if (onQueueInfo) {
             onQueueInfo(queueInfo);

package/node-server/dist/kernel/kernelspec.d.ts

@@ -10,6 +10,16 @@ export type { KernelSpec } from './types';
  * Standard kernelspec search paths
  */
 export declare function getKernelSearchPaths(): string[];
+/**
+ * Read kernelspecs from a list of `…/kernels` directories. `seen` dedupes by
+ * kernel name across calls (first path wins — Jupyter precedence order).
+ */
+export declare function readKernelSpecsFromPaths(searchPaths: string[], options?: {
+    skipDefaultPythonSpecs?: boolean;
+    seen?: Set<string>;
+}): KernelSpec[];
+/** The `share/jupyter/kernels` dir belonging to each interpreter's prefix. */
+export declare function envKernelspecDirs(envPythonPaths: string[]): string[];
 /**
  * Discover all available kernelspecs on the system
  * Uses 60-second in-memory cache to avoid repeated disk I/O
@@ -23,6 +33,23 @@ export declare function invalidateKernelspecCache(): void;
  * Get a specific kernelspec by name
  */
 export declare function getKernelSpec(name: string): KernelSpec | null;
+/**
+ * Env kernels (VSCode-style raw launch): any Python environment can be used
+ * as a kernel WITHOUT registering a kernelspec on disk. The kernel name
+ * `env:<pythonPath>` resolves to a synthetic in-memory spec that launches
+ * `<python> -m ipykernel_launcher` directly — only ipykernel needs to be
+ * importable in the environment; jupyter itself is never required.
+ */
+export declare const ENV_KERNEL_PREFIX = "env:";
+export declare function isEnvKernelName(name: string): boolean;
+/** The interpreter path encoded in an env: kernel name, or null. */
+export declare function envKernelPythonPath(name: string): string | null;
+export declare function makeEnvKernelSpec(pythonPath: string, displayName?: string): KernelSpec;
+/**
+ * Resolve a kernel name to a spec: env: names produce a synthetic raw-launch
+ * spec, anything else falls back to registered kernelspecs on disk.
+ */
+export declare function resolveKernelSpec(name: string, displayName?: string): KernelSpec | null;
 /**
  * Check if a kernelspec exists
  */

package/node-server/dist/kernel/kernelspec.js

@@ -39,14 +39,23 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_KERNEL_PREFIX = void 0;
 exports.getKernelSearchPaths = getKernelSearchPaths;
+exports.readKernelSpecsFromPaths = readKernelSpecsFromPaths;
+exports.envKernelspecDirs = envKernelspecDirs;
 exports.discoverKernelSpecs = discoverKernelSpecs;
 exports.invalidateKernelspecCache = invalidateKernelspecCache;
 exports.getKernelSpec = getKernelSpec;
+exports.isEnvKernelName = isEnvKernelName;
+exports.envKernelPythonPath = envKernelPythonPath;
+exports.makeEnvKernelSpec = makeEnvKernelSpec;
+exports.resolveKernelSpec = resolveKernelSpec;
 exports.hasKernelSpec = hasKernelSpec;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+const discovery_service_1 = require("../discovery/discovery-service");
+const conda_locations_1 = require("../discovery/conda-locations");
 // In-memory cache for kernelspecs (avoids repeated disk I/O)
 let kernelspecCache = null;
 let kernelspecCacheTime = 0;
@@ -139,12 +148,19 @@ function readKernelSpec(kernelDir) {
     }
 }
 /**
- * Perform actual kernelspec discovery (disk I/O)
+ * Auto-registered default python specs (`python3`, `python3.11`, …) inside an
+ * environment duplicate what the env row in the picker already offers ("run
+ * Python here") — showing N identical "Python 3 (ipykernel)" entries would
+ * drown the real kernels. VSCode hides these the same way.
  */
-function performKernelspecDiscovery() {
+const DEFAULT_PYTHON_SPEC_RE = /^python\d*(\.\d+)*$/i;
+/**
+ * Read kernelspecs from a list of `…/kernels` directories. `seen` dedupes by
+ * kernel name across calls (first path wins — Jupyter precedence order).
+ */
+function readKernelSpecsFromPaths(searchPaths, options = {}) {
     const specs = [];
-    const seenNames = new Set();
-    const searchPaths = getKernelSearchPaths();
+    const seenNames = options.seen ?? new Set();
     for (const searchPath of searchPaths) {
         if (!fs.existsSync(searchPath)) {
             continue;
@@ -159,6 +175,9 @@ function performKernelspecDiscovery() {
                 if (seenNames.has(kernelName)) {
                     continue;
                 }
+                if (options.skipDefaultPythonSpecs && DEFAULT_PYTHON_SPEC_RE.test(kernelName)) {
+                    continue;
+                }
                 const kernelDir = path.join(searchPath, kernelName);
                 const spec = readKernelSpec(kernelDir);
                 if (spec) {
@@ -173,6 +192,24 @@ function performKernelspecDiscovery() {
     }
     return specs;
 }
+/** The `share/jupyter/kernels` dir belonging to each interpreter's prefix. */
+function envKernelspecDirs(envPythonPaths) {
+    const dirs = envPythonPaths.map(p => path.join((0, conda_locations_1.prefixForPythonExe)(p), 'share', 'jupyter', 'kernels'));
+    return [...new Set(dirs)];
+}
+/**
+ * Perform actual kernelspec discovery (disk I/O): the standard Jupyter search
+ * paths first, then every discovered Python environment's own
+ * share/jupyter/kernels (how conda-installed kernels like R/Julia surface) —
+ * with each env's redundant default python spec hidden.
+ */
+function performKernelspecDiscovery() {
+    const seen = new Set();
+    const specs = readKernelSpecsFromPaths(getKernelSearchPaths(), { seen });
+    const envPaths = Object.keys(discovery_service_1.pythonDiscovery.getFromCache() ?? {});
+    specs.push(...readKernelSpecsFromPaths(envKernelspecDirs(envPaths), { seen, skipDefaultPythonSpecs: true }));
+    return specs;
+}
 /**
  * Discover all available kernelspecs on the system
  * Uses 60-second in-memory cache to avoid repeated disk I/O
@@ -202,6 +239,40 @@ function getKernelSpec(name) {
     const specs = discoverKernelSpecs();
     return specs.find(s => s.name === name) || null;
 }
+/**
+ * Env kernels (VSCode-style raw launch): any Python environment can be used
+ * as a kernel WITHOUT registering a kernelspec on disk. The kernel name
+ * `env:<pythonPath>` resolves to a synthetic in-memory spec that launches
+ * `<python> -m ipykernel_launcher` directly — only ipykernel needs to be
+ * importable in the environment; jupyter itself is never required.
+ */
+exports.ENV_KERNEL_PREFIX = 'env:';
+function isEnvKernelName(name) {
+    return name.startsWith(exports.ENV_KERNEL_PREFIX);
+}
+/** The interpreter path encoded in an env: kernel name, or null. */
+function envKernelPythonPath(name) {
+    return isEnvKernelName(name) ? name.slice(exports.ENV_KERNEL_PREFIX.length) : null;
+}
+function makeEnvKernelSpec(pythonPath, displayName) {
+    return {
+        name: exports.ENV_KERNEL_PREFIX + pythonPath,
+        displayName: displayName || `Python (${pythonPath})`,
+        language: 'python',
+        path: '', // synthetic — no kernelspec directory on disk
+        argv: [pythonPath, '-m', 'ipykernel_launcher', '-f', '{connection_file}'],
+    };
+}
+/**
+ * Resolve a kernel name to a spec: env: names produce a synthetic raw-launch
+ * spec, anything else falls back to registered kernelspecs on disk.
+ */
+function resolveKernelSpec(name, displayName) {
+    const pythonPath = envKernelPythonPath(name);
+    if (pythonPath)
+        return makeEnvKernelSpec(pythonPath, displayName);
+    return getKernelSpec(name);
+}
 /**
  * Check if a kernelspec exists
  */

package/node-server/dist/notebook/headless-handler.d.ts

@@ -45,6 +45,16 @@ export declare class HeadlessOperationHandler {
      * Get notebook from cache, loading from disk if needed.
      */
     private getCachedNotebook;
+    /** In-flight cache warm-ups per notebook path (single-flight). */
+    private warming;
+    /**
+     * Warm the notebook + undo-history caches with non-blocking I/O. The sync
+     * fallback in getCachedNotebook blocks the event loop on a cache miss — on
+     * a network filesystem a large notebook + history read stalls every
+     * in-flight request (kernel completions included) for seconds. Entry points
+     * await this first so the sync accessors below are pure in-memory hits.
+     */
+    private ensureCached;
     private getCells;
     private getVisibleOutputs;
     private saveCells;

package/node-server/dist/notebook/headless-handler.js

@@ -43,7 +43,7 @@ exports.HeadlessOperationHandler = void 0;
 const fs = __importStar(require("fs"));
 const cell_hash_1 = require("./cell-hash");
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
+const private_tmp_1 = require("../private-tmp");
 const uuid_1 = require("uuid");
 const registry_1 = require("../fs/notebook-formats/registry");
 const cell_metadata_1 = require("./cell-metadata");
@@ -90,6 +90,37 @@ class HeadlessOperationHandler {
         }
         return this.cache.get(notebookPath);
     }
+    /** In-flight cache warm-ups per notebook path (single-flight). */
+    warming = new Map();
+    /**
+     * Warm the notebook + undo-history caches with non-blocking I/O. The sync
+     * fallback in getCachedNotebook blocks the event loop on a cache miss — on
+     * a network filesystem a large notebook + history read stalls every
+     * in-flight request (kernel completions included) for seconds. Entry points
+     * await this first so the sync accessors below are pure in-memory hits.
+     */
+    ensureCached(notebookPath) {
+        if (!notebookPath || this.cache.has(notebookPath))
+            return Promise.resolve();
+        const inflight = this.warming.get(notebookPath);
+        if (inflight)
+            return inflight;
+        const run = (async () => {
+            const result = await this.fsService.getNotebookCells(notebookPath);
+            if (!this.cache.has(notebookPath)) {
+                this.cache.set(notebookPath, {
+                    cells: result.cells || [],
+                    metadata: result.metadata || {},
+                    dirty: false,
+                });
+            }
+            await this.undoRedoManager.warm(notebookPath, this.cache.get(notebookPath).cells);
+        })().finally(() => {
+            this.warming.delete(notebookPath);
+        });
+        this.warming.set(notebookPath, run);
+        return run;
+    }
     getCells(notebookPath) {
         return this.getCachedNotebook(notebookPath).cells;
     }
@@ -176,8 +207,8 @@ class HeadlessOperationHandler {
     /**
      * Check if agent has permission to modify this notebook.
      */
-    checkAgentPermission(notebookPath, _operationType) {
-        const status = this.fsService.getAgentPermissionStatus(notebookPath);
+    async checkAgentPermission(notebookPath, _operationType) {
+        const status = await this.fsService.getAgentPermissionStatusAsync(notebookPath);
         // can_agent_modify already encodes the tri-state rule (agent-created notebooks
         // are permitted unless explicitly revoked; user notebooks need permission +
         // history), so an explicit user revoke wins even for agent-created notebooks.
@@ -252,9 +283,20 @@ class HeadlessOperationHandler {
         // Read-only operations
         const readOnlyOps = new Set(['readCell', 'readCellOutput', 'searchCells', 'getUpdatesSince', 'startAgentSession', 'endAgentSession']);
         const permissionExemptOps = new Set(['createNotebook', 'readCell', 'readCellOutput', 'searchCells', 'getUpdatesSince', 'startAgentSession', 'endAgentSession']);
+        // Warm the notebook/history caches without blocking the event loop before
+        // any sync accessor below runs. createNotebook targets a file that may
+        // not exist yet; a failed warm defers to the operation's own error.
+        if (notebookPath && opType !== 'createNotebook') {
+            try {
+                await this.ensureCached(notebookPath);
+            }
+            catch {
+                // Operation handlers report missing/corrupt notebooks themselves
+            }
+        }
         // Check permission for write operations
         if (!permissionExemptOps.has(opType) && notebookPath) {
-            const permissionError = this.checkAgentPermission(notebookPath, opType);
+            const permissionError = await this.checkAgentPermission(notebookPath, opType);
             if (permissionError) {
                 return permissionError;
             }
@@ -385,6 +427,14 @@ class HeadlessOperationHandler {
      */
     async readNotebook(notebookPath, includeOutputs = true, maxLines, maxChars, maxLinesError, maxCharsError) {
         try {
+            // Non-blocking cache warm-up; on failure the sync accessor below
+            // produces the proper error (e.g. notebook not found).
+            try {
+                await this.ensureCached(notebookPath);
+            }
+            catch {
+                // fall through to getCachedNotebook's own error handling
+            }
             const notebook = this.getCachedNotebook(notebookPath);
             let cells = notebook.cells;
             if (includeOutputs) {
@@ -1034,7 +1084,7 @@ class HeadlessOperationHandler {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
     saveOutputToTempFile(content, cellId) {
-        const tempDir = path.join(os.tmpdir(), 'nebula', 'outputs');
+        const tempDir = (0, private_tmp_1.privateTmpDir)('outputs');
         if (!fs.existsSync(tempDir)) {
             fs.mkdirSync(tempDir, { recursive: true });
         }

package/node-server/dist/notebook/undoRedoManager.d.ts

@@ -139,6 +139,14 @@ export declare class HeadlessUndoRedoManager {
      * Get or initialize undo state for a notebook.
      */
     getState(notebookPath: string, cells: NebulaCell[]): NotebookUndoState;
+    /**
+     * Preload a notebook's history without blocking the event loop. After this
+     * resolves, getState is a pure in-memory hit — its loadHistorySync fallback
+     * (a large journal read that stalls every in-flight request on a network
+     * filesystem) never fires. No-op if state already exists.
+     */
+    warm(notebookPath: string, cells: NebulaCell[]): Promise<void>;
+    private initState;
     /**
      * Rebuild undo stack from history.
      */

package/node-server/dist/notebook/undoRedoManager.js

@@ -147,25 +147,48 @@ class HeadlessUndoRedoManager {
             catch (err) {
                 console.warn(`[UndoRedoManager] Failed to load history for ${notebookPath}:`, err);
             }
-            // Initialize state
-            const state = {
-                undoStack: [],
-                redoStack: [],
-                fullHistory: loadedHistory.length > 0 ? loadedHistory : [{
-                        type: 'snapshot',
-                        cells: cells.map(stripCellOutputs),
-                        timestamp: Date.now()
-                    }],
-                lastContent: new Map(cells.map(c => [c.id, c.content]))
-            };
-            // Rebuild undo stack from history
-            if (loadedHistory.length > 0) {
-                state.undoStack = this.rebuildUndoStack(loadedHistory);
-            }
-            this.states.set(notebookPath, state);
+            this.initState(notebookPath, cells, loadedHistory);
         }
         return this.states.get(notebookPath);
     }
+    /**
+     * Preload a notebook's history without blocking the event loop. After this
+     * resolves, getState is a pure in-memory hit — its loadHistorySync fallback
+     * (a large journal read that stalls every in-flight request on a network
+     * filesystem) never fires. No-op if state already exists.
+     */
+    async warm(notebookPath, cells) {
+        if (this.states.has(notebookPath))
+            return;
+        let loadedHistory = [];
+        try {
+            loadedHistory = (await this.fsService.loadHistory(notebookPath));
+        }
+        catch (err) {
+            console.warn(`[UndoRedoManager] Failed to load history for ${notebookPath}:`, err);
+        }
+        // A concurrent sync getState may have initialized while we awaited
+        if (this.states.has(notebookPath))
+            return;
+        this.initState(notebookPath, cells, loadedHistory);
+    }
+    initState(notebookPath, cells, loadedHistory) {
+        const state = {
+            undoStack: [],
+            redoStack: [],
+            fullHistory: loadedHistory.length > 0 ? loadedHistory : [{
+                    type: 'snapshot',
+                    cells: cells.map(stripCellOutputs),
+                    timestamp: Date.now()
+                }],
+            lastContent: new Map(cells.map(c => [c.id, c.content]))
+        };
+        // Rebuild undo stack from history
+        if (loadedHistory.length > 0) {
+            state.undoStack = this.rebuildUndoStack(loadedHistory);
+        }
+        this.states.set(notebookPath, state);
+    }
     /**
      * Rebuild undo stack from history.
      */

package/node-server/dist/private-tmp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Per-user private temp directories.
+ *
+ * Shared paths like /tmp/nebula-kernels break on multi-user machines twice
+ * over: the first user's mkdir (with a restrictive umask) locks everyone else
+ * out, and anything world-readable leaks — kernel connection files carry the
+ * HMAC key, which is remote code execution as the kernel's owner for anyone
+ * who can read it.
+ *
+ * Layout: <tmpdir>/nebula-<username>/<segments...>, mode 0700 throughout.
+ * /tmp is sticky, so another user CAN pre-create our directory name — we
+ * verify ownership after mkdir and refuse to use a directory we don't own.
+ */
+export declare function privateTmpDir(...segments: string[]): string;

package/node-server/dist/private-tmp.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Per-user private temp directories.
+ *
+ * Shared paths like /tmp/nebula-kernels break on multi-user machines twice
+ * over: the first user's mkdir (with a restrictive umask) locks everyone else
+ * out, and anything world-readable leaks — kernel connection files carry the
+ * HMAC key, which is remote code execution as the kernel's owner for anyone
+ * who can read it.
+ *
+ * Layout: <tmpdir>/nebula-<username>/<segments...>, mode 0700 throughout.
+ * /tmp is sticky, so another user CAN pre-create our directory name — we
+ * verify ownership after mkdir and refuse to use a directory we don't own.
+ */
+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.privateTmpDir = privateTmpDir;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function privateTmpDir(...segments) {
+    const user = (os.userInfo().username || String(process.getuid?.() ?? 'user'))
+        .replace(/[^a-zA-Z0-9._-]/g, '_');
+    const root = path.join(os.tmpdir(), `nebula-${user}`);
+    const dir = path.join(root, ...segments);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32' && typeof process.getuid === 'function') {
+        const st = fs.statSync(root);
+        if (st.uid !== process.getuid()) {
+            throw new Error(`${root} exists but is owned by uid ${st.uid}, not us (${process.getuid()}) — ` +
+                `refusing to write private files into another user's directory. Remove or rename it.`);
+        }
+        // mkdirSync's mode is filtered by umask and ignored for pre-existing dirs;
+        // assert the closed mode explicitly.
+        fs.chmodSync(root, 0o700);
+    }
+    return dir;
+}

package/node-server/dist/routes/autocomplete.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AI autocomplete API — inline code completions for notebook cells.
+ *
+ * Routes live under /api and are auth-protected like the rest of the API.
+ * Backed by the nebula-autocomplete engine, which drives a Claude Code / Codex
+ * CLI using the user's own subscription. The CLI can run in one of two places:
+ *
+ *   - on THIS server (default) — when the Nebula host itself has claude/codex
+ *     (a local install, or a login node where the CLIs are available);
+ *   - on the USER'S machine over the reverse SSH tunnel ("run on my machine") —
+ *     for remote Nebula where the user would rather use their own laptop's CLI +
+ *     subscription. See the `transport` field on the completion request.
+ *
+ * Engines are created lazily and cached per (backend, transport) so a warm pool
+ * is reused across turns; disposed on server shutdown.
+ */
+import { FastifyInstance } from 'fastify';
+export declare function disposeAutocompleteEngines(): void;
+export default function autocompleteRoutes(fastify: FastifyInstance): Promise<void>;