nebula-notebook 0.2.21 → 0.2.23

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

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = computeRoutes;
 const os = __importStar(require("os"));
 const allocation_service_1 = require("../scheduler/allocation-service");
+const arm_setup_prompt_1 = require("../scheduler/arm-setup-prompt");
 function currentUser() {
     return process.env.USER || process.env.LOGNAME || os.userInfo().username;
 }
@@ -105,6 +106,19 @@ async function computeRoutes(fastify) {
         const estimate = await sched.estimateStart(spec);
         return reply.send(estimate);
     });
+    /**
+     * Agent-executable ARM setup: this installation's facts + a rendered prompt
+     * the user pastes to an agent. configured=true means an arm64 runtime is
+     * already wired in (the UI then shows nothing).
+     */
+    fastify.get('/compute/arm-setup', async (_req, reply) => {
+        const sched = allocation_service_1.allocationService.getScheduler();
+        const ctx = allocation_service_1.allocationService.getLaunchContext();
+        if (!sched || !ctx)
+            return reply.code(400).send({ error: 'scheduler not available' });
+        const facts = await (0, arm_setup_prompt_1.gatherArmSetupFacts)(sched, ctx);
+        return reply.send({ configured: facts.configured, prompt: (0, arm_setup_prompt_1.buildArmSetupPrompt)(facts), facts });
+    });
     /** List current allocations (pending / running / active / ended). */
     fastify.get('/compute/allocations', async (_req, reply) => {
         return reply.send({ allocations: allocation_service_1.allocationService.list() });

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

@@ -8,6 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.headlessHandler = exports.operationRouter = exports.fsService = void 0;
 exports.default = notebookRoutes;
+const driving_context_1 = require("../terminal/driving-context");
 const fs_service_1 = require("../fs/fs-service");
 Object.defineProperty(exports, "fsService", { enumerable: true, get: function () { return fs_service_1.fsService; } });
 const operation_router_1 = require("../notebook/operation-router");
@@ -314,6 +315,17 @@ async function notebookRoutes(fastify) {
             if (result.code === 'sealed_read_only') {
                 return reply.code(403).send(result);
             }
+            // Drift notice: when the calling agent declared its terminal (env var →
+            // header) and the user is viewing a DIFFERENT notebook than this
+            // operation targets, say so once per switch — in the one channel the
+            // agent cannot miss. Never blocks the operation.
+            const agentTerminal = request.headers['x-nebula-agent-terminal'];
+            const opPath = typeof operation.notebookPath === 'string' ? operation.notebookPath : '';
+            if (typeof agentTerminal === 'string' && agentTerminal && opPath && result.success !== false) {
+                const notice = driving_context_1.drivingContext.driftNotice(agentTerminal, opPath);
+                if (notice)
+                    result.notice = notice;
+            }
             return reply.send(result);
         }
         catch (err) {

package/node-server/dist/scheduler/allocation-service.d.ts

@@ -52,6 +52,7 @@ export declare class AllocationService {
     private scheduleNextPoll;
     isEnabled(): boolean;
     getScheduler(): Scheduler | null;
+    getLaunchContext(): LaunchContext | null;
     list(): Allocation[];
     get(id: string): Allocation | undefined;
     create(spec: JobSpec): Promise<Allocation>;

package/node-server/dist/scheduler/allocation-service.js

@@ -182,6 +182,9 @@ class AllocationService {
     getScheduler() {
         return this.scheduler;
     }
+    getLaunchContext() {
+        return this.ctx;
+    }
     list() {
         return [...this.allocations.values()].sort((a, b) => b.createdAt - a.createdAt);
     }

package/node-server/dist/scheduler/arm-setup-prompt.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent-executable ARM setup prompt.
+ *
+ * Setting up aarch64 compute support is a one-time, judgment-heavy HPC task
+ * (storage policy, partition choice, whether compute nodes have internet) —
+ * wrong shape for one-click automation, right shape for an agent. The server
+ * contributes what it KNOWS (its own paths, node version, detected aarch64
+ * partitions + required QOS, the env var names); the prompt tells the agent
+ * to verify every step and finish with an end-to-end allocation proof.
+ */
+import type { Scheduler } from './types';
+import type { LaunchContext } from './job-template';
+export interface ArmSetupFacts {
+    configured: boolean;
+    serverArch: string;
+    nodeVersion: string;
+    nodeBin: string;
+    installDir: string;
+    suggestedArmDir: string;
+    suggestedArmNodeDir: string;
+    armPartitions: {
+        name: string;
+        qos: string[] | null;
+    }[];
+}
+export declare function gatherArmSetupFacts(scheduler: Scheduler, ctx: LaunchContext, serverArch?: string, nodeVersion?: string): Promise<ArmSetupFacts>;
+export declare function buildArmSetupPrompt(f: ArmSetupFacts): string;

package/node-server/dist/scheduler/arm-setup-prompt.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Agent-executable ARM setup prompt.
+ *
+ * Setting up aarch64 compute support is a one-time, judgment-heavy HPC task
+ * (storage policy, partition choice, whether compute nodes have internet) —
+ * wrong shape for one-click automation, right shape for an agent. The server
+ * contributes what it KNOWS (its own paths, node version, detected aarch64
+ * partitions + required QOS, the env var names); the prompt tells the agent
+ * to verify every step and finish with an end-to-end allocation proof.
+ */
+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.gatherArmSetupFacts = gatherArmSetupFacts;
+exports.buildArmSetupPrompt = buildArmSetupPrompt;
+const path = __importStar(require("path"));
+const arch_1 = require("./arch");
+async function gatherArmSetupFacts(scheduler, ctx, serverArch = process.arch, nodeVersion = process.version) {
+    const installDir = path.dirname(ctx.cwd); // ctx.cwd is <checkout>/node-server
+    const armPartitions = [];
+    try {
+        const load = await scheduler.load();
+        for (const p of load.partitions) {
+            // Homogeneous partitions whose arch differs from the server's. Mixed or
+            // unknown partitions are skipped — no safe pick exists (see arch.ts).
+            if (p.archs?.length === 1 && (0, arch_1.normalizeArch)(p.archs[0]) !== (0, arch_1.normalizeArch)(serverArch)) {
+                let qos = null;
+                try {
+                    qos = await scheduler.allowedQos(p.name);
+                }
+                catch { /* optional */ }
+                armPartitions.push({ name: p.name, qos });
+            }
+        }
+    }
+    catch { /* scheduler unavailable — prompt degrades to placeholders */ }
+    return {
+        configured: Boolean(ctx.archOverrides?.arm64),
+        serverArch,
+        nodeVersion,
+        nodeBin: ctx.nodeBin,
+        installDir,
+        suggestedArmDir: `${installDir}-arm64`,
+        // <prefix>/bin/node -> sibling <prefix>-arm64
+        suggestedArmNodeDir: `${path.dirname(path.dirname(ctx.nodeBin))}-arm64`,
+        armPartitions,
+    };
+}
+function buildArmSetupPrompt(f) {
+    const part = f.armPartitions[0];
+    const partName = part?.name ?? '<arm-partition>';
+    const qosFlag = part?.qos?.length ? ` --qos=${part.qos[0]}` : '';
+    const partitionList = f.armPartitions.length
+        ? f.armPartitions.map((p) => `${p.name}${p.qos?.length ? ` (requires --qos, one of: ${p.qos.join(', ')})` : ''}`).join('; ')
+        : '<arm-partition> (none auto-detected — ask the user, or check `sinfo` + `scontrol show node` Arch= fields)';
+    const armNodeBin = `${f.suggestedArmNodeDir}/bin/node`;
+    return `You are enabling aarch64 (ARM) compute allocations for an existing Nebula Notebook server on an HPC cluster. Nebula re-launches its own install on compute nodes, so ARM partitions need an arm64 Node.js runtime and an arm64-installed copy of the checkout, both on shared storage. Work on the SERVER (where the Nebula server process runs). VERIFY each step before the next; when a step fails, diagnose it — do not skip. Ask the user only for genuinely missing facts (e.g. storage policy).
+
+FACTS about this installation (real values, verified by the server):
+- Server CPU arch: ${f.serverArch}; Node ${f.nodeVersion} at ${f.nodeBin}
+- Nebula checkout: ${f.installDir}
+- ARM partitions detected: ${partitionList}
+- Env vars the server reads at startup: NEBULA_ARM64_NODE_BIN, NEBULA_ARM64_DIR
+
+STEPS:
+1. Confirm ${f.installDir} is on storage the compute nodes share (e.g. \`df -h\` / ask the user). Plan sibling paths: ${f.suggestedArmNodeDir} and ${f.suggestedArmDir} (or wherever policy dictates — same filesystem).
+2. arm64 Node runtime: download https://nodejs.org/dist/${f.nodeVersion}/node-${f.nodeVersion}-linux-arm64.tar.xz, extract so ${armNodeBin} exists. Verify with \`file ${armNodeBin}\` (must say aarch64/ARM). Do NOT try to run it on this ${f.serverArch} machine.
+3. Second checkout: \`git clone ${f.installDir} ${f.suggestedArmDir}\`, then set its origin to the same remote as the source checkout.
+4. Install server deps ON an ARM node — native modules must be arm64 builds:
+   srun -p ${partName}${qosFlag} --time=30 --mem=8G -c4 bash -c 'export PATH=${f.suggestedArmNodeDir}/bin:$PATH && cd ${f.suggestedArmDir}/node-server && npm install --no-audit --no-fund && node -e "require(\"zeromq\"); require(\"better-sqlite3\"); require(\"@homebridge/node-pty-prebuilt-multiarch\"); console.log(\"native modules ok\")"'
+   The final line MUST print "native modules ok". If compute nodes have no internet, tell the user — an npm mirror or admin help is needed; do not fake arm64 installs from this ${f.serverArch} machine.
+5. Build the workspace dependency (pure TypeScript, any arch works): \`cd ${f.suggestedArmDir}/packages/autocomplete && npm install && npm run build\` and verify dist/index.js exists.
+6. Configure the server: set NEBULA_ARM64_NODE_BIN=${armNodeBin} and NEBULA_ARM64_DIR=${f.suggestedArmDir} in the environment the Nebula server launches with (its launcher script / service unit — find how it is started), then restart it and verify /api/health answers.
+7. END-TO-END PROOF: \`nebula compute alloc --partition ${partName}${qosFlag ? ` --qos ${part.qos[0]}` : ''} --cpus 1 --mem 4 --walltime 30 --idle-timeout 10 --wait\` must reach state: active. Cancel it afterwards (\`nebula compute cancel <id>\`). If it fails, read the allocation's reason — it carries the job log tail.
+8. Kernels on ARM nodes also need an aarch64 Python with ipykernel (x86_64 conda envs will not run there). Create one on shared storage via srun on the ARM node (e.g. \`/usr/bin/python3 -m venv <shared>/envs/arm64-py && <shared>/envs/arm64-py/bin/pip install ipykernel\`), verify the import, and tell the user to pick it via "Enter interpreter path" (env:<path>) for notebooks bound to ARM allocations.
+
+Report at the end: what was installed where, the allocation id that went active, and anything you had to decide or could not verify.`;
+}

package/node-server/dist/scripts/show-auth-qr.js

@@ -1,37 +1,4 @@
 "use strict";
-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;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -40,7 +7,7 @@ const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const otplib_1 = require("otplib");
-const qrcode = __importStar(require("qrcode-terminal"));
+const setup_qr_1 = require("../auth/setup-qr");
 const AUTH_CONFIG_FILE = path_1.default.join(os_1.default.homedir(), '.nebula', 'auth.json');
 const ISSUER = 'NebulaNotebook';
 const ACCOUNT_NAME = 'local';
@@ -62,20 +29,30 @@ function readAuthConfig() {
     }
 }
 function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`show-auth-qr — reprint the 2FA setup QR for this machine's Nebula
+
+  npm run auth:qr              # compact QR (Unicode half-blocks)
+  npm run auth:qr -- --big     # font-independent QR (ANSI color blocks) —
+                               # use when the compact one renders as dashes
+  npm run auth:qr -- --url     # print only the otpauth:// URL (no QR)`);
+        return;
+    }
     const config = readAuthConfig();
     const secret = typeof config.totpSecret === 'string' ? config.totpSecret.trim() : '';
     if (!secret) {
-        fail(`[Auth] Missing \"totpSecret\" in ${AUTH_CONFIG_FILE}`);
+        fail(`[Auth] Missing "totpSecret" in ${AUTH_CONFIG_FILE}`);
     }
     const otpAuthUrl = otplib_1.authenticator.keyuri(ACCOUNT_NAME, ISSUER, secret);
-    console.log('\n' + '='.repeat(60));
-    console.log('  NEBULA NOTEBOOK - 2FA QR');
-    console.log('='.repeat(60));
-    console.log('\nScan this QR code with your authenticator app:\n');
-    qrcode.generate(otpAuthUrl, { small: true });
-    console.log('\nOr enter this key manually: ' + secret);
-    console.log(`\nConfig: ${AUTH_CONFIG_FILE}`);
-    console.log(`[Auth] setupComplete=${config.setupComplete === true ? 'true' : 'false'}`);
-    console.log('='.repeat(60) + '\n');
+    if (args.includes('--url')) {
+        console.log(otpAuthUrl);
+        return;
+    }
+    const mode = args.includes('--big') ? 'big' : 'small';
+    console.log((0, setup_qr_1.buildSetupInstructions)(secret, otpAuthUrl, (0, setup_qr_1.renderQr)(otpAuthUrl, mode)));
+    if (mode === 'small') {
+        console.log('Garbled? Re-run with --big for a font-independent QR.');
+    }
 }
 main();

package/node-server/dist/terminal/driving-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Driving context — which notebook the user is currently viewing, per agent
+ * terminal. Reported by the browser (notebook switch, tab focus, launch);
+ * consumed by agents via `nebula context` (pull) and via a drift notice the
+ * operation route attaches to results (push, at act time — the one channel
+ * an agent cannot miss, so it never has to poll).
+ *
+ * In-memory by design: the browser re-reports on every focus/switch, so
+ * state heals within seconds of a server restart.
+ */
+declare class DrivingContext {
+    private byTerminal;
+    setDriving(terminalId: string, notebook: string): void;
+    getDriving(terminalId: string): {
+        notebook: string;
+        at: number;
+    } | null;
+    /**
+     * One-line drift notice when `targetNotebook` differs from what the user is
+     * viewing — once per switch. Operations on the driving notebook re-arm the
+     * notice (so a later switch away notifies again).
+     */
+    driftNotice(terminalId: string, targetNotebook: string): string | null;
+    clear(): void;
+}
+export declare const drivingContext: DrivingContext;
+export {};

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

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Driving context — which notebook the user is currently viewing, per agent
+ * terminal. Reported by the browser (notebook switch, tab focus, launch);
+ * consumed by agents via `nebula context` (pull) and via a drift notice the
+ * operation route attaches to results (push, at act time — the one channel
+ * an agent cannot miss, so it never has to poll).
+ *
+ * In-memory by design: the browser re-reports on every focus/switch, so
+ * state heals within seconds of a server restart.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.drivingContext = void 0;
+function ago(ms) {
+    const s = Math.max(1, Math.round(ms / 1000));
+    if (s < 90)
+        return `${s}s ago`;
+    const m = Math.round(s / 60);
+    return `${m}m ago`;
+}
+class DrivingContext {
+    byTerminal = new Map();
+    setDriving(terminalId, notebook) {
+        if (!terminalId?.trim() || !notebook?.trim())
+            return;
+        const existing = this.byTerminal.get(terminalId);
+        if (existing && existing.notebook === notebook)
+            return; // focus ping, not a switch
+        this.byTerminal.set(terminalId, {
+            notebook,
+            at: Date.now(),
+            notifiedFor: existing ? null : null,
+        });
+    }
+    getDriving(terminalId) {
+        const d = this.byTerminal.get(terminalId);
+        return d ? { notebook: d.notebook, at: d.at } : null;
+    }
+    /**
+     * One-line drift notice when `targetNotebook` differs from what the user is
+     * viewing — once per switch. Operations on the driving notebook re-arm the
+     * notice (so a later switch away notifies again).
+     */
+    driftNotice(terminalId, targetNotebook) {
+        const d = this.byTerminal.get(terminalId);
+        if (!d || !targetNotebook)
+            return null;
+        if (d.notebook === targetNotebook) {
+            d.notifiedFor = null; // aligned — future switches notify again
+            return null;
+        }
+        if (d.notifiedFor === d.notebook)
+            return null; // already told about this switch
+        d.notifiedFor = d.notebook;
+        return (`note: the user is now viewing ${d.notebook} (switched ${ago(Date.now() - d.at)}); ` +
+            `this operation targeted ${targetNotebook}. Keep going if your instruction named this ` +
+            `notebook explicitly; if it said "this notebook/cell" without a path, it likely means ${d.notebook} — confirm before editing.`);
+    }
+    clear() {
+        this.byTerminal.clear();
+    }
+}
+exports.drivingContext = new DrivingContext();

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

@@ -48,6 +48,7 @@ const agent_registry_1 = require("./agent-registry");
 const binding_store_1 = require("./binding-store");
 const remote_agent_config_1 = require("./remote-agent-config");
 const remote_agent_identity_1 = require("./remote-agent-identity");
+const driving_context_1 = require("./driving-context");
 const fs_service_1 = require("../fs/fs-service");
 // Get configured root directory for terminals
 function getDefaultCwd() {
@@ -131,6 +132,24 @@ async function setupTerminalRoutes(fastify) {
             ? { pushed: true, path: `~/${remote_agent_identity_1.REMOTE_TOKEN_PATH}` }
             : { pushed: false, reason: 'your machine did not accept the token over the reverse tunnel (tunnel down or key not authorized)' });
     });
+    // Driving context: which notebook the user is viewing, per agent terminal.
+    // Browser reports on notebook switch / tab focus / launch; agents read it
+    // back with `nebula context`. In-memory — the browser re-reports on focus.
+    fastify.put('/api/terminals/driving', async (request, reply) => {
+        const body = request.body || {};
+        if (!body.terminal?.trim() || !body.notebook?.trim()) {
+            return reply.code(400).send({ error: 'terminal and notebook are required' });
+        }
+        driving_context_1.drivingContext.setDriving(body.terminal.trim(), body.notebook.trim());
+        return reply.send({ ok: true });
+    });
+    fastify.get('/api/terminals/driving', async (request, reply) => {
+        const terminal = String(request.query?.terminal || '').trim();
+        if (!terminal)
+            return reply.code(400).send({ error: 'terminal is required' });
+        const d = driving_context_1.drivingContext.getDriving(terminal);
+        return reply.send(d ?? { notebook: null });
+    });
     fastify.put('/api/terminals/agent-config', async (request, reply) => {
         const body = request.body || {};
         // Only fields actually present are touched (undefined keeps, null erases).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nebula-notebook",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "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",