@a13xu/lucid 1.16.2 → 1.19.0

package/build/tools/init.js

@@ -5,6 +5,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { fileURLToPath } from "url";
 import { indexProject } from "../indexer/project.js";
 import { saveAdminConfig, loadAdminConfig, isAdminConfigured, sendTestAlert, } from "../security/alerts.js";
+import { isConfigured as isLocalLlmConfigured, loadLocalConfig } from "../local-llm/config.js";
+import { describeRuntime } from "../local-llm/runtimes.js";
 export const InitProjectSchema = z.object({
     directory: z.string().optional(),
     // ── Admin alert configuration (asked once at project init) ──────────────
@@ -31,6 +33,9 @@ export const InitProjectSchema = z.object({
 });
 const LUCID_MARKER = "Lucid: call sync_file";
 const LUCID_UPDATE_MARKER = "lucid-update-check";
+const LUCID_GUARD_MARKER = "lucid-guard-pre-edit";
+const LUCID_SESSION_TICK_MARKER = "lucid-session-tick";
+const LUCID_SESSION_COMPACT_MARKER = "lucid-session-compact";
 const LUCID_HOOK = {
     matcher: "Write|Edit|NotebookEdit",
     hooks: [
@@ -40,6 +45,38 @@ const LUCID_HOOK = {
         },
     ],
 };
+// PreToolUse hook: snapshot file + block destructive truncates BEFORE write.
+// Reads Claude Code's PreToolUse JSON from stdin; exit 2 hard-blocks the tool.
+// Marker token included so we can idempotently detect prior installs.
+const LUCID_PRE_EDIT_HOOK = {
+    matcher: "Write|Edit|MultiEdit|NotebookEdit",
+    hooks: [
+        {
+            type: "command",
+            command: `lucid guard pre-edit 2>&1 # ${LUCID_GUARD_MARKER}`,
+        },
+    ],
+};
+// UserPromptSubmit hook: track session length → emit /compact and /clear hints.
+// stdout from this hook is injected into Claude's context for the upcoming turn.
+const LUCID_SESSION_TICK_HOOK = {
+    hooks: [
+        {
+            type: "command",
+            command: `lucid session tick # ${LUCID_SESSION_TICK_MARKER}`,
+        },
+    ],
+};
+// PreCompact hook: reset per-session counters when /compact runs so the next
+// hint cycle starts from a clean baseline.
+const LUCID_PRE_COMPACT_HOOK = {
+    hooks: [
+        {
+            type: "command",
+            command: `lucid session compact # ${LUCID_SESSION_COMPACT_MARKER}`,
+        },
+    ],
+};
 // SessionStart hook: checks npm registry and notifies if update is available.
 // Uses only Node.js built-in https module — no external dependencies required.
 const LUCID_UPDATE_HOOK = {
@@ -84,6 +121,36 @@ function installHooks(dir) {
         hooks["PostToolUse"] = [...postToolUse, LUCID_HOOK];
         changed = true;
     }
+    // ── PreToolUse: backup + truncate guard ──────────────────────────────────
+    const preToolUse = hooks["PreToolUse"] ?? [];
+    const guardAlreadyInstalled = preToolUse.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_GUARD_MARKER);
+    });
+    if (!guardAlreadyInstalled) {
+        hooks["PreToolUse"] = [...preToolUse, LUCID_PRE_EDIT_HOOK];
+        changed = true;
+    }
+    // ── UserPromptSubmit: session-cost hints (/compact, /clear) ──────────────
+    const userPromptSubmit = hooks["UserPromptSubmit"] ?? [];
+    const sessionTickInstalled = userPromptSubmit.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_SESSION_TICK_MARKER);
+    });
+    if (!sessionTickInstalled) {
+        hooks["UserPromptSubmit"] = [...userPromptSubmit, LUCID_SESSION_TICK_HOOK];
+        changed = true;
+    }
+    // ── PreCompact: reset counters when /compact fires ────────────────────────
+    const preCompact = hooks["PreCompact"] ?? [];
+    const preCompactInstalled = preCompact.some((h) => {
+        const cmd = h.command ?? h.hooks?.[0]?.command ?? "";
+        return cmd.includes(LUCID_SESSION_COMPACT_MARKER);
+    });
+    if (!preCompactInstalled) {
+        hooks["PreCompact"] = [...preCompact, LUCID_PRE_COMPACT_HOOK];
+        changed = true;
+    }
     // ── SessionStart: version check ───────────────────────────────────────────
     const sessionStart = hooks["SessionStart"] ?? [];
     const updateAlreadyInstalled = sessionStart.some((h) => {
@@ -116,6 +183,42 @@ sync_file(path="<path of the file you just wrote/edited>")
 
 This keeps the Lucid knowledge graph up to date with the latest code.
 If multiple files changed (refactor, git pull), call sync_project() instead.
+
+## 🛡️  Lucid — Backup & Truncate Guard (automatic)
+
+A PreToolUse hook (\`lucid guard pre-edit\`) runs before every Write/Edit/MultiEdit:
+1. **Snapshot** the file into the versioned backup store (last 10 versions kept).
+2. **Block** destructive truncates: empty/whitespace overwrite, >70% shrink, or
+   ≥2 truncate attempts within 60s (cascade lock — common in autonomous loops).
+
+Tools available when you need them:
+- \`backup_file(path)\` — manual snapshot before risky refactors.
+- \`restore_file(path, version=1, dry_run=true)\` — preview/restore from backup.
+- \`check_truncate_risk(path, new_content)\` — assess a planned write.
+
+If a guard blocks legitimately (e.g. you really do want to empty a file), set
+\`LUCID_TRUNCATE_OVERRIDE=1\` for that one invocation, or run
+\`lucid guard clear\` to release a cascade lock. Do **not** disable the hook.
+
+## 💸  Lucid — Session-cost hints (/compact, /clear)
+
+Two hooks track session length to keep per-turn cost predictable:
+
+- **UserPromptSubmit** runs \`lucid session tick\` and may inject one or more of:
+  - \`/compact\` hint at **15 prompts**, re-emitted every **10** afterwards.
+  - \`/clear\` hint at **30 prompts** (one-shot — preferable when switching tasks).
+  - Cache-cold hint when idle gap exceeds **5 min** (prompt cache TTL).
+- **PreCompact** runs \`lucid session compact\` to reset the per-session counter
+  so the next hint cycle starts from a clean baseline.
+
+When you see a hint, surface it to the user and act on it — the cost model is
+per-turn linear with transcript length even when the cache is warm. Tools:
+- \`session_status\` — inspect prompt counts and pending hints.
+- \`lucid session reset\` — manually reset a single session counter (CLI).
+
+Tunable via env: \`LUCID_COMPACT_HINT_AT\`, \`LUCID_COMPACT_HINT_EVERY\`,
+\`LUCID_CLEAR_HINT_AT\`, \`LUCID_CACHE_STALE_SECONDS\`,
+\`LUCID_SESSION_HINTS_DISABLED=1\` to silence completely.
 <!-- /LUCID_SYNC -->
 `;
 function injectClaudeMdInstruction(dir) {
@@ -150,8 +253,11 @@ export async function handleInitProject(stmts, input) {
     const hookResult = installHooks(dir);
     if (hookResult.installed) {
         lines.push(`🔗 Claude Code hooks installed (.claude/settings.json)`);
-        lines.push(`   PostToolUse: reminder to call sync_file() after every Write/Edit`);
-        lines.push(`   SessionStart: auto-check for Lucid updates on session start`);
+        lines.push(`   PreToolUse:       backup + truncate guard before every Write/Edit/MultiEdit`);
+        lines.push(`   PostToolUse:      reminder to call sync_file() after every Write/Edit`);
+        lines.push(`   UserPromptSubmit: session-cost hints (/compact at 15, /clear at 30, cache-cold)`);
+        lines.push(`   PreCompact:       reset session counters when /compact fires`);
+        lines.push(`   SessionStart:     auto-check for Lucid updates on session start`);
     }
     else {
         lines.push(`🔗 Hooks: ${hookResult.reason}`);
@@ -256,6 +362,22 @@ export async function handleInitProject(stmts, input) {
             lines.push(`   Webhook HMAC signing: set LUCID_WEBHOOK_SECRET env var.`);
         }
     }
+    // ── Local LLM nudge ───────────────────────────────────────────────────────
+    lines.push(``);
+    lines.push(`🤖 Local LLM (delegate_local)`);
+    if (isLocalLlmConfigured()) {
+        const cfg = loadLocalConfig();
+        lines.push(`   Configured: ${cfg.model} via ${describeRuntime(cfg.runtime)} @ ${cfg.endpoint}`);
+    }
+    else {
+        lines.push(`   Not configured. To enable delegation of small specialized tasks to a local`);
+        lines.push(`   coder LLM (Ollama / LM Studio / llama.cpp / remote endpoint), run in your terminal:`);
+        lines.push(``);
+        lines.push(`     lucid local init`);
+        lines.push(``);
+        lines.push(`   It walks you through runtime detection, model selection, and a reachability test.`);
+        lines.push(`   Config is saved globally to ~/.lucid/local.json (one setup → all projects).`);
+    }
     lines.push(``);
     lines.push(`From now on, call sync_file(path) after every file you write or edit.`);
     lines.push(`Use recall() to query accumulated project knowledge.`);

package/build/tools/session.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const SessionStatusSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    session_id?: string | undefined;
+    limit?: number | undefined;
+}, {
+    session_id?: string | undefined;
+    limit?: number | undefined;
+}>;
+export declare function handleSessionStatus(stmts: Statements, args: z.infer<typeof SessionStatusSchema>): string;

package/build/tools/session.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { SESSION_TUNABLES } from "../guardian/session-tracker.js";
+// ---------------------------------------------------------------------------
+// session_status — show current session-cost state and hint thresholds
+// ---------------------------------------------------------------------------
+export const SessionStatusSchema = z.object({
+    session_id: z.string().optional()
+        .describe("Specific session id. Defaults to the most recently active session."),
+    limit: z.number().int().positive().max(50).optional()
+        .describe("How many recent sessions to list when session_id is omitted (default 5)."),
+});
+export function handleSessionStatus(stmts, args) {
+    const limit = args.limit ?? 5;
+    if (args.session_id) {
+        const row = stmts.getCliSession.get(args.session_id);
+        if (!row)
+            return `No session found with id=${args.session_id}`;
+        return formatSession(row, true);
+    }
+    const recent = stmts.recentCliSessions.all(limit);
+    if (recent.length === 0) {
+        return [
+            `No Claude Code sessions tracked yet.`,
+            ``,
+            `Hints fire at:`,
+            `  /compact at ${SESSION_TUNABLES.COMPACT_HINT_AT} prompts (re-emitted every ${SESSION_TUNABLES.COMPACT_HINT_EVERY})`,
+            `  /clear   at ${SESSION_TUNABLES.CLEAR_HINT_AT} prompts (one-shot)`,
+            `  cache-cold after ${SESSION_TUNABLES.CACHE_STALE_SECONDS}s idle`,
+        ].join("\n");
+    }
+    const lines = [
+        `📊 Recent Claude Code sessions (top ${recent.length}):`,
+        ``,
+    ];
+    for (const r of recent)
+        lines.push(formatSession(r, false));
+    lines.push(``);
+    lines.push(`Thresholds: /compact@${SESSION_TUNABLES.COMPACT_HINT_AT} (+${SESSION_TUNABLES.COMPACT_HINT_EVERY}), ` +
+        `/clear@${SESSION_TUNABLES.CLEAR_HINT_AT}, cache-cold>${SESSION_TUNABLES.CACHE_STALE_SECONDS}s`);
+    return lines.join("\n");
+}
+function formatSession(r, full) {
+    const idle = Math.floor(Date.now() / 1000) - r.last_activity_at;
+    const idleStr = idle < 60 ? `${idle}s` : idle < 3600 ? `${Math.round(idle / 60)}m` : `${Math.round(idle / 3600)}h`;
+    const status = r.prompt_count >= SESSION_TUNABLES.CLEAR_HINT_AT ? "🔴" :
+        r.prompt_count >= SESSION_TUNABLES.COMPACT_HINT_AT ? "🟠" : "🟢";
+    const head = `${status} ${r.session_id.slice(0, 8)}…  ${r.prompt_count} prompts  idle=${idleStr}  compacts=${r.compact_count}`;
+    if (!full)
+        return "  " + head;
+    return [
+        head,
+        `   started:    ${new Date(r.started_at * 1000).toISOString()}`,
+        `   last activ: ${new Date(r.last_activity_at * 1000).toISOString()}`,
+        r.last_compact_event_at
+            ? `   last compact: ${new Date(r.last_compact_event_at * 1000).toISOString()}`
+            : `   last compact: —`,
+        r.cwd ? `   cwd: ${r.cwd}` : ``,
+    ].filter(Boolean).join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a13xu/lucid",
-  "version": "1.16.2",
+  "version": "1.19.0",
   "description": "Token-efficient memory, code indexing, and validation for Claude Code agents — SQLite + FTS5, TF-IDF + Qdrant retrieval, AST skeleton pruning, diff-aware context, Logic Guardian drift detection",
   "type": "module",
   "bin": {