nebula-notebook 0.1.1 → 0.2.1

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

@@ -40,8 +40,12 @@ exports.setupTerminalRoutes = setupTerminalRoutes;
 exports.setupTerminalWebSocket = setupTerminalWebSocket;
 exports.cleanupTerminals = cleanupTerminals;
 const ws_1 = require("ws");
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const pty_manager_1 = require("./pty-manager");
+const agent_registry_1 = require("./agent-registry");
+const binding_store_1 = require("./binding-store");
 const fs_service_1 = require("../fs/fs-service");
 // Get configured root directory for terminals
 function getDefaultCwd() {
@@ -59,11 +63,82 @@ const wsConnections = new Map();
  */
 async function setupTerminalRoutes(fastify) {
     // Terminal health check (includes terminal count and repo root for the
-    // path-qualified MCP setup hint shown in the agent terminal UI)
+    // path-qualified MCP setup hint shown in the agent terminal UI, plus
+    // hostname/port so the UI can compose an exact SSH tunnel command)
     fastify.get('/api/terminals/health', async (_request, reply) => {
-        return reply.send({ status: 'ok', terminals: pty_manager_1.ptyManager.list().length, repo_root: NEBULA_REPO_ROOT });
+        return reply.send({
+            status: 'ok',
+            terminals: pty_manager_1.ptyManager.list().length,
+            repo_root: NEBULA_REPO_ROOT,
+            hostname: os.hostname(),
+            port: Number(process.env.PORT) || 3000,
+        });
+    });
+    // Probe a loopback port on THIS host — used by remote-agent mode to detect
+    // whether the user's reverse SSH channel (ssh -R <port>:localhost:22) is up.
+    // Loopback-only by construction; the port is user-chosen and random.
+    fastify.get('/api/terminals/reverse-check', async (request, reply) => {
+        const port = Number(request.query.port);
+        if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+            return reply.status(400).send({ error: 'port must be an integer in 1024-65535' });
+        }
+        // Two-signal probe at the cost of one connection: `up` = the listener
+        // accepted (fast path, unchanged); `ssh` = an SSH banner arrived within
+        // 700ms of connecting (an sshd greets immediately with "SSH-2.0-...").
+        // ssh=false means the port is forwarded but nothing SSH answers — the
+        // classic Remote-Login-off case; ssh=null means banner unknown (slow
+        // network) and MUST NOT be treated as a failure.
+        const result = await new Promise((resolve) => {
+            const sock = net.connect({ host: '127.0.0.1', port, timeout: 1200 });
+            let bannerTimer = null;
+            const finish = (up, ssh) => {
+                if (bannerTimer)
+                    clearTimeout(bannerTimer);
+                sock.destroy();
+                resolve({ up, ssh });
+            };
+            sock.once('connect', () => {
+                bannerTimer = setTimeout(() => finish(true, null), 700);
+                sock.once('data', (buf) => finish(true, buf.toString('latin1').startsWith('SSH-')));
+            });
+            sock.once('timeout', () => finish(false, null));
+            sock.once('error', () => finish(false, null));
+        });
+        return reply.send({ up: result.up, ssh: result.ssh });
     });
     // List all terminals
+    // ---- Agent registry: project-scoped agent sessions (see agent-registry.ts) ----
+    fastify.get('/api/agents', async (_request, reply) => {
+        return reply.send({ agents: await agent_registry_1.agentRegistry.listEnriched() });
+    });
+    fastify.post('/api/agents/register', async (request, reply) => {
+        const b = (request.body ?? {});
+        if (!b.terminalId || !b.kind || !b.workdir) {
+            return reply.code(400).send({ error: 'terminalId, kind, workdir required' });
+        }
+        const record = agent_registry_1.agentRegistry.register({
+            terminalId: b.terminalId,
+            kind: b.kind === 'codex' ? 'codex' : 'claude',
+            workdir: b.workdir,
+            location: b.location === 'remote' ? 'remote' : 'server',
+            sessionId: b.sessionId,
+            launchedFrom: b.launchedFrom,
+            mirrorSlug: b.mirrorSlug,
+        });
+        return reply.send(record);
+    });
+    fastify.post('/api/agents/:id/hibernate', async (request, reply) => {
+        const { id } = request.params;
+        if (!agent_registry_1.agentRegistry.hibernate(id))
+            return reply.code(404).send({ error: 'unknown agent' });
+        return reply.send({ ok: true });
+    });
+    fastify.delete('/api/agents/:id', async (request, reply) => {
+        const { id } = request.params;
+        if (!agent_registry_1.agentRegistry.remove(id))
+            return reply.code(404).send({ error: 'unknown agent' });
+        return reply.send({ ok: true });
+    });
     fastify.get('/api/terminals', async (_request, reply) => {
         return reply.send(pty_manager_1.ptyManager.list());
     });
@@ -104,6 +179,63 @@ async function setupTerminalRoutes(fastify) {
             });
         }
     });
+    // --- Terminal bindings: which named pty a notebook's panel attaches to ---
+    // GET returns the stored binding, or the plane default when none is stored
+    // (shell → server-shared srv-main; agent → project scope, name resolved
+    // client-side from the chosen workdir).
+    fastify.get('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane } = request.query;
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        const stored = binding_store_1.terminalBindings.get(file_path, plane);
+        if (stored) {
+            return reply.send({
+                plane, scope: stored.scope, name: stored.name,
+                custom_name: stored.customName ?? null, stored: true,
+            });
+        }
+        if (plane === 'shell') {
+            return reply.send({ plane, scope: 'server', name: binding_store_1.SHARED_SHELL_NAME, custom_name: null, stored: false });
+        }
+        return reply.send({ plane, scope: 'project', name: null, custom_name: null, stored: false });
+    });
+    fastify.put('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane, scope, name } = request.body || {};
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        if (!['server', 'project', 'notebook', 'named'].includes(scope || '')) {
+            return reply.code(400).send({ detail: 'scope must be server|project|notebook|named' });
+        }
+        try {
+            const binding = binding_store_1.terminalBindings.set(file_path, plane, scope, name);
+            return reply.send({
+                plane, scope: binding.scope, name: binding.name,
+                custom_name: binding.customName ?? null, stored: true,
+            });
+        }
+        catch (e) {
+            return reply.code(400).send({ detail: e instanceof Error ? e.message : 'Invalid binding' });
+        }
+    });
+    fastify.delete('/api/terminals/binding', async (request, reply) => {
+        const { file_path, plane } = request.query;
+        if (!file_path || (plane !== 'shell' && plane !== 'agent')) {
+            return reply.code(400).send({ detail: 'file_path and plane (shell|agent) are required' });
+        }
+        binding_store_1.terminalBindings.delete(file_path, plane);
+        return reply.send({ ok: true });
+    });
+    // Process-table probe: does this pty's shell have a live child? Clients MUST
+    // check this before typing a launch command into an existing pty — records
+    // can mis-score liveness (a hand-resumed agent never re-registers), and a
+    // launch line typed into a live TUI becomes a chat prompt (lab report).
+    // busy:null = unknown (pty gone / pgrep unavailable) — claim nothing.
+    fastify.get('/api/terminals/:id/busy', async (request, reply) => {
+        const busy = await pty_manager_1.ptyManager.hasLiveChild(request.params.id);
+        return reply.send({ busy });
+    });
     // Get terminal info
     fastify.get('/api/terminals/:id', async (request, reply) => {
         const terminal = pty_manager_1.ptyManager.getTerminalInfo(request.params.id);
@@ -184,28 +316,28 @@ function setupTerminalWebSocket(server) {
         // Send buffered output for reconnection
         const buffer = pty_manager_1.ptyManager.getOutputBuffer(terminalId);
         if (buffer) {
-            const replayMsg = { type: 'replay', data: buffer };
+            // Append an authoritative reassert of the sticky input modes so a
+            // reconnect never leaves mouse/focus reporting dangling on at the shell
+            // (the buffer trim can drop or split the app's own mode-reset).
+            const info = pty_manager_1.ptyManager.getTerminalInfo(terminalId);
+            const replayMsg = {
+                type: 'replay',
+                data: buffer + pty_manager_1.ptyManager.getModeReset(terminalId),
+                cols: info?.cols,
+                rows: info?.rows,
+            };
             ws.send(JSON.stringify(replayMsg));
         }
-        // Collaborative mode: broadcast output to ALL connected clients
-        const broadcastOutput = (data) => {
-            const msg = { type: 'output', data };
-            const msgStr = JSON.stringify(msg);
-            for (const conn of connections) {
-                if (conn.readyState === ws_1.WebSocket.OPEN) {
-                    conn.send(msgStr);
-                }
+        // One subscription per websocket, sending only to ITS socket — the pty
+        // layer now multicasts, so no shared-closure broadcast trickery needed.
+        const unsubData = pty_manager_1.ptyManager.addDataListener(terminalId, (data) => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: 'output', data }));
             }
-        };
-        pty_manager_1.ptyManager.setOnData(terminalId, broadcastOutput);
-        // Set up exit listener - broadcast to all connections
-        pty_manager_1.ptyManager.setOnExit(terminalId, (code) => {
-            const msg = { type: 'exit', code };
-            const msgStr = JSON.stringify(msg);
-            for (const conn of connections) {
-                if (conn.readyState === ws_1.WebSocket.OPEN) {
-                    conn.send(msgStr);
-                }
+        });
+        const unsubExit = pty_manager_1.ptyManager.addExitListener(terminalId, (code) => {
+            if (ws.readyState === ws_1.WebSocket.OPEN) {
+                ws.send(JSON.stringify({ type: 'exit', code }));
             }
         });
         // Handle incoming messages
@@ -230,13 +362,13 @@ function setupTerminalWebSocket(server) {
         // Handle disconnection
         ws.on('close', () => {
             console.log(`[Terminal] WebSocket disconnected from terminal ${terminalId}`);
+            unsubData();
+            unsubExit();
             const connections = wsConnections.get(terminalId);
             if (connections) {
                 connections.delete(ws);
                 if (connections.size === 0) {
                     wsConnections.delete(terminalId);
-                    // Clear the data listener when no connections
-                    pty_manager_1.ptyManager.setOnData(terminalId, null);
                 }
             }
         });

package/node-server/dist/terminal/types.d.ts

@@ -35,6 +35,8 @@ export type ServerMessage = {
 } | {
     type: 'replay';
     data: string;
+    cols?: number;
+    rows?: number;
 } | {
     type: 'exit';
     code: number;

package/node-server/dist/update-check.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Update check — notify-only, never auto-installs.
+ *
+ * Once at startup (and daily after), asks the npm registry for the latest
+ * published nebula-notebook version and compares it to the running one.
+ * Result is surfaced in /api/health (`update`) for the UI pill and logged
+ * once to the server console. Opt out with NEBULA_NO_UPDATE_CHECK=1.
+ * Network failures are silent: an update check must never affect operation.
+ */
+export interface UpdateInfo {
+    current: string;
+    latest: string | null;
+    update_available: boolean;
+    checked_at: number | null;
+}
+/** Numeric semver compare on MAJOR.MINOR.PATCH; ignores prerelease tags. */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+export declare function startUpdateChecker(): void;
+export declare function stopUpdateChecker(): void;
+export declare function getUpdateInfo(): UpdateInfo;

package/node-server/dist/update-check.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Update check — notify-only, never auto-installs.
+ *
+ * Once at startup (and daily after), asks the npm registry for the latest
+ * published nebula-notebook version and compares it to the running one.
+ * Result is surfaced in /api/health (`update`) for the UI pill and logged
+ * once to the server console. Opt out with NEBULA_NO_UPDATE_CHECK=1.
+ * Network failures are silent: an update check must never affect operation.
+ */
+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.isNewerVersion = isNewerVersion;
+exports.startUpdateChecker = startUpdateChecker;
+exports.stopUpdateChecker = stopUpdateChecker;
+exports.getUpdateInfo = getUpdateInfo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const REGISTRY_URL = 'https://registry.npmjs.org/nebula-notebook/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily
+const FETCH_TIMEOUT_MS = 4000;
+let info = { current: readCurrentVersion(), latest: null, update_available: false, checked_at: null };
+let timer = null;
+/** Running version from the repo/package root (this file is at node-server/{src,dist}/ — 2 levels up). */
+function readCurrentVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (typeof pkg.version === 'string')
+            return pkg.version;
+    }
+    catch { /* fall through */ }
+    return '0.0.0';
+}
+/** Numeric semver compare on MAJOR.MINOR.PATCH; ignores prerelease tags. */
+function isNewerVersion(latest, current) {
+    const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map(n => parseInt(n, 10) || 0);
+    const [lMaj, lMin, lPat] = parse(latest);
+    const [cMaj, cMin, cPat] = parse(current);
+    if (lMaj !== cMaj)
+        return lMaj > cMaj;
+    if (lMin !== cMin)
+        return lMin > cMin;
+    return lPat > cPat;
+}
+async function checkOnce() {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return;
+        const data = (await res.json());
+        if (typeof data.version !== 'string')
+            return;
+        const updateAvailable = isNewerVersion(data.version, info.current);
+        const firstDiscovery = updateAvailable && !info.update_available;
+        info = { ...info, latest: data.version, update_available: updateAvailable, checked_at: Date.now() };
+        if (firstDiscovery) {
+            console.log(`[Update] nebula-notebook v${data.version} is available (running v${info.current}) — ` +
+                `update with: npx nebula-notebook@latest (or git pull for source installs)`);
+        }
+    }
+    catch { /* offline / registry down / air-gapped cluster — stay quiet */ }
+}
+function startUpdateChecker() {
+    if (process.env.NEBULA_NO_UPDATE_CHECK)
+        return;
+    void checkOnce();
+    timer = setInterval(() => void checkOnce(), CHECK_INTERVAL_MS);
+    timer.unref?.(); // never keep the process alive for this
+}
+function stopUpdateChecker() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+function getUpdateInfo() {
+    return info;
+}

package/node-server/package.json

@@ -20,10 +20,12 @@
     "better-sqlite3": "^11.0.0",
     "fastify": "^5.8.2",
     "jsonwebtoken": "^9.0.2",
+    "nebula-autocomplete": "file:../packages/autocomplete",
     "otplib": "^12.0.1",
     "qrcode-terminal": "^0.12.0",
     "uuid": "^9.0.1",
     "ws": "^8.16.0",
+    "yaml": "^2.9.0",
     "zeromq": "^6.4.2"
   },
   "devDependencies": {

package/node_modules/nebula-autocomplete/README.md

@@ -0,0 +1,145 @@
+# nebula-autocomplete
+
+LLM code autocomplete for notebook editors, backed by **Claude Code CLI** or
+**Codex CLI** subscription auth (no API key). Three entry points:
+
+| Import | What it is |
+|---|---|
+| `nebula-autocomplete` | `AutocompleteEngine` + `ClaudeBackend` / `CodexBackend` (Node) |
+| `nebula-autocomplete/server` | `registerAutocompleteRoute(fastify, engine)` — SSE endpoint |
+| `nebula-autocomplete/client` | `createCompletionFetcher(url)` — browser SSE client |
+| `nebula-autocomplete/codemirror` | `ghostText(fetcher)` — CodeMirror 6 inline ghost text |
+
+> **Licensing:** subscription auth is for personal use. Anthropic/OpenAI
+> consumer terms prohibit routing other users through your subscription or
+> offering subscription login in a distributed app. To ship this to others,
+> implement a `CompletionBackend` that calls the provider API with a key —
+> the rest of the stack is unchanged.
+
+## Measured latency (2026-07, M-series Mac)
+
+| Backend | Model | Warm TTFB | Notes |
+|---|---|---|---|
+| `ClaudeBackend` | haiku 4.5 | ~1.4–2.1s | token-streamed; warm process pool |
+| `CodexBackend` | gpt-5.6-luna, low effort | ~2.2–2.7s | buffered; one-shot exec |
+
+Cache hits return in 0ms. Claude's harness costs ~24k input tokens per
+completion, codex ~12.6k — that overhead is inherent to CLI backends and is
+why a raw-API backend (~0.6–1s) is the upgrade path for keystroke-grade UX.
+
+## Quick start (server side)
+
+```ts
+import { AutocompleteEngine, ClaudeBackend } from "nebula-autocomplete";
+import { registerAutocompleteRoute } from "nebula-autocomplete/server";
+
+const engine = new AutocompleteEngine({
+  backend: new ClaudeBackend(),          // or new CodexBackend({ codexHome })
+  cacheSize: 128,
+  contextBudget: 6000,                   // chars of cross-cell context
+});
+
+// inside your Fastify route registration (prefix "/api"):
+registerAutocompleteRoute(fastify, engine); // POST /api/autocomplete (SSE)
+
+process.on("exit", () => engine.dispose());
+```
+
+`CodexBackend` tip: create a clean `CODEX_HOME` containing only `auth.json`
+(`mkdir -p .codex-home && cp ~/.codex/auth.json .codex-home/`) and pass it as
+`codexHome` — it skips global MCP servers/plugins/hooks (~2s/request faster).
+`gpt-5.6-luna` is the fast model that works with ChatGPT-subscription auth;
+`*-codex-mini` variants are API-key-only.
+
+## Quick start (client side, CodeMirror 6)
+
+```ts
+import { createCompletionFetcher } from "nebula-autocomplete/client";
+import { ghostText } from "nebula-autocomplete/codemirror";
+
+const fetchCompletion = createCompletionFetcher("/api/autocomplete");
+
+const extension = ghostText(
+  ({ prefix, suffix }, { signal, onChunk }) =>
+    fetchCompletion(
+      {
+        prefix,
+        suffix,
+        language: "python",
+        cells: allCellsRef.current ?? [],       // cross-cell context
+        activeCellIndex,
+        sessionKey: cellId,                      // supersedes stale requests
+      },
+      { signal, onChunk },
+    ).then((r) => r.text),
+  { debounceMs: 400 },
+);
+// add `extension` to the editor's extensions array
+```
+
+Tab accepts the suggestion, Escape dismisses, any edit or cursor move
+invalidates it. Ghost text renders via a `.cm-ghost-text` span (style it in
+your theme if the default 0.45 opacity doesn't fit).
+
+## Integrating into nebula-notebook
+
+This package now lives inside the nebula-notebook repo at
+`packages/autocomplete` and is wired up already:
+
+1. **Dependency** (in-repo `file:` link; bundled into the published tarball via
+   `bundledDependencies`):
+   - root `package.json`: `"nebula-autocomplete": "file:packages/autocomplete"`
+   - `node-server/package.json`: `"nebula-autocomplete": "file:../packages/autocomplete"`
+   `dist/` is built automatically by this package's `prepare` script on
+   `npm install` (see `scripts/postinstall.cjs`).
+2. **Server**: in `node-server/src/index.ts` where routes are registered under
+   `/api` (~line 302), create one engine at startup and call
+   `registerAutocompleteRoute(app, engine)`. Dispose it on shutdown.
+3. **Client**: in `components/CodeEditor.tsx`, add the `ghostText(...)`
+   extension to the extensions `useMemo` (~line 725). The existing
+   kernel/static dropdown completion (`createCombinedCompletionSource`, line
+   533) stays as-is — ghost text is complementary, not a replacement. Cells
+   context is already available via the `allCellsRef` prop (line 51).
+4. **Dev proxy**: nothing to add — Vite already proxies `/api` to the node
+   server (`vite.config.ts:19`).
+
+## API sketch
+
+- `engine.complete(req, { signal, onChunk }) → Promise<CompletionResult>` —
+  builds the prompt (instruction + nearest-cells context within budget +
+  `<CURSOR>` marker), checks the LRU cache, and calls the backend. Requests
+  sharing a `sessionKey` supersede each other. Output is fence-stripped and
+  prefix-echo-trimmed.
+- `CompletionBackend` — implement `{ name, complete(prompt, {signal, onChunk}), dispose() }`
+  to add a backend (e.g. Anthropic API for production).
+
+## Trajectory hygiene
+
+Completions must not spam CLI history/trajectory stores. Verified behavior:
+
+- **claude**: print mode + stream-json + `--tools ""` was observed to persist
+  nothing on macOS (claude 2.1.201), but Claude Code **can** write
+  `~/.claude/projects/<munged-cwd>/*.jsonl` session transcripts on other
+  versions/platforms — so we don't rely on that. Each worker runs in its own
+  UUID cwd; the backend deletes the matching `~/.claude/projects/*` transcript
+  dir on worker recycle (per-worker, so it never touches an active worker) and
+  the whole set on `dispose()`. Matching is by UUID token via
+  `transcriptDirMatchesToken`, which is munge-algorithm-independent and cannot
+  collide with a real project. Respects `CLAUDE_CONFIG_DIR`. The throwaway
+  `workspaceDir` (also removed on dispose) is a second guard.
+- **codex**: `--ephemeral` (no session/rollout files),
+  `history.persistence="none"` (no prompt history), and
+  `features.plugins=false` (skips the curated-plugins sync, which otherwise
+  clones tens of MB into `CODEX_HOME/.tmp` on **every** exec). Verified: zero
+  files and stable directory size across repeated completions. Codex still
+  maintains a few small bounded sqlite files in `CODEX_HOME`.
+
+## Development
+
+```sh
+npm install
+npm run build     # tsc → dist/
+npm test          # vitest unit tests (no CLI calls)
+npm run smoke     # live end-to-end vs claude   (uses your subscription)
+NEBULA_CODEX_HOME=path/to/.codex-home npm run smoke codex
+```

package/node_modules/nebula-autocomplete/dist/backends/claude.d.ts

@@ -0,0 +1,69 @@
+import type { CompletionBackend } from "../types.js";
+import { type Transport } from "../transport.js";
+export interface ClaudeBackendOptions {
+    /** Model passed to --model. Default "haiku" (fastest tier). */
+    model?: string;
+    /** Warm worker processes. Default 2. */
+    poolSize?: number;
+    /** Turns before a worker is recycled (stream-json turns share history). Default 8. */
+    maxTurnsPerWorker?: number;
+    /** Accumulated prompt chars before a worker is recycled. History size — not
+     *  turn count — is what drags TTFB, so this is the primary recycle driver.
+     *  Default 18_000 (~3 big-notebook prompts). */
+    maxHistoryCharsPerWorker?: number;
+    /** Per-turn timeout. Default 45_000 ms. */
+    turnTimeoutMs?: number;
+    /** Working directory for workers — keep it empty so no CLAUDE.md loads. */
+    workspaceDir?: string;
+    /** Path to the claude binary. Default "claude". */
+    binary?: string;
+    /** Where the claude process runs: locally (default) or over ssh on the user's
+     *  machine (remote Nebula + local agent). Default { kind: "local" }. */
+    transport?: Transport;
+    /** Thinking-token budget. Default 0: thinking never streams as ghost text
+     *  (observed burning a whole turn invisibly), but a budget can improve
+     *  tricky completions — surfaced as an Advanced setting. */
+    maxThinkingTokens?: number;
+}
+/**
+ * Persistent warm pool of `claude` CLI processes (subscription auth) in
+ * stream-json mode. Workers are recycled after maxTurnsPerWorker completions
+ * so conversation history never bloats the context.
+ */
+export declare class ClaudeBackend implements CompletionBackend {
+    readonly name = "claude";
+    private pool;
+    private opts;
+    private disposed;
+    private readonly wsToken;
+    constructor(options?: ClaudeBackendOptions);
+    /**
+     * Delete any Claude Code session-transcript directories that belong to this
+     * backend. Claude writes `~/.claude/projects/<munged-cwd>/*.jsonl` on some
+     * versions/platforms; the munged name preserves alphanumerics, so our
+     * wsToken (a UUID) always survives. We match by comparing alphanumeric-only
+     * forms, which is munge-algorithm-independent and cannot collide with a real
+     * project path. Best-effort: never throws into the caller.
+     */
+    private pruneTranscripts;
+    private ensurePool;
+    /**
+     * Spawn a worker wired for background self-healing: the claude CLI exits on
+     * its own after long idle, and replacing it lazily (at the next request)
+     * put the whole cold start — process boot + ssh reconnect + warmup turn —
+     * on the user's first post-idle completion (multi-second "autocomplete is
+     * dead after I come back" lag). Respawning the moment a worker dies keeps
+     * the pool warm through idle, so the first keystroke after a break pays the
+     * same ~1.5s as any other. Crash-loop guard: only self-respawn for workers
+     * that were healthy (survived 60s or completed a turn) — a broken binary
+     * dies instantly and would otherwise spawn-loop forever.
+     */
+    private spawnWorker;
+    complete(prompt: string, { signal, onChunk, diag }?: {
+        signal?: AbortSignal;
+        onChunk?: (t: string) => void;
+        diag?: import("../types.js").CompletionDiag;
+    }): Promise<string>;
+    private attempt;
+    dispose(): void;
+}