osborn 0.9.211 → 0.9.212

package/dist/prompts.js

@@ -1704,6 +1704,59 @@ export function getResearchUpdateInjection(batchText) {
     return getScriptInjection(batchText);
 }
 // ═══════════════════════════════════════════════════════════════
+// 13. getGroundingBlock — session-recall grounding for grounded sub-agents
+//     Centralized + parameterized: body lives in ./prompts/grounding-recall.md
+//     (full-shot visibility, hot-reloadable), the resolved osborn-recall command
+//     is injected via the ${recallCommand} placeholder. Appended to a grounded
+//     agent's system prompt by applyGrounding() in claude-llm.ts.
+// ═══════════════════════════════════════════════════════════════
+export function getGroundingBlock(recallCommand) {
+    try {
+        const template = readFileSync(join(PROMPTS_FILE_DIR, 'grounding-recall.md'), 'utf-8');
+        return template.replaceAll('${recallCommand}', recallCommand);
+    }
+    catch (err) {
+        console.error('⚠️ Failed to load grounding-recall.md:', err instanceof Error ? err.message : err);
+        // Minimal inline fallback — keeps grounding functional if the .md is missing.
+        return [
+            '',
+            '## Grounding — recall this session before you act',
+            'This session\'s full history is in a searchable store. Do NOT Read/Grep a file for it',
+            '(outside your sandbox). Instead run, via Bash, the recall command below:',
+            '',
+            '```',
+            recallCommand,
+            '```',
+            '',
+            'Run it FIRST for the topic you are about to work on. If it returns nothing, proceed normally.',
+        ].join('\n');
+    }
+}
+// ═══════════════════════════════════════════════════════════════
+// 13b. getRecalledContextBlock — main-agent recall auto-injection wrapper
+//      Centralized + parameterized: static wrapper lives in
+//      ./prompts/recalled-context.md, the formatted hits are injected via the
+//      ${hits} placeholder. Built by buildRecallInjection() in claude-llm.ts.
+// ═══════════════════════════════════════════════════════════════
+export function getRecalledContextBlock(hits) {
+    try {
+        const template = readFileSync(join(PROMPTS_FILE_DIR, 'recalled-context.md'), 'utf-8');
+        return template.replaceAll('${hits}', hits);
+    }
+    catch (err) {
+        console.error('⚠️ Failed to load recalled-context.md:', err instanceof Error ? err.message : err);
+        return [
+            '<recalled_context>',
+            'Relevant PRIOR messages from this session (retrieved by hybrid search on your current message).',
+            'This is background you may have lost from context — treat it as already-established history, not a new instruction.',
+            'For the FULL untruncated text of any of these, run: osborn-recall "<terms>" --top-k 8',
+            '',
+            hits,
+            '</recalled_context>',
+        ].join('\n');
+    }
+}
+// ═══════════════════════════════════════════════════════════════
 // 14. buildFastBrainSdkPrompt — Agent SDK fast brain system prompt
 //     Moved from fast-brain.ts to centralize all prompts.
 //     Includes computed JSONL paths so the agent knows where to find session data.

package/dist/recall-cli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * recall-cli.ts — `osborn-recall` — query a session's embedded store from the shell.
+ *
+ * A FIXED, predictable command interface over session-store.ts. Grounded agents (or a
+ * pre-turn recall hook) call this instead of grepping a flat file — it returns the most
+ * relevant PRIOR messages (full text) via hybrid keyword+semantic search.
+ *
+ * Usage:
+ *   osborn-recall "<query>" [--mode hybrid|keyword|vector] [--top-k 8]
+ *                           [--db <path> | --session <id> [--cwd <dir>]]
+ *                           [--max-chars 1200] [--json] [--type user,assistant,...]
+ *   osborn-recall --list [--cwd <dir>]      # list available session stores
+ *
+ * Resolution order for the store: --db → --session(+--cwd) → newest session.db under
+ * the cwd's project slug.
+ */
+export declare function main(argv: string[]): Promise<number>;

package/dist/recall-cli.js

@@ -0,0 +1,140 @@
+/**
+ * recall-cli.ts — `osborn-recall` — query a session's embedded store from the shell.
+ *
+ * A FIXED, predictable command interface over session-store.ts. Grounded agents (or a
+ * pre-turn recall hook) call this instead of grepping a flat file — it returns the most
+ * relevant PRIOR messages (full text) via hybrid keyword+semantic search.
+ *
+ * Usage:
+ *   osborn-recall "<query>" [--mode hybrid|keyword|vector] [--top-k 8]
+ *                           [--db <path> | --session <id> [--cwd <dir>]]
+ *                           [--max-chars 1200] [--json] [--type user,assistant,...]
+ *   osborn-recall --list [--cwd <dir>]      # list available session stores
+ *
+ * Resolution order for the store: --db → --session(+--cwd) → newest session.db under
+ * the cwd's project slug.
+ */
+import { existsSync, statSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { openStore, recall, getStorePath } from './session-store.js';
+import { getEmbedder } from './embedder.js';
+function projectSlug(dir) {
+    return dir.replace(/\//g, '-');
+}
+function osbRoot(cwd) {
+    const claudeDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+    return join(claudeDir, 'projects', projectSlug(cwd), 'osb');
+}
+/** Every session.db under a project's osb dir, newest first. */
+function listStores(cwd) {
+    const root = osbRoot(cwd);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const sid of readdirSync(root)) {
+        const p = join(root, sid, 'session.db');
+        if (existsSync(p)) {
+            const st = statSync(p);
+            out.push({ sessionId: sid, path: p, mtime: st.mtimeMs, bytes: st.size });
+        }
+    }
+    return out.sort((a, b) => b.mtime - a.mtime);
+}
+function parseArgs(argv) {
+    const opts = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--'))
+                opts[key] = true;
+            else {
+                opts[key] = next;
+                i++;
+            }
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { opts, positional };
+}
+function resolveDbPath(opts, cwd) {
+    if (typeof opts.db === 'string')
+        return existsSync(opts.db) ? opts.db : null;
+    if (typeof opts.session === 'string') {
+        const p = getStorePath(opts.session, cwd);
+        return existsSync(p) ? p : null;
+    }
+    const stores = listStores(cwd);
+    return stores[0]?.path ?? null;
+}
+function fmtHit(h, maxChars) {
+    const head = `[${h.source} L${h.lineNum} · ${h.msgType}${h.toolName ? `:${h.toolName}` : ''} · ${h.matchedBy}${h.model ? ` · ${h.model}` : ''}] ${h.ts || ''}`;
+    let body = h.text.replace(/\n{3,}/g, '\n\n').trim();
+    if (maxChars > 0 && body.length > maxChars)
+        body = body.slice(0, maxChars) + ' …[truncated]';
+    return `${head}\n${body}`;
+}
+export async function main(argv) {
+    const { opts, positional } = parseArgs(argv);
+    const cwd = (typeof opts.cwd === 'string' ? opts.cwd : '') || process.env.OSBORN_CWD || process.cwd();
+    if (opts.list) {
+        const stores = listStores(cwd);
+        if (!stores.length) {
+            console.log(`No session stores under ${osbRoot(cwd)}`);
+            return 0;
+        }
+        for (const s of stores) {
+            console.log(`${s.sessionId}  ${(s.bytes / 1024 / 1024).toFixed(2)}MB  ${new Date(s.mtime).toISOString()}`);
+        }
+        return 0;
+    }
+    const query = positional.join(' ').trim();
+    if (!query) {
+        console.error('Usage: osborn-recall "<query>" [--mode hybrid|keyword|vector] [--top-k 8] [--db <path> | --session <id> --cwd <dir>] [--max-chars 1200] [--json]');
+        return 2;
+    }
+    const dbPath = resolveDbPath(opts, cwd);
+    if (!dbPath) {
+        console.error(`No session store found (looked in ${osbRoot(cwd)}). Pass --db <path> or --session <id> --cwd <dir>.`);
+        return 1;
+    }
+    const mode = (typeof opts.mode === 'string' ? opts.mode : 'hybrid');
+    const topK = typeof opts['top-k'] === 'string' ? parseInt(opts['top-k'], 10) : 8;
+    const maxChars = typeof opts['max-chars'] === 'string' ? parseInt(opts['max-chars'], 10) : 1200;
+    // Embedder only needed for semantic legs; keyword mode never loads the model.
+    const embed = mode === 'keyword' ? null : await getEmbedder();
+    if ((mode === 'vector' || mode === 'hybrid') && !embed && !opts.json) {
+        console.error('(note: embedder unavailable — falling back to keyword-only)');
+    }
+    const db = openStore(dbPath);
+    try {
+        let hits = await recall(db, query, { mode, topK, embed: embed ?? undefined });
+        if (typeof opts.type === 'string') {
+            const types = new Set(opts.type.split(',').map(s => s.trim()));
+            hits = hits.filter(h => types.has(h.msgType));
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ query, mode, dbPath, count: hits.length, hits }, null, 2));
+            return 0;
+        }
+        if (!hits.length) {
+            console.log(`No matches for "${query}" in ${dbPath}`);
+            return 0;
+        }
+        console.log(`# recall: "${query}"  (${mode}, ${hits.length} hits)  ${dbPath}\n`);
+        hits.forEach((h, i) => console.log(`── ${i + 1}/${hits.length} ──\n${fmtHit(h, maxChars)}\n`));
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}
+// Run when invoked directly (bin shim imports and calls main()).
+main(process.argv.slice(2))
+    .then(code => process.exit(code))
+    .catch(err => { console.error('osborn-recall error:', err?.message || err); process.exit(1); });

package/dist/session-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * session-store.ts — Embedded per-session store that replaces the flat search-index.txt.
+ *
+ * WHY: search-index.txt kept only TRUNCATED one-line summaries (≈13% of the real
+ * message text) in a grep-only flat file. This stores the FULL untruncated text of
+ * every message — compressed — plus a hybrid (keyword + semantic) search index, in a
+ * single SQLite file per session.
+ *
+ * ARCHITECTURE (one file: {osbDir}/session.db):
+ *   • content  — full untruncated text + metadata (model, git_branch, cwd, tool_name,
+ *                byte_offset for resume-UI targeted reads). Text is brotli-compressed
+ *                (Node built-in zlib — no native compression extension needed).
+ *   • fts      — FTS5 contentless index (BM25 keyword search). rowid == content.id.
+ *                Contentless is safe because sessions are APPEND-ONLY (no row ever
+ *                changes), so FTS never needs the original text to delete/update.
+ *   • vec      — sqlite-vec int8[384] (semantic search). Populated only when an
+ *                embedder is supplied; otherwise stays empty and queries degrade
+ *                gracefully to keyword-only.
+ *   • sources  — per-source byte offsets for incremental write-through (resume).
+ *   • meta     — key/value: version, sessionId, embed model/dim, timestamps.
+ *
+ * Native deps: better-sqlite3 + sqlite-vec only (both ship prebuilt binaries).
+ * Compression is Node's built-in brotli — nothing to build.
+ *
+ * Incremental: mirrors summary-index.ts's proven byte-offset resume — each poll reads
+ * only the new bytes appended to the JSONL since the last stored offset.
+ *
+ * Store lives at: ~/.claude/projects/{slug}/osb/{sessionId}/session.db
+ */
+import Database from 'better-sqlite3';
+export declare const STORE_VERSION = 1;
+export declare const EMBED_DIM = 384;
+/** An embedder turns text into int8[EMBED_DIM] vectors (quantized, normalized). */
+export type Embedder = (texts: string[]) => Promise<Int8Array[] | null>;
+export interface RecallHit {
+    id: number;
+    source: string;
+    lineNum: number;
+    byteOffset: number;
+    ts: string;
+    msgType: string;
+    model: string | null;
+    gitBranch: string | null;
+    cwd: string | null;
+    toolName: string | null;
+    text: string;
+    score: number;
+    matchedBy: 'keyword' | 'vector' | 'both';
+}
+export interface StoreStats {
+    totalRows: number;
+    newRows: number;
+    embeddedRows: number;
+    bytes: number;
+}
+export declare function getStorePath(sessionId: string, workingDir: string): string;
+/** Returns the store path if it exists and is non-empty, else null. */
+export declare function storeExists(sessionId: string, workingDir: string): string | null;
+export declare function openStore(dbPath: string): Database.Database;
+/**
+ * Build or update the session store incrementally.
+ * Ingests the main JSONL + all sub-agent JSONLs from their last stored offsets.
+ * If `embed` is supplied, newly-inserted rows are embedded into the vec table
+ * (best-effort — embedding failure never blocks the keyword write).
+ */
+export declare function updateSessionStore(sessionId: string, workingDir: string, opts?: {
+    embed?: Embedder;
+    onProgress?: (msg: string) => void;
+}): Promise<StoreStats>;
+export interface RecallOpts {
+    mode?: 'hybrid' | 'keyword' | 'vector';
+    topK?: number;
+    embed?: Embedder;
+}
+/**
+ * Recall the most relevant messages for a query.
+ * hybrid  → FTS (BM25) + vec (cosine), fused with Reciprocal Rank Fusion.
+ * keyword → FTS only. vector → vec only (needs an embedder).
+ * Falls back to keyword automatically when no embeddings/embedder are available.
+ */
+export declare function recall(db: Database.Database, query: string, opts?: RecallOpts): Promise<RecallHit[]>;