@0xmaxma/claude-gateway 1.6.9 → 1.7.1

package/mcp/tools/memory/module.ts

@@ -0,0 +1,152 @@
+/**
+ * Memory tool module (planning-64 K1) — implements ToolModule.
+ *
+ * Read-only, on-demand retrieval over the per-agent knowledge archive
+ * (`kb.sqlite`, built by src/ under Node). Two lanes of memory: the small core
+ * (MEMORY.md/USER.md) is injected every turn; everything else lives in the
+ * searchable archive and is reached here via `memory_search` / `memory_get` —
+ * so the bulk never has to sit in the prompt. Runs under Bun; reads via
+ * `bun:sqlite` (see archive-reader.ts).
+ */
+
+import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
+import { searchArchive, getExcerpt, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+
+/** Corpora the tool can serve. */
+const SUPPORTED_CORPORA = new Set(['memory', 'shared', 'all']);
+
+export class MemoryModule implements ToolModule {
+  id = 'memory';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    // Available whenever the agent's workspace dir is known (same gate as skills).
+    return Boolean(process.env.GATEWAY_WORKSPACE_DIR);
+  }
+
+  getTools(): McpToolDefinition[] {
+    return [
+      {
+        name: 'memory_search',
+        description:
+          'Search your long-term memory archive (past notes under memory/, plus MEMORY.md/USER.md) by keyword and get the most relevant snippets with their file + line range. Use this to recall details that are NOT in the memory currently loaded into your context — the archive holds far more than fits in the prompt. Read-only.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Keywords to search for.' },
+            maxResults: {
+              type: 'number',
+              description: 'Max snippets to return (default 6, max 20).',
+            },
+            corpus: {
+              type: 'string',
+              enum: ['memory', 'shared', 'all'],
+              description:
+                'Which corpus to search: "memory" (this agent, default), "shared" (the cross-agent shared KB), or "all" (both).',
+            },
+          },
+          required: ['query'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'memory_get',
+        description:
+          'Read an exact line range from one of your memory files (a path returned by memory_search, e.g. "memory/foo.md", or "MEMORY.md"/"USER.md"). Use after memory_search to pull the full context around a snippet. Read-only.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Memory-scoped path (memory/*.md, MEMORY.md, USER.md).' },
+            from: { type: 'number', description: '1-indexed start line (default 1).' },
+            lines: { type: 'number', description: 'Number of lines to return (default 200).' },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+    ];
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const workspaceDir = process.env.GATEWAY_WORKSPACE_DIR;
+    if (!workspaceDir) {
+      return this.err('Memory archive unavailable: no workspace directory configured.');
+    }
+
+    try {
+      switch (name) {
+        case 'memory_search': {
+          const query = typeof args.query === 'string' ? args.query.trim() : '';
+          if (!query) return this.err('memory_search requires a non-empty "query".');
+
+          // Fail closed on an unsupported corpus rather than silently widening scope.
+          const corpus = typeof args.corpus === 'string' ? args.corpus : 'memory';
+          if (!SUPPORTED_CORPORA.has(corpus)) {
+            return this.json({
+              results: [],
+              unavailable: true,
+              warning: `corpus "${corpus}" is not available yet (shared/all arrive in a later phase). Use "memory".`,
+            });
+          }
+
+          const rawMax = Number.isFinite(args.maxResults as number) ? (args.maxResults as number) : 6;
+          const maxResults = Math.max(1, Math.min(20, Math.floor(rawMax)));
+
+          const personalDb = archiveDbPath(workspaceDir);
+          const sharedDb = sharedDbPathFromEnv();
+          // Recall counter (planning-66): record retrievals ONLY against the
+          // per-agent archive (the GC tier). Gated by the gateway via env, mirroring
+          // GATEWAY_SHARED_KB_DIR — off unless dreaming.staleness.recordRetrievals.
+          const rec = { recordRetrievals: process.env.GATEWAY_RECORD_RETRIEVALS === '1' };
+          let results;
+          if (corpus === 'memory') {
+            results = searchArchive(personalDb, query, maxResults, rec).map((h) => ({ ...h, corpus: 'memory' }));
+          } else if (corpus === 'shared') {
+            if (!sharedDb) return this.json({ results: [], unavailable: true, warning: 'shared KB is not enabled.' });
+            results = searchArchive(sharedDb, query, maxResults).map((h) => ({ ...h, corpus: 'shared' }));
+          } else {
+            // "all": merge personal + shared, keep the best by bm25.
+            type Tagged = ReturnType<typeof searchArchive>[number] & { corpus: string };
+            const mine: Tagged[] = searchArchive(personalDb, query, maxResults, rec).map((h) => ({ ...h, corpus: 'memory' }));
+            const shared: Tagged[] = sharedDb
+              ? searchArchive(sharedDb, query, maxResults).map((h) => ({ ...h, corpus: 'shared' }))
+              : [];
+            results = mergeHits(mine, shared, maxResults);
+          }
+
+          if (results.length === 0) {
+            return this.json({
+              results: [],
+              note: 'No matches (or the archive has not been indexed yet).',
+            });
+          }
+          return this.json({ results, corpus });
+        }
+
+        case 'memory_get': {
+          const p = typeof args.path === 'string' ? args.path : '';
+          const from = Number.isFinite(args.from as number) ? (args.from as number) : 1;
+          const lines = Number.isFinite(args.lines as number) ? (args.lines as number) : 200;
+          const excerpt = getExcerpt(workspaceDir, p, from, lines);
+          if (!excerpt) {
+            return this.err(`memory_get: "${p}" is not a readable memory-scoped file (memory/*.md, MEMORY.md, USER.md).`);
+          }
+          return this.json(excerpt);
+        }
+
+        default:
+          return this.err(`Unknown memory tool: ${name}`);
+      }
+    } catch (e) {
+      return this.err(`memory tool error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  private json(obj: unknown): McpToolResult {
+    return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+  }
+
+  private err(text: string): McpToolResult {
+    return { content: [{ type: 'text', text }], isError: true };
+  }
+}

package/mcp/tools/memory/retrieval-recorder.ts

@@ -0,0 +1,66 @@
+/**
+ * Runtime-agnostic append-only retrieval recorder (planning-66).
+ *
+ * The read path (`archive-reader.ts`) runs under Bun (`bun:sqlite`); the tests and
+ * the src/ aggregator run under Node (`node:sqlite`). Both need to write the SAME
+ * append-only `kb_retrieval_log` table, so the actual SQL lives here behind a tiny
+ * `SqlRunner` seam that each runtime adapts to its own driver. This file imports
+ * NO sqlite driver, so it is safe to import from a Node/jest test (importing
+ * `archive-reader.ts` directly is not — it top-level-imports `bun:sqlite`).
+ *
+ * The recall counter is deliberately APPEND-ONLY and fire-and-forget: the Bun read
+ * path must never read-modify-write chunk rows (that would break the "mcp reads
+ * only / src writes" invariant and risk locking the hot search path). It only ever
+ * INSERTs into a dedicated log table; the Node side aggregates that log into
+ * `kb_entry_lifecycle.last_retrieved`/`retrieval_count` at GC time.
+ */
+
+/** Minimal write surface both `bun:sqlite` and `node:sqlite` can satisfy. */
+export interface SqlRunner {
+  run(sql: string, params?: unknown[]): void;
+}
+
+/** DDL for the append-only retrieval log. Idempotent; safe to call every write. */
+export const RETRIEVAL_LOG_DDL =
+  'CREATE TABLE IF NOT EXISTS kb_retrieval_log (' +
+  'rowid_id INTEGER PRIMARY KEY AUTOINCREMENT, entry_hash TEXT NOT NULL, retrieved_at INTEGER NOT NULL)';
+
+/** Ensure the log table exists (the Bun side may run before any Node index pass). */
+export function ensureRetrievalLog(db: SqlRunner): void {
+  db.run(RETRIEVAL_LOG_DDL);
+}
+
+/**
+ * Append one retrieval event, keyed by the STABLE `entry_hash` (never the line-
+ * based chunk id). Best-effort: a null/empty hash is ignored (a chunk outside any
+ * entry block carries no lifecycle identity). Callers wrap this in try/catch and
+ * never block their response on it.
+ */
+export function appendRetrieval(db: SqlRunner, entryHash: string | null | undefined, retrievedAt: number): void {
+  if (!entryHash) return;
+  ensureRetrievalLog(db);
+  db.run('INSERT INTO kb_retrieval_log (entry_hash, retrieved_at) VALUES (?, ?)', [entryHash, retrievedAt]);
+}
+
+/**
+ * Record a batch of retrieval hits (the entry_hashes of one search's results),
+ * de-duplicated so a single search that returns two chunks of the same entry
+ * counts once. Fire-and-forget; never throws out (errors are swallowed so a
+ * telemetry write can never fail a search response).
+ */
+export function recordRetrievalHits(
+  db: SqlRunner,
+  entryHashes: Array<string | null | undefined>,
+  retrievedAt: number,
+): void {
+  try {
+    const seen = new Set<string>();
+    for (const h of entryHashes) {
+      if (!h || seen.has(h)) continue;
+      seen.add(h);
+      appendRetrieval(db, h, retrievedAt);
+    }
+  } catch {
+    /* best-effort telemetry — never affect the search response */
+  }
+}

package/mcp/tools/skills/module.ts

@@ -108,6 +108,15 @@ export class SkillsModule implements ToolModule {
           additionalProperties: false,
         },
       },
+      {
+        name: 'skill_metrics',
+        description: 'Read the skill self-improvement effectiveness rollup for this agent: adoption funnel (auto-skill stickiness), cost-to-complete deltas, recovery-rate trend, enabled/disabled cohort, and the net-token ledger (tokens saved by reuse minus tokens spent reviewing). Read-only.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          additionalProperties: false,
+        },
+      },
     ];
   }
 
@@ -152,6 +161,25 @@ export class SkillsModule implements ToolModule {
           const result = await installSkill(params);
           return { content: [{ type: 'text', text: result }] };
         }
+        case 'skill_metrics': {
+          const apiUrl = (process.env.GATEWAY_API_URL || '').replace(/\/+$/, '');
+          const apiKey = process.env.GATEWAY_API_KEY;
+          const agentId = process.env.GATEWAY_AGENT_ID;
+          if (!apiUrl || !apiKey || !agentId) {
+            return {
+              content: [{ type: 'text', text: 'skill_metrics unavailable: gateway API env not configured' }],
+              isError: true,
+            };
+          }
+          const res = await fetch(`${apiUrl}/api/v1/agents/${encodeURIComponent(agentId)}/skill-metrics`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+          });
+          const body = await res.text();
+          if (!res.ok) {
+            return { content: [{ type: 'text', text: `skill_metrics failed (${res.status}): ${body}` }], isError: true };
+          }
+          return { content: [{ type: 'text', text: body }] };
+        }
         default:
           return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
       }

package/mcp/types.ts

@@ -77,8 +77,13 @@ export interface ChannelModule {
   /** MCP tools exposed by this module */
   getTools(): McpToolDefinition[];
 
-  /** Execute a tool call */
-  handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+  /**
+   * Execute a tool call. `signal` fires when the MCP client cancels this specific
+   * call (e.g. the CLI sends notifications/cancelled after a user Stop/Ctrl-C
+   * interrupts an in-flight tool call) — optional so existing modules that don't
+   * need it are unaffected.
+   */
+  handleTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<McpToolResult>;
 
   /** Initialize bot client for tool calls (non-blocking) */
   initBot?(): Promise<void>;
@@ -99,7 +104,8 @@ export interface ToolModule {
   toolVisibility: ToolVisibility;
   isEnabled(): boolean;
   getTools(): McpToolDefinition[];
-  handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult>;
+  /** See ChannelModule.handleTool's `signal` doc — same optional-cancellation contract. */
+  handleTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<McpToolResult>;
   skillsDir?: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.6.9",
+  "version": "1.7.1",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",