@stitchdb/cli 0.6.1 → 0.7.0

package/dist/cli.js

@@ -420,9 +420,10 @@ async function cmdHook(args) {
     const cfg = loadConfig();
     if (!cfg.apiKey)
         return; // not logged in, silently skip
-    // When the Stitch CLI spawns its own `claude -p` (e.g. for distillation),
-    // we don't want THAT inner conversation logged as a user/assistant turn —
-    // it would pollute the project thread with the distill prompt and JSON.
+    // When the Stitch CLI spawns its own `claude -p` (e.g. for distillation
+    // or file summary extraction), we don't want THAT inner conversation
+    // logged or its tool calls cached — it would create runaway recursion
+    // and pollute the thread with internal prompts.
     if (process.env.STITCH_HOOKS_DISABLED === '1')
         return;
     let raw = '';
@@ -446,6 +447,16 @@ async function cmdHook(args) {
     // (which is the directory `claude` was launched from).
     const cwd = event?.cwd || process.cwd();
     const threadName = inferThreadFor(cwd) || 'default';
+    // ── PreToolUse on Read: inject cached summary if hash matches ─────────
+    if (eventName === 'PreToolUse' && event?.tool_name === 'Read') {
+        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(() => { });
+        return;
+    }
     // ── SessionStart: inject prior context (token-efficient) ─────────────
     // Strategy: prefer distilled memories (dense facts) over raw turns. Only
     // include raw turns for the last 5 to give the agent immediate continuation.
@@ -453,16 +464,30 @@ async function cmdHook(args) {
         try {
             const stitch = client(cfg);
             const projectTag = (threadName.split('/')[0] || threadName).toLowerCase();
-            const [thread, memHits] = await Promise.all([
+            const [thread, memHits, workspaces, fileSummaries, aboutMems] = await Promise.all([
                 stitch.thread(threadName).recall({ last: 5 }).catch(() => ({ thread_id: '', recent: [], semantic: [] })),
                 stitch.recall(projectTag, { k: 8 }).catch(() => []),
+                stitch.workspaces.list().catch(() => []),
+                stitch.list({ limit: 12 }).then((all) => all.filter((m) => m.tags.some((t) => t.startsWith('file:')))).catch(() => []),
+                stitch.list({ tag: 'workspace:about', limit: 1 }).catch(() => []),
             ]);
+            const currentWs = Array.isArray(workspaces) && workspaces.length > 0 ? workspaces[0] : null;
             const lines = [];
             lines.push('<stitch-context>');
-            lines.push(`Project: ${threadName} · Stitch MCP server is available with tools: recall, remember, thread_recall, thread_append.`);
+            lines.push(`Project: ${threadName} · Workspace: ${currentWs?.name || '(unknown)'} · Stitch MCP tools: recall, remember, thread_recall, thread_append, workspace_setup, file_summary, file_summary_save.`);
             lines.push('');
+            // Nudge the AI to set a meaningful workspace name once.
+            if (currentWs?.name === 'default') {
+                lines.push('### ⚠ Workspace is still named "default"');
+                lines.push('Call the `workspace_setup` MCP tool with a slug-style name based on this project (e.g. the package.json name or repo dir).');
+                lines.push('');
+            }
+            if (Array.isArray(aboutMems) && aboutMems.length > 0) {
+                lines.push('### About this workspace');
+                lines.push(String(aboutMems[0].content || '').slice(0, 400));
+                lines.push('');
+            }
             if (Array.isArray(memHits) && memHits.length > 0) {
-                // Prefer distilled (auto-tagged) facts and decisions; fall back to anything else
                 const sortedMems = [...memHits].sort((a, b) => Number(b.score ?? 0) - Number(a.score ?? 0)).slice(0, 8);
                 lines.push('### Durable memories for this project');
                 for (const m of sortedMems) {
@@ -472,6 +497,16 @@ async function cmdHook(args) {
                 }
                 lines.push('');
             }
+            if (Array.isArray(fileSummaries) && fileSummaries.length > 0) {
+                lines.push('### File summaries (cached — call `file_summary` before reading)');
+                for (const m of fileSummaries.slice(0, 8)) {
+                    const fileTag = m.tags.find((t) => t.startsWith('file:'));
+                    const filePath = fileTag ? fileTag.slice(5) : '(unknown)';
+                    const txt = String(m.content || '').replace(/\n+/g, ' ').slice(0, 250);
+                    lines.push(`- **${filePath}** — ${txt}`);
+                }
+                lines.push('');
+            }
             if (thread.recent && thread.recent.length > 0) {
                 lines.push('### Most recent turns (continue from here)');
                 for (const t of thread.recent.slice(-5)) {
@@ -480,7 +515,7 @@ async function cmdHook(args) {
                 }
                 lines.push('');
             }
-            lines.push('Call `recall` for deeper search or `thread_recall` for older turns when needed.');
+            lines.push('Call `recall` for deeper search, `thread_recall` for older turns, `file_summary` BEFORE reading any non-trivial file (saves tokens).');
             lines.push('</stitch-context>');
             process.stdout.write(lines.join('\n'));
         }
@@ -549,6 +584,38 @@ function inferThreadFor(cwd) {
     }
     return path.basename(dir) || 'default';
 }
+/**
+ * Best-effort derive a workspace slug from a project directory:
+ * - package.json `name` (npm convention, slug-friendly already)
+ * - else folder basename, normalised to a lowercase slug
+ *
+ * The AI can later refine via the `workspace_setup` MCP tool — this is just
+ * the seed name so it isn't "default".
+ */
+function deriveWorkspaceName(cwd) {
+    // 1. package.json `name`.
+    try {
+        const pkgPath = path.join(cwd, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            if (typeof pkg.name === 'string' && pkg.name.trim()) {
+                // Strip leading scope (@org/) if any — keeps the slug clean.
+                const stripped = pkg.name.replace(/^@[^/]+\//, '').trim();
+                if (stripped)
+                    return slugify(stripped).slice(0, 60);
+            }
+        }
+    }
+    catch { /* fall through */ }
+    // 2. Folder basename.
+    return slugify(path.basename(cwd) || 'default').slice(0, 60) || 'default';
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'default';
+}
 function findProjectRoot(cwd) {
     let cur = cwd;
     for (let i = 0; i < 8; i++) {
@@ -604,6 +671,223 @@ function lastAssistantTextFromTranscript(transcriptPath) {
     catch { /* ignore */ }
     return text;
 }
+// ─── File summary cache ────────────────────────────────────────────────────
+//
+// Goal: when Claude reads a non-trivial file we've seen before, surface our
+// cached 2-3 sentence summary so the agent can decide whether to skim or
+// re-read in full. When Claude reads a file we haven't summarized (or that's
+// changed), kick off a background `claude -p` to extract a summary and save
+// it as a memory tagged `file:<path>` + `hash:<sha-prefix>`.
+//
+// Trade-off: the cache is hash-bound, so any byte change invalidates the
+// cached summary — fine for big stable files (docs, configs, third-party src),
+// less useful for files Claude is actively editing. The PostToolUse hook
+// re-summarizes after the next read, so the cache repopulates on its own.
+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.
+
+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.
+
+Skip preamble. Skip "this file …". Be specific. No markdown fences. No prose around it.
+
+File path: {{PATH}}
+
+File content:
+{{CONTENT}}
+`;
+function readFileContentFromHookEvent(event) {
+    // Claude Code hook 'tool_response' shape varies between versions; accept
+    // a few shapes. The Read tool's success path includes the file content
+    // somewhere in tool_response.
+    const r = event?.tool_response;
+    if (!r)
+        return '';
+    if (typeof r === 'string')
+        return r;
+    if (typeof r?.file?.content === 'string')
+        return r.file.content;
+    if (typeof r?.content === 'string')
+        return r.content;
+    if (Array.isArray(r?.content)) {
+        return r.content.map((c) => (typeof c === 'string' ? c : c?.text ?? '')).join('');
+    }
+    return '';
+}
+function relPathFor(cwd, abs) {
+    try {
+        return path.relative(cwd, abs) || abs;
+    }
+    catch {
+        return abs;
+    }
+}
+async function sha256Hex(s) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(s));
+    return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+async function lookupFileSummary(stitch, relPath) {
+    try {
+        const list = await stitch.list({ tag: `file:${relPath}`, limit: 5 });
+        if (!list || list.length === 0)
+            return null;
+        const first = list[0];
+        const hashTag = first.tags.find((t) => t.startsWith('hash:'));
+        return {
+            id: first.id,
+            content: first.content,
+            hash: hashTag ? hashTag.slice(5) : null,
+            created_at: first.created_at,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// PreToolUse on Read: if we have a cached summary for this exact file path,
+// emit Claude-Code-flavoured JSON to stdout that adds it as additional context.
+async function handlePreReadHook(cfg, event, cwd) {
+    const filePath = String(event?.tool_input?.file_path || '');
+    if (!filePath)
+        return;
+    const rel = relPathFor(cwd, filePath);
+    const stitch = client(cfg);
+    const cached = await lookupFileSummary(stitch, rel);
+    if (!cached)
+        return;
+    const ageMin = Math.round((Date.now() - cached.created_at) / 60_000);
+    const note = [
+        `Stitch cache: a prior summary of ${rel} exists (${ageMin}m ago).`,
+        cached.hash ? `Cached hash prefix: ${cached.hash}.` : '',
+        `Summary: ${cached.content}`,
+        `If the file hasn't changed, you can act on this summary alone and skip a full read; otherwise the read will re-cache the summary.`,
+    ].filter(Boolean).join('\n');
+    // Claude Code accepts a JSON object on stdout for PreToolUse with
+    // hookSpecificOutput.additionalContext to inject text into the model's
+    // context for this tool call.
+    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) {
+    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;
+        }
+    }
+    if (!body || 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];
+    if (last && last.hash === hashPrefix && Date.now() - last.lastSummarizedAt < FILE_SUMMARY_COOLDOWN_MS)
+        return;
+    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.
+    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], {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...process.env, STITCH_HOOKS_DISABLED: '1' },
+        });
+        child.unref();
+    }
+    catch { /* ignore */ }
+}
+// File summary state: per-file cooldown so we don't re-fire on every Read.
+const FILE_SUMMARY_STATE_FILE = path.join(CONFIG_DIR, 'file-summary-state.json');
+function loadFileSummaryState() {
+    try {
+        return JSON.parse(fs.readFileSync(FILE_SUMMARY_STATE_FILE, 'utf8'));
+    }
+    catch {
+        return { files: {} };
+    }
+}
+function saveFileSummaryState(s) {
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(FILE_SUMMARY_STATE_FILE, JSON.stringify(s, null, 2));
+}
+// `stitch _summarize-file <abs> <hashPrefix> <rel>` — internal entry called
+// from the detached PostToolUse spawn. Reads the file, asks claude -p for a
+// 2-3 sentence summary, saves as a Stitch memory.
+async function cmdSummarizeFile(args) {
+    const [abs, hashPrefix, rel] = args;
+    if (!abs || !hashPrefix || !rel)
+        return;
+    const cfg = loadConfig();
+    if (!cfg.apiKey)
+        return;
+    let body = '';
+    try {
+        body = fs.readFileSync(abs, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (!body || body.length > FILE_SUMMARY_MAX_BYTES)
+        return;
+    const claudeBin = process.env.STITCH_CLAUDE_BIN || 'claude';
+    const prompt = FILE_SUMMARY_PROMPT
+        .replace('{{PATH}}', rel)
+        .replace('{{CONTENT}}', body);
+    const result = await runWithStdin(claudeBin, ['-p'], prompt, {
+        cwd: process.cwd(),
+        env: { STITCH_HOOKS_DISABLED: '1' },
+    });
+    if (result.exit_code !== 0)
+        return;
+    const summary = result.stdout.trim().slice(0, 2000);
+    if (!summary)
+        return;
+    try {
+        const stitch = client(cfg);
+        const projectTag = (inferThread() || 'default').split('/')[0];
+        // Replace any prior summary for this path.
+        const prior = await stitch.list({ tag: `file:${rel}`, limit: 50 }).catch(() => []);
+        for (const p of prior) {
+            try {
+                await stitch.forget(p.id);
+            }
+            catch { }
+        }
+        await stitch.remember(summary, {
+            kind: 'snippet',
+            tags: [`file:${rel}`, `hash:${hashPrefix}`, 'auto:file-summary', `project:${projectTag}`],
+        });
+    }
+    catch { /* silent — never break a session */ }
+}
 // ── stitch link — pin a project's thread name so it's the same on every machine
 async function cmdLink(args) {
     const positionals = positional(args);
@@ -1179,6 +1463,26 @@ async function cmdInstall(args) {
     const ws = await stitch.resolveWorkspace();
     const baseUrl = cfg.baseUrl || 'https://db.stitchdb.com';
     const mcpUrl = `${baseUrl}/mcp/v1/${ws}`;
+    // 0. If the workspace is still called "default", upgrade its name to a
+    //    project-derived slug so memories surface under a meaningful identity.
+    //    The AI can later refine it via the workspace_setup MCP tool.
+    if (!hasFlag(args, ['--no-rename-workspace'])) {
+        try {
+            const current = await stitch.workspaces.get(ws);
+            if (current.name === 'default') {
+                const derived = deriveWorkspaceName(process.cwd());
+                if (derived && derived !== 'default') {
+                    process.stdout.write(`• Naming workspace "${derived}" (was "default")… `);
+                    await stitch.workspaces.update(ws, { name: derived });
+                    console.log('ok');
+                }
+            }
+        }
+        catch (e) {
+            // Older deployments may not have the PATCH endpoint yet.
+            console.log(`• Workspace rename skipped (${e?.message || e}).`);
+        }
+    }
     const noMcp = hasFlag(args, ['--no-mcp']);
     const noHooks = hasFlag(args, ['--no-hooks']);
     const noClaudeMd = hasFlag(args, ['--no-claude-md']);
@@ -1197,9 +1501,10 @@ async function cmdInstall(args) {
         else
             console.log(`failed (${stderr.trim().slice(0, 120)})`);
     }
-    // 2. Hooks: auto-log every turn + auto-inject prior context at session start
+    // 2. Hooks: auto-log every turn + auto-inject prior context at session start +
+    //          file-summary cache (Pre/PostToolUse on Read).
     if (!noHooks) {
-        process.stdout.write('• Wiring hooks (SessionStart + UserPromptSubmit + Stop)… ');
+        process.stdout.write('• Wiring hooks (SessionStart + UserPromptSubmit + Stop + Pre/PostToolUse:Read)… ');
         try {
             const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
             const existing = fs.existsSync(settingsPath)
@@ -1209,6 +1514,8 @@ async function cmdInstall(args) {
             existing.hooks.SessionStart = mergeHook(existing.hooks.SessionStart, STITCH_SESSION_START_HOOK);
             existing.hooks.UserPromptSubmit = mergeHook(existing.hooks.UserPromptSubmit, STITCH_USER_HOOK);
             existing.hooks.Stop = mergeHook(existing.hooks.Stop, STITCH_STOP_HOOK);
+            existing.hooks.PreToolUse = mergeHook(existing.hooks.PreToolUse, STITCH_PRE_READ_HOOK);
+            existing.hooks.PostToolUse = mergeHook(existing.hooks.PostToolUse, STITCH_POST_READ_HOOK);
             fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
             fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
             console.log('ok');
@@ -1290,10 +1597,11 @@ async function cmdInstall(args) {
     }
     console.log();
     console.log('Done. Open a fresh `claude` session — Stitch is wired.');
-    console.log('  • remember/recall tools are available');
+    console.log('  • workspace_setup, recall, remember, thread tools are available');
     console.log('  • every turn auto-logs to the thread for this repo');
     console.log('  • Claude auto-pulls past context at session start (per CLAUDE.md)');
     console.log('  • Claude memory files are mirrored to Stitch');
+    console.log('  • file Reads auto-cache 2-3 sentence summaries; Pre-Read injects them');
     console.log();
     console.log('Run `stitch sync --watch` to keep them in sync as Claude updates them.');
 }
@@ -1313,6 +1621,15 @@ 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.
+const STITCH_PRE_READ_HOOK = {
+    matcher: 'Read',
+    hooks: [{ type: 'command', command: 'stitch _hook' }],
+};
+const STITCH_POST_READ_HOOK = {
+    matcher: 'Read',
+    hooks: [{ type: 'command', command: 'stitch _hook' }],
+};
 function mergeHook(existing, entry) {
     const arr = Array.isArray(existing) ? existing.slice() : [];
     // Replace any earlier Stitch entry; identify by the marker.
@@ -1570,6 +1887,7 @@ async function main(argv) {
             case 'link': return cmdLink(rest);
             case 'distill': return cmdDistill(rest);
             case '_hook': return cmdHook(rest);
+            case '_summarize-file': return cmdSummarizeFile(rest);
             case 'update':
             case 'upgrade': return cmdUpdate(rest);
             case 'version':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   "license": "MIT",
   "engines": { "node": ">=20" },
   "dependencies": {
-    "@stitchdb/agent": "^0.1.1"
+    "@stitchdb/agent": "^0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.4.0",