@getmegabrain/cli 0.1.4 → 0.1.6

package/dist/cloud-fork.js

@@ -0,0 +1,104 @@
+/**
+ * `megabrain --session <id> --cloud-fork` — fork a MegaBrain cloud session
+ * into a local OpenCode session.
+ *
+ * The web UI hands users this command for any cloud session. Flow:
+ *   1. Download the session export from the session-ingest worker
+ *      (`GET /api/session/:id/export`, authenticated with the same Kilo user
+ *      JWT issued by `megabrain login`).
+ *   2. `opencode import <file>` to materialize the session locally.
+ *   3. Launch `opencode --session <id> --fork` so the user continues on a
+ *      fork instead of mutating the imported original.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const SESSION_INGEST_URL = (process.env.MEGABRAIN_SESSION_INGEST_URL ?? 'https://session-ingest.vasilij-lukin.workers.dev').replace(/\/+$/, '');
+const SESSION_ID_RE = /^ses_[a-z0-9]+$/i;
+export function isValidSessionId(sessionId) {
+    return SESSION_ID_RE.test(sessionId);
+}
+/**
+ * Detects `--cloud-fork` and extracts the `--session <id>` / `--session=<id>`
+ * value from raw argv. `--session` stays in passthroughArgs — it is only
+ * removed together with `--cloud-fork` by the caller when forking.
+ */
+export function parseCloudForkArgs(argv) {
+    let cloudFork = false;
+    let sessionId = null;
+    const passthroughArgs = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--cloud-fork') {
+            cloudFork = true;
+            continue;
+        }
+        if (arg === '--session' && i + 1 < argv.length) {
+            sessionId = argv[i + 1];
+            passthroughArgs.push(arg, argv[i + 1]);
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--session=')) {
+            sessionId = arg.slice('--session='.length);
+            passthroughArgs.push(arg);
+            continue;
+        }
+        passthroughArgs.push(arg);
+    }
+    return { cloudFork, sessionId, passthroughArgs };
+}
+/**
+ * Guards against error surfaces served as 200 (e.g. `{"detail":"..."}`):
+ * a valid OpenCode session export always carries `info.id`, and `opencode
+ * import` crashes with a cryptic error when it's missing.
+ */
+export function exportPayloadSessionId(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return null;
+    const info = payload.info;
+    if (info === null || typeof info === 'undefined' || typeof info !== 'object')
+        return null;
+    const id = info.id;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+/**
+ * Downloads the cloud session export to a temp file and returns its path.
+ * The caller owns cleanup.
+ */
+export async function downloadSessionExport(sessionId, token) {
+    const url = `${SESSION_INGEST_URL}/api/session/${encodeURIComponent(sessionId)}/export`;
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(300_000),
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach MegaBrain to download session ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status === 404) {
+        throw new Error(`Cloud session ${sessionId} was not found (or does not belong to your account).`);
+    }
+    if (res.status === 401 || res.status === 403) {
+        throw new Error('Your MegaBrain sign-in is no longer valid. Run `megabrain login` and retry.');
+    }
+    if (!res.ok) {
+        throw new Error(`Downloading session ${sessionId} failed (HTTP ${res.status}). Try again.`);
+    }
+    const body = await res.text();
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        throw new Error(`Session ${sessionId} export is not valid JSON. Try again.`);
+    }
+    if (exportPayloadSessionId(payload) === null) {
+        throw new Error(`Session ${sessionId} export is missing session metadata. Try again.`);
+    }
+    const tmpPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'megabrain-cloud-fork-')), `${sessionId}.json`);
+    fs.writeFileSync(tmpPath, body, { mode: 0o600 });
+    return tmpPath;
+}

package/dist/device-auth.js

@@ -38,28 +38,40 @@ function tryOpenBrowser(url) {
     }
 }
 const POLL_INTERVAL_MS = 2000;
-export async function login(log = console.log) {
+/**
+ * Begin a device-auth attempt without blocking: returns the code + verification URL to show
+ * the user immediately, and a `completed` promise that polls until it is approved. The
+ * `megabrain science` daemon uses this to render the code in the browser while it waits;
+ * `login()` (below) is the terminal wrapper that also prints it and opens the browser.
+ */
+export async function startDeviceAuth() {
     const { code, verificationUrl, expiresIn } = await createDeviceAuthCode();
+    const deadline = Date.now() + expiresIn * 1000;
+    const completed = (async () => {
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+            const result = await pollDeviceAuthCode(code);
+            if (result.status === 'approved') {
+                return { token: result.token, userId: result.userId, userEmail: result.userEmail };
+            }
+            if (result.status === 'denied')
+                throw new Error('Sign-in was denied.');
+            if (result.status === 'expired') {
+                throw new Error('Sign-in code expired. Run `megabrain login` again.');
+            }
+            // 'pending' — keep polling.
+        }
+        throw new Error('Sign-in timed out. Run `megabrain login` again.');
+    })();
+    return { code, verificationUrl, expiresIn, completed };
+}
+export async function login(log = console.log) {
+    const { code, verificationUrl, completed } = await startDeviceAuth();
     log('');
     log(`  Confirm this code:  ${code}`);
     log(`  Sign in at:         ${verificationUrl}`);
     log('');
     log('  Opening your browser…');
     tryOpenBrowser(verificationUrl);
-    const deadline = Date.now() + expiresIn * 1000;
-    while (Date.now() < deadline) {
-        await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
-        const result = await pollDeviceAuthCode(code);
-        if (result.status === 'approved') {
-            return { token: result.token, userId: result.userId, userEmail: result.userEmail };
-        }
-        if (result.status === 'denied') {
-            throw new Error('Sign-in was denied.');
-        }
-        if (result.status === 'expired') {
-            throw new Error('Sign-in code expired. Run `megabrain login` again.');
-        }
-        // 'pending' — keep polling.
-    }
-    throw new Error('Sign-in timed out. Run `megabrain login` again.');
+    return completed;
 }

package/dist/index.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { login } from './device-auth.js';
 import { readCredentials, writeCredentials, clearCredentials } from './credentials.js';
 import { writeOpenCodeConfig } from './opencode-config.js';
 import { fetchGatewayModelIds } from './models.js';
 import { ensureOpencodeBinary } from './opencode.js';
+import { parseCloudForkArgs, isValidSessionId, downloadSessionExport } from './cloud-fork.js';
+import { runScience, runScienceUrl } from './science/index.js';
 async function signIn() {
     console.log('Signing in to MegaBrain…');
     const { token, userId, userEmail } = await login();
@@ -53,6 +57,31 @@ function runOpenCode(args) {
         child.on('exit', code => resolve(code ?? 0));
     });
 }
+/**
+ * Forks a cloud session locally: downloads the session export from the
+ * MegaBrain session-ingest service, imports it into OpenCode, then launches
+ * OpenCode on a fork of the imported session.
+ */
+async function runCloudFork(sessionId) {
+    const credentials = readCredentials();
+    if (!credentials) {
+        throw new Error('Not signed in. Run `megabrain login` and retry.');
+    }
+    console.log(`Downloading cloud session ${sessionId}…`);
+    const exportPath = await downloadSessionExport(sessionId, credentials.token);
+    try {
+        console.log('Importing session into OpenCode…');
+        const importExitCode = await runOpenCode(['import', exportPath]);
+        if (importExitCode !== 0) {
+            throw new Error(`Importing session ${sessionId} failed (opencode exit ${importExitCode}).`);
+        }
+    }
+    finally {
+        fs.rmSync(path.dirname(exportPath), { recursive: true, force: true });
+    }
+    console.log('Starting a fork of the imported session…\n');
+    return runOpenCode(['--session', sessionId, '--fork']);
+}
 async function main() {
     const command = process.argv[2];
     switch (command) {
@@ -65,9 +94,27 @@ async function main() {
         case 'whoami':
             runWhoami();
             return;
+        case 'science':
+            if (process.argv[3] === 'url') {
+                await runScienceUrl();
+            }
+            else {
+                await runScience();
+            }
+            return;
         default: {
+            const args = process.argv.slice(2);
+            const { cloudFork, sessionId } = parseCloudForkArgs(args);
+            if (cloudFork) {
+                if (!sessionId || !isValidSessionId(sessionId)) {
+                    throw new Error('Usage: megabrain --session <ses_…> --cloud-fork (a valid cloud session id is required).');
+                }
+                await ensureSignedIn();
+                process.exitCode = await runCloudFork(sessionId);
+                return;
+            }
             await ensureSignedIn();
-            const exitCode = await runOpenCode(process.argv.slice(2));
+            const exitCode = await runOpenCode(args);
             process.exitCode = exitCode;
         }
     }

package/dist/science/index.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { MEGABRAIN_CONFIG_DIR } from '../paths.js';
+import { startScienceServer } from './server.js';
+/**
+ * `megabrain science` — start the local daemon that serves the workbench on localhost, and
+ * `megabrain science url` — print a fresh single-use sign-in link for the running daemon.
+ * See docs/megabrain-science/reference/claude-science-flow.md §0 (architecture) and §1.1.
+ */
+const RUNTIME_FILE = path.join(MEGABRAIN_CONFIG_DIR, 'science-daemon.json');
+function writeRuntime(rt) {
+    fs.mkdirSync(MEGABRAIN_CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(RUNTIME_FILE, JSON.stringify(rt), { mode: 0o600 });
+}
+function readRuntime() {
+    try {
+        return JSON.parse(fs.readFileSync(RUNTIME_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+    const args = platform === 'win32' ? ['', url] : [url];
+    try {
+        const child = spawn(command, args, {
+            shell: platform === 'win32',
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The printed URL is the fallback.
+    }
+}
+/** Start the daemon, print + open the first sign-in link, and run until interrupted. */
+export async function runScience() {
+    const { server, port, nonces, kernels, origin } = await startScienceServer();
+    writeRuntime({ port, pid: process.pid });
+    const url = `${origin()}/?nonce=${nonces.create()}`;
+    console.log('\n  MegaBrain Science is running.');
+    console.log(`  Open this link to sign in (works once, expires in 3 minutes):\n\n    ${url}\n`);
+    console.log('  Run `megabrain science url` for a fresh link. Ctrl+C to stop.\n');
+    openBrowser(url);
+    const shutdown = () => {
+        fs.rmSync(RUNTIME_FILE, { force: true });
+        kernels.stopAll();
+        server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+/** Ask the running daemon for a fresh sign-in URL and print it. */
+export async function runScienceUrl() {
+    const rt = readRuntime();
+    if (!rt) {
+        throw new Error('MegaBrain Science is not running. Start it with `megabrain science`.');
+    }
+    let res;
+    try {
+        res = await fetch(`http://127.0.0.1:${rt.port}/internal/mint`, { method: 'POST' });
+    }
+    catch {
+        throw new Error('MegaBrain Science is not running. Start it with `megabrain science`.');
+    }
+    if (!res.ok)
+        throw new Error(`Could not mint a sign-in link (HTTP ${res.status}).`);
+    const { url } = (await res.json());
+    console.log(`\n  ${url}\n`);
+    openBrowser(url);
+}

package/dist/science/kernel-protocol.js

@@ -0,0 +1,7 @@
+/**
+ * Kernel Protocol — the transport-agnostic contract the local kernel speaks (ported from the
+ * retired Electron app's `shared/kernel-protocol.ts`). The daemon writes KernelRequest lines
+ * to the kernel's stdin and reads KernelFrame lines from its stdout (newline-delimited JSON).
+ * State persists across cells for the process lifetime — the "kernel shared with the agent".
+ */
+export {};

package/dist/science/kernel.js

@@ -0,0 +1,117 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * The local Python kernel — MegaBrain Science's differentiator (#274, reference §0/§1.2). The
+ * agent's model runs in the cloud (via the Gateway), but code executes HERE, on the user's
+ * machine, in a long-lived process whose namespace persists across cells. Raw data never
+ * leaves the machine; only code and chosen results do.
+ *
+ * `KernelBridge` spawns `python3 -u kernel_driver.py` and speaks the Kernel Protocol over
+ * newline-delimited JSON on stdio, streaming frames to subscribers. `KernelManager` keeps one
+ * bridge per session. This is the piece kept from the retired Electron app; the launcher is
+ * pluggable so an SSH/HPC runtime can replace `spawn` later without touching the protocol.
+ */
+export const KERNEL_DRIVER_PATH = fileURLToPath(new URL('./kernel_driver.py', import.meta.url));
+const PYTHON_BIN = process.env.MB_PYTHON_BIN ?? 'python3';
+export class KernelBridge {
+    driverPath;
+    child = null;
+    buffer = '';
+    handlers = new Set();
+    cellCounter = 0;
+    constructor(driverPath = KERNEL_DRIVER_PATH) {
+        this.driverPath = driverPath;
+    }
+    onFrame(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    start() {
+        if (this.child)
+            return;
+        this.emit({ type: 'status', state: 'starting' });
+        if (!existsSync(this.driverPath)) {
+            this.emit({
+                type: 'status',
+                state: 'error',
+                error: `kernel driver missing: ${this.driverPath}`,
+            });
+            return;
+        }
+        const child = spawn(PYTHON_BIN, ['-u', this.driverPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child = child;
+        child.stdout.on('data', (c) => this.onStdout(c));
+        child.stderr.on('data', (c) => this.emit({ type: 'status', state: 'error', error: c.toString('utf8') }));
+        child.on('error', err => this.emit({ type: 'status', state: 'error', error: `kernel failed to start: ${err.message}` }));
+        child.on('exit', code => {
+            this.child = null;
+            this.emit({ type: 'status', state: 'error', error: `kernel exited (code ${code})` });
+        });
+    }
+    /** Run a cell; returns the assigned cellId so callers can correlate frames. */
+    execute(code) {
+        if (!this.child)
+            this.start();
+        this.cellCounter += 1;
+        const cellId = `cell-${this.cellCounter}`;
+        this.send({ type: 'execute', cellId, code });
+        return cellId;
+    }
+    send(request) {
+        if (!this.child)
+            this.start();
+        this.child?.stdin.write(`${JSON.stringify(request)}\n`);
+    }
+    restart() {
+        this.stop();
+        this.buffer = '';
+        this.start();
+    }
+    stop() {
+        this.child?.kill();
+        this.child = null;
+    }
+    onStdout(chunk) {
+        this.buffer += chunk.toString('utf8');
+        let nl = this.buffer.indexOf('\n');
+        while (nl !== -1) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (line) {
+                try {
+                    this.emit(JSON.parse(line));
+                }
+                catch {
+                    this.emit({ type: 'stream', cellId: '', kind: 'stdout', data: line });
+                }
+            }
+            nl = this.buffer.indexOf('\n');
+        }
+    }
+    emit(frame) {
+        for (const h of this.handlers)
+            h(frame);
+    }
+}
+/** One kernel per session, started on demand. */
+export class KernelManager {
+    bridges = new Map();
+    get(sessionId) {
+        let bridge = this.bridges.get(sessionId);
+        if (!bridge) {
+            bridge = new KernelBridge();
+            bridge.start();
+            this.bridges.set(sessionId, bridge);
+        }
+        return bridge;
+    }
+    restart(sessionId) {
+        this.bridges.get(sessionId)?.restart();
+    }
+    stopAll() {
+        for (const bridge of this.bridges.values())
+            bridge.stop();
+        this.bridges.clear();
+    }
+}

package/dist/science/kernel_driver.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""MegaBrain Science — local Python kernel driver.
+
+Implements the Kernel Protocol over newline-delimited JSON on stdio. The Electron
+main process (KernelSupervisor) spawns this with `python3 -u kernel_driver.py`,
+writes KernelRequest lines to stdin, and reads KernelFrame lines from stdout.
+
+State (the exec namespace) persists across cells for the process lifetime, which
+is what makes the kernel "shared with the agent": variables and imports set in one
+cell are visible in the next.
+"""
+
+import contextlib
+import io
+import json
+import sys
+import traceback
+
+# Persistent namespace shared across all cells in this session.
+NAMESPACE: dict = {"__name__": "__mb_science__"}
+
+
+def emit(frame: dict) -> None:
+    sys.stdout.write(json.dumps(frame) + "\n")
+    sys.stdout.flush()
+
+
+def run_cell(cell_id: str, code: str) -> None:
+    emit({"type": "status", "cellId": cell_id, "state": "busy"})
+    stdout, stderr = io.StringIO(), io.StringIO()
+    try:
+        with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            # Compile as a module body so top-level expressions still assign/print
+            # normally; the persistent NAMESPACE keeps state between cells.
+            exec(compile(code, f"<{cell_id}>", "exec"), NAMESPACE)
+    except Exception:  # noqa: BLE001 - surface any user error as a stderr stream
+        stderr.write(traceback.format_exc())
+
+    out, err = stdout.getvalue(), stderr.getvalue()
+    if out:
+        emit({"type": "stream", "cellId": cell_id, "kind": "stdout", "data": out})
+    if err:
+        emit({"type": "stream", "cellId": cell_id, "kind": "stderr", "data": err})
+    emit({"type": "status", "cellId": cell_id, "state": "idle"})
+
+
+def emit_snapshot() -> None:
+    import platform
+
+    try:
+        import importlib.metadata as md
+
+        packages = sorted(f"{d.metadata['Name']}=={d.version}" for d in md.distributions())
+    except Exception:  # noqa: BLE001 - environment listing is best-effort
+        packages = []
+
+    emit(
+        {
+            "type": "snapshot",
+            "env": {
+                "language": "python",
+                "version": platform.python_version(),
+                "platform": platform.platform(),
+                "packages": packages,
+            },
+        }
+    )
+
+
+def main() -> None:
+    emit({"type": "status", "state": "idle"})
+    for raw in sys.stdin:
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        kind = request.get("type")
+        if kind == "execute":
+            run_cell(request.get("cellId", ""), request.get("code", ""))
+        elif kind == "snapshot":
+            emit_snapshot()
+        elif kind == "interrupt":
+            # Cooperative interrupt is a follow-up; ack for now.
+            emit({"type": "status", "state": "idle"})
+        # "restart" is handled by the supervisor by killing/respawning us.
+
+
+if __name__ == "__main__":
+    main()

package/dist/science/nonce.js

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Single-use, short-lived nonces for the browser sign-in hand-off.
+ *
+ * The `megabrain science` daemon prints a `http://127.0.0.1:PORT/?nonce=…` URL and opens it
+ * in the browser. Opening that link is what authorizes *this* browser to drive *this* local
+ * daemon — so a random other process on the machine can't. The nonce works once and expires a
+ * few minutes after it was printed; `megabrain science url` mints a fresh one. See
+ * docs/megabrain-science/reference/claude-science-flow.md §1.1 (screen 01).
+ */
+const NONCE_TTL_MS = 3 * 60 * 1000; // 3 minutes, matching the printed hint.
+export class NonceStore {
+    now;
+    ttlMs;
+    nonces = new Map();
+    constructor(now = Date.now, ttlMs = NONCE_TTL_MS) {
+        this.now = now;
+        this.ttlMs = ttlMs;
+    }
+    /** Mint a fresh nonce and return it (URL-safe hex). */
+    create() {
+        this.sweep();
+        const nonce = randomBytes(20).toString('hex');
+        this.nonces.set(nonce, { createdAt: this.now(), used: false });
+        return nonce;
+    }
+    /**
+     * Validate and consume a nonce. Single-use: a second claim of the same nonce returns
+     * 'used'. Returns 'unknown' for a nonce we never issued (or already swept), 'expired'
+     * past the TTL.
+     */
+    claim(nonce) {
+        const entry = this.nonces.get(nonce);
+        if (!entry)
+            return 'unknown';
+        if (this.now() - entry.createdAt > this.ttlMs) {
+            this.nonces.delete(nonce);
+            return 'expired';
+        }
+        if (entry.used)
+            return 'used';
+        entry.used = true;
+        return 'ok';
+    }
+    /** Drop expired entries so the map doesn't grow unbounded across `url` re-mints. */
+    sweep() {
+        const cutoff = this.now() - this.ttlMs;
+        for (const [nonce, entry] of this.nonces) {
+            if (entry.createdAt < cutoff)
+                this.nonces.delete(nonce);
+        }
+    }
+}