nebula-notebook 0.2.0 → 0.2.1

package/node-server/dist/routes/autocomplete.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disposeAutocompleteEngines = disposeAutocompleteEngines;
+exports.default = autocompleteRoutes;
+const child_process_1 = require("child_process");
+const environment_1 = require("../environment");
+const nebula_autocomplete_1 = require("nebula-autocomplete");
+const server_1 = require("nebula-autocomplete/server");
+const engines = new Map();
+/**
+ * Async command runner. NEVER use spawnSync here: these probes run ssh calls
+ * that can take 10+ seconds, and spawnSync freezes Node's event loop — which
+ * stalls EVERYTHING the server does (terminal WS input, API responses), felt
+ * as "the whole app is unresponsive for ~10s after a refresh".
+ */
+function runCmd(cmd, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let out = '';
+        let done = false;
+        const finish = (status) => { if (!done) {
+            done = true;
+            resolve({ status, stdout: out });
+        } };
+        let proc;
+        try {
+            proc = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        }
+        catch {
+            return finish(null);
+        }
+        const timer = setTimeout(() => { try {
+            proc.kill('SIGKILL');
+        }
+        catch { /* */ } finish(null); }, timeoutMs);
+        proc.stdout?.on('data', (d) => (out += d.toString()));
+        proc.on('error', () => { clearTimeout(timer); finish(null); });
+        proc.on('exit', (code) => { clearTimeout(timer); finish(code); });
+    });
+}
+async function binaryAvailable(name) {
+    return (await runCmd('which', [name], 3000)).status === 0;
+}
+/** Parse + validate a client-supplied transport (untrusted input). */
+function parseTransport(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const t = raw;
+    const port = Number(t.port);
+    const user = typeof t.user === 'string' ? t.user.trim() : '';
+    const bin = typeof t.bin === 'string' ? t.bin.trim() : '';
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return null;
+    if (!user || !/^[A-Za-z0-9._-]+$/.test(user))
+        return null;
+    if (!bin.startsWith('/'))
+        return null; // must be an absolute path
+    const host = typeof t.host === 'string' && t.host.trim() ? t.host.trim() : 'localhost';
+    return { port, user, bin, host };
+}
+function toSsh(t) {
+    return { kind: 'ssh', host: t.host ?? 'localhost', port: t.port, user: t.user, remoteBin: t.bin };
+}
+function sanitizeTuning(name, raw) {
+    // Experimental tuning surface: any shell-safe model id is allowed (it's the
+    // user's own CLI/subscription; a bad id just fails the worker's warmup
+    // visibly). Pattern-gated so nothing hostile reaches the spawn argv.
+    let model = typeof raw.model === 'string' ? raw.model.trim().toLowerCase() : '';
+    if (name === 'claude') {
+        // Default sonnet (was haiku): BENCHMARKED (eval/bench.mjs, 54 samples/config,
+        // interleaved) — sonnet ttfb p50 1086ms vs haiku 987ms (+10%, fixed API
+        // overhead dominates short completions) while fixing haiku's context
+        // failures (100% vs 94% ctx-accuracy). Thinking: on haiku it engages
+        // every turn (probed: ~1-1.5k chars) = 3-8s of non-streaming dead air; on
+        // sonnet MAX_THINKING_TOKENS never engages at all for completion-sized
+        // prompts (probed: 0 thinking chars, 4/4), so it can't help there either.
+        model = /^[a-z0-9][a-z0-9._:-]{0,63}$/.test(model) ? model : 'sonnet';
+    }
+    else
+        model = ''; // codex: fixed model
+    const rawTokens = Number(raw.thinkingTokens);
+    const thinkingTokens = Number.isFinite(rawTokens)
+        ? Math.min(16_000, Math.max(0, Math.round(rawTokens)))
+        : raw.thinking === true ? 4096 : 0;
+    return { model, thinkingTokens };
+}
+function engineKey(name, t, tune) {
+    const base = t ? `${name}:ssh:${t.user}@${t.host ?? 'localhost'}:${t.port}:${t.bin}` : name;
+    return `${base}:${tune.model}:${tune.thinkingTokens}`;
+}
+function getEngine(name, t, tune) {
+    const key = engineKey(name, t, tune);
+    let engine = engines.get(key);
+    if (!engine) {
+        const backend = name === 'codex'
+            ? new nebula_autocomplete_1.CodexBackend({
+                codexHome: t ? undefined : process.env.NEBULA_AUTOCOMPLETE_CODEX_HOME,
+                transport: t ? toSsh(t) : { kind: 'local' },
+            })
+            : new nebula_autocomplete_1.ClaudeBackend({
+                transport: t ? toSsh(t) : { kind: 'local' },
+                ...(tune.model ? { model: tune.model } : {}),
+                maxThinkingTokens: tune.thinkingTokens,
+            });
+        // contextBudget 20000: field testing showed 20k chars of context leaves
+        // latency essentially unchanged (worker history is prefix-cached; only the
+        // new message is uncached) — an earlier small A/B suggesting otherwise was
+        // cache/variance artifact. 20k covers the whole notebook in most cases;
+        // per-request overrides (Advanced settings) are clamped inside the engine.
+        engine = new nebula_autocomplete_1.AutocompleteEngine({ backend, contextBudget: 20_000 });
+        engines.set(key, engine);
+    }
+    return engine;
+}
+function disposeAutocompleteEngines() {
+    for (const engine of engines.values())
+        engine.dispose();
+    engines.clear();
+}
+/**
+ * Discover the absolute path of a provider CLI on the user's machine over the
+ * reverse tunnel (PATH isn't set for a non-interactive ssh, so running the CLI
+ * needs an absolute path). Uses a login shell + a sentinel so rc-file noise
+ * doesn't corrupt the result. Best-effort; returns null on any failure.
+ */
+async function discoverRemoteBin(port, user, provider, host = 'localhost') {
+    if (!Number.isInteger(port) || !/^[A-Za-z0-9._-]+$/.test(user))
+        return null;
+    // `whence -p` FIRST: on the user's machine `claude`/`codex` is typically a zsh
+    // FUNCTION, so `command -v` returns the function name (not a path) and would
+    // short-circuit. `whence -p` (zsh) resolves the actual binary; `command -v` is
+    // the fallback for non-zsh login shells (where `whence` doesn't exist).
+    const remote = `$SHELL -lic 'printf "NB_BIN=%s\\n" "$(whence -p ${provider} 2>/dev/null || command -v ${provider} 2>/dev/null)"' 2>/dev/null`;
+    const res = await runCmd('ssh', ['-p', String(port), '-o', 'ProxyCommand=none', '-o', 'StrictHostKeyChecking=accept-new',
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=8', `${user}@${host}`, remote], 12000);
+    if (res.status !== 0 || !res.stdout)
+        return null;
+    const line = res.stdout.split('\n').find((l) => l.startsWith('NB_BIN='));
+    const bin = line ? line.slice('NB_BIN='.length).trim() : '';
+    return bin.startsWith('/') ? bin : null;
+}
+/**
+ * Actually RUN a provider CLI on THIS server with a trivial prompt to tell
+ * "installed" from "usable" (logged in). Bounded + best-effort. Returns a status
+ * the diagnostics UI can render.
+ */
+async function checkCliUsable(name) {
+    if (!(await binaryAvailable(name)))
+        return { installed: false, usable: false, detail: 'not installed on this server' };
+    return new Promise((resolve) => {
+        const cfg = `/tmp/nebula-diag-${name}-${process.pid}-${Math.round(process.hrtime()[1])}`;
+        const args = name === 'claude'
+            ? ['-p', 'reply with just: ok', '--model', 'haiku']
+            : ['exec', '--json', '--skip-git-repo-check', '--sandbox', 'read-only', '--color', 'never', '--ephemeral', '-m', 'gpt-5.6-luna', 'reply ok'];
+        const env = { ...process.env, CLAUDE_CODE_MAX_OUTPUT_TOKENS: '64', CLAUDE_CONFIG_DIR: cfg };
+        let out = '', err = '', done = false;
+        const finish = (r) => { if (!done) {
+            done = true;
+            resolve(r);
+        } };
+        let proc;
+        try {
+            proc = (0, child_process_1.spawn)(name, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch {
+            return finish({ installed: true, usable: false, detail: 'failed to launch' });
+        }
+        const timer = setTimeout(() => { try {
+            proc.kill('SIGKILL');
+        }
+        catch { /* */ } finish({ installed: true, usable: false, detail: 'timed out (no response in 25s)' }); }, 25000);
+        proc.stdout?.on('data', (d) => (out += d.toString()));
+        proc.stderr?.on('data', (d) => (err += d.toString()));
+        proc.on('error', () => { clearTimeout(timer); finish({ installed: true, usable: false, detail: 'failed to launch' }); });
+        proc.on('exit', (code) => {
+            clearTimeout(timer);
+            const blob = (out + '\n' + err).toLowerCase();
+            const authIssue = /log ?in|logged in|authenticat|unauthor|oauth|api key|credit balance|subscription|setup-token|not authenticated/.test(blob);
+            if (authIssue)
+                return finish({ installed: true, usable: false, detail: 'not logged in on this server' });
+            if (code === 0 && out.trim())
+                return finish({ installed: true, usable: true, detail: 'logged in' });
+            return finish({ installed: true, usable: false, detail: err.trim().slice(-160) || `exited ${code}` });
+        });
+    });
+}
+async function autocompleteRoutes(fastify) {
+    /**
+     * Which CLI backends are usable on THIS server (for the settings UI and the
+     * editor's ghost-text gate). "Usable" means an actual trivial turn succeeds
+     * (logged in), not merely that the binary exists — a binary without
+     * credentials previously reported true here, so the UI enabled ghost text
+     * that could only ever produce "Not logged in" errors. The real probe costs
+     * a CLI round trip, so results are cached with a TTL.
+     */
+    let statusCache = null;
+    let statusProbe = null;
+    const STATUS_TTL_MS = 5 * 60_000;
+    fastify.get('/autocomplete/status', async (_req, reply) => {
+        if (!statusCache || Date.now() - statusCache.at > STATUS_TTL_MS) {
+            if (!statusProbe) {
+                statusProbe = Promise.all([checkCliUsable('claude'), checkCliUsable('codex')])
+                    .then(([claude, codex]) => {
+                    const backends = { claude: claude.usable, codex: codex.usable };
+                    statusCache = { at: Date.now(), backends };
+                    return backends;
+                })
+                    .finally(() => { statusProbe = null; });
+            }
+            await statusProbe;
+        }
+        return reply.send({
+            enabled: true,
+            backends: statusCache.backends,
+        });
+    });
+    /**
+     * Resolve the user's local CLI paths over the reverse tunnel, so the client
+     * can enable "run on my machine". Body: { port, user, host? }.
+     * Returns { ok, reachable, claude, codex }.
+     */
+    fastify.post('/autocomplete/probe-remote', async (req, reply) => {
+        const body = (req.body ?? {});
+        const port = Number(body.port);
+        const user = typeof body.user === 'string' ? body.user.trim() : '';
+        const host = typeof body.host === 'string' && body.host.trim() ? body.host.trim() : 'localhost';
+        if (!Number.isInteger(port) || port <= 0 || !user) {
+            return reply.code(400).send({ ok: false, error: 'port and user required' });
+        }
+        const [claude, codex] = await Promise.all([
+            discoverRemoteBin(port, user, 'claude', host),
+            discoverRemoteBin(port, user, 'codex', host),
+        ]);
+        return reply.send({ ok: true, reachable: claude !== null || codex !== null, claude, codex });
+    });
+    /**
+     * Comprehensive diagnostics for the settings "AI" tab. Body: { port?, user? }.
+     * Reports the environment, whether this server's CLIs are usable (logged in),
+     * and — if tunnel params are given — whether the user's machine is reachable
+     * and which CLIs resolve there.
+     */
+    fastify.post('/autocomplete/diagnose', async (req, reply) => {
+        const body = (req.body ?? {});
+        const port = Number(body.port);
+        const user = typeof body.user === 'string' ? body.user.trim() : '';
+        const host = typeof body.host === 'string' && body.host.trim() ? body.host.trim() : 'localhost';
+        const hasTunnel = Number.isInteger(port) && port > 0 && !!user;
+        const [claude, codex] = await Promise.all([checkCliUsable('claude'), checkCliUsable('codex')]);
+        let tunnel = null;
+        if (hasTunnel) {
+            const [rc, rx] = await Promise.all([
+                discoverRemoteBin(port, user, 'claude', host),
+                discoverRemoteBin(port, user, 'codex', host),
+            ]);
+            tunnel = { configured: true, reachable: rc !== null || rx !== null, claude: rc, codex: rx };
+        }
+        return reply.send({ environment: (0, environment_1.getEnvironment)(), server: { claude, codex }, tunnel });
+    });
+    /** POST /autocomplete — SSE stream. Body may include `transport` to run the
+     *  CLI on the user's machine instead of this server. */
+    (0, server_1.registerAutocompleteRoute)(fastify, (req) => {
+        const raw = req;
+        const name = req.backend === 'codex' ? 'codex' : 'claude';
+        const t = parseTransport(raw.transport);
+        return getEngine(name, t, sanitizeTuning(name, raw));
+    });
+    // Pre-warm the default local engine at server start: the first completion
+    // after a server (re)start otherwise pays engine creation + pool spawn +
+    // warmup turns on the user's keystroke (measured ~19s cold). Booting it
+    // here moves that entirely off the request path. Best-effort; claude only
+    // (the default backend — codex spawns per-request by design).
+    void binaryAvailable('claude').then((ok) => {
+        if (ok)
+            getEngine('claude', null, { model: 'sonnet', thinkingTokens: 0 });
+    }).catch(() => { });
+    fastify.addHook('onClose', async () => {
+        disposeAutocompleteEngines();
+    });
+}

package/node-server/dist/routes/fs.js

@@ -41,7 +41,7 @@ exports.default = fsRoutes;
 const fs_service_1 = require("../fs/fs-service");
 Object.defineProperty(exports, "fsService", { enumerable: true, get: function () { return fs_service_1.fsService; } });
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
+const private_tmp_1 = require("../private-tmp");
 const nodeFs = __importStar(require("fs"));
 async function fsRoutes(fastify) {
     /**
@@ -50,7 +50,7 @@ async function fsRoutes(fastify) {
     fastify.get('/fs/list', async (request, reply) => {
         try {
             const dirPath = request.query.path || '~';
-            const result = fs_service_1.fsService.listDirectory(dirPath);
+            const result = await fs_service_1.fsService.listDirectory(dirPath);
             return reply.send(result);
         }
         catch (err) {
@@ -319,10 +319,27 @@ async function fsRoutes(fastify) {
                 '.zip': 'application/zip',
             };
             const contentType = mimeTypes[extension] || 'application/octet-stream';
+            // Inline viewing (?inline=1): hand the file to the browser's own viewer
+            // in a new tab instead of forcing a download. Restricted to an allowlist
+            // of types the browser renders SAFELY as data (PDF/images/media/text).
+            // HTML is intentionally excluded — served inline same-origin, its JS
+            // could read the Nebula auth token; it goes through the trust-gated
+            // /?html= view instead. nosniff stops the browser from re-interpreting a
+            // mislabeled file as something executable.
+            const wantInline = request.query.inline === '1' || request.query.inline === 'true';
+            const INLINE_OK = new Set([
+                '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp', '.ico', '.avif',
+                '.mp4', '.webm', '.mov', '.m4v', '.ogv',
+                '.mp3', '.wav', '.ogg', '.oga', '.flac', '.m4a', '.aac',
+                '.txt', '.csv', '.tsv', '.log', '.json', '.md',
+            ]);
+            const inline = wantInline && INLINE_OK.has(extension);
+            const disposition = inline ? 'inline' : 'attachment';
             const stream = nodeFs.createReadStream(normalizedPath);
             return reply
                 .header('Content-Type', contentType)
-                .header('Content-Disposition', `attachment; filename="${filename}"`)
+                .header('X-Content-Type-Options', 'nosniff')
+                .header('Content-Disposition', `${disposition}; filename="${filename}"`)
                 .header('Content-Length', stat.size)
                 .send(stream);
         }
@@ -357,7 +374,7 @@ async function fsRoutes(fastify) {
                 return reply.code(400).send({ detail: 'path is required' });
             }
             // Save the uploaded file to a temp location first
-            const tmpPath = path.join(os.tmpdir(), `upload-${Date.now()}-${data.filename}`);
+            const tmpPath = path.join((0, private_tmp_1.privateTmpDir)('uploads'), `upload-${Date.now()}-${path.basename(data.filename || 'file')}`);
             const writeStream = nodeFs.createWriteStream(tmpPath);
             await new Promise((resolve, reject) => {
                 data.file.pipe(writeStream);

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

@@ -45,6 +45,8 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const kernel_service_1 = require("../kernel/kernel-service");
 const kernelspec_1 = require("../kernel/kernelspec");
+const discovery_service_1 = require("../discovery/discovery-service");
+const types_1 = require("../discovery/types");
 const fs_service_1 = require("../fs/fs-service");
 const operation_router_1 = require("../notebook/operation-router");
 const kernel_proxy_1 = require("../cluster/kernel-proxy");
@@ -109,7 +111,11 @@ kernelService.initialize().catch(err => {
     console.error('Failed to initialize kernel service:', err);
 });
 function buildKernelMetadata(kernelName) {
-    const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
+    // env: kernels have no on-disk spec — synthesize one, preferring the
+    // discovery cache's label ("Python 3.10 (conda: hypir)") over the raw path.
+    const envPython = (0, kernelspec_1.envKernelPythonPath)(kernelName);
+    const cachedLabel = envPython ? discovery_service_1.pythonDiscovery.getFromCache()?.[envPython]?.displayName : undefined;
+    const spec = (0, kernelspec_1.resolveKernelSpec)(kernelName, cachedLabel);
     return {
         kernelspec: {
             name: kernelName,
@@ -118,6 +124,20 @@ function buildKernelMetadata(kernelName) {
         },
     };
 }
+/**
+ * Map provisioning failures to structured responses (matching routes/python.ts)
+ * so the UI can branch on `code` — e.g. open the ipykernel install prompt —
+ * instead of parsing error prose. Returns true if the error was handled.
+ */
+function sendProvisionError(reply, err) {
+    if (!(err instanceof types_1.KernelProvisionError))
+        return false;
+    const status = err.code === 'python_not_found' ? 404
+        : err.code === 'externally_managed' || err.code === 'needs_ipykernel' ? 422
+            : 500;
+    reply.code(status).send({ detail: err.message, code: err.code, install_hint: err.installHint });
+    return true;
+}
 async function persistNotebookKernelMetadata(filePath, kernelName) {
     // Best-effort: persisting the kernel choice into the notebook's metadata is a
     // secondary side-effect. If it fails (e.g. the notebook file doesn't exist yet,
@@ -498,6 +518,8 @@ async function kernelRoutes(fastify) {
             return reply.send({ session_id: sessionId, kernel_name, server_id: localServerId, mtime: notebookMtime });
         }
         catch (err) {
+            if (sendProvisionError(reply, err))
+                return reply;
             const message = err instanceof Error ? err.message : 'Unknown error';
             return reply.code(500).send({ detail: message });
         }
@@ -526,7 +548,7 @@ async function kernelRoutes(fastify) {
      */
     fastify.post('/kernels/for-file', async (request, reply) => {
         try {
-            const { file_path, kernel_name = 'python3', server_id, client_origin } = request.body;
+            const { file_path, kernel_name, server_id, client_origin } = request.body;
             if (!file_path) {
                 return reply.code(400).send({ detail: 'file_path is required' });
             }
@@ -548,6 +570,25 @@ async function kernelRoutes(fastify) {
                     }
                 }
             }
+            // No explicit kernel and no saved preference: resolve from the
+            // notebook's own kernelspec metadata (headless callers — CLI/MCP —
+            // don't resolve it client-side the way the UI does). Only then fall
+            // back to python3.
+            if (!effectiveKernelName) {
+                try {
+                    const metadata = await fs_service_1.fsService.getNotebookMetadataAsync(normalizedFilePath);
+                    const specName = metadata.kernelspec?.name;
+                    if (specName) {
+                        effectiveKernelName = specName;
+                    }
+                }
+                catch {
+                    // fall through to the default
+                }
+            }
+            if (!effectiveKernelName) {
+                effectiveKernelName = 'python3';
+            }
             // Check if we should start on a remote server
             if (effectiveServerId && effectiveServerId !== localServerId && effectiveServerId !== 'local') {
                 // Start on remote server
@@ -594,6 +635,8 @@ async function kernelRoutes(fastify) {
             });
         }
         catch (err) {
+            if (sendProvisionError(reply, err))
+                return reply;
             const message = err instanceof Error ? err.message : 'Unknown error';
             return reply.code(500).send({ detail: message });
         }

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

@@ -87,6 +87,12 @@ async function notebookRoutes(fastify) {
                 return reply.code(400).send({ detail: 'cells is required' });
             }
             const result = await fs_service_1.fsService.saveNotebookBundle(filePath, cells, kernel_name, history);
+            // Outputs-unchanged sentinel couldn't be resolved against the file on
+            // disk (first save, changed ids, external rewrite…) — tell the client
+            // to resend the full payload.
+            if (!result.success && result.needsFull) {
+                return reply.code(409).send({ detail: 'unchanged-outputs sentinel unresolved; resend full payload', code: 'needs_full' });
+            }
             // The UI just wrote newer content than whatever the headless handler may
             // have cached. Drop the cache so headless ops (an agent working after the
             // user closes the tab) reload from disk instead of serving — or worse,
@@ -185,7 +191,7 @@ async function notebookRoutes(fastify) {
                 status: 'ok',
                 notebook_path,
                 mtime: result.mtime,
-                ...(result.status || fs_service_1.fsService.getAgentPermissionStatus(notebook_path)),
+                ...(result.status || await fs_service_1.fsService.getAgentPermissionStatusAsync(notebook_path)),
             });
         }
         catch (err) {
@@ -202,7 +208,7 @@ async function notebookRoutes(fastify) {
             if (!filePath) {
                 return reply.code(400).send({ detail: 'path query parameter is required' });
             }
-            const status = fs_service_1.fsService.getAgentPermissionStatus(filePath);
+            const status = await fs_service_1.fsService.getAgentPermissionStatusAsync(filePath);
             return reply.send({
                 notebook_path: filePath,
                 ...status,

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

@@ -2,7 +2,6 @@
  * Python Discovery API Routes
  */
 import { FastifyInstance } from 'fastify';
-import { PythonDiscoveryService } from '../discovery/discovery-service';
-declare const discoveryService: PythonDiscoveryService;
+declare const discoveryService: import("../discovery/discovery-service").PythonDiscoveryService;
 export default function pythonRoutes(fastify: FastifyInstance): Promise<void>;
 export { discoveryService };

package/node-server/dist/routes/python.js

@@ -11,7 +11,10 @@ const kernelspec_1 = require("../kernel/kernelspec");
 const default_kernel_1 = require("../kernel/default-kernel");
 const server_registry_1 = require("../cluster/server-registry");
 const kernel_1 = require("./kernel");
-const discoveryService = new discovery_service_1.PythonDiscoveryService();
+// The shared singleton — kernel-service preflight/labels and per-env
+// kernelspec scanning read its in-memory cache, so routes must write through
+// the SAME instance (a second instance would leave the singleton stale).
+const discoveryService = discovery_service_1.pythonDiscovery;
 exports.discoveryService = discoveryService;
 async function pythonRoutes(fastify) {
     /**
@@ -41,6 +44,9 @@ async function pythonRoutes(fastify) {
                 const data = await response.json();
                 return reply.send(data);
             }
+            // Discover Python environments FIRST: kernelspec discovery also scans
+            // each known env's share/jupyter/kernels, so it must see the fresh list.
+            const environments = await discoveryService.discover({ forceRefresh: refresh });
             // Get Jupyter kernelspecs and transform to snake_case
             const kernelspecs = (0, kernelspec_1.discoverKernelSpecs)(refresh).map(k => ({
                 name: k.name,
@@ -50,8 +56,6 @@ async function pythonRoutes(fastify) {
                 python_path: k.argv?.[0] || null, // First element of argv is typically the Python executable
             }));
             const kernelspecNames = new Set(kernelspecs.map(k => k.name));
-            // Get discovered Python environments
-            const environments = await discoveryService.discover({ forceRefresh: refresh });
             // Convert to snake_case and match with kernelspecs
             const envObjects = environments.map(env => ({
                 path: env.path,
@@ -75,6 +79,138 @@ async function pythonRoutes(fastify) {
             return reply.code(500).send({ detail: message });
         }
     });
+    /**
+     * Install ipykernel into an environment (no kernelspec registration — env
+     * kernels raw-launch). One installer chosen up front (conda → uv → pip).
+     *
+     * Responds with an NDJSON stream so the UI can show installer output LIVE:
+     *   {"type":"output","data":"…"}    — stdout/stderr chunks as they arrive
+     *   {"type":"done","installer":…}   — success terminator
+     *   {"type":"error","detail":…,"code":…,"install_hint":…} — failure terminator
+     * Pre-stream validation failures are plain JSON error responses.
+     */
+    fastify.post('/python/install-ipykernel', async (request, reply) => {
+        const { python_path, server_id } = request.body;
+        if (!python_path) {
+            return reply.code(400).send({ detail: 'python_path is required' });
+        }
+        const localServerId = server_registry_1.serverRegistry.getLocalServerId();
+        if (server_id && server_id !== localServerId && server_id !== 'local') {
+            const server = server_registry_1.serverRegistry.getServer(server_id);
+            if (!server) {
+                return reply.code(404).send({ detail: `Server not found: ${server_id}` });
+            }
+            if (server.status !== 'online') {
+                return reply.code(503).send({ detail: `Server is offline: ${server_id}` });
+            }
+            const response = await fetch(`${server.url}/api/python/install-ipykernel`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(process.env.NEBULA_CLUSTER_SECRET ? { 'X-Nebula-Cluster-Secret': process.env.NEBULA_CLUSTER_SECRET } : {}),
+                },
+                body: JSON.stringify({ python_path }),
+            });
+            if (!response.ok || !response.body) {
+                const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+                return reply.code(response.status).send({
+                    detail: error.detail || 'Failed to install ipykernel',
+                    code: error.code,
+                    install_hint: error.install_hint,
+                });
+            }
+            // Pipe the remote NDJSON stream through untouched.
+            reply.hijack();
+            reply.raw.writeHead(200, { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-cache' });
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                for await (const chunk of response.body) {
+                    reply.raw.write(chunk);
+                }
+            }
+            catch { /* upstream died — terminate what we have */ }
+            reply.raw.end();
+            return reply;
+        }
+        // Local install: stream output as it happens, then a terminator event.
+        reply.hijack();
+        reply.raw.writeHead(200, { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-cache' });
+        const send = (obj) => reply.raw.write(`${JSON.stringify(obj)}\n`);
+        try {
+            const result = await discoveryService.installIpykernel(python_path, (chunk) => send({ type: 'output', data: chunk }));
+            send({ type: 'done', installer: result.installer, message: result.message, python_path });
+        }
+        catch (err) {
+            if (err instanceof types_1.KernelProvisionError) {
+                send({ type: 'error', detail: err.message, code: err.code, install_hint: err.installHint });
+            }
+            else {
+                send({ type: 'error', detail: err instanceof Error ? err.message : 'Unknown error' });
+            }
+        }
+        reply.raw.end();
+        return reply;
+    });
+    /**
+     * Probe a manually-entered interpreter path ("Enter interpreter path…"):
+     * validate it runs, classify + enrich it, persist it into the discovery
+     * cache, and return it in the same snake_case shape as /python/environments.
+     */
+    fastify.post('/python/probe', async (request, reply) => {
+        try {
+            const { python_path, server_id } = request.body;
+            if (!python_path) {
+                return reply.code(400).send({ detail: 'python_path is required' });
+            }
+            const localServerId = server_registry_1.serverRegistry.getLocalServerId();
+            if (server_id && server_id !== localServerId && server_id !== 'local') {
+                const server = server_registry_1.serverRegistry.getServer(server_id);
+                if (!server) {
+                    return reply.code(404).send({ detail: `Server not found: ${server_id}` });
+                }
+                if (server.status !== 'online') {
+                    return reply.code(503).send({ detail: `Server is offline: ${server_id}` });
+                }
+                const response = await fetch(`${server.url}/api/python/probe`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(process.env.NEBULA_CLUSTER_SECRET ? { 'X-Nebula-Cluster-Secret': process.env.NEBULA_CLUSTER_SECRET } : {}),
+                    },
+                    body: JSON.stringify({ python_path }),
+                });
+                if (!response.ok) {
+                    const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+                    return reply.code(response.status).send({
+                        detail: error.detail || 'Failed to probe interpreter',
+                        code: error.code,
+                        install_hint: error.install_hint,
+                    });
+                }
+                return reply.send(await response.json());
+            }
+            const env = await discoveryService.probeAndRemember(python_path);
+            return reply.send({
+                path: env.path,
+                version: env.version,
+                display_name: env.displayName,
+                env_type: env.envType,
+                env_name: env.envName,
+                has_ipykernel: env.hasIpykernel,
+                externally_managed: env.externallyManaged,
+                install_hint: env.installHint,
+                kernel_name: env.kernelName,
+            });
+        }
+        catch (err) {
+            if (err instanceof types_1.KernelProvisionError) {
+                const status = err.code === 'python_not_found' ? 404 : 500;
+                return reply.code(status).send({ detail: err.message, code: err.code, install_hint: err.installHint });
+            }
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            return reply.code(500).send({ detail: message });
+        }
+    });
     /**
      * Install ipykernel and register a Python environment as a Jupyter kernel
      */