@jeffober/thatch 0.1.43 → 0.1.45

package/src/commands.ts

@@ -1,12 +1,35 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import {
+  defragCore,
+  extractionCore,
+  hygieneCore,
+  mcpToolName,
+  opencodeToolName,
+  reflectCore,
+  type ToolNamer,
+} from "./prompts";
 
 /**
- * Thatch's wrap-up slash commands for opencode, shipped as command markdown
- * files synced into the global opencode config dir (~/.config/opencode/command/
- * thatch/). The plugin writes them on every load so template updates self-heal
- * without a reinstall. Config is loaded before plugins during server startup,
- * so a first-ever install becomes visible on the next start.
+ * Thatch's slash commands, shipped as command markdown files synced into each
+ * host's command directory:
+ *
+ * - opencode: ~/.config/opencode/command/thatch/ - synced by the plugin on
+ *   every load, so template updates self-heal without a reinstall. Config is
+ *   loaded before plugins during server startup, so a first-ever install
+ *   becomes visible on the next start.
+ * - Claude Code: ~/.claude/commands/thatch/ (or the project's .claude/
+ *   commands/thatch/) - synced by `thatch setup --claude`, which has no
+ *   plugin to do it on load.
+ *
+ * Two command families live here:
+ *
+ * - Actions (/thatch/defrag, extract, hygiene, reflect): user-invoked
+ *   wrappers around a behavior that the nudges otherwise only run on their
+ *   own schedule. Each action body is a prompt core from src/prompts.ts, so
+ *   nudge and command wording cannot drift.
+ * - Wrap-ups (/thatch/compact, exit): greenlight-token commands that need
+ *   the opencode plugin's TUI control routes, so they are opencode-only.
  */
 
 /** Greenlight token ending /thatch/compact's assistant response when compaction is safe. */
@@ -24,19 +47,92 @@ export const EXIT_READY_TOKEN = "THATCH_EXIT_READY";
  */
 
 const sharedChecklist = `1. Flush pending persistence. Call thatch_get_extraction_payload; if it returns buffered tool interactions, process them now (write any memories worth keeping), then call thatch_extraction_done to mark them complete. Complete any memory writes you promised earlier but have not made.
-2. Check for loose ends. Review the conversation for todos, follow-ups, or open questions raised earlier that were never addressed, and surface anything the user should address before the wrap-up completes.
+2. Check for loose ends. Review the conversation for todos, follow-ups, or open questions raised earlier that were never addressed, and surface anything the user should address before the wrap-up completes.`;
 
-Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:`;
+const userMessageSection = `# User Message
+
+$ARGUMENTS
+
+(That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
+
+/**
+ * One on-demand action: the command name (minus the thatch/ prefix), the
+ * description shown in the command menu, and the instruction body (a prompt
+ * core). opencodeOnly marks actions that need a session identity or other
+ * plugin-only capability; those are excluded from Claude Code command files
+ * and MCP prompts.
+ */
+export interface ActionDef {
+  name: string;
+  description: string;
+  body: string;
+  opencodeOnly?: boolean;
+}
+
+/**
+ * The on-demand action set, shared by every host that renders actions. The
+ * bodies come from prompt cores so a wording change lands in the nudge and
+ * the command at once. `tool` renders tool names in the host's spelling.
+ */
+export function actionDefs(tool: ToolNamer): ActionDef[] {
+  return [
+    {
+      name: "defrag",
+      description: "Consolidate duplicate and near-duplicate memories in the store",
+      body: defragCore(tool),
+    },
+    {
+      name: "extract",
+      description: "Drain the extraction queue now",
+      // Needs the invoking session's ID (via get_session_info, opencode-only)
+      // and the plugin's extraction payload provider.
+      opencodeOnly: true,
+      body: `First call thatch_get_session_info to learn this session's ID. Below, replace SESSION_ID with that value.
+
+Dispatch a task with background: true and subagent_type: "general" (required for thatch tool access) with this prompt:
+
+"${extractionCore("thatch_get_extraction_payload", "thatch_extraction_done", ' with session_id \\"SESSION_ID\\"')}"
+
+After dispatching, call thatch_extraction_done to acknowledge.`,
+    },
+    {
+      name: "hygiene",
+      description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
+      body: hygieneCore(),
+    },
+    {
+      name: "reflect",
+      description: "Persist what this session learned as memories",
+      body: reflectCore(tool),
+    },
+  ];
+}
+
+/** Renders one action as a full command markdown file. */
+export function renderActionCommand(action: ActionDef): string {
+  return `---
+description: ${action.description}
+---
+${userMessageSection}
+
+# ${action.name.charAt(0).toUpperCase() + action.name.slice(1)}
+
+${action.body}`;
+}
 
 const COMPACT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then compact if clear
 ---
-$ARGUMENTS
+${userMessageSection}
+
+# Pre-compact wrap-up
 
-Pre-compaction wrap-up. Work through this checklist before responding:
+Work through this checklist before responding:
 
 ${sharedChecklist}
 
+Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:
+
 ${COMPACT_READY_TOKEN}
 
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
@@ -44,9 +140,11 @@ If anything is outstanding, list the items concisely so the user can address the
 const EXIT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then exit opencode if clear
 ---
-$ARGUMENTS
+${userMessageSection}
+
+# Pre-exit wrap-up
 
-Pre-exit wrap-up. Work through this checklist before responding:
+Work through this checklist before responding:
 
 ${sharedChecklist}
 3. Leave the chat directory. Call thatch_chat_unregister for this session - the session is exiting, so other sessions must stop addressing mail to it.
@@ -57,29 +155,40 @@ ${EXIT_READY_TOKEN}
 
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. opencode will only exit when the token is present.`;
 
-/** One wrap-up command: the command name (minus the thatch/ prefix) and its full markdown file content. */
+/** One command: the command name (minus the thatch/ prefix) and its full markdown file content. */
 export interface CommandDef {
   name: string;
   content: string;
 }
 
-/** The wrap-up command set, as full command-file contents ready to write. */
+/** The opencode command set: wrap-ups plus every action, as full file contents. */
 export function opencodeCommandDefs(): CommandDef[] {
   return [
     { name: "compact", content: COMPACT_TEMPLATE },
     { name: "exit", content: EXIT_TEMPLATE },
+    ...actionDefs(opencodeToolName).map((a) => ({ name: a.name, content: renderActionCommand(a) })),
   ];
 }
 
 /**
- * Sync the wrap-up commands into <configHome>/opencode/command/thatch/.
- * Idempotent: each file is written only when its on-disk content differs.
- * Returns the paths that were written (empty when everything was current).
+ * The Claude Code command set: the actions minus the opencode-only ones.
+ * The wrap-up commands are excluded too - their greenlight check needs the
+ * plugin's command.execute.before arming and TUI control routes.
  */
-export function installOpencodeCommands(configHome: string): string[] {
-  const dir = join(configHome, "opencode", "command", "thatch");
+export function claudeCommandDefs(): CommandDef[] {
+  return actionDefs(mcpToolName)
+    .filter((a) => !a.opencodeOnly)
+    .map((a) => ({ name: a.name, content: renderActionCommand(a) }));
+}
+
+/**
+ * Sync command files into dir. Idempotent: each file is written only when
+ * its on-disk content differs. Returns the paths that were written (empty
+ * when everything was current).
+ */
+function syncCommandFiles(dir: string, defs: CommandDef[]): string[] {
   const written: string[] = [];
-  for (const def of opencodeCommandDefs()) {
+  for (const def of defs) {
     const path = join(dir, `${def.name}.md`);
     let current: string | null = null;
     try {
@@ -95,3 +204,13 @@ export function installOpencodeCommands(configHome: string): string[] {
   }
   return written;
 }
+
+/** Sync opencode's commands into <configHome>/opencode/command/thatch/. */
+export function installOpencodeCommands(configHome: string): string[] {
+  return syncCommandFiles(join(configHome, "opencode", "command", "thatch"), opencodeCommandDefs());
+}
+
+/** Sync Claude Code's commands into <claudeDir>/commands/thatch/ (claudeDir is ~/.claude or <project>/.claude). */
+export function installClaudeCommands(claudeDir: string): string[] {
+  return syncCommandFiles(join(claudeDir, "commands", "thatch"), claudeCommandDefs());
+}

package/src/db.ts

@@ -1,4 +1,6 @@
 import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { blobToVector, cosineSimilarity } from "./vector-math";
 import {
   PredictionEngine,
@@ -58,6 +60,13 @@ export class ThatchDB {
   #chat: ChatStore;
 
   constructor(path: string) {
+    // bun:sqlite creates the file but not its parent directory. On a fresh
+    // machine the default path (~/.config/thatch/thatch.db) has no dir yet, so
+    // create it here - otherwise every command fails with SQLITE_CANTOPEN.
+    // `:memory:` and other special paths have no meaningful parent to create.
+    if (path !== ":memory:" && !path.startsWith("file:")) {
+      mkdirSync(dirname(path), { recursive: true });
+    }
     this.#db = new Database(path, { create: true });
     this.#db.run("PRAGMA journal_mode = WAL");
     this.#db.run("PRAGMA busy_timeout = 5000");
@@ -284,6 +293,20 @@ export class ThatchDB {
       )
     `);
 
+    // Hook-parent-process -> session mapping (Claude Code identity anchor):
+    // hooks learn the true session id from the host's hook payload and run
+    // as children of the same process that spawned the MCP server, so the
+    // server resolves its own parent pid against this table - an identity
+    // the model cannot claim. Rows are timestamped; stale rows are ignored
+    // (pid reuse) rather than deleted.
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS chat_host_pids (
+        ppid       INTEGER PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        seen_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    `);
+
     this.#migrateColumns();
     this.#migrateChatNameCollation();
     this.#migrateChatTopic();
@@ -291,6 +314,7 @@ export class ThatchDB {
     this.#migrateChatBroadcastFlag();
     this.#migrateChatAuto();
     this.#migrateChatWorktree();
+    this.#migrateChatHostPid();
   }
 
   // chat_sessions tables created before the auto column lack it; the ALTER
@@ -322,6 +346,16 @@ export class ThatchDB {
     }
   }
 
+  // The released schema has no host_pid column (liveness is heartbeat age;
+  // see chatLiveness). A development database may carry one; drop it so
+  // every database matches a fresh install.
+  #migrateChatHostPid(): void {
+    const cols = (this.#db.query("PRAGMA table_info(chat_sessions)").all() as any[]).map((r) => r.name);
+    if (cols.includes("host_pid")) {
+      this.#db.run("ALTER TABLE chat_sessions DROP COLUMN host_pid");
+    }
+  }
+
   // chat_messages tables created before the via_broadcast column lack it;
   // the ALTER adds it, and existing rows read as direct sends (which they
   // were).
@@ -935,6 +969,18 @@ export class ThatchDB {
     return this.#chat.unreadCount(sessionID);
   }
 
+  recordChatHostPid(ppid: number, sessionID: string) {
+    return this.#chat.recordHostPid(ppid, sessionID);
+  }
+
+  findChatSessionByHostPid(ppid: number, maxAgeSeconds: number): string | null {
+    return this.#chat.findSessionByHostPid(ppid, maxAgeSeconds);
+  }
+
+  continueChatSession(oldSessionID: string, newSessionID: string) {
+    return this.#chat.continueSession(oldSessionID, newSessionID);
+  }
+
   heartbeatChatSessions(sessionIDs: string[]) {
     return this.#chat.heartbeat(sessionIDs);
   }

package/src/debug.ts

@@ -0,0 +1,44 @@
+import { appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// Opt-in diagnostic logging for questions a live harness cannot otherwise
+// answer ("what did the plugin actually see at init?"). Lines go to
+// debug.log beside the database, never to the host's stdout or stderr:
+// the plugin runs inside opencode's TUI process, where console output is
+// invisible or garbles the screen, and test sandboxes point the database at
+// a tmp dir so their debug output never reaches the quality gate.
+//
+// Off unless THATCH_DEBUG is set. THATCH_DEBUG=1 (or "all" / "*") logs every
+// tag. Otherwise it is a comma-separated list of tag filters: a filter
+// matches a tag when it equals the whole tag ("chat:startup") or the
+// feature part before the colon ("chat" matches every chat:* tag).
+//
+// Tags are `feature:aspect`, rendered in square brackets, so a grep on
+// "[chat:" pulls one feature's story out of a shared file.
+
+export type DebugLog = (tag: string, msg: string) => void;
+
+// Decide, from a THATCH_DEBUG value, whether a tag is enabled. Exported for
+// tests; callers use createDebugLog.
+export function debugEnabled(spec: string | undefined, tag: string): boolean {
+  if (!spec) return false;
+  const s = spec.trim();
+  if (s === "1" || s === "all" || s === "*") return true;
+  const feature = tag.split(":")[0];
+  return s.split(",").map((f) => f.trim()).filter(Boolean).some((f) => f === tag || f === feature);
+}
+
+// Build the logger for a database location. Every line: ISO timestamp,
+// bracketed tag, message. Writes never throw: diagnostics must not break
+// the host, so a missing directory or a full disk simply drops the line.
+export function createDebugLog(dbPath: string, spec: string | undefined = process.env.THATCH_DEBUG): DebugLog {
+  const file = join(dirname(dbPath), "debug.log");
+  return (tag, msg) => {
+    if (!debugEnabled(spec, tag)) return;
+    try {
+      appendFileSync(file, `${new Date().toISOString()} [${tag}] ${msg}\n`);
+    } catch {
+      // Intentionally silent; see above.
+    }
+  };
+}

package/src/embeddings.ts

@@ -1,9 +1,48 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 // BGE-small-en-v1.5 requires a query prefix for asymmetric search.
 // Passage (memory content) gets no prefix - the model was trained
 // to encode passages without instruction.
 const QUERY_PREFIX =
   "Represent this sentence for searching relevant passages: ";
 
+/**
+ * Writable directory for the downloaded model files.
+ *
+ * transformers.js defaults its filesystem cache to a `.cache` folder *inside*
+ * its own package directory (`node_modules/@huggingface/transformers/.cache`).
+ * That breaks any read-only install - a global `bun install -g`, and Nix store
+ * paths in particular - and gets wiped on every reinstall. Anchor the cache in
+ * the platform's per-user cache location instead so it survives upgrades and
+ * works from an immutable store path.
+ *
+ *   THATCH_MODEL_CACHE  explicit override (highest priority)
+ *   XDG_CACHE_HOME      explicit base dir -> $XDG_CACHE_HOME/thatch/models
+ *   macOS              ~/Library/Caches/thatch/models
+ *   Windows            %LOCALAPPDATA%\thatch\models
+ *   Linux / other      ~/.cache/thatch/models
+ *
+ * `platform` and `home` are injectable for testing; they default to the real
+ * runtime values.
+ */
+export function modelCacheDir(
+  platform: NodeJS.Platform = process.platform,
+  home: string = homedir(),
+): string {
+  const env = process.env;
+  if (env.THATCH_MODEL_CACHE) return env.THATCH_MODEL_CACHE;
+  // Respect an explicit XDG override on any platform (some macOS users set it).
+  if (env.XDG_CACHE_HOME) return join(env.XDG_CACHE_HOME, "thatch", "models");
+  const base =
+    platform === "darwin"
+      ? join(home, "Library", "Caches")
+      : platform === "win32"
+        ? (env.LOCALAPPDATA ?? join(home, "AppData", "Local"))
+        : join(home, ".cache");
+  return join(base, "thatch", "models");
+}
+
 /**
  * Interface for an embedding model so tests can supply a mock.
  * `name` is the tag stored alongside each entry so a future reader can tell
@@ -90,7 +129,9 @@ export function resetBackendForTests(): void {
 
 const defaultPipelineFactory: PipelineFactory = async (modelName) => {
   const mode = await configureBackend();
-  const { pipeline } = await import("@huggingface/transformers");
+  const { pipeline, env } = await import("@huggingface/transformers");
+  // Redirect the model cache out of the (possibly read-only) package tree.
+  env.cacheDir = modelCacheDir();
   if (mode === "native") {
     return pipeline("feature-extraction", modelName);
   }