@0xmaxma/claude-gateway 1.6.9 → 1.7.1

package/dist/ui/web-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":";;AAIA,sDAq4BC;AAQD,8CAiFC;AAl+BD;;;GAGG;AACH,SAAgB,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAm4BD,CAAC;AACT,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,cAAc,GAAG,EAAE;IACnD,MAAM,UAAU,GAAG,cAAc;SAC9B,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9F,+EAA+E;IAC/E,8EAA8E;IAC9E,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC;uBACiB,UAAU,QAAQ;QACrC,CAAC,CAAC;;;;;;;YAOM,CAAC;IACX,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6BH,CAAC;AACT,CAAC"}
+{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":"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"}

package/mcp/package.json

@@ -4,7 +4,8 @@
   "type": "module",
   "bin": "./server.ts",
   "scripts": {
-    "start": "bun install --no-summary && bun server.ts"
+    "start": "bun install --no-summary && bun server.ts",
+    "test": "bun test"
   },
   "dependencies": {
     "@line/bot-sdk": "^11.0.2",

package/mcp/server.ts

@@ -23,6 +23,7 @@ import { ImageModule } from './tools/image/module';
 import { ShareImageModule } from './tools/share-image/module';
 import { AppsModule } from './tools/apps/module';
 import { ApiModule } from './tools/api/module';
+import { MemoryModule } from './tools/memory/module';
 import { buildChannelInstructions } from './instructions';
 import type { ChannelModule, ToolModule, McpToolDefinition } from './types';
 
@@ -46,6 +47,7 @@ const modules: AnyModule[] = [
   new ShareImageModule(),
   new AppsModule(),
   new ApiModule(),
+  new MemoryModule(),
 ];
 
 // Build tool-to-module mapping for enabled modules
@@ -100,7 +102,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: visibleTools,
 }));
 
-mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
   const toolName = req.params.name;
   const args = (req.params.arguments ?? {}) as Record<string, unknown>;
 
@@ -112,7 +114,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     };
   }
 
-  return mod.handleTool(toolName, args);
+  // extra.signal fires on notifications/cancelled for THIS call (the SDK matches
+  // it by requestId) — the CLI sends that when a user Stop/Ctrl-C interrupts an
+  // in-flight tool call. Threaded through so a long-running module (image
+  // generation's poll loop) can react instead of running to its full timeout.
+  return mod.handleTool(toolName, args, extra.signal);
 });
 
 // Connect MCP transport

package/mcp/tools/image/module.ts

@@ -109,14 +109,17 @@ export class ImageModule implements ToolModule {
     return imageToolDefs;
   }
 
-  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+  async handleTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<McpToolResult> {
     if (name !== 'generate_image') {
       return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
     }
     const action = typeof args.action === 'string' ? args.action : 'generate';
     switch (action) {
       case 'generate':
-        return this.handleGenerate(args);
+        // Only "generate" gets the signal — it's the one action with a multi-second
+        // poll loop worth reacting to a Stop mid-flight (#2216 follow-up on the
+        // getpod side). status/list/list_refs are single bounded requests already.
+        return this.handleGenerate(args, signal);
       case 'status':
         return this.handleStatus(args);
       case 'list':
@@ -257,7 +260,7 @@ export class ImageModule implements ToolModule {
     };
   }
 
-  private async handleGenerate(args: Record<string, unknown>): Promise<McpToolResult> {
+  private async handleGenerate(args: Record<string, unknown>, signal?: AbortSignal): Promise<McpToolResult> {
     const prompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
     const model = typeof args.model === 'string' ? args.model.trim() : '';
     if (!prompt) {
@@ -369,11 +372,16 @@ export class ImageModule implements ToolModule {
       return { content: [{ type: 'text', text: 'generate_image: image service did not return a task_id' }], isError: true };
     }
 
-    // Poll (E2) until done/failed or budget exceeded.
+    // Poll (E2) until done/failed, budget exceeded, or the caller cancels this call
+    // (Stop mid-generation — #2216 follow-up). Checked at the top of every
+    // iteration AND inside the sleep itself, so a cancel lands within one wakeup
+    // instead of waiting out the full poll interval.
     const deadline = Date.now() + this.pollTimeoutMs();
     let last: JobResponse = submit;
     while (Date.now() < deadline) {
-      await sleep(DEFAULT_POLL_INTERVAL_MS);
+      if (signal?.aborted) return this.cancelledResult(taskId);
+      await sleep(DEFAULT_POLL_INTERVAL_MS, signal);
+      if (signal?.aborted) return this.cancelledResult(taskId);
       const polled = await this.fetchJob(taskId);
       if (polled.__transportError) {
         // transient transport error — keep polling until deadline
@@ -528,6 +536,36 @@ export class ImageModule implements ToolModule {
     return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_POLL_TIMEOUT_MS;
   }
 
+  /**
+   * Best-effort E3 cancel — fires and never throws, so a failed cancel call can
+   * never break the caller's own (already-cancelled) tool response. The api-side
+   * cancel is itself idempotent/no-op-safe on an already-terminal or unknown task,
+   * so no need to track whether this actually reached a still-running job.
+   */
+  private async cancelJob(taskId: string): Promise<void> {
+    try {
+      await fetch(`${this.baseUrl()}/v1/images/jobs/${encodeURIComponent(taskId)}/cancel`, {
+        method: 'POST',
+        headers: this.headers(),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch {
+      // non-fatal — the local tool call already reports itself cancelled either way
+    }
+  }
+
+  /** Tool result for a Stop-triggered cancellation, firing the E3 cancel first. */
+  private cancelledResult(taskId: string): McpToolResult {
+    void this.cancelJob(taskId);
+    return {
+      content: [{
+        type: 'text',
+        text: `generate_image: cancelled (task_id ${taskId}).`,
+      }],
+      isError: true,
+    };
+  }
+
   /** Fetch a job (E2), classifying transport vs HTTP errors so the poller can retry transient ones. */
   private async fetchJob(taskId: string): Promise<{ job?: JobResponse; httpError?: { status: number; body: string }; __transportError?: unknown }> {
     let res: Response;
@@ -654,12 +692,14 @@ export class ImageModule implements ToolModule {
         text: JSON.stringify({
           status: 'done',
           task_id: taskId,
+          ...(model ? { model } : {}),
           byok: job.byok ?? false,
           cost: job.cost ?? 0,
           files,
           ...(artifacts ? { artifacts } : {}),
           ...(droppedImages > 0 ? { dropped_images: droppedImages } : {}),
           note: 'Image saved. Deliver it to the user with your channel delivery tool — api_reply/reply (files: [...]), or line_image on LINE. Do NOT open/Read the file to inspect it first; attach it and answer briefly.'
+            + (model ? ` Mention which model made it (${model}).` : '')
             + (artifacts ? ' To edit this image later, reference it via its artifact_ref (e.g. image: "artifact:...").' : '')
             + (droppedImages > 0 ? ` (${droppedImages} extra image(s) beyond the cap were not saved)` : ''),
         }),
@@ -720,8 +760,19 @@ export class ImageModule implements ToolModule {
   }
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
+// Resolves early (without rejecting) on abort — the poll loop re-checks
+// signal.aborted itself right after, so this only needs to shorten the wait.
+// The abort listener is removed when the timer fires normally: sleep() is called
+// once per poll iteration against the SAME long-lived signal (up to ~75 times for
+// the default 150s/2s budget), so leaving { once:true } listeners around on the
+// non-abort path would pile them onto that one signal and trip Node's
+// MaxListenersExceededWarning.
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((r) => {
+    const onAbort = () => { clearTimeout(t); r(); };
+    const t = setTimeout(() => { signal?.removeEventListener('abort', onAbort); r(); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
 }
 
 function sanitize(s: string): string {

package/mcp/tools/memory/archive-reader.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Bun tests for the knowledge-archive read path (planning-64 K1).
+ *
+ * Runs under Bun (`bun test`) because the reader uses `bun:sqlite` — the Node
+ * jest suite cannot load this module. The fixture DB is built with bun:sqlite
+ * using the SAME schema src/ writes under node:sqlite (external-content FTS5 +
+ * provenance/recall), so this exercises the real query path end to end.
+ */
+
+import { test, expect } from 'bun:test';
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { searchArchive, getExcerpt, isMemoryScopedPath, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+
+// Build a temp agent dir with a kb.sqlite carrying the given chunks.
+function mkAgentWithArchive(
+  chunks: Array<{ id: string; path: string; start: number; end: number; text: string; origin?: string; importance?: number }>,
+): { agentDir: string; workspaceDir: string; dbPath: string } {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  const dbPath = archiveDbPath(workspaceDir); // agentDir/kb.sqlite
+
+  const db = new Database(dbPath);
+  db.exec('PRAGMA foreign_keys=ON');
+  db.exec(`
+    CREATE TABLE kb_chunks (rowid_id INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT UNIQUE, path TEXT,
+      start_line INTEGER, end_line INTEGER, text TEXT, updated_at INTEGER);
+    CREATE TABLE kb_chunk_recall (chunk_id TEXT PRIMARY KEY, importance INTEGER, triggers TEXT, project_key TEXT,
+      FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE TABLE kb_chunk_provenance (chunk_id TEXT PRIMARY KEY, origin_class TEXT, session_kind TEXT,
+      observed_at INTEGER, supersedes_key TEXT, FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE VIRTUAL TABLE kb_chunks_fts USING fts5(text, content='kb_chunks', content_rowid='rowid_id');
+    CREATE TRIGGER kb_chunks_ai AFTER INSERT ON kb_chunks BEGIN
+      INSERT INTO kb_chunks_fts(rowid, text) VALUES (new.rowid_id, new.text);
+    END;
+  `);
+  const ins = db.prepare('INSERT INTO kb_chunks(id,path,start_line,end_line,text,updated_at) VALUES(?,?,?,?,?,?)');
+  const insR = db.prepare('INSERT INTO kb_chunk_recall(chunk_id,importance) VALUES(?,?)');
+  const insP = db.prepare('INSERT INTO kb_chunk_provenance(chunk_id,origin_class,session_kind,observed_at) VALUES(?,?,?,?)');
+  for (const c of chunks) {
+    ins.run(c.id, c.path, c.start, c.end, c.text, 1);
+    insR.run(c.id, c.importance ?? null);
+    insP.run(c.id, c.origin ?? 'agent', 'unknown', 1);
+  }
+  db.close();
+  return { agentDir, workspaceDir, dbPath };
+}
+
+test('isMemoryScopedPath: accepts memory-scoped, rejects traversal/abs/out-of-scope', () => {
+  expect(isMemoryScopedPath('MEMORY.md')).toBe(true);
+  expect(isMemoryScopedPath('USER.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/foo.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/sub/bar.md')).toBe(true);
+  expect(isMemoryScopedPath('../secret.md')).toBe(false);
+  // The discriminating case: ends in .md AND starts with memory/, so ONLY the
+  // ".." guard rejects it — proves that guard is load-bearing.
+  expect(isMemoryScopedPath('memory/../secret.md')).toBe(false);
+  expect(isMemoryScopedPath('memory/../../etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('/etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('notes/random.md')).toBe(false);
+  expect(isMemoryScopedPath('AGENTS.md')).toBe(false);
+});
+
+test('searchArchive: FTS match returns ranked hit with provenance + importance', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/getpod.md#1-1', path: 'memory/getpod.md', start: 1, end: 1, text: 'Getpod ingress returns 401 before the gateway', origin: 'agent', importance: 7 },
+    { id: 'memory/apps.md#1-1', path: 'memory/apps.md', start: 1, end: 1, text: 'apps router mounts under gateway-router', origin: 'agent' },
+  ]);
+  try {
+    const hits = searchArchive(archiveDbPath(workspaceDir), 'ingress 401', 6);
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/getpod.md');
+    expect(hits[0].originClass).toBe('agent');
+    expect(hits[0].importance).toBe(7);
+    expect(hits[0].startLine).toBe(1);
+    expect(typeof hits[0].score).toBe('number');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+// Regression (#351): a kb.sqlite built before the planning-66 `entry_hash`
+// column (exactly what `mkAgentWithArchive` produces) must not crash the read
+// path with `no such column: entry_hash`. searchArchive heals the column in
+// place and returns hits with entryHash=null. Proven to throw on pre-fix code.
+test('searchArchive: DB missing entry_hash column does not throw and heals it', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/x.md#1-1', path: 'memory/x.md', start: 1, end: 1, text: 'ingress 401 token mismatch', origin: 'agent' },
+  ]);
+  const dbPath = archiveDbPath(workspaceDir);
+  const cols = (dbPath: string): string[] => {
+    const d = new Database(dbPath, { readonly: true });
+    try {
+      return (d.query(`PRAGMA table_info(kb_chunks)`).all() as Array<{ name: string }>).map((c) => c.name);
+    } finally {
+      d.close();
+    }
+  };
+  try {
+    // Precondition: the pre-#346 fixture genuinely lacks the column.
+    expect(cols(dbPath)).not.toContain('entry_hash');
+
+    let hits: ReturnType<typeof searchArchive> = [];
+    expect(() => {
+      hits = searchArchive(dbPath, 'ingress 401', 6);
+    }).not.toThrow();
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/x.md');
+    expect(hits[0].entryHash).toBeNull();
+
+    // The read path healed the DB in place so subsequent writers/readers are safe.
+    expect(cols(dbPath)).toContain('entry_hash');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('searchArchive: missing DB → [], empty/punctuation query → []', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  try {
+    expect(searchArchive(archiveDbPath(workspaceDir), 'anything', 6)).toEqual([]); // no kb.sqlite
+    const { workspaceDir: ws2, agentDir: dir2 } = mkAgentWithArchive([
+      { id: 'm#1-1', path: 'memory/a.md', start: 1, end: 1, text: 'hello world' },
+    ]);
+    expect(searchArchive(archiveDbPath(ws2), '   !!! ', 6)).toEqual([]); // no usable tokens
+    fs.rmSync(dir2, { recursive: true, force: true });
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('getExcerpt: bounded line range; out-of-scope/missing → null', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  fs.writeFileSync(path.join(workspaceDir, 'memory/note.md'), 'l1\nl2\nl3\nl4\nl5');
+  try {
+    const ex = getExcerpt(workspaceDir, 'memory/note.md', 2, 2);
+    expect(ex).not.toBeNull();
+    expect(ex!.text).toBe('l2\nl3');
+    expect(ex!.from).toBe(2);
+    expect(ex!.to).toBe(3);
+    expect(ex!.totalLines).toBe(5);
+    expect(ex!.truncated).toBe(true);
+
+    // Whole file → not truncated.
+    expect(getExcerpt(workspaceDir, 'memory/note.md', 1, 100)!.truncated).toBe(false);
+    // Out-of-scope path and missing file → null.
+    expect(getExcerpt(workspaceDir, '../secret.md', 1, 5)).toBeNull();
+    expect(getExcerpt(workspaceDir, 'memory/missing.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('sharedDbPathFromEnv: null when unset, <dir>/kb.sqlite when set (K3 corpus:shared)', () => {
+  const prev = process.env.GATEWAY_SHARED_KB_DIR;
+  try {
+    delete process.env.GATEWAY_SHARED_KB_DIR;
+    expect(sharedDbPathFromEnv()).toBeNull();
+    process.env.GATEWAY_SHARED_KB_DIR = '   ';
+    expect(sharedDbPathFromEnv()).toBeNull(); // blank → disabled
+    process.env.GATEWAY_SHARED_KB_DIR = '/tmp/shared/kb/global';
+    expect(sharedDbPathFromEnv()).toBe('/tmp/shared/kb/global/kb.sqlite');
+  } finally {
+    if (prev === undefined) delete process.env.GATEWAY_SHARED_KB_DIR;
+    else process.env.GATEWAY_SHARED_KB_DIR = prev;
+  }
+});
+
+test('mergeHits: round-robin interleave (bm25 not comparable across corpora), capped', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Each list is already best-first within its own corpus. A cross-corpus numeric
+  // sort would mix incomparable bm25 scales; interleave a,c,b instead (personal
+  // first each round), capped at the limit.
+  const merged = mergeHits([mk('a', -0.9), mk('b', -0.1)], [mk('c', -0.5), mk('d', -0.05)], 3);
+  expect(merged.map((h) => h.path)).toEqual(['a', 'c', 'b']);
+});
+
+test('mergeHits: interleave preserves per-corpus order even when scales differ', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Shared scores numerically "better" (more negative) must NOT starve the personal
+  // corpus — round-robin gives p1, s1, p2, s2.
+  const merged = mergeHits([mk('p1', -0.2), mk('p2', -0.05)], [mk('s1', -9), mk('s2', -8)], 4);
+  expect(merged.map((h) => h.path)).toEqual(['p1', 's1', 'p2', 's2']);
+});
+
+test('getExcerpt: a symlink inside memory/ escaping the workspace is refused', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  // A secret target OUTSIDE the workspace, and a memory/ symlink pointing at it.
+  const secret = path.join(agentDir, 'outside-secret.md');
+  fs.writeFileSync(secret, 'TOPSECRET outside the workspace');
+  fs.symlinkSync(secret, path.join(workspaceDir, 'memory', 'evil.md'));
+  try {
+    // Passes the string scope check (memory/*.md) but realpath escapes the ws → null.
+    expect(getExcerpt(workspaceDir, 'memory/evil.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});

package/mcp/tools/memory/archive-reader.ts

@@ -0,0 +1,253 @@
+/**
+ * Read-only reader for the per-agent knowledge archive (planning-64 K1).
+ *
+ * The archive `kb.sqlite` is BUILT by src/ under Node via `node:sqlite`
+ * (src/agent/knowledge). These MCP tools run under **Bun**, which has no
+ * `node:sqlite`, so the read path here uses **`bun:sqlite`** instead. Same
+ * on-disk SQLite/FTS5 file — verified that node:sqlite writes and bun:sqlite
+ * reads it back via `bm25()`. This is a deliberate, read-only mirror of the
+ * query half of `src/agent/knowledge/archive-db.ts`; keep the two in sync.
+ */
+
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as path from 'path';
+import { recordRetrievalHits } from './retrieval-recorder';
+
+export interface SearchHit {
+  path: string;
+  startLine: number;
+  endLine: number;
+  score: number; // bm25 (lower = more relevant); surfaced for transparency
+  snippet: string;
+  originClass: string | null;
+  importance: number | null;
+  /** Stable archive-entry identity (planning-66); null outside any entry block. */
+  entryHash: string | null;
+}
+
+/** Archive DB path for an agent: sibling of history.db at agents/<id>/kb.sqlite. */
+export function archiveDbPath(workspaceDir: string): string {
+  return path.join(path.dirname(workspaceDir), 'kb.sqlite');
+}
+
+/**
+ * Shared, cross-agent vault DB path from the gateway-provided env
+ * (`GATEWAY_SHARED_KB_DIR` = the resolved <root>/<project> dir), or null when
+ * shared KB is disabled / not configured (planning-64 K3).
+ */
+export function sharedDbPathFromEnv(): string | null {
+  const dir = process.env.GATEWAY_SHARED_KB_DIR;
+  if (!dir || !dir.trim()) return null;
+  return path.join(dir, 'kb.sqlite');
+}
+
+/**
+ * Merge hit lists (per-agent + shared), keeping the best `limit`. bm25 scores are
+ * corpus-relative — the value depends on each index's term/document statistics —
+ * so scores from two independent FTS indexes are NOT on a comparable scale and a
+ * global sort can spuriously rank one corpus over the other. Each list is already
+ * sorted best-first within its own corpus, so interleave them round-robin for a
+ * fair blend instead of a cross-corpus numeric sort.
+ */
+export function mergeHits<T extends SearchHit>(a: T[], b: T[], limit: number): T[] {
+  const out: T[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max && out.length < limit; i++) {
+    if (i < a.length) out.push(a[i]);
+    if (out.length < limit && i < b.length) out.push(b[i]);
+  }
+  return out;
+}
+
+/** Build an FTS5 MATCH string: quote each token so punctuation can't inject syntax. */
+function toFtsMatch(query: string): string {
+  return query
+    .split(/[^\p{L}\p{N}_]+/u)
+    .filter(Boolean)
+    .map((t) => `"${t.replace(/"/g, '""')}"`)
+    .join(' ');
+}
+
+/**
+ * Keyword search over the archive (FTS5 BM25). Returns [] when the index does
+ * not exist yet or the query has no usable tokens. Read-only; never creates a DB.
+ *
+ * When `recordRetrievals` is set (planning-66), each returned entry's stable
+ * `entry_hash` is appended to `kb_retrieval_log` through a SEPARATE, dedicated
+ * writable handle AFTER the results are built — append-only and fire-and-forget,
+ * so the read path never read-modify-writes chunk rows and never blocks/locks the
+ * search response. The Node side folds this log into per-entry recency at GC time.
+ */
+/** True when kb_chunks carries the planning-66 `entry_hash` column. */
+function hasEntryHashColumn(db: Database): boolean {
+  const cols = db.query(`PRAGMA table_info(kb_chunks)`).all() as Array<{ name: string }>;
+  return cols.some((c) => c.name === 'entry_hash');
+}
+
+/**
+ * Idempotent, best-effort heal for a pre-#346 archive DB. The `entry_hash`
+ * column is only added by the writer (`ArchiveDb` constructor migration); a
+ * `kb.sqlite` that has not been reindexed since #346 still lacks it, so the
+ * read-only search query below crashes with `no such column: entry_hash`. Add
+ * the column in place via a short writable handle (mirroring the recall-logging
+ * handle further down). A read-only filesystem simply skips — the column-aware
+ * query then falls back to a NULL `entryHash` so search still returns hits.
+ */
+function ensureEntryHashColumn(dbPath: string): void {
+  try {
+    const w = new Database(dbPath);
+    try {
+      w.exec('PRAGMA busy_timeout=2000');
+      if (!hasEntryHashColumn(w)) {
+        w.exec(`ALTER TABLE kb_chunks ADD COLUMN entry_hash TEXT`);
+        w.exec(`CREATE INDEX IF NOT EXISTS idx_kb_chunks_entry_hash ON kb_chunks(entry_hash)`);
+      }
+    } finally {
+      w.close();
+    }
+  } catch {
+    /* read-only / locked DB — the column-aware query below degrades gracefully */
+  }
+}
+
+export function searchArchive(
+  dbPath: string,
+  query: string,
+  maxResults: number,
+  opts?: { recordRetrievals?: boolean; now?: number },
+): SearchHit[] {
+  if (!fs.existsSync(dbPath)) return [];
+  const match = toFtsMatch(query);
+  if (!match) return [];
+
+  // Heal pre-#346 DBs in place so the query never crashes on a missing column.
+  ensureEntryHashColumn(dbPath);
+
+  const db = new Database(dbPath, { readonly: true });
+  // If the heal above could not run (read-only FS), select a NULL entry_hash
+  // rather than referencing a column that does not exist.
+  const entryHashSelect = hasEntryHashColumn(db) ? 'c.entry_hash' : 'NULL';
+  let hits: SearchHit[];
+  try {
+    const rows = db
+      .query(
+        `SELECT c.id AS id, c.path AS path, c.start_line AS startLine, c.end_line AS endLine,
+                c.text AS text, ${entryHashSelect} AS entryHash, bm25(kb_chunks_fts) AS score,
+                p.origin_class AS originClass, r.importance AS importance
+         FROM kb_chunks_fts f
+         JOIN kb_chunks c ON c.rowid_id = f.rowid
+         LEFT JOIN kb_chunk_provenance p ON p.chunk_id = c.id
+         LEFT JOIN kb_chunk_recall r ON r.chunk_id = c.id
+         WHERE kb_chunks_fts MATCH ?
+         ORDER BY bm25(kb_chunks_fts)
+         LIMIT ?`,
+      )
+      .all(match, maxResults) as Array<{
+      path: string;
+      startLine: number;
+      endLine: number;
+      text: string;
+      entryHash: string | null;
+      score: number;
+      originClass: string | null;
+      importance: number | null;
+    }>;
+    hits = rows.map((r) => ({
+      path: r.path,
+      startLine: r.startLine,
+      endLine: r.endLine,
+      score: r.score,
+      snippet: r.text.length > 500 ? `${r.text.slice(0, 500)}…` : r.text,
+      originClass: r.originClass,
+      importance: r.importance,
+      entryHash: r.entryHash,
+    }));
+  } finally {
+    db.close();
+  }
+
+  // Recall counter (planning-66): fire-and-forget, append-only, best-effort. A
+  // dedicated writable handle (WAL + busy_timeout so it never fails a concurrent
+  // reindex) logs the retrieved entries AFTER the read handle is closed. Any error
+  // is swallowed inside recordRetrievalHits — telemetry never fails a search.
+  if (opts?.recordRetrievals && hits.length > 0) {
+    try {
+      const w = new Database(dbPath);
+      try {
+        w.exec('PRAGMA busy_timeout=2000');
+        recordRetrievalHits(
+          { run: (sql, params = []) => void w.query(sql).run(...(params as never[])) },
+          hits.map((h) => h.entryHash),
+          opts.now ?? Date.now(),
+        );
+      } finally {
+        w.close();
+      }
+    } catch {
+      /* best-effort telemetry — never affect the search response */
+    }
+  }
+  return hits;
+}
+
+/** A memory-scoped path: MEMORY.md, USER.md, or memory/**.md — no traversal. */
+export function isMemoryScopedPath(relPath: string): boolean {
+  const p = relPath.replace(/\\/g, '/');
+  if (p.includes('..') || path.isAbsolute(p)) return false;
+  if (p === 'MEMORY.md' || p === 'USER.md') return true;
+  return p.startsWith('memory/') && p.endsWith('.md');
+}
+
+export interface Excerpt {
+  path: string;
+  from: number;
+  to: number;
+  text: string;
+  totalLines: number;
+  truncated: boolean;
+}
+
+/**
+ * Bounded exact excerpt of a memory file by line range (1-indexed). Reads the
+ * file directly (it is the source of truth). Returns null for an out-of-scope
+ * path or a missing file.
+ */
+export function getExcerpt(
+  workspaceDir: string,
+  relPath: string,
+  from = 1,
+  lines = 200,
+): Excerpt | null {
+  // Validate and read the SAME normalized path so the check can't diverge from
+  // what is actually opened.
+  const rel = relPath.replace(/\\/g, '/');
+  if (!isMemoryScopedPath(rel)) return null;
+  const abs = path.join(workspaceDir, rel);
+  if (!fs.existsSync(abs)) return null;
+  // Containment against symlink escape: a memory/x.md symlink pointing outside
+  // the workspace passes the string check but must not be readable through the
+  // tool. Resolve real paths and require the target stays under the workspace.
+  try {
+    const realBase = fs.realpathSync(workspaceDir);
+    const realTarget = fs.realpathSync(abs);
+    if (realTarget !== realBase && !realTarget.startsWith(realBase + path.sep)) return null;
+  } catch {
+    return null; // realpath failed (broken symlink, race) → refuse
+  }
+
+  const all = fs.readFileSync(abs, 'utf8').split('\n');
+  const total = all.length;
+  const start = Math.max(1, Math.floor(from));
+  const count = Math.max(1, Math.floor(lines));
+  const end = Math.min(total, start + count - 1);
+  const slice = start > total ? [] : all.slice(start - 1, end);
+  return {
+    path: relPath,
+    from: start,
+    to: start > total ? start : end,
+    text: slice.join('\n'),
+    totalLines: total,
+    truncated: end < total,
+  };
+}