@nexrall/code-core 1.0.0

package/dist/api/client.d.ts

@@ -0,0 +1,27 @@
+import type { Message, SSEEvent, AuthConfig, EnvContext, EditorContext } from '../types';
+export declare const API_BASE = "https://api.nexrall.com";
+export interface StreamChatOptions {
+    model: string;
+    env?: EnvContext;
+    editorContext?: EditorContext | null;
+    nexrallMd?: string;
+    mode?: string;
+    effort?: string;
+    clientType?: string;
+    abortSignal?: {
+        aborted: boolean;
+    };
+    /** Extra tool definitions from MCP servers — backend merges into Anthropic call. */
+    extraTools?: Array<{
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }>;
+    /** Catalogue of custom sub-agent types — injected into the system prompt. */
+    agents?: string;
+}
+export declare function streamChat(messages: Message[], options: StreamChatOptions, onEvent: (e: SSEEvent) => void): Promise<Message>;
+export declare function getBalance(): Promise<number>;
+export declare function exchangeVscodeCode(code: string): Promise<AuthConfig>;
+export declare function login(email: string, password: string): Promise<AuthConfig>;
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAA8B,UAAU,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKrH,eAAO,MAAM,QAAQ,4BAA4B,CAAC;AAiBlD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACjG,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CAkVlB;AAID,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAalD;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgB1E;AAID,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBhF"}

package/dist/api/client.js

@@ -0,0 +1,414 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_BASE = void 0;
+exports.streamChat = streamChat;
+exports.getBalance = getBalance;
+exports.exchangeVscodeCode = exchangeVscodeCode;
+exports.login = login;
+const eventsource_parser_1 = require("eventsource-parser");
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const index_1 = require("../auth/index");
+// ─── Constants ────────────────────────────────────────────────────────────────
+exports.API_BASE = 'https://api.nexrall.com';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function authHeaders() {
+    const token = (0, index_1.getToken)();
+    if (!token) {
+        throw new Error('Not authenticated. Run `nexrall-code login` first.');
+    }
+    return {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    };
+}
+// ─── Retry helpers ────────────────────────────────────────────────────────────
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 1000;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function streamChat(messages, options, onEvent) {
+    const { model, env, editorContext, nexrallMd, mode, effort, clientType, abortSignal, extraTools, agents } = options;
+    // Bridge custom abort signal → native AbortController so fetch is cancelled immediately
+    const controller = new AbortController();
+    if (abortSignal?.aborted)
+        throw Object.assign(new Error('Aborted'), { name: 'AbortError' });
+    let abortPoll;
+    if (abortSignal) {
+        abortPoll = setInterval(() => { if (abortSignal.aborted)
+            controller.abort(); }, 50);
+    }
+    const fetchArgs = [
+        `${exports.API_BASE}/api/code/chat`,
+        {
+            method: 'POST',
+            headers: authHeaders(),
+            body: JSON.stringify({ messages, model, env, editorContext, nexrallMd, mode, effort, clientType, extraTools, agents }),
+            signal: controller.signal,
+        },
+    ];
+    // A transient mid-stream failure (Anthropic "overloaded_error") arrives as an SSE error
+    // event over an ALREADY-200 response, so the connect-time HTTP-status retry below can't
+    // see it. We detect it in the parser and retry the WHOLE attempt with exponential backoff
+    // — but only while nothing has been emitted to the caller yet, so a retry can never
+    // duplicate already-rendered text or tool calls.
+    const isRetryableStreamMsg = (m) => /overloaded|rate.?limit|temporarily|unavailable|try again|internal server error/i.test(String(m ?? ''));
+    // One network attempt: connect (with connect-time 429/5xx retry) and consume the stream to
+    // completion. Returns the assembled assistant Message, or throws — tagging a transient
+    // pre-content failure with { retryable: true } for the outer loop below.
+    async function runAttempt() {
+        // Retry loop — handles connect-time 429 (rate limit) and 5xx (server errors, incl. 529)
+        let response;
+        let lastErr;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                response = await (0, node_fetch_1.default)(...fetchArgs);
+                if (response.status === 429 && attempt < MAX_RETRIES) {
+                    const retryAfter = parseInt(response.headers.get('retry-after') ?? '0', 10);
+                    await sleep(retryAfter > 0 ? retryAfter * 1000 : RETRY_BASE_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                if (response.status >= 500 && response.status < 600 && attempt < MAX_RETRIES) {
+                    await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                break; // success or non-retryable error
+            }
+            catch (err) {
+                // Don't retry on abort
+                if (err.name === 'AbortError')
+                    throw err;
+                lastErr = err;
+                if (attempt < MAX_RETRIES) {
+                    await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+                    continue;
+                }
+            }
+        }
+        if (!response)
+            throw lastErr ?? new Error('Request failed after max retries');
+        if (!response.ok) {
+            const errText = await response.text();
+            let errMsg = `API error ${response.status}`;
+            try {
+                const parsed = JSON.parse(errText);
+                if (parsed.error)
+                    errMsg = parsed.error;
+            }
+            catch {
+                errMsg = errText || errMsg;
+            }
+            throw new Error(errMsg);
+        }
+        if (!response.body) {
+            throw new Error('Response body is null');
+        }
+        // Accumulated state for building the assistant message
+        const textParts = [];
+        const toolUseBlocks = [];
+        let completedMessage = null;
+        // Once anything has been shown to the caller (text / tool_use / thinking), a retry would
+        // duplicate it — so from that point on a stream error is surfaced, never retried.
+        let emittedToCaller = false;
+        // Partial input accumulator keyed by tool_use id
+        const partialInputs = {};
+        await new Promise((resolve, reject) => {
+            // Feed chunks from the response body into the SSE parser.
+            // Declared here so the heartbeat watchdog closure can reference it.
+            const stream = response.body;
+            // ── Heartbeat watchdog ────────────────────────────────────────────────────
+            // The backend sends ": ping" comments every 20 s. If we receive no data at
+            // all for 45 s the connection has silently dropped (proxy timeout, network
+            // blip). Reject so the caller sees an actionable error instead of hanging.
+            const HEARTBEAT_TIMEOUT_MS = 45000;
+            // Progress watchdog. The backend's ": ping" keepalive (every 20 s) resets lastDataAt,
+            // so the heartbeat above only catches a fully dead connection — NOT an upstream model
+            // stall, where Anthropic stops emitting tokens but the backend keeps pinging. That case
+            // would otherwise hang on "Thinking…" forever. lastProgressAt is bumped ONLY on real
+            // model events (see parser below), never on pings, so a genuine stall trips this and
+            // surfaces a retryable error.
+            // Two-phase stall limits:
+            //   • BEFORE the first model event, the upstream is doing prompt processing (time-to-
+            //     first-token). On big contexts (1M window, cold prompt cache, large tool schemas)
+            //     that phase emits NOTHING until message_start and can legitimately exceed 150 s.
+            //     Killing it there was the "timeout 150s → retry instantly works" bug: the first
+            //     attempt warmed the prompt cache, so the retry's TTFT was short. Allow 300 s.
+            //   • AFTER the first model event, tokens are flowing; a 150 s silent gap mid-stream
+            //     is a genuine stall.
+            const FIRST_EVENT_TIMEOUT_MS = 300000;
+            const PROGRESS_TIMEOUT_MS = 150000;
+            let sawModelEvent = false;
+            let lastDataAt = Date.now();
+            let lastProgressAt = Date.now();
+            const heartbeatWatchdog = setInterval(() => {
+                const now = Date.now();
+                if (now - lastDataAt > HEARTBEAT_TIMEOUT_MS) {
+                    clearInterval(heartbeatWatchdog);
+                    stream.destroy?.();
+                    reject(new Error('Connection lost — no data received for 45 s. Retry your message.'));
+                    return;
+                }
+                const stallLimitMs = sawModelEvent ? PROGRESS_TIMEOUT_MS : FIRST_EVENT_TIMEOUT_MS;
+                if (now - lastProgressAt > stallLimitMs) {
+                    clearInterval(heartbeatWatchdog);
+                    stream.destroy?.();
+                    // If nothing has been shown to the caller yet, a fresh attempt can't duplicate
+                    // output — tag it retryable so the outer loop transparently retries the turn
+                    // instead of killing it. Once output has been emitted, a retry would duplicate
+                    // rendered text/tool calls, so surface the stall as a terminal error.
+                    const stallErr = new Error(sawModelEvent
+                        ? `The model stopped responding mid-stream (no output for ${Math.round(stallLimitMs / 1000)} s). Retry your message.`
+                        : `The model did not start responding within ${Math.round(stallLimitMs / 1000)} s (large context can take a while to process). Retry your message.`);
+                    reject(emittedToCaller ? stallErr : Object.assign(stallErr, { retryable: true }));
+                    return;
+                }
+            }, 5000);
+            const parser = (0, eventsource_parser_1.createParser)((event) => {
+                lastDataAt = Date.now(); // any SSE data (including ": ping" comments) resets the watchdog
+                // Skip reconnect-interval events
+                if (event.type !== 'event') {
+                    return;
+                }
+                {
+                    const raw = event.data;
+                    if (!raw || raw === '[DONE]') {
+                        resolve();
+                        return;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        return; // Skip malformed lines
+                    }
+                    if (typeof parsed !== 'object' || parsed === null || !('type' in parsed)) {
+                        return;
+                    }
+                    const evt = parsed;
+                    // Reaching here means a well-formed model event was parsed (": ping" keepalive
+                    // comments never produce a ParsedEvent with data) — count it as real progress.
+                    lastProgressAt = Date.now();
+                    sawModelEvent = true;
+                    switch (evt.type) {
+                        case 'text': {
+                            const text = typeof evt.text === 'string' ? evt.text : '';
+                            textParts.push(text);
+                            emittedToCaller = true;
+                            onEvent({ type: 'text', text });
+                            break;
+                        }
+                        case 'tool_use': {
+                            const block = {
+                                type: 'tool_use',
+                                id: typeof evt.id === 'string' ? evt.id : '',
+                                name: typeof evt.name === 'string' ? evt.name : '',
+                                input: evt.input ?? {},
+                            };
+                            // Handle streaming input deltas
+                            if (typeof evt.input_json_delta === 'string') {
+                                partialInputs[block.id] = (partialInputs[block.id] ?? '') + evt.input_json_delta;
+                                try {
+                                    block.input = JSON.parse(partialInputs[block.id]);
+                                }
+                                catch {
+                                    // Input not fully streamed yet
+                                    return;
+                                }
+                            }
+                            toolUseBlocks.push(block);
+                            emittedToCaller = true;
+                            onEvent({ type: 'tool_use', id: block.id, name: block.name, input: block.input });
+                            break;
+                        }
+                        case 'message_complete': {
+                            // Build the complete assistant message from accumulated parts
+                            const contentBlocks = [];
+                            const fullText = textParts.join('');
+                            if (fullText) {
+                                contentBlocks.push({ type: 'text', text: fullText });
+                            }
+                            contentBlocks.push(...toolUseBlocks);
+                            completedMessage = {
+                                role: 'assistant',
+                                content: contentBlocks,
+                            };
+                            onEvent({ type: 'message_complete', message: completedMessage });
+                            break;
+                        }
+                        case 'usage': {
+                            if (typeof evt.input_tokens === 'number' && typeof evt.output_tokens === 'number') {
+                                onEvent({
+                                    type: 'usage',
+                                    usage: {
+                                        input_tokens: evt.input_tokens,
+                                        output_tokens: evt.output_tokens,
+                                        cache_creation_input_tokens: typeof evt.cache_creation_input_tokens === 'number' ? evt.cache_creation_input_tokens : undefined,
+                                        cache_read_input_tokens: typeof evt.cache_read_input_tokens === 'number' ? evt.cache_read_input_tokens : undefined,
+                                    },
+                                });
+                            }
+                            break;
+                        }
+                        case 'context_warning': {
+                            const message = typeof evt.message === 'string' ? evt.message : '';
+                            if (message)
+                                onEvent({ type: 'error', message: `⚠️ ${message}` });
+                            break;
+                        }
+                        case 'thinking': {
+                            const text = typeof evt.text === 'string' ? evt.text : '';
+                            if (text) {
+                                emittedToCaller = true;
+                                onEvent({ type: 'thinking', text });
+                            }
+                            break;
+                        }
+                        case 'thinking_progress': {
+                            // Without this case the live token counter never updated and long thinking
+                            // phases (e.g. after reading a large file) looked frozen on "Thinking…".
+                            const tokens = typeof evt.tokens === 'number' ? evt.tokens : 0;
+                            onEvent({ type: 'thinking_progress', tokens });
+                            break;
+                        }
+                        case 'thinking_delta': {
+                            // Live thinking text streamed token-by-token so a long thinking phase shows
+                            // content as it forms, not a single block dumped at message completion.
+                            const text = typeof evt.text === 'string' ? evt.text : '';
+                            if (text) {
+                                emittedToCaller = true;
+                                onEvent({ type: 'thinking_delta', text });
+                            }
+                            break;
+                        }
+                        case 'done': {
+                            onEvent({ type: 'done' });
+                            resolve();
+                            break;
+                        }
+                        case 'error': {
+                            const message = typeof evt.message === 'string' ? evt.message :
+                                typeof evt.error === 'string' ? evt.error : 'Unknown SSE error';
+                            // Transient upstream failure before any output → let the outer loop retry it
+                            // transparently instead of killing the turn (this is the "Overloaded" case).
+                            if (isRetryableStreamMsg(message) && !emittedToCaller) {
+                                clearInterval(heartbeatWatchdog);
+                                stream.destroy?.();
+                                reject(Object.assign(new Error(message), { retryable: true }));
+                            }
+                            else {
+                                onEvent({ type: 'error', message });
+                                reject(new Error(message));
+                            }
+                            break;
+                        }
+                    }
+                }
+            });
+            stream.on('data', (chunk) => {
+                lastDataAt = Date.now();
+                if (abortSignal?.aborted) {
+                    stream.destroy?.();
+                    return;
+                }
+                parser.feed(chunk.toString('utf-8'));
+            });
+            stream.on('end', () => { clearInterval(heartbeatWatchdog); resolve(); });
+            // Treat stream destruction from abort as a clean exit, not an error
+            stream.on('error', (err) => {
+                clearInterval(heartbeatWatchdog);
+                if (abortSignal?.aborted || controller.signal.aborted) {
+                    resolve();
+                    return;
+                }
+                reject(err);
+            });
+        });
+        if (completedMessage) {
+            return completedMessage;
+        }
+        // Fallback: build message from accumulated parts if message_complete wasn't sent
+        const contentBlocks = [];
+        const fullText = textParts.join('');
+        if (fullText) {
+            contentBlocks.push({ type: 'text', text: fullText });
+        }
+        contentBlocks.push(...toolUseBlocks);
+        return { role: 'assistant', content: contentBlocks };
+    }
+    // Outer retry loop — retries a WHOLE attempt on a transient pre-content failure
+    // (overloaded_error / stall / dropped connection), with exponential backoff. Because
+    // runAttempt only tags an error retryable when nothing was emitted, a retry can never
+    // duplicate rendered output.
+    try {
+        for (let sAttempt = 0; sAttempt <= MAX_RETRIES; sAttempt++) {
+            try {
+                return await runAttempt();
+            }
+            catch (err) {
+                if (abortSignal?.aborted || controller.signal.aborted || err.name === 'AbortError')
+                    throw err;
+                if (err.retryable && sAttempt < MAX_RETRIES) {
+                    await sleep(RETRY_BASE_MS * Math.pow(2, sAttempt));
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new Error('Request failed after max retries');
+    }
+    finally {
+        if (abortPoll)
+            clearInterval(abortPoll);
+    }
+}
+// ─── Get Balance ──────────────────────────────────────────────────────────────
+async function getBalance() {
+    const response = await (0, node_fetch_1.default)(`${exports.API_BASE}/api/code/balance`, {
+        method: 'GET',
+        headers: authHeaders(),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`API error ${response.status}: ${errText}`);
+    }
+    const data = (await response.json());
+    return typeof data.balance === 'number' ? data.balance : 0;
+}
+// ─── VSCode OAuth ─────────────────────────────────────────────────────────────
+async function exchangeVscodeCode(code) {
+    const response = await (0, node_fetch_1.default)(`${exports.API_BASE}/api/auth/vscode-exchange`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`OAuth exchange failed (${response.status}): ${errText}`);
+    }
+    const data = (await response.json());
+    if (!data.token)
+        throw new Error('No token in exchange response');
+    return { token: data.token, email: data.user?.email ?? '' };
+}
+// ─── Login ────────────────────────────────────────────────────────────────────
+async function login(email, password) {
+    const response = await (0, node_fetch_1.default)(`${exports.API_BASE}/api/auth/login/email`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    if (!response.ok) {
+        const errText = await response.text();
+        throw new Error(`Login failed (${response.status}): ${errText}`);
+    }
+    const data = (await response.json());
+    if (!data.token) {
+        throw new Error('Login response missing token');
+    }
+    return { token: data.token, email: data.email ?? email };
+}
+//# sourceMappingURL=client.js.map

package/dist/auth/index.d.ts

@@ -0,0 +1,7 @@
+import type { AuthConfig } from '../types';
+export declare function saveAuth(config: AuthConfig): void;
+export declare function loadAuth(): AuthConfig | null;
+export declare function clearAuth(): void;
+export declare function isAuthenticated(): boolean;
+export declare function getToken(): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAiB3C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAGjD;AAED,wBAAgB,QAAQ,IAAI,UAAU,GAAG,IAAI,CAmB5C;AAED,wBAAgB,SAAS,IAAI,IAAI,CAQhC;AAED,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED,wBAAgB,QAAQ,IAAI,MAAM,GAAG,IAAI,CAGxC"}

package/dist/auth/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveAuth = saveAuth;
+exports.loadAuth = loadAuth;
+exports.clearAuth = clearAuth;
+exports.isAuthenticated = isAuthenticated;
+exports.getToken = getToken;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// ─── Config Path ──────────────────────────────────────────────────────────────
+const CONFIG_DIR = path.join(os.homedir(), '.nexrall');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function ensureConfigDir() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+// ─── Auth Operations ──────────────────────────────────────────────────────────
+function saveAuth(config) {
+    ensureConfigDir();
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+function loadAuth() {
+    try {
+        if (!fs.existsSync(CONFIG_FILE)) {
+            return null;
+        }
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'token' in parsed &&
+            typeof parsed.token === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function clearAuth() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            fs.unlinkSync(CONFIG_FILE);
+        }
+    }
+    catch {
+        // Ignore errors on clear
+    }
+}
+function isAuthenticated() {
+    const auth = loadAuth();
+    return auth !== null && auth.token.length > 0;
+}
+function getToken() {
+    const auth = loadAuth();
+    return auth?.token ?? null;
+}
+//# sourceMappingURL=index.js.map

package/dist/checkpoint/manager.d.ts

@@ -0,0 +1,86 @@
+export declare function isMutatingTool(name: string): boolean;
+export declare function isPotentiallyMutatingBash(command: string): boolean;
+export interface FileSnapshot {
+    absPath: string;
+    /** Did the path exist (as a file) before the mutation? */
+    existed: boolean;
+    /** Pre-mutation content as a Buffer (binary-safe), or null if absent/too large/not a file. */
+    content: Buffer | null;
+}
+export interface CheckpointSummary {
+    id: number;
+    label: string;
+    /** Conversation length (message count) just before this turn ran. */
+    messageIndex: number;
+    fileCount: number;
+    createdAt: string;
+    /** Number of potentially-mutating bash commands run in this turn (NOT rewindable). */
+    bashCount: number;
+    /** `git stash create` commit hash captured before the first mutating bash — manual recovery point. */
+    gitStashHash?: string;
+}
+export interface RestoreResult {
+    /** Absolute paths that were rolled back. */
+    restored: string[];
+    /** Truncate the conversation to this many messages to match the rewound state. */
+    messageIndex: number;
+    /** Total mutating bash commands across the rewound turns — their effects were NOT undone. */
+    bashCount: number;
+    /** git stash hashes captured across the rewound turns (newest first) for manual recovery. */
+    gitStashHashes: string[];
+}
+export declare class CheckpointManager {
+    private readonly workDir;
+    private turns;
+    private current;
+    private nextId;
+    private readonly storeDir;
+    /**
+     * @param workDir project root the snapshots are relative to
+     * @param scope   optional namespace (e.g. session id) so different sessions in
+     *                the same directory keep independent rewind histories
+     */
+    constructor(workDir: string, scope?: string);
+    private resolve;
+    /**
+     * Open a new turn. `label` is a short description (usually the user prompt),
+     * `messageIndex` is the conversation length the turn should rewind to.
+     */
+    beginTurn(label: string, messageIndex: number): void;
+    /**
+     * Snapshot the pre-mutation state of the files a tool is about to touch.
+     * Must be called BEFORE the tool executes. No-op for non-mutating tools or
+     * when no turn is open. First snapshot of a path within a turn wins (so the
+     * earliest pre-state is preserved even if the file is edited repeatedly).
+     */
+    recordBeforeMutation(name: string, input: Record<string, unknown>): void;
+    /**
+     * Record a bash command about to run in this turn. If it looks mutating,
+     * bump the turn's bash counter (so rewind can warn) and — on the FIRST
+     * mutating bash of the turn, if workDir is a dirty git repo — capture a
+     * `git stash create` hash as a manual recovery point. `git stash create`
+     * writes a dangling commit and does NOT touch the working tree or the stash
+     * list, so it is side-effect-free from the user's perspective.
+     */
+    recordBashCommand(command: string): void;
+    private tryGitStashCreate;
+    /** Seal the open turn into history. Empty turns (no mutations, no bash) are discarded. */
+    commitTurn(): void;
+    list(): CheckpointSummary[];
+    hasCheckpoints(): boolean;
+    /**
+     * Roll the working tree back to the state it had just before the checkpoint
+     * turn ran. Snapshots are applied newest → target so the earliest pre-state
+     * wins for any path touched in multiple turns. Returns the conversation
+     * truncation point, or null if the id is unknown.
+     */
+    restore(checkpointId: number): RestoreResult | null;
+    private applySnapshot;
+    private turnFile;
+    private persistTurn;
+    private persistIndex;
+    private deleteTurnFile;
+    private prune;
+    private loadFromDisk;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/checkpoint/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/checkpoint/manager.ts"],"names":[],"mappings":"AA4CA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAQD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMlE;AAyBD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AA6BD,qBAAa,iBAAiB;IAWhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;;;OAIG;gBAC0B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAa5D,OAAO,CAAC,OAAO;IAIf;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAcpD;;;;;OAKG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA8BxE;;;;;;;OAOG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQxC,OAAO,CAAC,iBAAiB;IAiBzB,0FAA0F;IAC1F,UAAU,IAAI,IAAI;IAWlB,IAAI,IAAI,iBAAiB,EAAE;IAY3B,cAAc,IAAI,OAAO;IAIzB;;;;;OAKG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IA0BnD,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,YAAY;CAkCrB"}