@a13xu/lucid 1.16.2 → 1.20.0

package/build/index.js

@@ -25,6 +25,10 @@ import { GenerateComponentSchema, handleGenerateComponent, ScaffoldPageSchema, h
 import { handleSmartContext, SmartContextSchema } from "./tools/smart-context.js";
 import { handleSuggestModel, SuggestModelSchema } from "./tools/model-advisor.js";
 import { handleCompressText, CompressTextSchema } from "./tools/compress.js";
+import { handleBackupFile, BackupFileSchema, handleRestoreFile, RestoreFileSchema, handleCheckTruncateRisk, CheckTruncateRiskSchema, } from "./tools/backup.js";
+import { handleSessionStatus, SessionStatusSchema } from "./tools/session.js";
+import { handleDelegateLocal, DelegateLocalSchema, handleLocalLlmStatus, LocalLlmStatusSchema, } from "./tools/delegate-local.js";
+import { loadLocalConfig } from "./local-llm/config.js";
 // ---------------------------------------------------------------------------
 // CLI mode: lucid watch | lucid status | lucid stop
 // ---------------------------------------------------------------------------
@@ -33,6 +37,201 @@ if (_cliCmd === "watch" || _cliCmd === "status" || _cliCmd === "stop") {
     await runCli(_cliCmd, _cliArgs);
     process.exit(0);
 }
+if (_cliCmd === "guard") {
+    const exitCode = await runGuardCli(_cliArgs);
+    process.exit(exitCode);
+}
+if (_cliCmd === "session") {
+    const exitCode = await runSessionCli(_cliArgs);
+    process.exit(exitCode);
+}
+if (_cliCmd === "local") {
+    const { runLocalLlmCli } = await import("./local-llm/setup-cli.js");
+    const exitCode = await runLocalLlmCli(_cliArgs);
+    process.exit(exitCode);
+}
+// ---------------------------------------------------------------------------
+// `lucid guard <subcmd>` — invoked from Claude Code hooks (PreToolUse, etc.)
+//
+// Subcommands:
+//   pre-edit              Read PreToolUse JSON from stdin, snapshot the file,
+//                         then assess truncate risk. Exit 2 = block (hard).
+//   pre-edit --path P     Same, but path provided as flag (no stdin parse).
+//   clear                 Clear cascade lock by purging recent truncate_events.
+//   status                Show cascade-lock status + last events.
+// ---------------------------------------------------------------------------
+async function runGuardCli(args) {
+    const sub = args[0];
+    const { initDatabase, prepareStatements } = await import("./database.js");
+    const db = initDatabase();
+    const stmts = prepareStatements(db);
+    if (sub === "clear") {
+        db.exec("DELETE FROM truncate_events");
+        process.stderr.write("[Lucid guard] Cascade lock cleared.\n");
+        return 0;
+    }
+    if (sub === "status") {
+        const { isCascadeBlocked, TUNABLES } = await import("./guardian/truncate-guard.js");
+        const cascade = isCascadeBlocked(stmts);
+        const since = Math.floor(Date.now() / 1000) - TUNABLES.CASCADE_WINDOW_SECONDS;
+        const events = stmts.recentTruncateEvents.all(since);
+        process.stdout.write(`Cascade locked: ${cascade.blocked} (${cascade.count}/${TUNABLES.CASCADE_THRESHOLD} ` +
+            `within ${TUNABLES.CASCADE_WINDOW_SECONDS}s)\n`);
+        for (const e of events) {
+            process.stdout.write(`  ${new Date(e.created_at * 1000).toISOString()} ` +
+                `${e.filepath} ${e.prev_size}B→${e.new_size}B (${(e.shrink_ratio * 100).toFixed(0)}%)\n`);
+        }
+        return 0;
+    }
+    if (sub === "pre-edit") {
+        return await guardPreEdit(stmts, args.slice(1));
+    }
+    process.stderr.write(`Usage: lucid guard <pre-edit|clear|status>\n`);
+    return 64; // EX_USAGE
+}
+async function guardPreEdit(stmts, flagArgs) {
+    const { backupFile, assessTruncate, recordTruncateEvent } = await import("./guardian/truncate-guard.js");
+    // Override switch — never blocks. Useful for one-off legitimate truncates.
+    if (process.env["LUCID_TRUNCATE_OVERRIDE"] === "1")
+        return 0;
+    const pathFlagIdx = flagArgs.indexOf("--path");
+    let path = pathFlagIdx >= 0 ? flagArgs[pathFlagIdx + 1] : undefined;
+    let content = null;
+    let toolName = "Write";
+    // Try parsing PreToolUse JSON from stdin (Claude Code hook protocol).
+    // Skip stdin read when --path is given OR when stdin is a TTY (manual run).
+    if (!path && !process.stdin.isTTY) {
+        const raw = await readStdin();
+        if (raw.trim()) {
+            try {
+                const payload = JSON.parse(raw);
+                toolName = payload.tool_name ?? "Write";
+                const ti = payload.tool_input ?? {};
+                path = ti.file_path ?? ti.path;
+                if (typeof ti.content === "string")
+                    content = ti.content;
+                else if (Array.isArray(ti.edits)) {
+                    // MultiEdit — sum up final state crudely: use new_strings concatenated.
+                    content = ti.edits.map((e) => e.new_string ?? "").join("\n");
+                }
+                else if (typeof ti.new_string === "string") {
+                    content = ti.new_string;
+                }
+            }
+            catch {
+                // Non-JSON stdin — ignore, fall through to "no path" error.
+            }
+        }
+    }
+    if (!path) {
+        process.stderr.write("[Lucid guard] No file path in hook input — allowing.\n");
+        return 0;
+    }
+    // Snapshot BEFORE assessing — even if we end up blocking, we want the version
+    // that's about to be overwritten safely stored.
+    const snap = backupFile(stmts, path, `pre-${toolName.toLowerCase()}`);
+    if (snap.saved) {
+        process.stderr.write(`[Lucid guard] 📸 Snapshot stored for ${path}\n`);
+    }
+    const verdict = assessTruncate(path, content, stmts);
+    if (!verdict.blocked)
+        return 0;
+    recordTruncateEvent(stmts, path, verdict.prevSize, verdict.newSize, true);
+    // Exit code 2 → Claude Code blocks the tool call and surfaces stderr.
+    process.stderr.write(`🛑 [Lucid guard] BLOCK [${verdict.rule}] ${path}\n` +
+        `   ${verdict.reason}\n` +
+        (verdict.cascade
+            ? `   Override: set LUCID_TRUNCATE_OVERRIDE=1 or run "lucid guard clear".\n`
+            : `   prev=${verdict.prevSize}B new=${verdict.newSize}B keep=${(verdict.shrinkRatio * 100).toFixed(0)}%\n` +
+                `   Restore via: restore_file(path="${path}")\n`));
+    return 2;
+}
+// ---------------------------------------------------------------------------
+// `lucid session <subcmd>` — invoked from UserPromptSubmit & PreCompact hooks.
+//
+// Subcommands:
+//   tick           Read UserPromptSubmit JSON from stdin → emit hints to stdout
+//                  (Claude Code injects stdout as additional context).
+//   compact        Read PreCompact JSON from stdin → reset session counters.
+//   status         Print recent sessions + active hint thresholds.
+//   reset [--id S] Reset a single session counter (or the latest if no --id).
+// ---------------------------------------------------------------------------
+async function runSessionCli(args) {
+    const sub = args[0];
+    const { initDatabase, prepareStatements } = await import("./database.js");
+    const db = initDatabase();
+    const stmts = prepareStatements(db);
+    if (sub === "tick")
+        return await sessionTickCli(stmts);
+    if (sub === "compact")
+        return await sessionCompactCli(stmts);
+    if (sub === "status") {
+        const { handleSessionStatus } = await import("./tools/session.js");
+        process.stdout.write(handleSessionStatus(stmts, { limit: 10 }) + "\n");
+        return 0;
+    }
+    if (sub === "reset") {
+        const idIdx = args.indexOf("--id");
+        if (idIdx >= 0 && args[idIdx + 1]) {
+            stmts.resetCliSessionCount.run(args[idIdx + 1]);
+            process.stderr.write(`[Lucid session] Reset counters for ${args[idIdx + 1]}\n`);
+        }
+        else {
+            const recent = stmts.recentCliSessions.all(1);
+            if (recent.length === 0) {
+                process.stderr.write("No sessions tracked.\n");
+                return 0;
+            }
+            stmts.resetCliSessionCount.run(recent[0].session_id);
+            process.stderr.write(`[Lucid session] Reset counters for ${recent[0].session_id}\n`);
+        }
+        return 0;
+    }
+    process.stderr.write(`Usage: lucid session <tick|compact|status|reset>\n`);
+    return 64;
+}
+async function sessionTickCli(stmts) {
+    const { tickSession } = await import("./guardian/session-tracker.js");
+    const payload = await readHookPayload();
+    const sid = payload?.session_id ?? "unknown-session";
+    const cwd = payload?.cwd ?? null;
+    const result = tickSession(stmts, sid, cwd);
+    // Emit hints to stdout — Claude Code injects them as additional context.
+    for (const h of result.hints)
+        process.stdout.write(h + "\n");
+    return 0;
+}
+async function sessionCompactCli(stmts) {
+    const { markCompactEvent } = await import("./guardian/session-tracker.js");
+    const payload = await readHookPayload();
+    const sid = payload?.session_id ?? "unknown-session";
+    markCompactEvent(stmts, sid);
+    process.stderr.write(`[Lucid session] /compact recorded — counters reset for ${sid}\n`);
+    return 0;
+}
+async function readHookPayload() {
+    if (process.stdin.isTTY)
+        return null;
+    const raw = await readStdin();
+    if (!raw.trim())
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readStdin() {
+    return new Promise((resolveStdin) => {
+        let buf = "";
+        const timer = setTimeout(() => resolveStdin(buf), 250);
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { buf += chunk; });
+        process.stdin.on("end", () => { clearTimeout(timer); resolveStdin(buf); });
+        process.stdin.on("error", () => { clearTimeout(timer); resolveStdin(buf); });
+    });
+}
 async function runCli(cmd, args) {
     const { join } = await import("path");
     const { homedir } = await import("os");
@@ -152,6 +351,14 @@ if (_embeddingUrl) {
 else {
     allowHost("https://api.openai.com");
 }
+// Local-LLM endpoint (may be remote — user-opted-in via `lucid local init`)
+const _localCfg = loadLocalConfig();
+if (_localCfg?.enabled) {
+    try {
+        allowHost(_localCfg.endpoint);
+    }
+    catch { /* ignore */ }
+}
 // ---------------------------------------------------------------------------
 // MCP Server (high-level McpServer API, SDK 1.27+)
 // ---------------------------------------------------------------------------
@@ -391,6 +598,53 @@ server.registerTool("check_code_quality", {
     inputSchema: checkCodeQualityShape,
 }, tx("check_code_quality", (args) => handleCheckCodeQuality(CheckCodeQualitySchema.parse(args))));
 // ---------------------------------------------------------------------------
+// Tools — Local LLM (Ollama / LM Studio / llama.cpp / remote endpoint)
+// ---------------------------------------------------------------------------
+server.registerTool("delegate_local", {
+    title: "Delegate to Local LLM",
+    description: "Send a prompt to the user-configured local LLM (Ollama / LM Studio / llama.cpp / remote " +
+        "endpoint). Returns the raw completion. Configure once via `lucid local init`. Best for " +
+        "small specialized tasks (docstrings, type hints, simple refactors, regex). Claude should " +
+        "review the output before applying it via Edit/Write.",
+    inputSchema: DelegateLocalSchema.shape,
+}, tx("delegate_local", async (args) => handleDelegateLocal(args)));
+server.registerTool("local_llm_status", {
+    title: "Local LLM Status",
+    description: "Inspect the local-LLM configuration: runtime, endpoint, model, reachability. " +
+        "Returns setup instructions if not yet configured.",
+    inputSchema: LocalLlmStatusSchema.shape,
+}, tx("local_llm_status", async () => handleLocalLlmStatus()));
+// ---------------------------------------------------------------------------
+// Tools — Session Cost Tracker
+// ---------------------------------------------------------------------------
+server.registerTool("session_status", {
+    title: "Session Status",
+    description: "Show recent Claude Code sessions with prompt counts, idle time, and /compact " +
+        "history. Use to inspect when /compact or /clear hints are about to fire.",
+    inputSchema: SessionStatusSchema.shape,
+}, tx("session_status", (args) => handleSessionStatus(stmts, args)));
+// ---------------------------------------------------------------------------
+// Tools — Backup & Truncate Guard
+// ---------------------------------------------------------------------------
+server.registerTool("backup_file", {
+    title: "Backup File",
+    description: "Snapshot the current on-disk content of a file into Lucid's versioned backup store " +
+        "(zlib-compressed, last 10 versions kept). Use before risky edits.",
+    inputSchema: BackupFileSchema.shape,
+}, tx("backup_file", (args) => handleBackupFile(stmts, args)));
+server.registerTool("restore_file", {
+    title: "Restore File",
+    description: "Restore a file from a previous Lucid backup. version=1 is the latest snapshot, " +
+        "2 is the one before, etc. Pass dry_run=true to preview without writing.",
+    inputSchema: RestoreFileSchema.shape,
+}, tx("restore_file", (args) => handleRestoreFile(stmts, args)));
+server.registerTool("check_truncate_risk", {
+    title: "Check Truncate Risk",
+    description: "Assess whether writing new_content (or new_size) to path would constitute a destructive " +
+        "truncate (empty/whitespace overwrite, >70% shrink, or active cascade lock). Read-only by default.",
+    inputSchema: CheckTruncateRiskSchema.shape,
+}, tx("check_truncate_risk", (args) => handleCheckTruncateRisk(stmts, args)));
+// ---------------------------------------------------------------------------
 // Tools — Planning
 // ---------------------------------------------------------------------------
 server.registerTool("plan_create", {

package/build/local-llm/client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTTP client wrapping Ollama and OpenAI-compatible /v1/chat/completions
+ * endpoints behind a single normalized interface.
+ *
+ * Inputs are validated; the configured endpoint is registered with the SSRF
+ * allowlist by the caller (see src/index.ts) so remote endpoints work after
+ * explicit user opt-in via `lucid local init`.
+ */
+import type { GenerateRequest, GenerateResponse, LocalLlmConfig } from "./types.js";
+export declare class LocalLlmError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare function generate(cfg: LocalLlmConfig, req: GenerateRequest): Promise<GenerateResponse>;
+/** Lightweight reachability check — just probes /api/tags or /v1/models. */
+export declare function ping(cfg: LocalLlmConfig): Promise<{
+    ok: boolean;
+    latency_ms: number;
+    detail?: string;
+}>;

package/build/local-llm/client.js

@@ -0,0 +1,140 @@
+/**
+ * HTTP client wrapping Ollama and OpenAI-compatible /v1/chat/completions
+ * endpoints behind a single normalized interface.
+ *
+ * Inputs are validated; the configured endpoint is registered with the SSRF
+ * allowlist by the caller (see src/index.ts) so remote endpoints work after
+ * explicit user opt-in via `lucid local init`.
+ */
+export class LocalLlmError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "LocalLlmError";
+    }
+}
+export async function generate(cfg, req) {
+    if (!cfg.enabled) {
+        throw new LocalLlmError("Local LLM is disabled. Run `lucid local init` to set it up.");
+    }
+    return cfg.runtime === "ollama"
+        ? generateOllama(cfg, req)
+        : generateOpenAi(cfg, req);
+}
+// ---------------------------------------------------------------------------
+// Ollama  POST /api/chat   (preferred — gives system role)
+// ---------------------------------------------------------------------------
+async function generateOllama(cfg, req) {
+    const url = `${cfg.endpoint.replace(/\/+$/, "")}/api/chat`;
+    const messages = [];
+    if (req.system)
+        messages.push({ role: "system", content: req.system });
+    messages.push({ role: "user", content: req.prompt });
+    const body = {
+        model: cfg.model,
+        messages,
+        stream: false,
+        options: {
+            temperature: req.temperature ?? 0.2,
+            num_predict: req.max_tokens ?? 2048,
+            ...(req.stop ? { stop: req.stop } : {}),
+        },
+    };
+    const start = Date.now();
+    const res = await postJson(url, body, cfg);
+    const latency = Date.now() - start;
+    const content = res.message?.content ?? "";
+    return {
+        text: content,
+        model: cfg.model,
+        latency_ms: latency,
+        prompt_tokens: res.prompt_eval_count,
+        completion_tokens: res.eval_count,
+    };
+}
+// ---------------------------------------------------------------------------
+// OpenAI-compatible  POST /v1/chat/completions
+// ---------------------------------------------------------------------------
+async function generateOpenAi(cfg, req) {
+    const url = `${cfg.endpoint.replace(/\/+$/, "")}/v1/chat/completions`;
+    const messages = [];
+    if (req.system)
+        messages.push({ role: "system", content: req.system });
+    messages.push({ role: "user", content: req.prompt });
+    const body = {
+        model: cfg.model,
+        messages,
+        temperature: req.temperature ?? 0.2,
+        max_tokens: req.max_tokens ?? 2048,
+        stream: false,
+    };
+    if (req.stop)
+        body["stop"] = req.stop;
+    const start = Date.now();
+    const res = await postJson(url, body, cfg);
+    const latency = Date.now() - start;
+    const choice = res.choices?.[0];
+    const usage = res.usage;
+    return {
+        text: choice?.message?.content ?? "",
+        model: cfg.model,
+        latency_ms: latency,
+        prompt_tokens: usage?.prompt_tokens,
+        completion_tokens: usage?.completion_tokens,
+    };
+}
+// ---------------------------------------------------------------------------
+// Shared transport
+// ---------------------------------------------------------------------------
+async function postJson(url, body, cfg) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), cfg.timeout_ms);
+    const headers = { "Content-Type": "application/json" };
+    if (cfg.api_key)
+        headers["Authorization"] = `Bearer ${cfg.api_key}`;
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: ac.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new LocalLlmError(`Local LLM request failed: ${res.status} ${res.statusText}${text ? " — " + text.slice(0, 200) : ""}`, res.status);
+        }
+        return await res.json();
+    }
+    catch (e) {
+        if (e instanceof LocalLlmError)
+            throw e;
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("aborted")) {
+            throw new LocalLlmError(`Local LLM request timed out after ${cfg.timeout_ms}ms`);
+        }
+        throw new LocalLlmError(`Local LLM request failed: ${msg}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Lightweight reachability check — just probes /api/tags or /v1/models. */
+export async function ping(cfg) {
+    const url = cfg.runtime === "ollama"
+        ? `${cfg.endpoint.replace(/\/+$/, "")}/api/tags`
+        : `${cfg.endpoint.replace(/\/+$/, "")}/v1/models`;
+    const start = Date.now();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 3_000);
+    try {
+        const res = await fetch(url, { signal: ac.signal });
+        return { ok: res.ok, latency_ms: Date.now() - start, detail: res.ok ? undefined : `HTTP ${res.status}` };
+    }
+    catch (e) {
+        return { ok: false, latency_ms: Date.now() - start, detail: e instanceof Error ? e.message : "unreachable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/build/local-llm/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Global config for the local-LLM endpoint, persisted at ~/.lucid/local.json.
+ * Project lucid.config.json may override (read by loadConfig in src/config.ts —
+ * here we only handle the global file so all projects share one setup by default).
+ */
+import type { LocalLlmConfig } from "./types.js";
+export declare function getConfigPath(): string;
+export declare function loadLocalConfig(): LocalLlmConfig | null;
+export declare function saveLocalConfig(cfg: LocalLlmConfig): void;
+export declare function disableLocalConfig(): boolean;
+export declare function isConfigured(): boolean;

package/build/local-llm/config.js

@@ -0,0 +1,50 @@
+/**
+ * Global config for the local-LLM endpoint, persisted at ~/.lucid/local.json.
+ * Project lucid.config.json may override (read by loadConfig in src/config.ts —
+ * here we only handle the global file so all projects share one setup by default).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+const CONFIG_DIR = join(homedir(), ".lucid");
+const CONFIG_PATH = join(CONFIG_DIR, "local.json");
+export function getConfigPath() {
+    return CONFIG_PATH;
+}
+export function loadLocalConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return null;
+    try {
+        const raw = readFileSync(CONFIG_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.endpoint !== "string" || typeof parsed.model !== "string")
+            return null;
+        return {
+            enabled: parsed.enabled !== false,
+            runtime: parsed.runtime ?? "ollama",
+            endpoint: parsed.endpoint,
+            model: parsed.model,
+            api_key: parsed.api_key,
+            timeout_ms: parsed.timeout_ms ?? 60_000,
+            configured_at: parsed.configured_at ?? new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveLocalConfig(cfg) {
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+}
+export function disableLocalConfig() {
+    const cfg = loadLocalConfig();
+    if (!cfg)
+        return false;
+    saveLocalConfig({ ...cfg, enabled: false });
+    return true;
+}
+export function isConfigured() {
+    const cfg = loadLocalConfig();
+    return cfg !== null && cfg.enabled;
+}

package/build/local-llm/runtimes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Probe known local-LLM runtimes on localhost (and any user-supplied endpoint).
+ *
+ * Detection rules:
+ *   GET /api/tags    → Ollama       (lists pulled models)
+ *   GET /v1/models   → OpenAI-compat (LM Studio, llama.cpp server, vLLM, …)
+ *
+ * Probes are short-timeout (1.5s) so they don't block setup.
+ */
+import type { DetectedRuntime, RuntimeKind } from "./types.js";
+/** Probe one specific endpoint. Returns null if nothing answers. */
+export declare function probeEndpoint(endpoint: string, headers?: Record<string, string>): Promise<DetectedRuntime | null>;
+/** Probe all known local ports — used for first-run auto-detect. */
+export declare function autoDetectLocal(): Promise<DetectedRuntime[]>;
+/** Human-readable runtime label, never throws. */
+export declare function describeRuntime(kind: RuntimeKind): string;

package/build/local-llm/runtimes.js

@@ -0,0 +1,82 @@
+/**
+ * Probe known local-LLM runtimes on localhost (and any user-supplied endpoint).
+ *
+ * Detection rules:
+ *   GET /api/tags    → Ollama       (lists pulled models)
+ *   GET /v1/models   → OpenAI-compat (LM Studio, llama.cpp server, vLLM, …)
+ *
+ * Probes are short-timeout (1.5s) so they don't block setup.
+ */
+const KNOWN_LOCAL_PORTS = [
+    { port: 11434, hint: "Ollama default" },
+    { port: 1234, hint: "LM Studio default" },
+    { port: 8080, hint: "llama.cpp server default" },
+    { port: 8000, hint: "vLLM / generic" },
+];
+const PROBE_TIMEOUT_MS = 1_500;
+async function probeUrl(url, headers) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), PROBE_TIMEOUT_MS);
+    const start = Date.now();
+    try {
+        const res = await fetch(url, { signal: ac.signal, headers });
+        if (!res.ok)
+            return { ok: false, latency: Date.now() - start };
+        const body = await res.json().catch(() => null);
+        return { ok: true, latency: Date.now() - start, body: body ?? undefined };
+    }
+    catch {
+        return { ok: false, latency: Date.now() - start };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Probe one specific endpoint. Returns null if nothing answers. */
+export async function probeEndpoint(endpoint, headers) {
+    const base = endpoint.replace(/\/+$/, "");
+    // Try Ollama first (cheap & specific) — body MUST have `.models` array,
+    // otherwise it's just a random service that happens to 200 on /api/tags.
+    const ollama = await probeUrl(`${base}/api/tags`, headers);
+    if (ollama.ok && hasOllamaShape(ollama.body)) {
+        return { kind: "ollama", endpoint: base, models: extractOllamaModels(ollama.body), latency_ms: ollama.latency };
+    }
+    // Then try OpenAI-compatible — body MUST have `.data` array of model entries.
+    const oai = await probeUrl(`${base}/v1/models`, headers);
+    if (oai.ok && hasOpenAiShape(oai.body)) {
+        return { kind: "openai-compat", endpoint: base, models: extractOpenAiModels(oai.body), latency_ms: oai.latency };
+    }
+    return null;
+}
+function hasOllamaShape(body) {
+    return !!body && typeof body === "object" && Array.isArray(body.models);
+}
+function hasOpenAiShape(body) {
+    return !!body && typeof body === "object" && Array.isArray(body.data);
+}
+/** Probe all known local ports — used for first-run auto-detect. */
+export async function autoDetectLocal() {
+    const probes = KNOWN_LOCAL_PORTS.map((p) => probeEndpoint(`http://localhost:${p.port}`));
+    const results = await Promise.all(probes);
+    return results.filter((r) => r !== null);
+}
+function extractOllamaModels(body) {
+    if (!body || typeof body !== "object")
+        return [];
+    const list = body.models;
+    return Array.isArray(list) ? list.map((m) => m.name ?? "").filter(Boolean) : [];
+}
+function extractOpenAiModels(body) {
+    if (!body || typeof body !== "object")
+        return [];
+    const data = body.data;
+    return Array.isArray(data) ? data.map((m) => m.id ?? "").filter(Boolean) : [];
+}
+/** Human-readable runtime label, never throws. */
+export function describeRuntime(kind) {
+    switch (kind) {
+        case "ollama": return "Ollama";
+        case "openai-compat": return "OpenAI-compatible (LM Studio / llama.cpp / vLLM)";
+        default: return "unknown";
+    }
+}

package/build/local-llm/setup-cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Interactive `lucid local <subcmd>` CLI.
+ * Subcommands: init | status | test | disable | pull
+ */
+export declare function runLocalLlmCli(args: string[]): Promise<number>;