@stitchdb/cli 0.7.2 → 0.7.4

package/dist/cli.js

@@ -490,9 +490,11 @@ async function cmdHook(args) {
         await handlePreReadHook(cfg, event, cwd || process.cwd()).catch(() => { });
         return;
     }
-    // ── PostToolUse on Read: opportunistically save a fresh summary ───────
-    if (eventName === 'PostToolUse' && event?.tool_name === 'Read') {
-        await handlePostReadHook(cfg, event, cwd || process.cwd()).catch(() => { });
+    // ── PostToolUse on Read/Edit/Write/MultiEdit: keep the file-summary
+    //    cache fresh. After an edit we re-hash the on-disk file and
+    //    re-summarise, so a stale "old version" memory never lingers.
+    if (eventName === 'PostToolUse' && ['Read', 'Edit', 'Write', 'MultiEdit'].includes(String(event?.tool_name))) {
+        await handlePostFileChangeHook(cfg, event, cwd || process.cwd()).catch(() => { });
         return;
     }
     // ── SessionStart: self-heal hook config + inject prior context ─────────
@@ -502,6 +504,10 @@ async function cmdHook(args) {
     // Stitch hook entries — never touching non-Stitch ones.
     if (eventName === 'SessionStart') {
         ensureHooksUpToDate();
+        // Catch-up distillation: if a previous session ended with undistilled
+        // turns (user exited under threshold), distill them now in the
+        // background so they surface in this session's context very soon.
+        maybeAutoDistill(threadName, { force: true }).catch(() => { });
     }
     // Strategy: prefer distilled memories (dense facts) over raw turns. Only
     // include raw turns for the last 5 to give the agent immediate continuation.
@@ -731,13 +737,14 @@ function lastAssistantTextFromTranscript(transcriptPath) {
 const FILE_SUMMARY_MIN_BYTES = 500; // skip tiny files
 const FILE_SUMMARY_MAX_BYTES = 200_000; // skip absolutely huge files
 const FILE_SUMMARY_COOLDOWN_MS = 5 * 60_000; // per-file: don't re-summarize more than once per 5 min
-const FILE_SUMMARY_PROMPT = `You are summarising a single source file for an AI coding assistant cache.
+const FILE_SUMMARY_PROMPT = `You are summarising a single source file for an AI coding assistant's persistent project cache. Other agents will read this summary before deciding whether to open the file in full, so it must enable a real mental model of the project — not just describe the file in isolation.
 
-Return ONLY a 2-3 sentence summary describing:
-  • What the file does (purpose, the few exported symbols / commands / endpoints worth knowing).
-  • Any important pattern, convention, or non-obvious behaviour another agent would benefit from before reading the file in full.
+Return ONLY a 2-4 sentence summary that covers:
+  1. PURPOSE — what this file does, its key exported symbols / routes / commands / classes worth knowing, any non-obvious invariant or pattern.
+  2. CONNECTIONS — concrete other files/modules this depends on (real import paths, real symbol names) AND who/what typically depends on this. Use real names from the file content; don't generalise.
+  3. WHEN TO OPEN — what kind of task forces an edit here vs a peek. (e.g. "edit this when adding a new auth provider; safe to skip for purely UI changes").
 
-Skip preamble. Skip "this file …". Be specific. No markdown fences. No prose around it.
+Be dense and specific. No preamble. No "this file ...". No markdown fences. No prose around it. Plain text only.
 
 File path: {{PATH}}
 
@@ -816,47 +823,64 @@ async function handlePreReadHook(cfg, event, cwd) {
     const payload = { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: note } };
     process.stdout.write(JSON.stringify(payload));
 }
-// PostToolUse on Read: kick off a background `claude -p` to summarize this
-// file IF we don't already have a summary at the current hash. Fire-and-forget.
-async function handlePostReadHook(cfg, event, cwd) {
+// PostToolUse handler for tools that observe-or-modify a single file
+// (Read, Edit, Write, MultiEdit). Kicks off a background `claude -p` to
+// (re-)summarise this file unless we already have an up-to-date cached
+// summary for this exact hash. Fire-and-forget.
+//
+// Read flow:    file content same as cache → no-op. Different → re-summarise.
+// Edit flow:    file content always different from cache → re-summarise. The
+//               existing summary is replaced by cmdSummarizeFile so no stale
+//               memory persists.
+// Write/MultiEdit: same as Edit.
+//
+// A 30 s "min-interval" floor on top of the hash-keyed cooldown prevents a
+// flurry of edits within seconds from spawning N parallel claude -p calls
+// for the same file.
+async function handlePostFileChangeHook(cfg, event, cwd) {
     const filePath = String(event?.tool_input?.file_path || '');
     if (!filePath)
         return;
     const rel = relPathFor(cwd, filePath);
-    const content = readFileContentFromHookEvent(event);
-    // Fall back to reading from disk if hook payload didn't carry content.
-    let body = content;
-    if (!body) {
-        try {
-            body = fs.readFileSync(filePath, 'utf8');
-        }
-        catch {
-            return;
-        }
+    // After Edit/Write the on-disk content is what we want; the hook payload
+    // may also carry it, but reading from disk is always correct.
+    let body = '';
+    try {
+        body = fs.readFileSync(filePath, 'utf8');
     }
-    if (!body || body.length < FILE_SUMMARY_MIN_BYTES)
+    catch {
+        return;
+    }
+    if (!body)
+        return;
+    // Tiny files: not worth a summary. Huge files: skip; would exhaust context.
+    if (body.length < FILE_SUMMARY_MIN_BYTES)
         return;
     if (body.length > FILE_SUMMARY_MAX_BYTES)
         return;
     const fullHash = await sha256Hex(body);
     const hashPrefix = fullHash.slice(0, 16);
-    // Per-file cooldown so a hot-edited file doesn't re-summarize on every read.
     const state = loadFileSummaryState();
     const last = state.files[rel];
+    // Hash-keyed dedupe: same content as last spawn → nothing to do.
     if (last && last.hash === hashPrefix && Date.now() - last.lastSummarizedAt < FILE_SUMMARY_COOLDOWN_MS)
         return;
+    // Min-interval floor: regardless of hash change, don't spawn more often
+    // than once per 30 s for the same file (catches edit flurries).
+    const MIN_RESPAWN_MS = 30_000;
+    if (last && Date.now() - last.lastSummarizedAt < MIN_RESPAWN_MS)
+        return;
+    // Optimisation: confirm the API view is also stale before spending tokens.
     const stitch = client(cfg);
     const cached = await lookupFileSummary(stitch, rel);
     if (cached && cached.hash === hashPrefix) {
-        // Already summarized this exact version — refresh cooldown and bail.
         state.files[rel] = { hash: hashPrefix, lastSummarizedAt: Date.now() };
         saveFileSummaryState(state);
         return;
     }
-    // Mark BEFORE spawning so a flurry of Read events doesn't fire N spawns.
+    // Mark BEFORE spawning so overlapping events don't fire N spawns.
     state.files[rel] = { hash: hashPrefix, lastSummarizedAt: Date.now() };
     saveFileSummaryState(state);
-    // Spawn detached: stitch _summarize-file <abs-path> <hash> <rel>
     try {
         const cliPath = process.argv[1] || (await import('node:url')).fileURLToPath(import.meta.url);
         const child = spawn(process.argv[0], [cliPath, '_summarize-file', filePath, hashPrefix, rel], {
@@ -964,9 +988,13 @@ async function cmdLink(args) {
 // Triggered manually (`stitch distill`), and automatically by the Stop hook
 // when conditions are met (cooldown + new-turn threshold).
 const DISTILL_STATE_FILE = path.join(CONFIG_DIR, 'distill-state.json');
-const DISTILL_COOLDOWN_MS = 10 * 60 * 1000; // distill at most once per 10 min per thread
-const DISTILL_MIN_NEW_TURNS = 5; // need 5 new turns before bothering
+// No time-based cooldown — purely turn-count driven. The previous time gate
+// could leave turns undistilled if the user exited Claude before the next
+// firing window. Now: every Stop checks the pending-turn count, and if the
+// user exits below threshold, the next SessionStart catches up.
+const DISTILL_MIN_NEW_TURNS = 5; // distill once 5+ new turns are pending
 const DISTILL_BATCH_SIZE = 30; // turns per distillation pass
+const DISTILL_DEBOUNCE_MS = 90 * 1000; // small in-flight guard so a flurry of Stops doesn't fire N spawns
 function loadDistillState() {
     try {
         return JSON.parse(fs.readFileSync(DISTILL_STATE_FILE, 'utf8'));
@@ -1203,14 +1231,24 @@ async function distillClear(args) {
     }
     console.log(`Cleared ${deleted} memories.`);
 }
-// Triggered from the Stop hook (fire-and-forget, never blocks the user).
-async function maybeAutoDistill(thread) {
+// Triggered from Stop hook AND SessionStart catch-up. Fire-and-forget.
+//
+// Decision logic:
+//   - If `pending = currentTurns - lastDistilledTurns` >= DISTILL_MIN_NEW_TURNS,
+//     spawn a distill pass. No time-based cooldown — leaving turns undistilled
+//     because the user happened to exit before the next firing window is the
+//     wrong behaviour.
+//   - SessionStart calls this with `force = true` when ANY pending turns exist
+//     so a session that ended mid-batch (e.g. 3 pending) still gets caught up.
+//   - DISTILL_DEBOUNCE_MS is a tiny in-process guard so a flurry of Stop
+//     events from a single agent run doesn't trigger N parallel claude -p
+//     spawns; once one is in flight, others within the window become no-ops.
+async function maybeAutoDistill(thread, opts = {}) {
     const state = loadDistillState();
     const meta = state.threads[thread] || { lastDistilledAt: 0, lastTurnAt: 0, lastTurnCount: 0 };
-    // Cool-down: don't distill more than once per 30 min per thread.
-    if (Date.now() - meta.lastDistilledAt < DISTILL_COOLDOWN_MS)
+    // In-flight debounce: if we just spawned one, skip.
+    if (Date.now() - meta.lastDistilledAt < DISTILL_DEBOUNCE_MS)
         return;
-    // Need at least N new turns since last pass.
     const cfg = loadConfig();
     const stitch = client(cfg);
     let recallSize = 0;
@@ -1221,17 +1259,21 @@ async function maybeAutoDistill(thread) {
     catch {
         return;
     }
-    if (recallSize - meta.lastTurnCount < DISTILL_MIN_NEW_TURNS)
+    const pending = recallSize - meta.lastTurnCount;
+    // Default path: only distill once enough turns have piled up.
+    // SessionStart catch-up: distill if there's ANY pending turn.
+    const threshold = opts.force ? 1 : DISTILL_MIN_NEW_TURNS;
+    if (pending < threshold)
         return;
     // Mark BEFORE running so we don't double-fire on overlapping Stop events.
     state.threads[thread] = { lastDistilledAt: Date.now(), lastTurnAt: Date.now(), lastTurnCount: recallSize };
     saveDistillState(state);
-    // Detach: spawn a background process so the Stop hook returns immediately.
-    // The detached child runs `stitch distill` for this thread.
+    // Detach: spawn a background process so the hook returns immediately.
     try {
         const child = spawn(process.argv[0], [process.argv[1] || (await import('node:url')).fileURLToPath(import.meta.url), 'distill', '--thread', thread, '--n', String(DISTILL_BATCH_SIZE)], {
             detached: true,
             stdio: 'ignore',
+            env: { ...process.env, STITCH_HOOKS_DISABLED: '1' },
         });
         child.unref();
     }
@@ -1666,13 +1708,17 @@ const STITCH_SESSION_START_HOOK = {
     matcher: '*',
     hooks: [{ type: 'command', command: 'stitch _hook SessionStart' }],
 };
-// File summary cache: only fires for the Read tool, both pre and post.
+// File summary cache:
+//   • PreToolUse fires only on Read (cached summary surfaces before the read).
+//   • PostToolUse fires on Read, Edit, Write, MultiEdit — Edit/Write/MultiEdit
+//     invalidate any prior summary so a stale "old version" memory never
+//     lingers. The matcher is a regex (Claude Code accepts pipe alternation).
 const STITCH_PRE_READ_HOOK = {
     matcher: 'Read',
     hooks: [{ type: 'command', command: 'stitch _hook' }],
 };
 const STITCH_POST_READ_HOOK = {
-    matcher: 'Read',
+    matcher: 'Read|Edit|Write|MultiEdit',
     hooks: [{ type: 'command', command: 'stitch _hook' }],
 };
 function mergeHook(existing, entry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {