nebula-notebook-mcp 0.2.0 → 0.3.0

package/dist/cli/session.js

@@ -0,0 +1,111 @@
+/**
+ * `nebula session …` — agent-lock sessions.
+ *
+ * `session start` acquires the agent lock via the shared client and persists
+ * the agent token to $NEBULA_STATE_DIR (or ~/.nebula), keyed by hash of
+ * url+path, so separate CLI invocations share the same lock. Other commands
+ * attach the token automatically (see makeClient in shared.ts).
+ */
+import { NebulaClient } from '../notebook/client.js';
+import { CliError, EXIT, clearSessionState, loadSessionState, newAgentId, parse, printHint, printJson, requirePositional, resolveUrl, saveSessionState, } from './shared.js';
+const SESSION_HELP = `usage: nebula session start <path> [--name NAME]
+       nebula session end <path>
+
+Holds/releases the agent lock for a notebook. The session token is stored in
+$NEBULA_STATE_DIR (default ~/.nebula), so every later nebula invocation for
+the same server+notebook automatically carries the lock until 'session end'.
+
+examples:
+  nebula session start analysis.ipynb --name refactor-bot
+  nebula nb edit analysis.ipynb cell-3 --content 'x = 1'   # uses the lock
+  nebula session end analysis.ipynb`;
+export async function cmdSession(argv) {
+    const [sub, ...rest] = argv;
+    switch (sub) {
+        case 'start':
+            return sessionStart(rest);
+        case 'end':
+            return sessionEnd(rest);
+        case undefined:
+        case '--help':
+        case '-h':
+            console.log(SESSION_HELP);
+            return sub === undefined ? EXIT.USAGE : EXIT.OK;
+        default:
+            throw new CliError(`unknown session subcommand: ${sub}`, EXIT.USAGE, "run 'nebula session --help' for usage");
+    }
+}
+async function sessionStart(argv) {
+    const { values, positionals } = parse(argv, { name: { type: 'string' } });
+    if (values.help) {
+        console.log(SESSION_HELP);
+        return EXIT.OK;
+    }
+    const nbPath = requirePositional(positionals, 0, 'path', 'nebula session start <path> [--name NAME]');
+    const url = resolveUrl(values.url);
+    const name = values.name;
+    // Reuse an existing token for this url+path so a re-start keeps the identity.
+    const existing = loadSessionState(url, nbPath);
+    const agentId = existing?.agentId ?? newAgentId();
+    const client = new NebulaClient({
+        baseUrl: url,
+        agentId,
+        clientName: name ?? 'nebula-cli',
+        autoStartAgentSession: false,
+    });
+    const result = await client.startAgentSession(nbPath, agentId);
+    if (!result.success) {
+        throw new CliError(result.error ?? 'failed to start session', EXIT.ERROR);
+    }
+    const stateFile = saveSessionState({
+        url,
+        path: nbPath,
+        agentId,
+        name,
+        startedAt: Date.now(),
+    });
+    if (values.json) {
+        printJson({ path: nbPath, agentId, stateFile, warning: result.data?.warning });
+        return EXIT.OK;
+    }
+    console.log(`session started for ${nbPath} (agent ${agentId})`);
+    if (result.data?.warning) {
+        console.log(`warning: ${result.data.warning}`);
+    }
+    printHint(`later invocations reuse this lock; release it with: nebula session end ${nbPath}`, values);
+    return EXIT.OK;
+}
+async function sessionEnd(argv) {
+    const { values, positionals } = parse(argv);
+    if (values.help) {
+        console.log(SESSION_HELP);
+        return EXIT.OK;
+    }
+    const nbPath = requirePositional(positionals, 0, 'path', 'nebula session end <path>');
+    const url = resolveUrl(values.url);
+    const existing = loadSessionState(url, nbPath);
+    if (!existing) {
+        throw new CliError(`no CLI session for ${nbPath}`, EXIT.ERROR, `start one with: nebula session start ${nbPath}`);
+    }
+    const client = new NebulaClient({
+        baseUrl: url,
+        agentId: existing.agentId,
+        clientName: existing.name ?? 'nebula-cli',
+        autoStartAgentSession: false,
+    });
+    const result = await client.endAgentSession(nbPath);
+    if (!result.success) {
+        // Keep the state file so the user can retry ending the session.
+        throw new CliError(result.error ?? 'failed to end session', EXIT.ERROR);
+    }
+    clearSessionState(url, nbPath);
+    if (values.json) {
+        printJson({ path: nbPath, ended: true, sessionDuration: result.data?.sessionDuration });
+        return EXIT.OK;
+    }
+    const duration = result.data?.sessionDuration;
+    console.log(duration !== undefined ? `session ended (${Math.round(duration / 1000)}s)` : 'session ended');
+    printHint(`reads still work without a session; start a new one with: nebula session start ${nbPath}`, values);
+    return EXIT.OK;
+}
+//# sourceMappingURL=session.js.map

package/dist/cli/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/cli/session.ts"],"names":[],"mappings":"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"}

package/dist/cli/shared.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared CLI plumbing: exit codes, flag parsing, server URL resolution,
+ * session-state persistence, and output helpers.
+ *
+ * The CLI is a thin layer over the shared NebulaClient / tools code (the same
+ * code the MCP server uses) — nothing in here talks HTTP directly.
+ */
+import { NebulaClient } from '../notebook/client.js';
+export declare const EXIT: {
+    readonly OK: 0;
+    /** Generic failure */
+    readonly ERROR: 1;
+    /** Usage / configuration error (bad flags, missing NEBULA_URL, …) */
+    readonly USAGE: 2;
+    /** Kernel dead or not found */
+    readonly KERNEL: 7;
+    /** Optimistic-concurrency conflict (cell changed since last read) */
+    readonly CONFLICT: 9;
+    /** Execution still running when --max-wait expired (not an error) */
+    readonly RUNNING: 3;
+};
+export declare class CliError extends Error {
+    readonly code: number;
+    readonly hintText?: string | undefined;
+    constructor(message: string, code?: number, hintText?: string | undefined);
+}
+export interface ParsedArgs {
+    values: Record<string, string | boolean | undefined>;
+    positionals: string[];
+}
+type FlagSpec = Record<string, {
+    type: 'string' | 'boolean';
+    short?: string;
+}>;
+export declare function parse(argv: string[], flags?: FlagSpec): ParsedArgs;
+export declare function requirePositional(positionals: string[], index: number, name: string, usage: string): string;
+export declare function resolveUrl(flagUrl: unknown): string;
+export interface CliSessionState {
+    url: string;
+    path: string;
+    agentId: string;
+    name?: string;
+    startedAt: number;
+}
+/** State file is keyed by hash(url + notebook path) so invocations share the lock. */
+export declare function sessionFilePath(url: string, notebookPath: string): string;
+export declare function loadSessionState(url: string, notebookPath: string): CliSessionState | null;
+export declare function saveSessionState(state: CliSessionState): string;
+export declare function clearSessionState(url: string, notebookPath: string): void;
+export declare function newAgentId(): string;
+/**
+ * Build a NebulaClient for a command. If a CLI session exists for this
+ * url+notebook, its agent token is attached automatically so the invocation
+ * shares the agent lock started by `nebula session start`.
+ */
+export declare function makeClient(url: string, notebookPath?: string): NebulaClient;
+export declare function resolveContentInput(content: unknown, contentFile: unknown, stdinMarker: boolean): Promise<string>;
+export declare function printJson(data: unknown): void;
+/** At most one contextual next-step hint per command (AXI); suppressed by --quiet/--json. */
+export declare function printHint(text: string, values: ParsedArgs['values']): void;
+export declare function firstLineOf(content: string, max?: number): string;
+export declare function tailLines(text: string, n: number): string[];
+export declare function parseIntFlag(value: unknown, name: string, fallback: number): number;
+/** Map an operation error message to a CliError with the right exit code/hint. */
+export declare function toCliError(message: string | undefined, notebookPath?: string): CliError;
+export {};
+//# sourceMappingURL=shared.d.ts.map

package/dist/cli/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/cli/shared.ts"],"names":[],"mappings":"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"}

package/dist/cli/shared.js

@@ -0,0 +1,213 @@
+/**
+ * Shared CLI plumbing: exit codes, flag parsing, server URL resolution,
+ * session-state persistence, and output helpers.
+ *
+ * The CLI is a thin layer over the shared NebulaClient / tools code (the same
+ * code the MCP server uses) — nothing in here talks HTTP directly.
+ */
+import { parseArgs } from 'node:util';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { NebulaClient } from '../notebook/client.js';
+// =============================================================================
+// Exit codes
+// =============================================================================
+export const EXIT = {
+    OK: 0,
+    /** Generic failure */
+    ERROR: 1,
+    /** Usage / configuration error (bad flags, missing NEBULA_URL, …) */
+    USAGE: 2,
+    /** Kernel dead or not found */
+    KERNEL: 7,
+    /** Optimistic-concurrency conflict (cell changed since last read) */
+    CONFLICT: 9,
+    /** Execution still running when --max-wait expired (not an error) */
+    RUNNING: 3,
+};
+export class CliError extends Error {
+    code;
+    hintText;
+    constructor(message, code = EXIT.ERROR, hintText) {
+        super(message);
+        this.code = code;
+        this.hintText = hintText;
+        this.name = 'CliError';
+    }
+}
+/** Flags accepted by every command. */
+const COMMON_FLAGS = {
+    url: { type: 'string' },
+    json: { type: 'boolean' },
+    quiet: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+export function parse(argv, flags = {}) {
+    const options = { ...COMMON_FLAGS, ...flags };
+    // parseArgs rejects `--index -1` as ambiguous; fold negative-number values
+    // of string flags into `--index=-1` form before parsing.
+    const args = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const name = arg.startsWith('--') ? arg.slice(2) : undefined;
+        const next = argv[i + 1];
+        if (name && options[name]?.type === 'string' && next !== undefined && /^-\d/.test(next)) {
+            args.push(`${arg}=${next}`);
+            i += 1;
+        }
+        else {
+            args.push(arg);
+        }
+    }
+    try {
+        const { values, positionals } = parseArgs({
+            args,
+            options,
+            allowPositionals: true,
+            strict: true,
+        });
+        return { values: values, positionals };
+    }
+    catch (e) {
+        throw new CliError(e instanceof Error ? e.message : String(e), EXIT.USAGE, "run the command with --help for usage");
+    }
+}
+export function requirePositional(positionals, index, name, usage) {
+    const value = positionals[index];
+    if (!value) {
+        throw new CliError(`missing <${name}>`, EXIT.USAGE, `usage: ${usage}`);
+    }
+    return value;
+}
+// =============================================================================
+// Server URL resolution: --url flag > NEBULA_URL env > error
+// =============================================================================
+export function resolveUrl(flagUrl) {
+    const url = (typeof flagUrl === 'string' && flagUrl) || process.env.NEBULA_URL;
+    if (!url) {
+        throw new CliError('no Nebula server URL configured', EXIT.USAGE, 'pass --url http://localhost:8000 or export NEBULA_URL=http://localhost:8000');
+    }
+    return url.replace(/\/+$/, '');
+}
+function stateDir() {
+    return process.env.NEBULA_STATE_DIR || path.join(os.homedir(), '.nebula');
+}
+/** State file is keyed by hash(url + notebook path) so invocations share the lock. */
+export function sessionFilePath(url, notebookPath) {
+    const key = createHash('sha256').update(`${url}\n${notebookPath}`).digest('hex').slice(0, 16);
+    return path.join(stateDir(), `cli-session-${key}.json`);
+}
+export function loadSessionState(url, notebookPath) {
+    try {
+        const raw = fs.readFileSync(sessionFilePath(url, notebookPath), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.agentId === 'string' && parsed.agentId ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSessionState(state) {
+    const file = sessionFilePath(state.url, state.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    return file;
+}
+export function clearSessionState(url, notebookPath) {
+    fs.rmSync(sessionFilePath(url, notebookPath), { force: true });
+}
+export function newAgentId() {
+    return `nebula-cli-${randomBytes(4).toString('hex')}`;
+}
+/**
+ * Build a NebulaClient for a command. If a CLI session exists for this
+ * url+notebook, its agent token is attached automatically so the invocation
+ * shares the agent lock started by `nebula session start`.
+ */
+export function makeClient(url, notebookPath) {
+    const session = notebookPath ? loadSessionState(url, notebookPath) : null;
+    return new NebulaClient({
+        baseUrl: url,
+        agentId: session?.agentId,
+        clientName: session?.name ?? 'nebula-cli',
+        // Sessions are explicit in the CLI (nebula session start/end).
+        autoStartAgentSession: false,
+    });
+}
+// =============================================================================
+// Content input: --content <str> | --content-file <f> | "-" (stdin)
+// =============================================================================
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+export async function resolveContentInput(content, contentFile, stdinMarker) {
+    const provided = [content !== undefined, contentFile !== undefined, stdinMarker].filter(Boolean);
+    if (provided.length !== 1) {
+        throw new CliError('provide exactly one of --content <str>, --content-file <file>, or - (stdin)', EXIT.USAGE);
+    }
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (typeof contentFile === 'string') {
+        try {
+            return fs.readFileSync(contentFile, 'utf-8');
+        }
+        catch (e) {
+            throw new CliError(`cannot read --content-file ${contentFile}: ${e instanceof Error ? e.message : String(e)}`, EXIT.USAGE);
+        }
+    }
+    return readStdin();
+}
+// =============================================================================
+// Output helpers
+// =============================================================================
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/** At most one contextual next-step hint per command (AXI); suppressed by --quiet/--json. */
+export function printHint(text, values) {
+    if (!values.quiet && !values.json) {
+        console.log(`hint: ${text}`);
+    }
+}
+export function firstLineOf(content, max = 80) {
+    const lines = content.split('\n');
+    let first = lines[0];
+    let truncated = lines.length > 1;
+    if (first.length > max) {
+        first = first.slice(0, max);
+        truncated = true;
+    }
+    return truncated ? `${first}…` : first;
+}
+export function tailLines(text, n) {
+    const lines = text.replace(/\n$/, '').split('\n');
+    return lines.slice(Math.max(0, lines.length - n));
+}
+export function parseIntFlag(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number.parseInt(String(value), 10);
+    if (Number.isNaN(n)) {
+        throw new CliError(`${name} must be an integer, got "${String(value)}"`, EXIT.USAGE);
+    }
+    return n;
+}
+/** Map an operation error message to a CliError with the right exit code/hint. */
+export function toCliError(message, notebookPath) {
+    const msg = message || 'operation failed';
+    if (/agent session required/i.test(msg)) {
+        return new CliError(msg, EXIT.ERROR, `start one with: nebula session start ${notebookPath ?? '<path>'}`);
+    }
+    if (/kernel session not found|no kernel|kernel .*dead/i.test(msg)) {
+        return new CliError(msg, EXIT.KERNEL);
+    }
+    return new CliError(msg, EXIT.ERROR);
+}
+//# sourceMappingURL=shared.js.map

package/dist/cli/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/cli/shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,EAAE,EAAE,CAAC;IACL,sBAAsB;IACtB,KAAK,EAAE,CAAC;IACR,qEAAqE;IACrE,KAAK,EAAE,CAAC;IACR,+BAA+B;IAC/B,MAAM,EAAE,CAAC;IACT,qEAAqE;IACrE,QAAQ,EAAE,CAAC;IACX,qEAAqE;IACrE,OAAO,EAAE,CAAC;CACF,CAAC;AAEX,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGtB;IACA;IAHX,YACE,OAAe,EACN,OAAe,IAAI,CAAC,KAAK,EACzB,QAAiB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAqB;QACzB,aAAQ,GAAR,QAAQ,CAAS;QAG1B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAaD,uCAAuC;AACvC,MAAM,YAAY,GAAa;IAC7B,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACvB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IACzB,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;CACtC,CAAC;AAEF,MAAM,UAAU,KAAK,CAAC,IAAc,EAAE,QAAkB,EAAE;IACxD,MAAM,OAAO,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,KAAK,EAAE,CAAC;IAE9C,2EAA2E;IAC3E,yDAAyD;IACzD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxF,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;YAC5B,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;YACxC,IAAI;YACJ,OAAO;YACP,gBAAgB,EAAE,IAAI;YACtB,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,MAA8B,EAAE,WAAW,EAAE,CAAC;IACjE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAChB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAC1C,IAAI,CAAC,KAAK,EACV,uCAAuC,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,WAAqB,EAAE,KAAa,EAAE,IAAY,EAAE,KAAa;IACjG,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAAC,YAAY,IAAI,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,6DAA6D;AAC7D,gFAAgF;AAEhF,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,MAAM,GAAG,GAAG,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IAC/E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,QAAQ,CAChB,iCAAiC,EACjC,IAAI,CAAC,KAAK,EACV,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAcD,SAAS,QAAQ;IACf,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5E,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,YAAoB;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,KAAK,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9F,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,YAAoB;IAChE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;QAClD,OAAO,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAsB;IACrD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACpD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,YAAoB;IACjE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,cAAc,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,YAAqB;IAC3D,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,OAAO,IAAI,YAAY,CAAC;QACtB,OAAO,EAAE,GAAG;QACZ,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,UAAU,EAAE,OAAO,EAAE,IAAI,IAAI,YAAY;QACzC,+DAA+D;QAC/D,qBAAqB,EAAE,KAAK;KAC7B,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,oEAAoE;AACpE,gFAAgF;AAEhF,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAgB,EAChB,WAAoB,EACpB,WAAoB;IAEpB,MAAM,QAAQ,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,WAAW,KAAK,SAAS,EAAE,WAAW,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjG,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,QAAQ,CAChB,6EAA6E,EAC7E,IAAI,CAAC,KAAK,CACX,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,QAAQ,CAChB,8BAA8B,WAAW,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAC1F,IAAI,CAAC,KAAK,CACX,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAS,EAAE,CAAC;AACrB,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAA4B;IAClE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,GAAG,GAAG,EAAE;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACvB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5B,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,OAAO,SAAS,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,CAAS;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,IAAY,EAAE,QAAgB;IACzE,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAAC,GAAG,IAAI,6BAA6B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,OAA2B,EAAE,YAAqB;IAC3E,MAAM,GAAG,GAAG,OAAO,IAAI,kBAAkB,CAAC;IAC1C,IAAI,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,wCAAwC,YAAY,IAAI,QAAQ,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,mDAAmD,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/cli/skill.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `nebula setup-skill` — install a Claude Code Agent Skill that teaches
+ * agents launched OUTSIDE Nebula terminals (plain shells, SSH sessions, other
+ * projects) how to drive notebooks with this CLI. Inside Nebula terminals the
+ * bootstrap prompt + PATH injection already cover this; the skill closes the
+ * gap everywhere else.
+ *
+ * The skill content is embedded here (single source of truth) so `npx
+ * nebula-notebook-mcp` installs work without file-resolution games.
+ */
+export declare function cmdSetupSkill(argv: string[]): Promise<number>;
+//# sourceMappingURL=skill.d.ts.map

package/dist/cli/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/cli/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0HH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDnE"}

package/dist/cli/skill.js

@@ -0,0 +1,176 @@
+/**
+ * `nebula setup-skill` — install a Claude Code Agent Skill that teaches
+ * agents launched OUTSIDE Nebula terminals (plain shells, SSH sessions, other
+ * projects) how to drive notebooks with this CLI. Inside Nebula terminals the
+ * bootstrap prompt + PATH injection already cover this; the skill closes the
+ * gap everywhere else.
+ *
+ * The skill content is embedded here (single source of truth) so `npx
+ * nebula-notebook-mcp` installs work without file-resolution games.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseArgs } from 'node:util';
+import { CliError, EXIT } from './shared.js';
+const SKILL_MD = `---
+name: nebula-notebook
+description: Drive Jupyter-style notebooks (.ipynb/.qmd/.py percent) on a Nebula Notebook server with the \`nebula\` CLI — read/edit/insert/delete cells, execute with output in one call, search, manage kernels. Use when the user asks to work on a notebook served by Nebula (a NEBULA_URL / localhost:3000 notebook server), run or fix notebook cells, or inspect notebook outputs.
+---
+
+# Nebula Notebook CLI
+
+Work with notebooks on a running Nebula server via the \`nebula\` CLI.
+
+## Connect (do this first — it depends on where you are running)
+
+Find the server URL, in this order:
+
+1. **\`NEBULA_URL\` already set?** (\`echo $NEBULA_URL\`) — you are likely inside a
+   Nebula terminal; everything is pre-wired. Verify: \`curl -s $NEBULA_URL/api/health\`.
+2. **Same machine as the server?** Try \`curl -s http://localhost:3000/api/health\`
+   — if it answers \`{"status":"ok"...}\`, use \`export NEBULA_URL=http://localhost:3000\`.
+3. **Server is remote (common on HPC: it runs on a login node).** Two cases —
+   ASK THE USER which applies; do not guess:
+   - a tunnel is already forwarded (they browse Nebula at \`http://localhost:3000\`
+     on this machine) → step 2 will have worked;
+   - no tunnel yet → ask the user to run one, e.g.
+     \`ssh -L 3000:<server-host>:3000 <cluster>\`, or to give you a directly
+     reachable URL. The right URL is whatever THEY open the Nebula UI at.
+4. Health check fails everywhere → tell the user the server looks down and ask
+   how they normally start/reach it (\`npx nebula-notebook\` locally).
+
+Notebook paths in commands are paths on the SERVER's filesystem (ask the user
+or find them via the UI/file browser if unsure — they are usually absolute).
+
+If \`nebula\` is not on PATH: \`npx -p nebula-notebook-mcp nebula …\`, or from a
+Nebula repo checkout: \`<repo>/packages/mcp/bin/nebula\`.
+
+## Commands
+
+\`\`\`bash
+nebula nb read <path>                    # list cells: #idx id type [n] first-line
+nebula nb read <path> --cells 3-8 --outputs --full
+nebula run <path> <cell-id> --tail 40    # execute AND print output tail in one call
+nebula nb edit <path> <cell-id> --content-file -   # stdin; or --content '...'
+nebula nb insert <path> --index N --content '...' [--type markdown] [--id my-id]
+nebula nb delete <path> <cell-id>
+nebula nb search <path> <query> --limit 5
+nebula kernel status|restart|interrupt <path>
+nebula session start <path>              # hold the agent edit lock (persists across invocations)
+nebula session end <path>
+nebula compute status|queues|alloc|ls|use|cancel   # cluster compute (see below)
+\`\`\`
+
+All commands accept \`--json\` (raw) and \`--quiet\` (no hint line).
+Notebook paths are absolute paths on the SERVER's filesystem.
+
+## Long-running cells — no polling
+
+\`nebula run\` BLOCKS until the cell finishes (it follows the execution
+internally). So for anything that might take a while, **launch it as a
+background shell task and move on** — the process exiting IS the completion
+signal; you will be notified. Never write your own poll loop.
+
+\`\`\`bash
+nebula run <path> train-cell --max-wait 0 --tail 60   # run in background; 0 = wait however long it takes
+\`\`\`
+
+Exit codes tell you what happened: 0 done-ok · 1 cell errored (traceback in the
+tail) · 3 still running when --max-wait expired. \`--no-wait\` exists for true
+fire-and-forget (check later with \`nebula nb read --outputs\`).
+
+## Cluster compute (optional)
+
+Some Nebula servers sit on HPC clusters and can run notebook kernels on
+scheduler-backed compute allocations. The feature is detection-gated — absent
+on laptops/plain servers — so **check \`nebula compute status\` first**; if it
+says no scheduler, skip this section entirely (kernels run on the server).
+
+Typical flow:
+
+\`\`\`bash
+nebula compute status                                  # scheduler present?
+nebula compute queues                                  # partitions, idle CPUs/GPUs, backlog
+nebula compute alloc --partition gpu --gpus 1 --walltime 2 --idle-timeout 60 --wait   # background task; blocks until active
+nebula compute use <alloc-id> <notebook.ipynb>         # bind the notebook's kernels to it
+nebula run <notebook.ipynb> <cell-id>                  # now executes on the allocation
+nebula compute cancel <alloc-id>                       # when the task is done
+\`\`\`
+
+\`alloc --wait\` follows the queue internally (like \`nebula run\`): launch it
+as a background shell task and the process exit is the signal — never write
+your own poll loop.
+
+Etiquette — allocations consume real cluster resources:
+
+- Request modest resources: only the CPUs/GPUs/memory/walltime the task needs.
+- Add \`--idle-timeout 60\` to allocations you create: the allocation ends
+  itself after 60 idle minutes (no kernel/terminal activity), so a forgotten
+  allocation never squats on GPUs.
+- Cancel allocations you created as soon as the task completes (the idle
+  timeout is a safety net, not a substitute).
+- NEVER cancel allocations you did not create (\`nebula compute ls\` shows all).
+
+## Rules
+
+- **Read before editing.** Edits are OCC-checked against what you last read.
+- **Exit code 9 = edit conflict**: the cell changed (usually the user typing).
+  The current content is printed — re-apply your change against it and retry.
+  This is normal collaboration, not an error.
+- **Exit code 7** = no kernel session; \`nebula run\` starts one automatically.
+- Prefer \`nebula run\` over edit-then-hope: it executes and returns status,
+  execution_count, and the output tail in a single call.
+- For multi-edit work, \`nebula session start\` first (shows the user a purple
+  "agent session" badge and locks out conflicting edits), \`session end\` when done.
+- Pipe freely: \`nebula nb read <path> --full | grep -n pattern\` filters
+  before output reaches your context.
+`;
+export async function cmdSetupSkill(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            project: { type: 'boolean', default: false },
+            dir: { type: 'string' },
+            print: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            quiet: { type: 'boolean', default: false },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        console.log(`nebula setup-skill — install the Claude Code skill for this CLI
+
+Teaches agents in plain terminals (outside Nebula) when and how to use nebula.
+
+  nebula setup-skill              # → ~/.claude/skills/nebula-notebook/SKILL.md (all projects)
+  nebula setup-skill --project    # → ./.claude/skills/nebula-notebook/SKILL.md (this repo)
+  nebula setup-skill --dir <d>    # → <d>/nebula-notebook/SKILL.md
+  nebula setup-skill --print      # print the skill to stdout instead`);
+        return EXIT.OK;
+    }
+    if (values.print) {
+        process.stdout.write(SKILL_MD);
+        return EXIT.OK;
+    }
+    const baseDir = values.dir
+        ? path.resolve(values.dir)
+        : values.project
+            ? path.join(process.cwd(), '.claude', 'skills')
+            : path.join(os.homedir(), '.claude', 'skills');
+    const skillDir = path.join(baseDir, 'nebula-notebook');
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    try {
+        await fs.mkdir(skillDir, { recursive: true });
+        await fs.writeFile(skillPath, SKILL_MD, 'utf-8');
+    }
+    catch (err) {
+        throw new CliError(`failed to write skill: ${err instanceof Error ? err.message : String(err)}`, EXIT.ERROR, 'check permissions, or use --dir / --print');
+    }
+    console.log(`installed: ${skillPath}`);
+    if (!values.quiet) {
+        console.log('hint: new Claude Code sessions will discover it automatically; set NEBULA_URL in shells where agents run');
+    }
+    return EXIT.OK;
+}
+//# sourceMappingURL=skill.js.map

package/dist/cli/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/cli/skill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgHhB,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAC3B,IAAI,EAAE,IAAI;QACV,OAAO,EAAE;YACP,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;YAC5C,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACvB,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;YAC1C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;YACrD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;SAC3C;QACD,gBAAgB,EAAE,KAAK;KACxB,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC;;;;;;;sEAOsD,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG;QACxB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QAC1B,CAAC,CAAC,MAAM,CAAC,OAAO;YACd,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC;YAC/C,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEnD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAElD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAChB,0BAA0B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC5E,IAAI,CAAC,KAAK,EACV,2CAA2C,CAC5C,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,cAAc,SAAS,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,0GAA0G,CAAC,CAAC;IAC1H,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 export * from './types.js';
 export { classifyError, getErrorMessage, formatErrorMessage, shouldRetry, calculateRetryDelay, ErrorCategory, type ClassifiedError, type RecoverabilityStatus, } from './errors.js';
 export { CircuitBreaker, createCircuitBreaker, CircuitState, type CircuitBreakerOptions, type CircuitBreakerEvent, type CircuitBreakerListener, type CircuitBreakerResult, } from './circuit-breaker.js';
-export { NebulaClient, createNebulaClient, type NebulaClientConfig, type KernelSession, type ExecutionResult, type WriteCellResult, } from './notebook/client.js';
-export { type Tool, type ToolDefinition, type ToolResult, type MCPContent, allTools, toolsByName, toolCategories, notebookTools, kernelTools, executionTools, getToolDefinitions, executeToolByName, executeToolForMCP, getTool, hasTool, getToolNamesByCategory, readNotebookTool, readCellTool, readOutputTool, insertCellTool, updateCellTool, deleteCellTool, createNotebookTool, moveCellTool, duplicateCellTool, searchCellsTool, updateMetadataTool, listKernelsTool, kernelStartTool, kernelStopTool, kernelRestartTool, kernelInterruptTool, executeCellTool, } from './tools/index.js';
+export { NebulaClient, createNebulaClient, type NebulaClientConfig, type KernelSession, type ExecutionResult, type WriteCellResult, type ComputeAllocation, type ComputeAllocationState, type ComputeSpec, type ComputeStatus, type ComputePartitions, type ComputePartitionLoad, type ComputeQosLoad, type ComputeStartEstimate, } from './notebook/client.js';
+export { type Tool, type ToolDefinition, type ToolResult, type MCPContent, allTools, toolsByName, toolCategories, notebookTools, kernelTools, executionTools, computeTools, getToolDefinitions, executeToolByName, executeToolForMCP, getTool, hasTool, getToolNamesByCategory, readNotebookTool, readCellTool, readOutputTool, insertCellTool, updateCellTool, deleteCellTool, createNotebookTool, moveCellTool, duplicateCellTool, searchCellsTool, updateMetadataTool, listKernelsTool, kernelStartTool, kernelStopTool, kernelRestartTool, kernelInterruptTool, executeCellTool, computeStatusTool, listComputeQueuesTool, requestAllocationTool, listAllocationsTool, cancelAllocationTool, useAllocationTool, } from './tools/index.js';
 export { readNotebookCells, writeNotebookCell, executeCell, searchNotebookCells, readCellsToolDefinition, writeCellToolDefinition, executeCellToolDefinition, searchCellsToolDefinition, type ReadCellsParams, type ReadCellsResult, type WriteCellParams, type ExecuteCellParams, type ExecuteCellResult, type SearchCellsParams, type SearchCellsResult, } from './notebook/tools.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,cAAc,YAAY,CAAC;AAK3B,OAAO,EACL,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EAGf,QAAQ,EACR,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EAGd,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,sBAAsB,EAGtB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAGlB,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EAGnB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,cAAc,YAAY,CAAC;AAK3B,OAAO,EACL,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAEL,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EAGf,QAAQ,EACR,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,cAAc,EACd,YAAY,EAGZ,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,sBAAsB,EAGtB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAGlB,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EAGnB,eAAe,EAGf,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC"}