@a13xu/lucid 1.16.1 → 1.19.0

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>;

package/build/local-llm/setup-cli.js

@@ -0,0 +1,298 @@
+/**
+ * Interactive `lucid local <subcmd>` CLI.
+ * Subcommands: init | status | test | disable | pull
+ */
+import { createInterface } from "readline";
+import { spawn } from "child_process";
+import { loadLocalConfig, saveLocalConfig, disableLocalConfig, getConfigPath, } from "./config.js";
+import { autoDetectLocal, probeEndpoint, describeRuntime } from "./runtimes.js";
+import { generate, ping } from "./client.js";
+const RECOMMENDED_MODELS = [
+    { name: "qwen2.5-coder:1.5b", size: "~1 GB", note: "fast on CPU (~30 tok/s)  — recommended for brief synthesis" },
+    { name: "qwen2.5-coder:3b", size: "~3 GB", note: "balanced (~15 tok/s on CPU)" },
+    { name: "qwen2.5-coder:7b", size: "~7 GB", note: "best quality (~7 tok/s on CPU; 60+ on GPU)" },
+];
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+export async function runLocalLlmCli(args) {
+    const sub = args[0];
+    if (sub === "init")
+        return await cmdInit(args.slice(1));
+    if (sub === "status")
+        return await cmdStatus();
+    if (sub === "test")
+        return await cmdTest();
+    if (sub === "disable")
+        return cmdDisable();
+    if (sub === "pull")
+        return await cmdPull(args.slice(1));
+    process.stderr.write(`Usage: lucid local <init|status|test|disable|pull <model>>\n`);
+    return 64;
+}
+// ---------------------------------------------------------------------------
+// init — guided 5-step setup
+// ---------------------------------------------------------------------------
+async function cmdInit(_args) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write("\n🤖  Lucid Local LLM — interactive setup\n");
+        process.stdout.write(`     Config will be saved to ${getConfigPath()}\n\n`);
+        // ── Step 1: detect or accept remote endpoint ──────────────────────────
+        process.stdout.write("Step 1/5  Detecting local runtimes…\n");
+        const detected = await autoDetectLocal();
+        let chosen = null;
+        if (detected.length > 0) {
+            process.stdout.write(`  Found ${detected.length} runtime(s):\n`);
+            detected.forEach((d, i) => {
+                process.stdout.write(`    [${i + 1}] ${describeRuntime(d.kind)}  ${d.endpoint}  (${d.latency_ms}ms, ${d.models?.length ?? 0} models)\n`);
+            });
+            process.stdout.write(`    [r] Enter remote endpoint URL\n`);
+            process.stdout.write(`    [s] Skip — show install instructions\n`);
+            const ans = (await ask(rl, "  Choice [1]: ")).trim().toLowerCase() || "1";
+            if (ans === "s") {
+                showInstallInstructions();
+                return 0;
+            }
+            if (ans === "r") {
+                chosen = await promptRemoteEndpoint(rl);
+                if (!chosen)
+                    return 1;
+            }
+            else {
+                const idx = Number(ans) - 1;
+                if (Number.isFinite(idx) && idx >= 0 && idx < detected.length) {
+                    chosen = detected[idx];
+                }
+                else {
+                    process.stderr.write("  Invalid choice.\n");
+                    return 64;
+                }
+            }
+        }
+        else {
+            process.stdout.write("  No local runtime detected on common ports (11434, 1234, 8080, 8000).\n");
+            process.stdout.write("    [r] Enter remote endpoint URL\n");
+            process.stdout.write("    [s] Show install instructions and exit\n");
+            const ans = (await ask(rl, "  Choice [r]: ")).trim().toLowerCase() || "r";
+            if (ans === "s") {
+                showInstallInstructions();
+                return 0;
+            }
+            chosen = await promptRemoteEndpoint(rl);
+            if (!chosen)
+                return 1;
+        }
+        // ── Step 2: choose model ──────────────────────────────────────────────
+        process.stdout.write("\nStep 2/5  Choose model\n");
+        if (chosen.models && chosen.models.length > 0) {
+            process.stdout.write("  Already pulled on this runtime:\n");
+            chosen.models.slice(0, 10).forEach((m, i) => process.stdout.write(`    [${i + 1}] ${m}\n`));
+            process.stdout.write("    [n] None of these — show recommended downloads\n");
+            const ans = (await ask(rl, "  Choice [n]: ")).trim().toLowerCase() || "n";
+            if (ans !== "n") {
+                const models = chosen.models;
+                const idx = Number(ans) - 1;
+                if (Number.isFinite(idx) && idx >= 0 && idx < models.length) {
+                    const model = models[idx];
+                    return await finalizeSetup(rl, chosen.kind, chosen.endpoint, model, false);
+                }
+            }
+        }
+        process.stdout.write("\n  Recommended (Python-specialized coders):\n");
+        RECOMMENDED_MODELS.forEach((m, i) => {
+            process.stdout.write(`    [${i + 1}] ${m.name.padEnd(24)} ${m.size.padEnd(7)} ${m.note}\n`);
+        });
+        process.stdout.write("    [c] Custom model name (already pulled or to pull)\n");
+        const mAns = (await ask(rl, "  Choice [1]: ")).trim().toLowerCase() || "1";
+        let modelName;
+        if (mAns === "c") {
+            modelName = (await ask(rl, "  Model name (e.g. qwen2.5-coder:7b): ")).trim();
+            if (!modelName) {
+                process.stderr.write("  Empty name.\n");
+                return 64;
+            }
+        }
+        else {
+            const idx = Number(mAns) - 1;
+            if (!Number.isFinite(idx) || idx < 0 || idx >= RECOMMENDED_MODELS.length) {
+                process.stderr.write("  Invalid choice.\n");
+                return 64;
+            }
+            modelName = RECOMMENDED_MODELS[idx].name;
+        }
+        return await finalizeSetup(rl, chosen.kind, chosen.endpoint, modelName, true);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function finalizeSetup(rl, kind, endpoint, model, mayPull) {
+    // ── Step 3: optional pull ─────────────────────────────────────────────
+    if (mayPull && kind === "ollama") {
+        const pullAns = (await ask(rl, `\nStep 3/5  Pull "${model}" via ollama now? [Y/n]: `)).trim().toLowerCase();
+        if (pullAns === "" || pullAns === "y" || pullAns === "yes") {
+            const code = await streamPull(model);
+            if (code !== 0) {
+                process.stderr.write(`  ⚠️  ollama pull exited with code ${code}. You can rerun: ollama pull ${model}\n`);
+            }
+        }
+    }
+    else {
+        process.stdout.write("\nStep 3/5  Skipping model pull (handled by runtime).\n");
+    }
+    // ── Step 4: test ──────────────────────────────────────────────────────
+    process.stdout.write("\nStep 4/5  Testing endpoint…\n");
+    const probeCfg = {
+        enabled: true, runtime: kind, endpoint, model,
+        timeout_ms: 30_000,
+        configured_at: new Date().toISOString(),
+    };
+    const reach = await ping(probeCfg);
+    if (!reach.ok) {
+        process.stderr.write(`  ❌ Endpoint not reachable: ${reach.detail ?? "?"}\n`);
+        const cont = (await ask(rl, "  Save config anyway? [y/N]: ")).trim().toLowerCase();
+        if (cont !== "y" && cont !== "yes")
+            return 1;
+    }
+    else {
+        process.stdout.write(`  ✓ Endpoint reachable (${reach.latency_ms}ms). Running 1-token generate…\n`);
+        try {
+            const out = await generate(probeCfg, { prompt: "Say OK.", max_tokens: 8, temperature: 0 });
+            const preview = out.text.replace(/\s+/g, " ").trim().slice(0, 60);
+            process.stdout.write(`  ✓ Model responded in ${out.latency_ms}ms: "${preview}"\n`);
+        }
+        catch (e) {
+            process.stderr.write(`  ⚠️  Generation failed: ${e.message}\n`);
+            const cont = (await ask(rl, "  Save config anyway? [y/N]: ")).trim().toLowerCase();
+            if (cont !== "y" && cont !== "yes")
+                return 1;
+        }
+    }
+    // ── Step 5: save ──────────────────────────────────────────────────────
+    saveLocalConfig(probeCfg);
+    process.stdout.write(`\nStep 5/5  ✅ Saved → ${getConfigPath()}\n`);
+    process.stdout.write(`\nRestart Claude Code to activate. delegate_local() will then be available.\n\n`);
+    return 0;
+}
+async function promptRemoteEndpoint(rl) {
+    const url = (await ask(rl, "  Endpoint URL (e.g. http://gpu.lan:11434): ")).trim();
+    if (!url)
+        return null;
+    const apiKey = (await ask(rl, "  Bearer token (optional, press Enter to skip): ")).trim();
+    process.stdout.write(`  Probing ${url}…\n`);
+    const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined;
+    const det = await probeEndpoint(url, headers);
+    if (!det) {
+        process.stderr.write(`  ❌ No Ollama or OpenAI-compatible endpoint found at ${url}\n`);
+        return null;
+    }
+    process.stdout.write(`  ✓ ${describeRuntime(det.kind)} detected (${det.latency_ms}ms, ${det.models?.length ?? 0} models)\n`);
+    // Stash the api key on the returned struct via a side channel (set on cfg later).
+    if (apiKey)
+        det.api_key = apiKey;
+    return det;
+}
+// ---------------------------------------------------------------------------
+// status / test / disable / pull
+// ---------------------------------------------------------------------------
+async function cmdStatus() {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        process.stdout.write("Local LLM: not configured. Run `lucid local init`.\n");
+        return 0;
+    }
+    process.stdout.write([
+        `Local LLM: ${cfg.enabled ? "enabled" : "disabled"}`,
+        `  runtime:  ${describeRuntime(cfg.runtime)}`,
+        `  endpoint: ${cfg.endpoint}`,
+        `  model:    ${cfg.model}`,
+        `  api_key:  ${cfg.api_key ? "(set)" : "(none)"}`,
+        `  config:   ${getConfigPath()}`,
+        `  saved at: ${cfg.configured_at}`,
+    ].join("\n") + "\n");
+    const reach = await ping(cfg);
+    process.stdout.write(`  reachable: ${reach.ok ? `✓ ${reach.latency_ms}ms` : `✗ ${reach.detail ?? "?"}`}\n`);
+    return 0;
+}
+async function cmdTest() {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        process.stderr.write("Not configured. Run `lucid local init` first.\n");
+        return 1;
+    }
+    process.stdout.write(`Testing ${cfg.model} on ${cfg.endpoint}…\n`);
+    try {
+        const out = await generate(cfg, {
+            prompt: "Write a one-line Python function that returns the square of its argument.",
+            max_tokens: 64, temperature: 0.1,
+        });
+        process.stdout.write(`✓ ${out.latency_ms}ms (prompt=${out.prompt_tokens ?? "?"}, completion=${out.completion_tokens ?? "?"})\n`);
+        process.stdout.write(`---\n${out.text.trim()}\n---\n`);
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`✗ ${e.message}\n`);
+        return 1;
+    }
+}
+function cmdDisable() {
+    const ok = disableLocalConfig();
+    process.stdout.write(ok ? "Local LLM disabled.\n" : "Nothing to disable (not configured).\n");
+    return 0;
+}
+async function cmdPull(args) {
+    const cfg = loadLocalConfig();
+    const model = args[0] ?? cfg?.model;
+    if (!model) {
+        process.stderr.write("Usage: lucid local pull <model>\n");
+        return 64;
+    }
+    if (cfg && cfg.runtime !== "ollama") {
+        process.stderr.write(`pull is only supported for Ollama runtimes. For ${describeRuntime(cfg.runtime)}, fetch the model via its own UI.\n`);
+        return 64;
+    }
+    return await streamPull(model);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ask(rl, prompt) {
+    return new Promise((resolveAns) => rl.question(prompt, resolveAns));
+}
+async function streamPull(model) {
+    return new Promise((resolveCode) => {
+        const proc = spawn("ollama", ["pull", model], { stdio: "inherit" });
+        proc.on("error", (e) => {
+            process.stderr.write(`  ⚠️  Could not run ollama: ${e.message}\n`);
+            process.stderr.write(`     Install Ollama first (see \`lucid local init\` step 1 instructions).\n`);
+            resolveCode(127);
+        });
+        proc.on("exit", (code) => resolveCode(code ?? 0));
+    });
+}
+function showInstallInstructions() {
+    process.stdout.write([
+        "",
+        "──────────────────────────────────────────────────────────────",
+        "Install a local LLM runtime, then re-run `lucid local init`.",
+        "",
+        "  Ollama  (recommended, simplest):",
+        "    Windows:  winget install Ollama.Ollama",
+        "    macOS:    brew install ollama  (or download from ollama.com/download)",
+        "    Linux:    curl -fsSL https://ollama.com/install.sh | sh",
+        "",
+        "  LM Studio (GUI, OpenAI-compatible server):",
+        "    Download: https://lmstudio.ai/",
+        "    Start the local server in the GUI before re-running setup.",
+        "",
+        "  llama.cpp server (advanced):",
+        "    https://github.com/ggerganov/llama.cpp  →  ./server -m model.gguf",
+        "",
+        "  Remote endpoint:",
+        "    Any of the above hosted on another machine — re-run init and",
+        "    pick `[r] Enter remote endpoint URL`. Bearer auth supported.",
+        "──────────────────────────────────────────────────────────────",
+        "",
+    ].join("\n"));
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Shared types for the local-LLM subsystem (Ollama / LM Studio / llama.cpp /
+ * any OpenAI-compatible self-hosted endpoint).
+ */
+export type RuntimeKind = "ollama" | "openai-compat" | "unknown";
+export interface LocalLlmConfig {
+    enabled: boolean;
+    runtime: RuntimeKind;
+    endpoint: string;
+    model: string;
+    api_key?: string;
+    timeout_ms: number;
+    configured_at: string;
+}
+export interface DetectedRuntime {
+    kind: RuntimeKind;
+    endpoint: string;
+    models?: string[];
+    latency_ms?: number;
+}
+export interface GenerateRequest {
+    prompt: string;
+    system?: string;
+    max_tokens?: number;
+    temperature?: number;
+    stop?: string[];
+}
+export interface GenerateResponse {
+    text: string;
+    model: string;
+    latency_ms: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+}

package/build/local-llm/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for the local-LLM subsystem (Ollama / LM Studio / llama.cpp /
+ * any OpenAI-compatible self-hosted endpoint).
+ */
+export {};