@chatpanel/gateway 0.6.40 → 0.6.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/connect-agents.js

@@ -20,7 +20,7 @@ import os from 'node:os';
 
 // The six read-only tools the ChatPanel MCP server exposes (history + skills). Named here so
 // the Codex approval blocks stay in step with what the server actually advertises.
-const TOOLS = ['search_history', 'get_record', 'list_history', 'list_skills', 'open_skill', 'read_skill_file'];
+const TOOLS = ['search_history', 'get_record', 'find_related', 'list_history', 'list_skills', 'open_skill', 'read_skill_file'];
 
 // Resolve the command a config should launch. A bare name works when the client inherits a
 // normal PATH; an absolute path is the safe fallback when it does not.

package/src/history-store.js

@@ -187,8 +187,32 @@ export class HistoryStore {
     return n;
   }
 
-  search(query, opts) {
-    return this.index.search(query, opts);
+  // Mirror the SQLite engine's richer contract so both backends behave the same: type/date
+  // filters, offset paging, and a matching snippet (over-fetch from the ranker, then filter
+  // and page, since SearchIndex has no WHERE clause).
+  search(query, { limit = 10, offset = 0, type = null, since = null, before = null } = {}) {
+    const raw = this.index.search(query, { limit: (limit + offset) * 3 + 20 });
+    const out = [];
+    for (const r of raw) {
+      const rec = this.records.get(r.id);
+      if (!rec) continue;
+      if (type && rec.type !== type) continue;
+      if (since != null && (rec.date || 0) < since) continue;
+      if (before != null && (rec.date || 0) > before) continue;
+      out.push({ id: r.id, score: r.score, title: rec.title, type: rec.type, date: rec.date, snippet: snippetOf(rec.text, query) });
+    }
+    return out.slice(offset, offset + limit);
+  }
+
+  // Graph navigation — records most connected to this one, by shared content.
+  related(id, { limit = 5 } = {}) {
+    const rec = this.records.get(id);
+    if (!rec) return [];
+    const raw = this.index.search(`${rec.title || ''} ${String(rec.text || '').slice(0, 2000)}`, { limit: limit + 5 });
+    return raw.filter((r) => r.id !== id).slice(0, limit).map((r) => {
+      const m = this.records.get(r.id) || {};
+      return { id: r.id, score: r.score, title: m.title, type: m.type, date: m.date };
+    });
   }
 
   // Metadata list for an external UI, newest first, paginated. No bodies.
@@ -199,7 +223,28 @@ export class HistoryStore {
     return { total: all.length, items: all.slice(offset, offset + limit) };
   }
 
-  get(id) {
-    return this.records.get(id) || null;
+  // Paged fetch for token management (maxChars/offset), matching SqliteHistoryStore.get.
+  get(id, { maxChars = null, offset = 0 } = {}) {
+    const rec = this.records.get(id);
+    if (!rec) return null;
+    const full = String(rec.text || '');
+    let text = offset ? full.slice(offset) : full;
+    let truncated = false;
+    if (maxChars && text.length > maxChars) { text = text.slice(0, maxChars); truncated = true; }
+    return { ...rec, text, totalChars: full.length, offset: Number(offset) || 0, truncated };
   }
 }
+
+// A short excerpt of `text` around the first query-term hit — the token-friendly preview a
+// search returns instead of the whole body. Falls back to the head when no term matches.
+function snippetOf(text, query, radius = 90) {
+  const s = String(text || '');
+  if (!s) return '';
+  const terms = String(query || '').toLowerCase().match(/[a-z0-9][a-z0-9'_+-]*/g) || [];
+  const lower = s.toLowerCase();
+  let idx = -1;
+  for (const t of terms) { const i = lower.indexOf(t); if (i >= 0 && (idx < 0 || i < idx)) idx = i; }
+  if (idx < 0) return s.slice(0, radius * 2).replace(/\s+/g, ' ').trim();
+  const start = Math.max(0, idx - radius);
+  return `${start > 0 ? '… ' : ''}${s.slice(start, idx + radius).replace(/\s+/g, ' ').trim()}${idx + radius < s.length ? ' …' : ''}`;
+}

package/src/mcp.js

@@ -21,6 +21,29 @@ import { ensureGatewayToken } from './gateway-token.js';
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER = { name: 'chatpanel-history', version: '1.0.0' };
 
+// MCP servers may return `instructions` from initialize; hosts (Codex, Claude Code, …) fold
+// them into the model's context. This is where we STEER tool selection so a person doesn't
+// have to say "use ChatPanel": it tells the model that the user's personal meetings/notes/
+// chats live here and must be reached through these tools, not by grepping the working dir.
+const INSTRUCTIONS = [
+  'ChatPanel holds the USER\'S OWN meetings, notes and past chats — transcripts, decisions,',
+  'action items, summaries — which usually are NOT in the working directory.',
+  '',
+  'Keep using all your normal tools. ADDITIONALLY, whenever the user\'s question touches a',
+  'meeting, call, demo, note, or past conversation ("outcome of the meeting", "what did we',
+  'decide", "action items", "notes from yesterday", a person/day/topic in their history),',
+  'ALSO consult ChatPanel — it is the source of truth for that personal history:',
+  '  • search_history — search by CONTENT (not the generic meeting title). Supports filters:',
+  '    type (chat|meeting|note), since/before (dates or relative like "7d", "yesterday"),',
+  '    and limit/offset paging. Returns compact snippets, not full bodies.',
+  '  • get_record — the full text of one result id; use maxChars/offset to page a long',
+  '    transcript instead of pulling it all into context.',
+  '  • find_related — follow the graph: given a record id, the records most connected to it.',
+  'Prefer these for the user\'s history and combine them with your other tools as you see fit.',
+  'Every result states how fresh the local copy is; if something recent is missing it may not',
+  'have synced yet — say so rather than concluding it does not exist.',
+].join('\n');
+
 // The calling agent's self-reported name (from MCP `initialize` clientInfo), so the
 // observability dashboard can say WHICH agent read what. Untrusted; the gateway coerces it.
 let clientName = 'unknown';
@@ -82,22 +105,42 @@ async function bridgeJson(path) {
 const TOOLS = [
   {
     name: 'search_history',
-    description: 'Full-text search the user\'s ChatPanel history — past chats, meeting transcripts, and notes — by keyword relevance. This is a LOCAL WARM COPY that syncs from ChatPanel; very recent items (a meeting from the last few hours) may not be here yet — every result reports how current the index is. If the user is sure something exists and it is not found, it likely has not synced; say so rather than concluding it does not exist. Meeting titles are often generic ("Zoom Meeting"), so search by CONTENT (topics, names, decisions), not the meeting title.',
+    description: 'Search the user\'s ChatPanel history — their past chats, meeting/call transcripts, and notes — by keyword relevance. Consult this (in ADDITION to your other tools) whenever the question touches a meeting, call, demo, note, or past conversation: "outcome of the meeting", "what did we decide", "action items", "what did <person> say", "notes from yesterday". Filters: `type` (chat|meeting|note), `since`/`before` (a date like 2026-08-01 or a relative window like "7d"/"yesterday"), and `limit`/`offset` for paging. Returns compact SNIPPETS (the matching excerpt) with each record\'s id/title/type/date — token-friendly; call get_record for the full text and find_related to follow connections. This is a LOCAL WARM COPY that syncs from ChatPanel; very recent items may not be here yet — results report how current the index is, so if something is missing it likely has not synced. Meeting titles are often generic ("Zoom Meeting"), so search by CONTENT, not the title.',
     inputSchema: {
       type: 'object',
       properties: {
-        query: { type: 'string', description: 'Natural-language / keyword query.' },
+        query: { type: 'string', description: 'Content keywords (topics, names, decisions) — not the meeting title.' },
+        type: { type: 'string', enum: ['chat', 'meeting', 'note'], description: 'Only this kind of record.' },
+        since: { type: 'string', description: 'Earliest date: 2026-08-01, or a relative window like "7d", "2 weeks", "yesterday".' },
+        before: { type: 'string', description: 'Latest date: a date or relative window like `since`.' },
         limit: { type: 'number', description: 'Max results (default 10).' },
+        offset: { type: 'number', description: 'Skip N results for paging (default 0).' },
       },
       required: ['query'],
     },
   },
   {
     name: 'get_record',
-    description: 'Fetch one full history record (its complete text) by id, e.g. chat:<id>, meeting:<id>, or note:<id> returned by search_history.',
+    description: 'Fetch one history record\'s full text by id (chat:<id>, meeting:<id>, note:<id> from search_history). For a long transcript, page it with maxChars + offset instead of pulling it all into context — the result says how many chars remain.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Record id such as chat:abc, meeting:imp_123, or note:xyz.' },
+        maxChars: { type: 'number', description: 'Return at most this many characters (token management for long transcripts).' },
+        offset: { type: 'number', description: 'Start at this character offset — page through with the offset the previous call reports.' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'find_related',
+    description: 'Graph navigation: given a record id (from search_history), return the records most connected to it by shared content — the meetings/notes/chats about the same topic, people or thread. Use it to expand from one hit to the surrounding context instead of re-searching.',
     inputSchema: {
       type: 'object',
-      properties: { id: { type: 'string', description: 'Record id such as chat:abc, meeting:imp_123, or note:xyz.' } },
+      properties: {
+        id: { type: 'string', description: 'The record id to find neighbours of.' },
+        limit: { type: 'number', description: 'Max related records (default 5).' },
+      },
       required: ['id'],
     },
   },
@@ -164,22 +207,62 @@ async function gatewayJson(path, init) {
 }
 
 // Run a tool → a plain-text result an agent can read.
+// Parse a since/before value into epoch ms: an ISO-ish date (2026-08-01) or a relative window
+// meaning "within the last N" — "7d", "2 weeks", "3 months", "yesterday", "today".
+function parseWhen(v) {
+  if (v == null || v === '') return null;
+  if (typeof v === 'number') return v;
+  const s = String(v).trim().toLowerCase();
+  const DAY = 86_400_000;
+  if (s === 'today') return Date.now() - DAY;
+  if (s === 'yesterday') return Date.now() - 2 * DAY;
+  const rel = /^(\d+)\s*(d|day|days|w|week|weeks|m|month|months|y|year|years)$/.exec(s);
+  if (rel) {
+    const n = Number(rel[1]);
+    const u = rel[2][0];
+    const mult = u === 'd' ? DAY : u === 'w' ? 7 * DAY : u === 'm' ? 30 * DAY : 365 * DAY;
+    return Date.now() - n * mult;
+  }
+  const t = Date.parse(s);
+  return Number.isNaN(t) ? null : t;
+}
+
+const fmtRow = (r, i) => `${i + 1}. [${r.id}] ${r.title || '(untitled)'} · ${r.type}${r.date ? ' · ' + new Date(r.date).toISOString().slice(0, 10) : ''}${r.snippet ? `\n     ${r.snippet}` : ''}`;
+
 async function callTool(name, args = {}) {
   if (name === 'search_history') {
+    const body = { query: String(args.query || ''), limit: Number(args.limit) || 10, offset: Math.max(0, Number(args.offset) || 0) };
+    if (args.type) body.type = String(args.type);
+    const since = parseWhen(args.since); if (since != null) body.since = since;
+    const before = parseWhen(args.before); if (before != null) body.before = before;
     const data = await gatewayJson('/v1/history/search', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ query: String(args.query || ''), limit: Number(args.limit) || 10 }),
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
     });
     const rows = data.results || [];
     const horizon = horizonLine(data.newest, data.size);
-    if (!rows.length) return `No match for "${args.query}".\n${horizon}\nIf you expected a recent item, it may not have synced yet — check ChatPanel directly, or try broader content keywords (titles are often generic).`;
-    return [horizon, '', `${rows.length} result(s) for "${args.query}":`, ...rows.map((r, i) => `${i + 1}. [${r.id}] ${r.title || '(untitled)'} · ${r.type}${r.date ? ' · ' + new Date(r.date).toISOString().slice(0, 10) : ''} · score ${r.score?.toFixed?.(3) ?? r.score}`)].join('\n') + '\n\nUse get_record with an id for the full text.';
+    const filt = [args.type && `type=${args.type}`, args.since && `since=${args.since}`, args.before && `before=${args.before}`].filter(Boolean).join(', ');
+    const tag = filt ? ` (${filt})` : '';
+    if (!rows.length) return `No match for "${args.query}"${tag}.\n${horizon}\nIf you expected a recent item, it may not have synced yet — check ChatPanel directly, or broaden the query (titles are often generic; try content keywords, or drop a filter).`;
+    return [horizon, '', `${rows.length} result(s) for "${args.query}"${tag}:`, ...rows.map(fmtRow)].join('\n')
+      + '\n\nget_record <id> for full text (maxChars/offset to page) · find_related <id> to follow connections.';
   }
   if (name === 'get_record') {
-    const data = await gatewayJson(`/v1/history/get?id=${encodeURIComponent(String(args.id || ''))}`);
+    const q = new URLSearchParams({ id: String(args.id || '') });
+    if (args.maxChars != null) q.set('maxChars', String(Math.max(1, Number(args.maxChars) || 0)));
+    if (args.offset != null) q.set('offset', String(Math.max(0, Number(args.offset) || 0)));
+    const data = await gatewayJson(`/v1/history/get?${q}`);
     const r = data.record;
-    return `[${r.id}] ${r.title || '(untitled)'} · ${r.type}${r.date ? ' · ' + new Date(r.date).toISOString().slice(0, 10) : ''}\n\n${r.text || '(empty)'}`;
+    const head = `[${r.id}] ${r.title || '(untitled)'} · ${r.type}${r.date ? ' · ' + new Date(r.date).toISOString().slice(0, 10) : ''}`;
+    const more = r.truncated
+      ? `\n\n[showing ${r.text.length} of ${r.totalChars} chars (from offset ${r.offset}). For the next part call get_record again with offset=${r.offset + r.text.length}.]`
+      : '';
+    return `${head}\n\n${r.text || '(empty)'}${more}`;
+  }
+  if (name === 'find_related') {
+    const data = await gatewayJson(`/v1/history/related?id=${encodeURIComponent(String(args.id || ''))}&limit=${Number(args.limit) || 5}`);
+    const rows = data.results || [];
+    if (!rows.length) return `Nothing related to ${args.id} found (or that id isn't in the warm index — run search_history first to get a valid id).`;
+    return [`Records related to ${args.id}:`, ...rows.map(fmtRow)].join('\n') + '\n\nget_record <id> for full text.';
   }
   if (name === 'list_history') {
     const q = new URLSearchParams({ limit: String(Number(args.limit) || 50), offset: String(Number(args.offset) || 0) });
@@ -223,7 +306,7 @@ export async function handleRpc(msg) {
     switch (method) {
       case 'initialize':
         clientName = params?.clientInfo?.name || clientName;
-        return ok({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER });
+        return ok({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER, instructions: INSTRUCTIONS });
       case 'tools/list':
         return ok({ tools: TOOLS });
       case 'tools/call': {

package/src/observability.js

@@ -2,7 +2,6 @@
 // The gateway keeps its dependency surface small; this one pure module is copied in
 // rather than pulling the whole events package, the same way the bridge vendors its
 // events files. Source of truth: chatpanel-events/observability.js.
-//
 // observability.js — the contract for "who consumed what, when, and how much is stored".
 //
 // ChatPanel's data is reachable by more than one agent now: the side panel, and any CLI
@@ -30,10 +29,13 @@ export const ACCESS_LOG_MAX = 500;
 // listed here is dropped. Content-bearing fields (a search `query`) are deliberately ABSENT —
 // the tool name already says "a search happened"; the words searched are not logged.
 const SAFE_ARGS = {
-  search_history: ['limit'],
+  // Metadata filters are safe to keep (they are not content) and useful to see in the log:
+  // "type=meeting since=7d". The search QUERY is deliberately absent — never recorded.
+  search_history: ['type', 'since', 'before', 'limit', 'offset'],
   list_history: ['limit', 'offset'],
-  get_record: ['id'],            // opaque record id, not content
-  open_skill: ['skill'],         // skill names are catalog identifiers, not PII
+  get_record: ['id', 'maxChars', 'offset'], // opaque record id + paging, not content
+  find_related: ['id', 'limit'],            // graph navigation from an opaque id
+  open_skill: ['skill'],                    // skill names are catalog identifiers, not PII
   read_skill_file: ['skill', 'path'],
   list_skills: ['limit'],
 };

package/src/server.js

@@ -46,7 +46,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.40';
+export const VERSION = '0.6.42';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -603,12 +603,24 @@ export function createGateway(cfg = loadConfig()) {
     if (pathname === '/v1/history/search' && req.method === 'POST') {
       try {
         const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
-        const results = historyStore.search(String(body.query || ''), { limit: Number(body.limit) || 10 });
+        const results = historyStore.search(String(body.query || ''), {
+          limit: Number(body.limit) || 10,
+          offset: Math.max(0, Number(body.offset) || 0),
+          type: body.type ? String(body.type) : null,
+          since: body.since != null ? Number(body.since) : null,
+          before: body.before != null ? Number(body.before) : null,
+        });
         return sendJson(res, 200, { ok: true, size: historyStore.size, newest: historyStore.newest, results });
       } catch (e) {
         return sendJson(res, 400, { error: { message: `search failed: ${e.message}`, type: 'search_error' } });
       }
     }
+    // Graph navigation — records most connected to a given one.
+    if (pathname === '/v1/history/related' && req.method === 'GET') {
+      const id = String(url.searchParams.get('id') || '');
+      const limit = Math.min(30, Math.max(1, Number(url.searchParams.get('limit')) || 5));
+      return sendJson(res, 200, { ok: true, results: historyStore.related(id, { limit }) });
+    }
     if (pathname === '/v1/history/status' && req.method === 'GET') {
       return sendJson(res, 200, { ok: true, size: historyStore.size, newest: historyStore.newest, bytes: historyStore.bytes });
     }
@@ -639,7 +651,9 @@ export function createGateway(cfg = loadConfig()) {
       return sendJson(res, 200, { ok: true, ...historyStore.list({ limit, offset }) });
     }
     if (pathname === '/v1/history/get' && req.method === 'GET') {
-      const record = historyStore.get(String(url.searchParams.get('id') || ''));
+      const maxChars = url.searchParams.get('maxChars') != null ? Math.max(1, Number(url.searchParams.get('maxChars')) || 0) : null;
+      const offset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
+      const record = historyStore.get(String(url.searchParams.get('id') || ''), { maxChars, offset });
       if (!record) return sendJson(res, 404, { error: { message: 'no such record', type: 'not_found' } });
       return sendJson(res, 200, { ok: true, record });
     }

package/src/sqlite-store.js

@@ -130,13 +130,44 @@ export class SqliteHistoryStore {
     return this.size;
   }
 
-  // [{ id, score, title, type, date }] — score higher = better (bm25 is negated).
-  search(query, { limit = 10 } = {}) {
+  // [{ id, score, title, type, date, snippet }] — score higher = better (bm25 is negated).
+  // Filters: type (chat|meeting|note), since/before (epoch ms bounds), offset (paging).
+  // `snippet` returns the matching excerpt from the transcript/body so a caller can rank and
+  // decide what to fetch WITHOUT pulling full bodies — the token-management path.
+  search(query, { limit = 10, offset = 0, type = null, since = null, before = null } = {}) {
     const match = ftsMatch(query);
     if (!match) return [];
+    const where = ['fts MATCH ?'];
+    const params = [match];
+    if (type) { where.push('r.type = ?'); params.push(String(type)); }
+    if (since != null) { where.push('r.date >= ?'); params.push(Number(since)); }
+    if (before != null) { where.push('r.date <= ?'); params.push(Number(before)); }
+    params.push(limit, offset);
     const rows = this.db.all(
-      'SELECT r.id id, r.title title, r.type type, r.date date, bm25(fts) b FROM fts JOIN records r ON r.id = fts.id WHERE fts MATCH ? ORDER BY b LIMIT ?',
-      [match, limit],
+      `SELECT r.id id, r.title title, r.type type, r.date date, bm25(fts) b,
+              snippet(fts, 2, '«', '»', ' … ', 12) snip
+       FROM fts JOIN records r ON r.id = fts.id
+       WHERE ${where.join(' AND ')} ORDER BY b LIMIT ? OFFSET ?`,
+      params,
+    );
+    return rows.map((r) => ({ id: r.id, score: -r.b, title: r.title, type: r.type, date: r.date, snippet: r.snip || '' }));
+  }
+
+  // Graph navigation — records most connected to a given one, by shared content. "More like
+  // this": build a MATCH from the record's title + a sample of its body, rank by bm25, drop
+  // self. Cheap and index-only; no embeddings needed for a first-class "related" primitive.
+  related(id, { limit = 5 } = {}) {
+    const rec = this.get(id);
+    if (!rec) return [];
+    const terms = ftsMatch(`${rec.title || ''} ${String(rec.text || '').slice(0, 2000)}`);
+    if (!terms) return [];
+    // Cap the OR-set so a long transcript doesn't build a giant MATCH.
+    const capped = terms.split(' OR ').slice(0, 40).join(' OR ');
+    const rows = this.db.all(
+      `SELECT r.id id, r.title title, r.type type, r.date date, bm25(fts) b
+       FROM fts JOIN records r ON r.id = fts.id
+       WHERE fts MATCH ? AND r.id != ? ORDER BY b LIMIT ?`,
+      [capped, id, limit],
     );
     return rows.map((r) => ({ id: r.id, score: -r.b, title: r.title, type: r.type, date: r.date }));
   }
@@ -147,11 +178,17 @@ export class SqliteHistoryStore {
     return { total, items };
   }
 
-  get(id) {
+  // Paged fetch for token management: maxChars caps the returned slice, offset pages a long
+  // transcript. Reports totalChars + truncated so a caller knows there is more to fetch.
+  get(id, { maxChars = null, offset = 0 } = {}) {
     const meta = this.db.get('SELECT id, title, type, date FROM records WHERE id = ?', [id]);
     if (!meta) return null;
     const body = this.db.get('SELECT text FROM fts WHERE id = ?', [id]);
-    return { ...meta, text: body?.text || '' };
+    const full = body?.text || '';
+    let text = offset ? full.slice(offset) : full;
+    let truncated = false;
+    if (maxChars && text.length > maxChars) { text = text.slice(0, maxChars); truncated = true; }
+    return { ...meta, text, totalChars: full.length, offset: Number(offset) || 0, truncated };
   }
 
   // Wipe every record — the user purging the on-disk warm copy. Returns how many were dropped.