dsh-memory-recall 0.1.0

package/src/recall-tool.js

@@ -0,0 +1,203 @@
+// The `session_search` tool: reading earlier chats, only with the user's say-so.
+//
+// Before anything is read, dsh's own approval prompt asks the user — attached
+// to this tool call in the chat, with what the model wants to look for. One
+// "allow" covers the rest of that reply (a search is usually followed by a
+// read around the best hit, and asking twice for one question is noise); the
+// grant is dropped the moment the chat goes idle, so the next question asks
+// again. A decline, a withdrawn prompt, or no way to ask at all means nothing
+// is read — the approval seam fails closed and so does this.
+
+import { RecallError } from './recall.js';
+import { TEXT_OUTPUT } from './memory-tool.js';
+
+export const RECALL_TOOL = 'session_search';
+
+export const RECALL_DESCRIPTION = [
+  'Look things up in the user\'s earlier chats. Asks the user for permission first; if they decline, say so and carry on',
+  'without it — do not call it again in the same reply. Results are the chats\' actual messages, not summaries.',
+  '',
+  'Shapes, picked by the arguments:',
+  '- `query`: find the chats that match best (top result comes with the messages around the match).',
+  '- `session_id` + `around_seq`: read the messages around one message of a chat found earlier.',
+  '- `session_id` alone: read how a chat began and ended.',
+  '- no arguments: list the most recent chats.',
+  'Add `workspace` (its title, its folder, or the workspace a user picked with @) to search or list only that',
+  "workspace's chats — a user message carrying [workspace \"Name\" — folder] means exactly that.",
+  '',
+  'The query is matched as an EXACT PHRASE, so use one or two distinctive keywords (a name, a file, an error) rather than',
+  'a sentence; if a multi-word phrase finds too little, each word is also tried on its own.',
+  'Use it when the user refers to an earlier conversation — "what did we decide about…", "like last time", "where did we',
+  'leave…". Searches chat history only: when the user names a file, URL or system, look at that directly.',
+].join('\n');
+
+const OUTCOME_TEXT = {
+  rejected: 'The user declined reading their past chats. Nothing was read. Tell them you cannot look it up without their permission, and do not ask again in this reply.',
+  cancelled: 'The permission request was withdrawn before an answer (the reply was stopped). Nothing was read.',
+  unavailable: 'Nobody could be asked for permission (no approval prompt is available in this dsh), so past chats were not read.',
+};
+
+const day = (ms) => (Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : 'unknown date');
+
+function titleOf(s) {
+  return s.title ? `"${s.title}"` : '(untitled chat)';
+}
+
+function sessionLine(s) {
+  return `${titleOf(s)} — ${day(s.createdAt)}${s.cwd ? ` — ${s.cwd}` : ''} — session_id ${s.sessionId}`;
+}
+
+function messageLines(list, mark) {
+  return list.map((m) => `   [#${m.seq} ${m.role}]${m.seq === mark ? ' ◀' : ''} ${m.text.replace(/\n+/g, ' ')}`);
+}
+
+/** The model-facing text for a recall result, capped at `max` characters. */
+export function formatRecall(result, max = 9000) {
+  const out = [];
+  if (result.mode === 'discover') {
+    const engine = result.engine === 'fts' ? "dsh's full-text index" : 'a literal scan of recent chats (full-text search is off)';
+    if (!result.results.length) {
+      out.push(`No earlier chat${result.workspace ? ` in workspace "${result.workspace}"` : ''} matches "${result.query}" (searched with ${engine}). Try one distinctive keyword, or another word for it.`);
+    } else {
+      out.push(`Found ${result.results.length} earlier chat(s) for "${result.query}"${result.workspace ? ` in workspace "${result.workspace}"` : ''} (searched with ${engine}${result.widened ? '; also word by word' : ''}):`);
+      result.results.forEach((r, i) => {
+        out.push('', `${i + 1}. ${sessionLine(r)}`);
+        if (r.matchedWords) out.push(`   Matched words: ${r.matchedWords.join(', ')}`);
+        out.push(`   Best match (#${r.match.seq}, ${r.match.role}): ${r.match.snippet}`);
+        if (r.context?.length) out.push('   Around it:', ...messageLines(r.context, r.match.seq));
+      });
+      out.push('', 'To read more of one: session_search with its session_id and around_seq set to a message number.');
+    }
+  } else if (result.mode === 'scroll') {
+    out.push(`From ${sessionLine(result.session)}, around message #${result.aroundSeq}:`, ...messageLines(result.messages, result.aroundSeq));
+  } else if (result.mode === 'read') {
+    out.push(`${sessionLine(result.session)} — ${result.total} messages.`);
+    if (result.head.length) out.push('How it began:', ...messageLines(result.head));
+    if (result.omitted) out.push(`   … ${result.omitted} message(s) in between — use around_seq to read any part …`);
+    if (result.tail.length) out.push(result.omitted ? 'How it ended:' : 'Then:', ...messageLines(result.tail));
+  } else if (result.mode === 'browse') {
+    const where = result.workspace ? ` in workspace "${result.workspace}"` : '';
+    out.push(result.sessions.length ? `Most recent earlier chats${where}:` : `There are no earlier chats${where} yet.`);
+    result.sessions.forEach((s, i) => out.push(`${i + 1}. ${sessionLine(s)}`));
+  }
+  const text = out.join('\n');
+  return text.length > max ? `${text.slice(0, max - 60).trimEnd()}\n… (cut to fit — narrow the search to see more)` : text;
+}
+
+/** Which of the four shapes the arguments ask for. */
+export function modeOf(args = {}) {
+  const has = (v) => typeof v === 'string' && v.trim() !== '';
+  if (has(args.session_id) && Number.isFinite(args.around_seq)) return 'scroll';
+  if (has(args.session_id)) return 'read';
+  if (has(args.query)) return 'discover';
+  return 'browse';
+}
+
+/** What the permission prompt says the model wants. */
+export function reasonFor(args = {}, workspace = null) {
+  const where = workspace ? ` in "${workspace}"` : '';
+  switch (modeOf(args)) {
+    case 'discover': return `Search your earlier chats${where} for "${String(args.query).trim()}".`;
+    case 'scroll': return `Read part of an earlier chat (${args.session_id}).`;
+    case 'read': return `Read the beginning and end of an earlier chat (${args.session_id}).`;
+    default: return workspace ? `List your chats in "${workspace}".` : 'List your most recent chats.';
+  }
+}
+
+/**
+ * @param {object} p
+ * @param {ReturnType<import('./recall.js').createRecall>} p.recall
+ * @param {Function} p.defineTool
+ * @param {() => object|undefined} p.getApproval  resolves the dsh approval service lazily
+ * @param {Map<string, number>} p.grants  chat id → time the grant lapses
+ * @param {object} p.log  per-call record for the chat card: {start, update}
+ * @param {boolean} [p.askFirst=true]
+ * @param {() => number} [p.now]
+ * @param {number} [p.grantMs]  a safety lapse, in case the idle event is missed
+ */
+export function createRecallTool({
+  recall, defineTool, getApproval, grants, log, askFirst = true, now = () => Date.now(), grantMs = 30 * 60_000,
+  resolveWorkspace = async () => null, listWorkspaces = async () => [],
+}) {
+  async function permission(exec, args, workspace) {
+    if (!askFirst) return 'allowed-once';
+    const chat = exec?.agent?.id;
+    if (chat && (grants.get(chat) ?? 0) > now()) return 'allowed-once';
+    const approval = getApproval();
+    if (!approval || typeof approval.request !== 'function' || !exec?.agent) return 'unavailable';
+    const outcome = await approval.request({
+      agent: exec.agent,
+      toolName: RECALL_TOOL,
+      callId: exec.callId,
+      reason: reasonFor(args, workspace),
+      signal: exec.signal,
+    });
+    if (outcome === 'allowed-once' && chat) grants.set(chat, now() + grantMs);
+    return outcome;
+  }
+
+  async function run(args, exec) {
+    const mode = modeOf(args);
+    const callId = exec?.callId;
+    const wanted = typeof args.workspace === 'string' ? args.workspace.trim() : '';
+    log.start(callId, { mode, query: args.query ?? null, sessionId: args.session_id ?? null, workspace: wanted || null });
+    // Which chats a workspace holds is metadata, not chat content, so it is
+    // resolved before asking — and the prompt can then say where it will look.
+    let workspace = null;
+    if (wanted && (mode === 'discover' || mode === 'browse')) {
+      try { workspace = await resolveWorkspace(wanted); } catch { workspace = null; }
+      if (!workspace) {
+        let names = [];
+        try { names = (await listWorkspaces()).map((w) => w.title); } catch { /* none to offer */ }
+        const text = `No workspace called "${wanted}".${names.length ? ` Workspaces: ${names.map((n) => `"${n}"`).join(', ')}.` : ''} Nothing was read.`;
+        log.update(callId, { status: 'error', error: text });
+        return text;
+      }
+      log.update(callId, { workspace: workspace.title });
+    }
+    log.update(callId, { status: 'awaiting-approval' });
+    let outcome;
+    try {
+      outcome = await permission(exec, args, workspace?.title ?? null);
+    } catch (error) {
+      outcome = 'unavailable';
+      log.update(callId, { note: String(error?.message ?? error) });
+    }
+    if (outcome !== 'allowed-once') {
+      log.update(callId, { status: 'declined', outcome });
+      return OUTCOME_TEXT[outcome] ?? OUTCOME_TEXT.unavailable;
+    }
+    log.update(callId, { status: 'searching' });
+    const excludeId = exec?.agent?.id;
+    try {
+      let result;
+      const scope = workspace ? new Set(workspace.chats.map((c) => c.sessionId)) : undefined;
+      if (mode === 'discover') result = await recall.discover({ query: args.query, limit: args.limit, sort: args.sort, excludeId, scope });
+      else if (mode === 'scroll') result = await recall.scroll({ sessionId: args.session_id.trim(), aroundSeq: args.around_seq });
+      else if (mode === 'read') result = await recall.read({ sessionId: args.session_id.trim() });
+      else result = await recall.browse({ limit: args.limit, excludeId, scope });
+      if (workspace) result.workspace = workspace.title;
+      log.update(callId, { status: 'done', result });
+      return formatRecall(result, recall.options.totalChars);
+    } catch (error) {
+      const message = error instanceof RecallError ? error.message : `could not read past chats: ${error?.message ?? error}`;
+      log.update(callId, { status: 'error', error: message });
+      return `Recall failed: ${message}`;
+    }
+  }
+
+  return defineTool({
+    name: RECALL_TOOL,
+    description: RECALL_DESCRIPTION,
+    parameters: {
+      query: { type: 'string', description: 'One or two distinctive keywords, matched as an exact phrase. Omit to list recent chats.' },
+      limit: { type: 'integer', description: 'How many chats to return (default 3, at most 10; for a listing, default 10).' },
+      sort: { type: 'string', enum: ['newest', 'oldest'], description: "'newest' for where something was left, 'oldest' for how it started; omit for best match." },
+      workspace: { type: 'string', description: "Only this workspace's chats: its title as the sidebar shows it, or its folder." },
+      session_id: { type: 'string', description: 'A chat from an earlier result, to read inside it.' },
+      around_seq: { type: 'integer', description: 'With session_id: the message number to read around (the #N shown in results).' },
+    },
+    output: TEXT_OUTPUT,
+    execute: async (args, exec) => ({ text: await run(args ?? {}, exec) }),
+  });
+}

package/src/recall.js

@@ -0,0 +1,282 @@
+// Looking things up in earlier chats, through dsh's own session query service.
+//
+// Four shapes, as in Hermes Agent's session_search:
+//   discover  a query            → the chats that match best, the top one with context
+//   scroll    a chat + a message → the messages around it
+//   read      a chat alone       → its opening and its end
+//   browse    nothing            → the most recent chats
+//
+// Everything returned is the chats' actual messages — no model call, no
+// summary that could be wrong. Only the user's own top-level chats are
+// searched: sub-agent sessions are the model talking to itself, and the chat
+// asking is left out (it already has its own history). Only user and assistant
+// messages count; tool calls and results are noise for "what did we decide".
+//
+// dsh's full-text index (SQLite FTS5) matches a query as a LITERAL PHRASE, so
+// "graft sidebar" finds only chats where those words are adjacent. When a
+// multi-word search comes back short, each distinctive word is searched on its
+// own and chats are ranked by how many of the words they contain. If the index
+// is switched off, a slower literal scan of recent chats stands in for it.
+
+export const MESSAGE_TYPES = ['user/message', 'assistant/message'];
+
+export const DEFAULTS = {
+  limit: 3,
+  maxLimit: 10,
+  browseLimit: 10,
+  /** Messages shown either side of a match. */
+  around: 3,
+  /** A single message is cut to this many characters. */
+  messageChars: 700,
+  /** The whole answer is cut to this many characters. */
+  totalChars: 9000,
+  /** How many recent chats the fallback scan reads, newest first. */
+  scanSessions: 150,
+};
+
+const STOPWORDS = new Set(('a an and are as at be but by did do does for from had has have how i if in into is it its '
+  + 'last me my of on or our that the their them then there these this those to was we were what when where which '
+  + 'who why will with you your about after again all also any can could just like more most not now only other '
+  + 'over same should some such than too very would chat chats talked discussed decided said '
+  // The words of the question itself ("what did we decide last time…"), which
+  // match half of any history and say nothing about the topic.
+  + 'decide decision time times remember recall conversation conversations earlier previous before ago '
+  + 'thing things something stuff back leave left mentioned told asked').split(' '));
+
+/** Distinctive words of a query, for the word-by-word pass. */
+export function keywords(query) {
+  const seen = new Set();
+  const out = [];
+  for (const word of String(query).toLowerCase().split(/[^\p{L}\p{N}_.\-]+/u)) {
+    const w = word.replace(/^[.\-]+|[.\-]+$/g, '');
+    if (w.length < 3 || STOPWORDS.has(w) || seen.has(w)) continue;
+    seen.add(w);
+    out.push(w);
+  }
+  return out.slice(0, 5);
+}
+
+/** dsh marks FTS matches with two private-use characters; show them as **bold**. */
+export function cleanSnippet(snippet) {
+  return String(snippet ?? '').replace(/\uFDD0/g, '**').replace(/\uFDD1/g, '**').replace(/\s+/g, ' ').trim();
+}
+
+const roleOf = (type) => (type === 'user/message' ? 'user' : 'assistant');
+const isRoot = (header) => header && !header.parentSession && header.origin !== 'subagent';
+
+function cut(text, max) {
+  const t = String(text ?? '').trim();
+  return t.length > max ? `${t.slice(0, max - 1).trimEnd()}…` : t;
+}
+
+/** A snippet around the first literal occurrence of `needle` in `text`. */
+export function excerpt(text, needle, width = 120) {
+  const t = String(text ?? '').replace(/\s+/g, ' ');
+  const at = needle ? t.toLowerCase().indexOf(String(needle).toLowerCase()) : -1;
+  if (at < 0) return cut(t, width * 2);
+  const start = Math.max(0, at - width);
+  const end = Math.min(t.length, at + needle.length + width);
+  return `${start > 0 ? '…' : ''}${t.slice(start, at)}**${t.slice(at, at + needle.length)}**${t.slice(at + needle.length, end)}${end < t.length ? '…' : ''}`;
+}
+
+export class RecallError extends Error {}
+
+/**
+ * @param {object} p
+ * @param {() => object|undefined} p.getQuery  resolves ctx.sessionQuery lazily
+ * @param {object} [p.options]
+ */
+export function createRecall({ getQuery, options = {} }) {
+  const o = { ...DEFAULTS, ...options };
+
+  const query = () => {
+    const q = getQuery();
+    if (!q || typeof q.listSessions !== 'function') {
+      throw new RecallError("dsh's session query service is not available in this deployment, so past chats cannot be read.");
+    }
+    return q;
+  };
+
+  async function titlesFor(ids) {
+    const out = new Map();
+    if (!ids.length) return out;
+    try {
+      const rows = await query().readTitleSnapshots(ids);
+      for (const row of rows ?? []) {
+        if (row?.status === 'fulfilled' && row.value?.title?.title) out.set(row.sessionId, row.value.title.title);
+      }
+    } catch { /* untitled is fine */ }
+    return out;
+  }
+
+  async function messages(sessionId, filters = []) {
+    const docs = await query().filterEvents(sessionId, [{ kind: 'type', values: MESSAGE_TYPES }, ...filters]);
+    return [...(docs ?? [])]
+      .filter((d) => String(d.text ?? '').trim() !== '')
+      .sort((a, b) => a.seq - b.seq)
+      .map((d) => ({ seq: d.seq, role: roleOf(d.type), time: d.time, text: cut(d.text, o.messageChars) }));
+  }
+
+  /** Up to `around` messages either side of `seq`. */
+  async function windowAround(sessionId, seq) {
+    const near = await messages(sessionId, [{ kind: 'seq', from: Math.max(0, seq - 60), to: seq + 60 }]);
+    let at = near.findIndex((m) => m.seq >= seq);
+    if (at < 0) at = near.length - 1;
+    return near.slice(Math.max(0, at - o.around), at + o.around + 1);
+  }
+
+  function sessionInfo(header, titles) {
+    return { sessionId: header.id, title: titles.get(header.id) ?? null, createdAt: header.createdAt, cwd: header.cwd ?? null };
+  }
+
+  /** FTS for one phrase → Map(sessionId → hit). Throws `disabled` when the index is off. */
+  /** Session filters: top-level chats, and only the scope's when there is one. */
+  const scopeFilters = (scope) => [
+    { kind: 'parent', values: [null] },
+    ...(scope ? [{ kind: 'id', values: [...scope] }] : []),
+  ];
+
+  async function ftsHits(phrase, excludeId, want, scope) {
+    const q = query();
+    if (typeof q.searchSessions !== 'function') throw Object.assign(new Error('no full-text search'), { disabled: true });
+    let page;
+    try {
+      page = await q.searchSessions({
+        query: phrase,
+        sessionFilters: scopeFilters(scope),
+        eventFilters: [{ kind: 'type', values: MESSAGE_TYPES }],
+        limit: Math.min(100, want + 5),
+      });
+    } catch (error) {
+      if (error?.code === 'SESSION_QUERY_SEARCH_DISABLED') throw Object.assign(new Error('search disabled'), { disabled: true });
+      throw error;
+    }
+    const hits = new Map();
+    for (const item of page?.items ?? []) {
+      if (!isRoot(item.header) || item.header.id === excludeId) continue;
+      hits.set(item.header.id, {
+        header: item.header,
+        match: { seq: item.bestMatch.seq, role: roleOf(item.bestMatch.type), time: item.bestMatch.time, snippet: cleanSnippet(item.bestMatch.snippet) },
+      });
+    }
+    return hits;
+  }
+
+  /** The literal scan used when the index is off: newest chats first, one match each. */
+  async function scanHits(phrase, excludeId, want, scope) {
+    const q = query();
+    const sessions = (await q.listSessions())
+      .map((r) => r.header)
+      .filter((h) => isRoot(h) && h.id !== excludeId && (!scope || scope.has(h.id)))
+      .sort((a, b) => b.createdAt - a.createdAt)
+      .slice(0, o.scanSessions);
+    const hits = new Map();
+    for (const header of sessions) {
+      if (hits.size >= want) break;
+      let docs;
+      try {
+        docs = await q.filterEvents(header.id, [{ kind: 'type', values: MESSAGE_TYPES }, { kind: 'text', text: phrase }]);
+      } catch { continue; } // one unreadable chat must not stop the scan
+      const first = [...(docs ?? [])].sort((a, b) => a.seq - b.seq)[0];
+      if (!first) continue;
+      hits.set(header.id, { header, match: { seq: first.seq, role: roleOf(first.type), time: first.time, snippet: excerpt(first.text, phrase) } });
+    }
+    return hits;
+  }
+
+  /**
+   * @param {object} p
+   * @param {Set<string>} [p.scope]  only these chats (a workspace's), when given
+   */
+  async function discover({ query: text, limit, sort, excludeId, scope }) {
+    const phrase = String(text ?? '').trim();
+    if (!phrase) throw new RecallError('query is empty');
+    const want = Math.max(1, Math.min(o.maxLimit, Number.isFinite(limit) ? Math.floor(limit) : o.limit));
+    let engine = 'fts';
+    if (scope && scope.size === 0) return { mode: 'discover', engine: 'fts', query: phrase, widened: false, results: [] };
+    let search = (p, n) => ftsHits(p, excludeId, n, scope);
+    let hits;
+    try {
+      hits = await search(phrase, want * 3);
+    } catch (error) {
+      if (!error?.disabled) throw error;
+      engine = 'scan';
+      search = (p, n) => scanHits(p, excludeId, n, scope);
+      hits = await search(phrase, want * 3);
+    }
+    // Phrase first; then, if that is thin, each distinctive word on its own.
+    const scored = new Map([...hits].map(([id, hit]) => [id, { ...hit, score: 100, words: [phrase] }]));
+    const words = keywords(phrase);
+    let widened = false;
+    if (scored.size < want && words.length > 1) {
+      widened = true;
+      for (const word of words) {
+        for (const [id, hit] of await search(word, want * 3)) {
+          const prior = scored.get(id);
+          if (prior) {
+            if (prior.score < 100) { prior.score += 1; prior.words.push(word); }
+          } else {
+            scored.set(id, { ...hit, score: 1, words: [word] });
+          }
+        }
+      }
+    }
+    let ranked = [...scored.values()].sort((a, b) => b.score - a.score || b.header.createdAt - a.header.createdAt);
+    ranked = ranked.slice(0, want);
+    if (sort === 'newest') ranked.sort((a, b) => b.header.createdAt - a.header.createdAt);
+    if (sort === 'oldest') ranked.sort((a, b) => a.header.createdAt - b.header.createdAt);
+    const titles = await titlesFor(ranked.map((r) => r.header.id));
+    const results = ranked.map((r) => ({
+      ...sessionInfo(r.header, titles),
+      match: r.match,
+      matchedWords: r.score >= 100 ? null : r.words,
+    }));
+    if (results[0]) {
+      try { results[0].context = await windowAround(results[0].sessionId, results[0].match.seq); } catch { /* the snippet still stands */ }
+    }
+    return { mode: 'discover', engine, query: phrase, widened, results };
+  }
+
+  async function headerOf(sessionId) {
+    const q = query();
+    const rows = await q.filterSessions([{ kind: 'id', values: [sessionId] }]);
+    const header = rows?.[0]?.header;
+    if (!header) throw new RecallError(`no chat with id ${sessionId}`);
+    return header;
+  }
+
+  async function scroll({ sessionId, aroundSeq }) {
+    const header = await headerOf(sessionId);
+    const titles = await titlesFor([sessionId]);
+    return { mode: 'scroll', session: sessionInfo(header, titles), aroundSeq, messages: await windowAround(sessionId, aroundSeq) };
+  }
+
+  async function read({ sessionId }) {
+    const header = await headerOf(sessionId);
+    const titles = await titlesFor([sessionId]);
+    const all = await messages(sessionId);
+    const head = all.slice(0, 4);
+    const tail = all.length > 10 ? all.slice(-6) : all.slice(4);
+    return {
+      mode: 'read',
+      session: sessionInfo(header, titles),
+      total: all.length,
+      head,
+      tail,
+      omitted: Math.max(0, all.length - head.length - tail.length),
+    };
+  }
+
+  async function browse({ limit, excludeId, scope }) {
+    const want = Math.max(1, Math.min(30, Number.isFinite(limit) ? Math.floor(limit) : o.browseLimit));
+    const headers = (await query().listSessions())
+      .map((r) => r.header)
+      .filter((h) => isRoot(h) && h.id !== excludeId && (!scope || scope.has(h.id)))
+      .sort((a, b) => b.createdAt - a.createdAt)
+      .slice(0, want);
+    const titles = await titlesFor(headers.map((h) => h.id));
+    return { mode: 'browse', sessions: headers.map((h) => sessionInfo(h, titles)) };
+  }
+
+  return { discover, scroll, read, browse, options: o };
+}

package/src/routes.js

@@ -0,0 +1,153 @@
+// Host routes for the browser half, and the per-call record the recall card reads.
+//
+//   GET  /plugin-data/dsh-memory-recall/state            → both stores: entries, usage, limits
+//   POST /plugin-data/dsh-memory-recall/entry            → an edit made in the Memory panel
+//   GET  /plugin-data/dsh-memory-recall/recall?callId=…  → what one session_search call did
+//   GET  /plugin-data/dsh-memory-recall/chats?session=…  → every chat, grouped by workspace, for the @ menu
+//
+// Edits from the panel are the user's own words, so they skip the injection
+// scan the model's writes go through — but not the budget: an over-full store
+// would be cut from nothing, silently, in the next prompt.
+
+export const BASE = '/plugin-data/dsh-memory-recall';
+export const STATE_PATH = `${BASE}/state`;
+export const ENTRY_PATH = `${BASE}/entry`;
+export const RECALL_PATH = `${BASE}/recall`;
+export const CHATS_PATH = `${BASE}/chats`;
+
+/** What the recall card needs from a result — titles and snippets, not whole chats. */
+export function summarize(result) {
+  if (!result) return null;
+  const brief = (s) => ({ sessionId: s.sessionId, title: s.title, createdAt: s.createdAt, cwd: s.cwd });
+  switch (result.mode) {
+    case 'discover':
+      return {
+        mode: 'discover', engine: result.engine, query: result.query, widened: result.widened,
+        results: result.results.map((r) => ({ ...brief(r), snippet: r.match.snippet, matchedWords: r.matchedWords })),
+      };
+    case 'scroll': return { mode: 'scroll', session: brief(result.session), count: result.messages.length };
+    case 'read': return { mode: 'read', session: brief(result.session), count: result.total };
+    case 'browse': return { mode: 'browse', sessions: result.sessions.map(brief) };
+    default: return null;
+  }
+}
+
+/** A bounded map of recent session_search calls, by call id. */
+export function createRecallLog(cap = 100, now = () => Date.now()) {
+  const calls = new Map();
+  return {
+    start(callId, info) {
+      if (!callId) return;
+      calls.set(callId, { ...info, status: 'starting', startedAt: now() });
+      while (calls.size > cap) calls.delete(calls.keys().next().value);
+    },
+    update(callId, patch) {
+      const entry = callId ? calls.get(callId) : undefined;
+      if (!entry) return;
+      const { result, ...rest } = patch;
+      Object.assign(entry, rest, result ? { summary: summarize(result) } : {}, { updatedAt: now() });
+    },
+    get: (callId) => calls.get(callId) ?? null,
+  };
+}
+
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(payload));
+}
+
+async function readBody(req) {
+  let text = '';
+  for await (const chunk of req ?? []) text += chunk;
+  if (!text) return {};
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** Both stores as the panel shows them. Re-read from disk, so a hand edit shows at once. */
+export async function stateOf(store, tooling = null) {
+  await store.load();
+  const one = (target) => ({ entries: store.entries[target], usage: store.usage(target) });
+  return { dir: store.dir, user: one('user'), memory: one('memory'), ...(tooling ? { tools: { ...tooling } } : {}) };
+}
+
+/**
+ * The @ menu's view of the chat index: the asking chat left out (mentioning
+ * the chat you are in is pointless), and its workspace named so the menu can
+ * list that one first.
+ */
+export async function chatsFor(chatIndex, sessionId, cwdOf = async () => null) {
+  const index = await chatIndex.list();
+  const without = (chats) => chats.filter((c) => c.sessionId !== sessionId);
+  let current = sessionId ? chatIndex.workspaceOf(index, sessionId, null) : null;
+  if (!current && sessionId) current = chatIndex.workspaceOf(index, sessionId, await cwdOf(sessionId));
+  return {
+    currentWorkspaceId: current?.id ?? null,
+    workspaces: index.workspaces
+      .map((w) => ({ id: w.id, title: w.title, path: w.path, chats: without(w.chats) }))
+      .filter((w) => w.chats.length),
+    ungrouped: without(index.ungrouped),
+  };
+}
+
+/**
+ * @param {object} webServer ctx.webServer
+ * @param {object} p {store, log, chatIndex?, cwdOf?}
+ * @returns {() => void} disposer
+ */
+export function registerRoutes(webServer, { store, log, chatIndex, cwdOf, tooling }) {
+  const off = [];
+  off.push(webServer.register({
+    kind: 'exact',
+    path: STATE_PATH,
+    handler: async (req = {}, res) => {
+      if ((req.method || 'GET').toUpperCase() !== 'GET') return sendJson(res, 405, { error: 'method not allowed' });
+      try {
+        sendJson(res, 200, await stateOf(store, tooling));
+      } catch (error) {
+        sendJson(res, 500, { error: `could not read memory: ${error?.message ?? error}` });
+      }
+    },
+  }));
+  off.push(webServer.register({
+    kind: 'exact',
+    path: ENTRY_PATH,
+    handler: async (req = {}, res) => {
+      if ((req.method || 'GET').toUpperCase() !== 'POST') return sendJson(res, 405, { error: 'method not allowed' });
+      const body = await readBody(req);
+      if (!body || typeof body !== 'object') return sendJson(res, 400, { error: 'the body must be a JSON object' });
+      const { target, action, content, old_text: oldText } = body;
+      let result;
+      if (action === 'add') result = await store.add(target, content, { scan: false });
+      else if (action === 'replace') result = await store.replace(target, oldText, content, { scan: false });
+      else if (action === 'remove') result = await store.remove(target, oldText);
+      else return sendJson(res, 400, { error: "action must be 'add', 'replace' or 'remove'" });
+      sendJson(res, result.success ? 200 : 400, { result, state: await stateOf(store, tooling) });
+    },
+  }));
+  off.push(webServer.register({
+    kind: 'exact',
+    path: RECALL_PATH,
+    handler: async (req = {}, res) => {
+      const callId = new URL(req.url ?? '/', 'http://x').searchParams.get('callId');
+      if (!callId) return sendJson(res, 400, { error: 'missing callId' });
+      const entry = log.get(callId);
+      sendJson(res, entry ? 200 : 404, entry ?? { error: 'no record of that call (dsh may have restarted since)' });
+    },
+  }));
+  if (chatIndex) {
+    off.push(webServer.register({
+      kind: 'exact',
+      path: CHATS_PATH,
+      handler: async (req = {}, res) => {
+        if ((req.method || 'GET').toUpperCase() !== 'GET') return sendJson(res, 405, { error: 'method not allowed' });
+        const sessionId = new URL(req.url ?? '/', 'http://x').searchParams.get('session');
+        try {
+          sendJson(res, 200, await chatsFor(chatIndex, sessionId, cwdOf));
+        } catch (error) {
+          sendJson(res, 503, { error: String(error?.message ?? error) });
+        }
+      },
+    }));
+  }
+  return () => { for (const dispose of off) dispose(); };
+}