@0xmaxma/claude-gateway 1.6.9 → 1.7.0

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/package.json

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