@a13xu/lucid 1.16.2 → 1.19.0

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

package/build/tools/backup.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const BackupFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    reason?: string | undefined;
+}, {
+    path: string;
+    reason?: string | undefined;
+}>;
+export declare function handleBackupFile(stmts: Statements, args: z.infer<typeof BackupFileSchema>): string;
+export declare const RestoreFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    backup_id: z.ZodOptional<z.ZodNumber>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    version?: number | undefined;
+    backup_id?: number | undefined;
+    dry_run?: boolean | undefined;
+}, {
+    path: string;
+    version?: number | undefined;
+    backup_id?: number | undefined;
+    dry_run?: boolean | undefined;
+}>;
+export declare function handleRestoreFile(stmts: Statements, args: z.infer<typeof RestoreFileSchema>): string;
+export declare const CheckTruncateRiskSchema: z.ZodObject<{
+    path: z.ZodString;
+    new_content: z.ZodOptional<z.ZodString>;
+    new_size: z.ZodOptional<z.ZodNumber>;
+    record: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    new_content?: string | undefined;
+    new_size?: number | undefined;
+    record?: boolean | undefined;
+}, {
+    path: string;
+    new_content?: string | undefined;
+    new_size?: number | undefined;
+    record?: boolean | undefined;
+}>;
+export declare function handleCheckTruncateRisk(stmts: Statements, args: z.infer<typeof CheckTruncateRiskSchema>): string;

package/build/tools/backup.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { resolve } from "path";
+import { writeFileSync } from "fs";
+import { decompress } from "../store/content.js";
+import { assessTruncate, backupFile, recordTruncateEvent, TUNABLES, } from "../guardian/truncate-guard.js";
+// ---------------------------------------------------------------------------
+// backup_file
+// ---------------------------------------------------------------------------
+export const BackupFileSchema = z.object({
+    path: z.string().min(1).describe("File to snapshot"),
+    reason: z.string().optional().describe("Why this snapshot was taken (logged)"),
+});
+export function handleBackupFile(stmts, args) {
+    const result = backupFile(stmts, args.path, args.reason ?? "manual");
+    const absPath = resolve(args.path);
+    const total = stmts.countBackups.get(absPath)?.count ?? 0;
+    if (!result.saved)
+        return `⏭️  ${result.reason} (${absPath})`;
+    return [
+        `📸 Backup created: ${absPath}`,
+        `   size: ${result.size}B  hash: ${result.hash?.slice(0, 12)}…`,
+        `   versions retained: ${Math.min(total, TUNABLES.BACKUP_RETENTION)}/${TUNABLES.BACKUP_RETENTION}`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// restore_file
+// ---------------------------------------------------------------------------
+export const RestoreFileSchema = z.object({
+    path: z.string().min(1).describe("File to restore"),
+    version: z.number().int().positive().optional()
+        .describe("1 = latest backup, 2 = previous, etc. Default: 1"),
+    backup_id: z.number().int().positive().optional()
+        .describe("Specific backup row id (overrides version)"),
+    dry_run: z.boolean().optional().describe("Show what would be restored without writing"),
+});
+export function handleRestoreFile(stmts, args) {
+    const absPath = resolve(args.path);
+    if (args.backup_id !== undefined) {
+        const row = stmts.getBackupById.get(args.backup_id);
+        if (!row)
+            return `❌ Backup id=${args.backup_id} not found`;
+        if (row.filepath !== absPath) {
+            return `❌ Backup id=${args.backup_id} belongs to ${row.filepath}, not ${absPath}`;
+        }
+        return doRestore(absPath, row.content, row.created_at, row.original_size, args.dry_run === true);
+    }
+    const all = stmts.getBackupsByPath.all(absPath);
+    if (all.length === 0)
+        return `❌ No backups found for: ${absPath}`;
+    const idx = (args.version ?? 1) - 1;
+    if (idx < 0 || idx >= all.length) {
+        return `❌ Version ${args.version} out of range (have ${all.length} backups for this file)`;
+    }
+    const row = all[idx];
+    return doRestore(absPath, row.content, row.created_at, row.original_size, args.dry_run === true);
+}
+function doRestore(absPath, blob, createdAt, originalSize, dryRun) {
+    const content = decompress(blob);
+    const ts = new Date(createdAt * 1000).toISOString();
+    if (dryRun) {
+        return [
+            `🔍 DRY RUN — would restore ${absPath}`,
+            `   from snapshot at ${ts}`,
+            `   size: ${originalSize}B  (${content.split("\n").length} lines)`,
+        ].join("\n");
+    }
+    writeFileSync(absPath, content, "utf-8");
+    return [
+        `♻️  Restored: ${absPath}`,
+        `   from snapshot at ${ts}`,
+        `   size: ${originalSize}B`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// check_truncate_risk
+// ---------------------------------------------------------------------------
+export const CheckTruncateRiskSchema = z.object({
+    path: z.string().min(1).describe("File path the write would target"),
+    new_content: z.string().optional()
+        .describe("Proposed new content. Omit to query cascade-lock status only."),
+    new_size: z.number().int().nonnegative().optional()
+        .describe("Proposed new size in bytes (alternative to new_content)"),
+    record: z.boolean().optional()
+        .describe("If true, log this as a truncate event (used by hook). Default: false"),
+});
+export function handleCheckTruncateRisk(stmts, args) {
+    const probeContent = args.new_content
+        ?? (args.new_size !== undefined ? " ".repeat(args.new_size) : null);
+    const verdict = assessTruncate(args.path, probeContent, stmts);
+    if (args.record === true && verdict.blocked) {
+        recordTruncateEvent(stmts, args.path, verdict.prevSize, verdict.newSize, true);
+    }
+    if (!verdict.blocked) {
+        return [
+            `✅ Safe write: ${resolve(args.path)}`,
+            `   prev: ${verdict.prevSize}B → new: ${verdict.newSize >= 0 ? verdict.newSize + "B" : "?"} ` +
+                `(keeps ${Math.round(verdict.shrinkRatio * 100)}%)`,
+        ].join("\n");
+    }
+    return [
+        `🛑 BLOCK [${verdict.rule}]: ${resolve(args.path)}`,
+        `   ${verdict.reason}`,
+        verdict.cascade
+            ? `   cascade_count=${verdict.cascadeCount} within ${TUNABLES.CASCADE_WINDOW_SECONDS}s`
+            : `   prev=${verdict.prevSize}B  new=${verdict.newSize}B  ratio=${verdict.shrinkRatio.toFixed(2)}`,
+    ].join("\n");
+}

package/build/tools/delegate-local.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const DelegateLocalSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    system: z.ZodOptional<z.ZodString>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    model?: string | undefined;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+}, {
+    prompt: string;
+    model?: string | undefined;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+}>;
+export declare function handleDelegateLocal(args: z.infer<typeof DelegateLocalSchema>): Promise<string>;
+export declare const LocalLlmStatusSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function handleLocalLlmStatus(): Promise<string>;

package/build/tools/delegate-local.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { loadLocalConfig } from "../local-llm/config.js";
+import { generate, ping, LocalLlmError } from "../local-llm/client.js";
+import { describeRuntime } from "../local-llm/runtimes.js";
+// ---------------------------------------------------------------------------
+// delegate_local — direct passthrough to the configured local LLM
+// ---------------------------------------------------------------------------
+export const DelegateLocalSchema = z.object({
+    prompt: z.string().min(1).describe("User prompt for the local model."),
+    system: z.string().optional().describe("Optional system prompt (Python coding role, conventions, …)."),
+    max_tokens: z.number().int().positive().max(8192).optional().describe("Cap on completion tokens. Default 2048."),
+    temperature: z.number().min(0).max(2).optional().describe("Sampling temperature. Default 0.2 (deterministic)."),
+    model: z.string().optional().describe("Override the configured default model."),
+});
+export async function handleDelegateLocal(args) {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        return [
+            `❌ Local LLM not configured.`,
+            `   Run in your terminal:  lucid local init`,
+            `   Then restart Claude Code so the new config is picked up.`,
+        ].join("\n");
+    }
+    if (!cfg.enabled) {
+        return `❌ Local LLM is disabled in ${cfg.endpoint} config. Run \`lucid local init\` to re-enable.`;
+    }
+    const effective = args.model ? { ...cfg, model: args.model } : cfg;
+    try {
+        const res = await generate(effective, {
+            prompt: args.prompt,
+            system: args.system,
+            max_tokens: args.max_tokens,
+            temperature: args.temperature,
+        });
+        const tokens = res.prompt_tokens !== undefined && res.completion_tokens !== undefined
+            ? `prompt=${res.prompt_tokens}, completion=${res.completion_tokens}`
+            : "tokens=?";
+        return [
+            `🤖 ${effective.model} via ${describeRuntime(effective.runtime)} (${res.latency_ms}ms, ${tokens})`,
+            ``,
+            res.text.trim(),
+        ].join("\n");
+    }
+    catch (e) {
+        if (e instanceof LocalLlmError) {
+            return `❌ ${e.message}`;
+        }
+        return `❌ Unexpected error: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// local_llm_status — informational
+// ---------------------------------------------------------------------------
+export const LocalLlmStatusSchema = z.object({});
+export async function handleLocalLlmStatus() {
+    const cfg = loadLocalConfig();
+    if (!cfg) {
+        return [
+            `Local LLM: not configured.`,
+            ``,
+            `To set it up, run in your terminal:  lucid local init`,
+            `It walks you through runtime detection (Ollama / LM Studio / llama.cpp /`,
+            `remote endpoint), model selection, and a reachability test.`,
+        ].join("\n");
+    }
+    const reach = await ping(cfg);
+    return [
+        `Local LLM: ${cfg.enabled ? "enabled" : "disabled"}`,
+        `  runtime:   ${describeRuntime(cfg.runtime)}`,
+        `  endpoint:  ${cfg.endpoint}`,
+        `  model:     ${cfg.model}`,
+        `  reachable: ${reach.ok ? `✓ ${reach.latency_ms}ms` : `✗ ${reach.detail ?? "?"}`}`,
+        `  saved at:  ${cfg.configured_at}`,
+    ].join("\n");
+}