verbalcoding 0.2.12 → 0.2.13

package/app-node/research_mode.test.mjs

@@ -0,0 +1,264 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  parseResearchCommand,
+  buildSynthesisPrompt,
+  parseSynthesisOutput,
+  renderResearchSpeech,
+  renderResearchMarkdown,
+  buildResearchEmbed,
+  runResearchTurn,
+  selectSearchBackend,
+  buildAgentDelegatedResearchPrompt,
+  parseAgentDelegatedOutput,
+} from './research_mode.mjs';
+
+test('parseResearchCommand picks up English "research X"', () => {
+  const c = parseResearchCommand('research the latest on STORM', 'en');
+  assert.equal(c.type, 'research');
+  assert.match(c.query, /STORM/);
+  assert.equal(c.depth, 'quick');
+});
+
+test('parseResearchCommand flags deep mode', () => {
+  const c = parseResearchCommand('deep research GraphRAG community detection', 'en');
+  assert.equal(c.type, 'research');
+  assert.equal(c.depth, 'deep');
+});
+
+test('parseResearchCommand recognizes Korean phrasing', () => {
+  const c = parseResearchCommand('Mem0 한번 리서치해줘', 'ko');
+  assert.equal(c.type, 'research');
+  assert.match(c.query, /Mem0/);
+});
+
+test('parseResearchCommand returns none for unrelated input', () => {
+  assert.equal(parseResearchCommand('write a unit test for parseDecisionAnswer', 'en').type, 'none');
+  assert.equal(parseResearchCommand('hi how are you', 'en').type, 'none');
+});
+
+test('parseResearchCommand does not hijack coding utterances containing the word "research"', () => {
+  assert.equal(parseResearchCommand('implement research mode', 'en').type, 'none');
+  assert.equal(parseResearchCommand('fix the research_mode regex', 'en').type, 'none');
+  assert.equal(parseResearchCommand('add docs about research turn', 'en').type, 'none');
+  assert.equal(parseResearchCommand('리서치 모드 코드 좀 봐', 'ko').type, 'none');
+  assert.equal(parseResearchCommand('리서치 코드 리팩토링해줘', 'ko').type, 'none');
+});
+
+test('parseResearchCommand still triggers on agent-routed forms', () => {
+  const c = parseResearchCommand('ask codex to research Node.js streams', 'en');
+  assert.equal(c.type, 'research');
+  assert.equal(c.query, 'Node.js streams');
+});
+
+test('parseResearchCommand preserves internal punctuation in technical queries', () => {
+  const cases = [
+    ['research Node.js streams', 'Node.js streams'],
+    ['look up GPT-4.1 vs Claude 4.7', 'GPT-4.1 vs Claude 4.7'],
+    ['research https://example.com/foo?bar=1', 'https://example.com/foo?bar=1'],
+    ['research what is 1.5 vs 2.0', 'what is 1.5 vs 2.0'],
+  ];
+  for (const [input, expected] of cases) {
+    const c = parseResearchCommand(input, 'en');
+    assert.equal(c.type, 'research', `failed parse for ${input}`);
+    assert.equal(c.query, expected, `expected '${expected}' from '${input}', got '${c.query}'`);
+  }
+});
+
+test('parseResearchCommand strips only trailing sentence punctuation', () => {
+  const c = parseResearchCommand('research Node.js streams.', 'en');
+  assert.equal(c.query, 'Node.js streams');
+  const q = parseResearchCommand('research GPT-4.1?', 'en');
+  assert.equal(q.query, 'GPT-4.1');
+});
+
+test('buildSynthesisPrompt embeds query and sources', () => {
+  const p = buildSynthesisPrompt({
+    query: 'STORM autoresearch',
+    sources: [{ title: 'STORM paper', url: 'https://arxiv.org/abs/2402.14207', snippet: 'Wikipedia-style writing' }],
+    language: 'en',
+  });
+  assert.match(p, /STORM autoresearch/);
+  assert.match(p, /\[1\] STORM paper/);
+});
+
+test('parseSynthesisOutput extracts bullets and sources block', () => {
+  const text = [
+    '- STORM uses perspective-grounded Q&A to draft long-form articles.',
+    '- It outperforms naive RAG on outline organization metrics.',
+    '- Known failure mode is over-association of unrelated facts.',
+    '',
+    'SOURCES:',
+    '[1] STORM paper',
+    '[2] STORM repo',
+  ].join('\n');
+  const { bullets, sourceLines } = parseSynthesisOutput(text);
+  assert.equal(bullets.length, 3);
+  assert.equal(sourceLines.length, 2);
+  assert.match(bullets[0], /STORM uses/);
+});
+
+test('renderResearchSpeech joins intro plus bullets and tags with prefix', () => {
+  const speech = renderResearchSpeech(['A.', 'B.', 'C.'], 'en');
+  assert.match(speech, /^Research finding:/);
+  assert.match(speech, /A\./);
+});
+
+test('renderResearchSpeech uses Korean prefix for ko', () => {
+  const speech = renderResearchSpeech(['ㄱ.', 'ㄴ.', 'ㄷ.'], 'ko');
+  assert.match(speech, /^리서치 결과:/);
+});
+
+test('renderResearchMarkdown numbers sources', () => {
+  const md = renderResearchMarkdown({
+    query: 'GraphRAG',
+    bullets: ['one'],
+    sources: [{ title: 'MS GraphRAG', url: 'https://example.com/g' }],
+    language: 'en',
+  });
+  assert.match(md, /1\. \[MS GraphRAG\]\(https:\/\/example\.com\/g\)/);
+});
+
+test('runResearchTurn happy path with mocked fetch and synth', async () => {
+  const env = { TAVILY_API_KEY: 'fake' };
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ({
+      answer: '',
+      results: [
+        { title: 'STORM Stanford', url: 'https://arxiv.org/abs/2402.14207', content: 'Wikipedia-style article generation.' },
+        { title: 'STORM Repo', url: 'https://github.com/stanford-oval/storm', content: 'Open-source implementation.' },
+      ],
+    }),
+  });
+  const synthesize = async () => '- STORM is a Wikipedia-style article writer.\n- Uses perspective-grounded Q&A.\n- Self-hostable and MIT-licensed.\n\nSOURCES:\n[1] STORM Stanford\n[2] STORM Repo';
+  const result = await runResearchTurn({ query: 'STORM autoresearch', env, fetchImpl, synthesize, language: 'en' });
+  assert.equal(result.status, 'ok');
+  assert.equal(result.bullets.length, 3);
+  assert.equal(result.sources.length, 2);
+  assert.match(result.speech, /STORM is a Wikipedia-style/);
+  assert.match(result.markdown, /arxiv\.org/);
+});
+
+test('runResearchTurn reports no_backend when both keys missing', async () => {
+  const result = await runResearchTurn({ query: 'x', env: {}, fetchImpl: async () => {}, synthesize: async () => '' });
+  assert.equal(result.status, 'no_backend');
+});
+
+test('buildResearchEmbed numbers source fields', () => {
+  const embed = buildResearchEmbed({
+    query: 'GraphRAG',
+    bullets: ['summary'],
+    sources: [
+      { title: 'MS GraphRAG', url: 'https://example.com/g' },
+      { title: 'LightRAG', url: 'https://example.com/l' },
+    ],
+    language: 'en',
+  });
+  assert.match(embed.title, /Research: GraphRAG/);
+  assert.equal(embed.fields.length, 2);
+  assert.match(embed.fields[0].name, /^\[1\] MS GraphRAG/);
+  assert.equal(embed.fields[1].value, 'https://example.com/l');
+});
+
+test('selectSearchBackend honors explicit SEARCH_BACKEND override', () => {
+  assert.equal(selectSearchBackend({ SEARCH_BACKEND: 'agent' }).kind, 'agent');
+  assert.equal(selectSearchBackend({ SEARCH_BACKEND: 'tavily', TAVILY_API_KEY: 'k' }).kind, 'tavily');
+  // explicit pick without matching key falls through to discovery order
+  assert.equal(selectSearchBackend({ SEARCH_BACKEND: 'brave' }).kind, 'none');
+  assert.equal(selectSearchBackend({ SEARCH_BACKEND: 'brave', TAVILY_API_KEY: 'k' }).kind, 'tavily');
+});
+
+test('selectSearchBackend default priority is tavily → brave → searxng → none', () => {
+  assert.equal(selectSearchBackend({}).kind, 'none');
+  assert.equal(selectSearchBackend({ SEARXNG_URL: 'http://localhost:8888' }).kind, 'searxng');
+  assert.equal(selectSearchBackend({ BRAVE_API_KEY: 'b', SEARXNG_URL: 'http://x' }).kind, 'brave');
+  assert.equal(selectSearchBackend({ TAVILY_API_KEY: 't', BRAVE_API_KEY: 'b' }).kind, 'tavily');
+});
+
+test('selectSearchBackend uses agent fallback opt-in when no key is present', () => {
+  assert.equal(selectSearchBackend({ SEARCH_BACKEND_AGENT_FALLBACK: '1' }).kind, 'agent');
+});
+
+test('runResearchTurn with SEARXNG_URL builds JSON request and synthesises bullets', async () => {
+  const env = { SEARXNG_URL: 'http://searx.local' };
+  const captured = [];
+  const fetchImpl = async (url) => {
+    captured.push(url);
+    return {
+      ok: true,
+      json: async () => ({
+        results: [
+          { title: 'LightRAG', url: 'https://arxiv.org/abs/2410.05779', content: 'LightRAG dual-level retrieval.' },
+          { title: 'HippoRAG', url: 'https://arxiv.org/abs/2405.14831', content: 'PPR-based memory.' },
+        ],
+      }),
+    };
+  };
+  const synthesize = async () => '- LightRAG is dual-level retrieval.\n- HippoRAG uses PPR.\n- GraphRAG uses Leiden clusters.\n\nSOURCES:\n[1] LightRAG\n[2] HippoRAG';
+  const result = await runResearchTurn({ query: 'GraphRAG family', env, fetchImpl, synthesize, language: 'en' });
+  assert.equal(result.status, 'ok');
+  assert.equal(result.sources.length, 2);
+  assert.equal(result.bullets.length, 3);
+  assert.match(captured[0], /searx\.local\/search\?.*q=GraphRAG/);
+  assert.match(captured[0], /format=json/);
+});
+
+test('runResearchTurn agent-delegated path skips performSearch and parses agent output', async () => {
+  const env = { SEARCH_BACKEND: 'agent' };
+  let fetchCalled = false;
+  const fetchImpl = async () => { fetchCalled = true; return { ok: false, json: async () => ({}) }; };
+  const synthCalls = [];
+  const synthesize = async (prompt, opts) => {
+    synthCalls.push({ prompt, opts });
+    return [
+      '- ACE evolves a per-project playbook that beats fine-tuning.',
+      '- It compounds across sessions without changing model weights.',
+      '- Open implementation available from the paper authors.',
+      '',
+      'SOURCES:',
+      '[1] ACE paper | https://arxiv.org/abs/2510.04618',
+      '[2] Project README | https://github.com/example/ace-repo',
+    ].join('\n');
+  };
+  const result = await runResearchTurn({ query: 'Agentic Context Engineering ACE', env, fetchImpl, synthesize, language: 'en' });
+  assert.equal(fetchCalled, false);
+  assert.equal(result.status, 'ok');
+  assert.equal(result.backend, 'agent');
+  assert.equal(result.bullets.length, 3);
+  assert.equal(result.sources.length, 2);
+  assert.equal(result.sources[0].url, 'https://arxiv.org/abs/2510.04618');
+  assert.equal(synthCalls[0].opts.task, true, 'agent-delegated synthesise call sets task=true for longer timeout');
+});
+
+test('parseAgentDelegatedOutput tolerates dash separators and missing brackets', () => {
+  const text = [
+    '- A.',
+    '- B.',
+    '- C.',
+    '',
+    'SOURCES:',
+    '[1] Foo paper — https://example.com/foo',
+    'Bar - https://example.com/bar',
+  ].join('\n');
+  const { bullets, sources } = parseAgentDelegatedOutput(text);
+  assert.equal(bullets.length, 3);
+  assert.equal(sources.length, 2);
+  assert.equal(sources[0].url, 'https://example.com/foo');
+  assert.equal(sources[1].url, 'https://example.com/bar');
+});
+
+test('buildAgentDelegatedResearchPrompt names the query and the strict format', () => {
+  const p = buildAgentDelegatedResearchPrompt({ query: 'STORM autoresearch', language: 'en' });
+  assert.match(p, /You have web access/);
+  assert.match(p, /STORM autoresearch/);
+  assert.match(p, /SOURCES:/);
+});
+
+test('runResearchTurn handles empty search gracefully', async () => {
+  const env = { TAVILY_API_KEY: 'fake' };
+  const fetchImpl = async () => ({ ok: true, json: async () => ({ results: [] }) });
+  const result = await runResearchTurn({ query: 'X', env, fetchImpl, synthesize: async () => '', language: 'en' });
+  assert.equal(result.status, 'empty');
+  assert.match(result.speech, /could not find/);
+});

package/app-node/restart_notice.mjs

@@ -15,6 +15,9 @@ export function cleanRestartDetail(detail = '', ttsVoice = '') {
       .trim();
   }
   return raw
+    .replace(/\bI applied this change:\s*/igu, '')
+    .replace(/\bRestarting now\b[.!?\s]*/igu, '')
+    .replace(/\bVoice may cut out briefly\b[.!?\s]*/igu, '')
     .replace(/이제\s*재시작할게[.!?。！？\s]*/gu, '')
     .replace(/잠깐\s*음성이\s*끊길\s*수\s*있어[.!?。！？\s]*/gu, '')
     .replace(/\s+/g, ' ')

package/app-node/restart_notice.test.mjs

@@ -35,3 +35,14 @@ test('restart detail strips restart boilerplate before formatting', () => {
     '재시작 완료. 다시 온라인이야. 에이전트 안내 고쳤어.',
   );
 });
+
+test('Korean restart detail strips stale English restart boilerplate', () => {
+  assert.equal(
+    cleanRestartDetail('I applied this change: OmniVoice 한국어 설정 반영. Restarting now. Voice may cut out briefly.', 'ko-KR-InJoonNeural'),
+    'OmniVoice 한국어 설정 반영.',
+  );
+  assert.equal(
+    formatRestartCompleteNotice('I applied this change: OmniVoice 한국어 설정 반영. Restarting now. Voice may cut out briefly.', 'ko-KR-InJoonNeural').speech,
+    '재시작 완료. 다시 온라인이야. OmniVoice 한국어 설정 반영.',
+  );
+});

package/app-node/session_ontology.mjs

@@ -0,0 +1,271 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const SCHEMA_VERSION = 1;
+const NODE_TYPES = new Set(['D', 'F', 'T', 'C', 'A', 'R']);
+const EDGE_PREDICATES = new Set(['d', 't', 'u', 'p', 'r', 's']);
+const TYPE_LABELS = {
+  D: { en: 'Decision', ko: '결정' },
+  F: { en: 'File', ko: '파일' },
+  T: { en: 'Tool', ko: '도구' },
+  C: { en: 'Concept', ko: '개념' },
+  A: { en: 'Agent', ko: '에이전트' },
+  R: { en: 'Result', ko: '결과' },
+};
+
+const FILE_RE = /\b[a-zA-Z0-9_./-]+\.(?:mjs|js|ts|tsx|jsx|py|md|json|yaml|yml|toml|sh|sql|go|rs|java|kt|swift|c|cpp|h|hpp)\b/g;
+const TOOL_RE = /\b(?:tool|command|cli|npm|yarn|pnpm|pip|cargo|docker|kubectl|gh|git|ffmpeg|whisper-cli|claude|codex|gemini|aider|cursor)\b/gi;
+const DECISION_RE = /\b[a-z][a-z0-9_]{2,}=[\w./-]{1,40}\b/g;
+
+function lc(value) { return String(value || '').trim().toLowerCase(); }
+function nowSec() { return Math.floor(Date.now() / 1000); }
+function safeChannelKey(value) { return String(value || 'default').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64); }
+function defaultRootDir() { return path.join(os.homedir(), '.verbalcoding', 'memory'); }
+function emptyState(channelKey) {
+  return {
+    v: SCHEMA_VERSION,
+    channelKey,
+    nodes: [],
+    edges: [],
+    meta: { updatedAt: nowSec(), nodeCount: 0, edgeCount: 0 },
+  };
+}
+
+export function buildExtractionPrompt({ text, language = 'en', knownNames = [] } = {}) {
+  const en = /^en/i.test(String(language || ''));
+  const lines = [];
+  lines.push(en
+    ? 'Extract a tiny knowledge graph from the message below. Reply ONLY with JSON of shape {"nodes":[{"t":"D|F|T|C|A|R","n":"name"}],"edges":[{"s":"name","p":"d|t|u|p|r|s","o":"name"}]}.'
+    : '아래 메시지에서 작은 지식 그래프를 추출해. JSON만 응답: {"nodes":[{"t":"D|F|T|C|A|R","n":"name"}],"edges":[{"s":"name","p":"d|t|u|p|r|s","o":"name"}]}.');
+  lines.push(en
+    ? 'Types: D=Decision (slot=value), F=File (path), T=Tool (command), C=Concept (noun), A=Agent (backend), R=Result (short summary).'
+    : '타입: D=결정(slot=value), F=파일, T=도구, C=개념, A=에이전트, R=결과 요약.');
+  lines.push(en
+    ? 'Predicates: d=decided, t=touched, u=used, p=produced, r=referenced, s=superseded_by.'
+    : '엣지: d=결정, t=수정, u=사용, p=생성, r=참조, s=덮어쓰기.');
+  if (knownNames.length) {
+    lines.push(en ? `Already known names (prefer these for dedup): ${knownNames.slice(0, 20).join(', ')}` : `이미 등록된 이름(중복 방지에 우선): ${knownNames.slice(0, 20).join(', ')}`);
+  }
+  lines.push(en ? `Message:\n${text}` : `메시지:\n${text}`);
+  lines.push(en ? 'Return ONLY the JSON object, no markdown.' : 'JSON 객체만 반환, 마크다운 없이.');
+  return lines.join('\n\n');
+}
+
+export function parseExtractionJson(raw) {
+  const t = String(raw || '').trim();
+  const fenceMatch = t.match(/```(?:json)?\s*([\s\S]+?)```/);
+  const body = fenceMatch ? fenceMatch[1] : t;
+  const firstBrace = body.indexOf('{');
+  const lastBrace = body.lastIndexOf('}');
+  if (firstBrace === -1 || lastBrace <= firstBrace) return { nodes: [], edges: [] };
+  try {
+    const parsed = JSON.parse(body.slice(firstBrace, lastBrace + 1));
+    const nodes = Array.isArray(parsed?.nodes) ? parsed.nodes : [];
+    const edges = Array.isArray(parsed?.edges) ? parsed.edges : [];
+    const nameToId = new Map();
+    const parsedNodes = [];
+    for (const n of nodes) {
+      if (!n || !n.t || !n.n) continue;
+      const id = `e_${n.t}_${String(n.n).toLowerCase()}`;
+      nameToId.set(String(n.n).toLowerCase(), id);
+      parsedNodes.push({ id, t: n.t, n: n.n });
+    }
+    const parsedEdges = [];
+    for (const e of edges) {
+      if (!e || !e.p) continue;
+      const s = nameToId.get(String(e.s || '').toLowerCase());
+      const o = nameToId.get(String(e.o || '').toLowerCase());
+      if (!s || !o) continue;
+      parsedEdges.push({ s, p: e.p, o });
+    }
+    return { nodes: parsedNodes, edges: parsedEdges };
+  } catch { return { nodes: [], edges: [] }; }
+}
+
+export function createSessionOntology({ rootDir, channelKey, maxNodes = 40, maxEdges = 80, fsApi = fs } = {}) {
+  const root = rootDir || defaultRootDir();
+  const channel = safeChannelKey(channelKey);
+  const filePath = path.join(root, `${channel}.json`);
+  let state = emptyState(channel);
+  let nextId = 1;
+
+  function nodeKey(node) { return `${node.t}::${lc(node.n)}`; }
+  function findNodeId(t, name) {
+    const key = `${t}::${lc(name)}`;
+    for (const node of state.nodes) if (nodeKey(node) === key) return node.id;
+    return null;
+  }
+  function evictIfNeeded() {
+    while (state.nodes.length > maxNodes) {
+      const idx = state.nodes.findIndex(n => n.t !== 'D');
+      if (idx === -1) break;
+      const evictedId = state.nodes[idx].id;
+      state.nodes.splice(idx, 1);
+      state.edges = state.edges.filter(e => e.s !== evictedId && e.o !== evictedId);
+    }
+    while (state.edges.length > maxEdges) state.edges.shift();
+  }
+
+  function add({ nodes = [], edges = [], supersedes = [] } = {}) {
+    const idMap = new Map();
+    const ts = nowSec();
+    const addedNodes = [];
+    for (const raw of nodes) {
+      if (!raw || !NODE_TYPES.has(raw.t)) continue;
+      const name = String(raw.n || '').trim();
+      if (!name) continue;
+      const existing = findNodeId(raw.t, name);
+      if (existing) { idMap.set(raw.id || existing, existing); continue; }
+      const node = { id: `n${nextId++}`, t: raw.t, n: name.slice(0, 80), ts: raw.ts || ts };
+      if (raw.by) node.by = String(raw.by).slice(0, 24);
+      state.nodes.push(node);
+      idMap.set(raw.id || node.id, node.id);
+      addedNodes.push(node.id);
+    }
+    for (const raw of edges) {
+      if (!raw || !EDGE_PREDICATES.has(raw.p)) continue;
+      const s = idMap.get(raw.s) || raw.s;
+      const o = idMap.get(raw.o) || raw.o;
+      if (!s || !o) continue;
+      const exists = state.edges.some(e => e.s === s && e.p === raw.p && e.o === o);
+      if (exists) continue;
+      state.edges.push({ s, p: raw.p, o, ts: raw.ts || ts });
+    }
+    for (const sup of supersedes) {
+      if (!sup) continue;
+      const oldId = idMap.get(sup.old) || sup.old;
+      const newId = idMap.get(sup.new) || sup.new;
+      if (!oldId || !newId) continue;
+      state.edges.push({ s: newId, p: 's', o: oldId, ts });
+    }
+    evictIfNeeded();
+    state.meta = { updatedAt: ts, nodeCount: state.nodes.length, edgeCount: state.edges.length };
+    return addedNodes;
+  }
+
+  function supersededIds() {
+    const sup = new Set();
+    for (const edge of state.edges) if (edge.p === 's') sup.add(edge.o);
+    return sup;
+  }
+  function neighborsOf(nodeIds) {
+    const out = new Set();
+    const ids = nodeIds instanceof Set ? nodeIds : new Set(nodeIds);
+    for (const edge of state.edges) {
+      if (ids.has(edge.s)) out.add(edge.o);
+      if (ids.has(edge.o)) out.add(edge.s);
+    }
+    return out;
+  }
+
+  function serializeForHandoff({ language = 'en', maxBytes = 1500 } = {}) {
+    const en = /^en/i.test(String(language || ''));
+    const labels = en
+      ? { decisions: 'Active decisions', touched: 'Relevant files', tools: 'Tools in play', results: 'Recent results', empty: '(no prior session context)' }
+      : { decisions: '활성 결정', touched: '관련 파일', tools: '사용 도구', results: '최근 결과', empty: '(이전 세션 컨텍스트 없음)' };
+    const sup = supersededIds();
+    const live = state.nodes.filter(n => !sup.has(n.id));
+    if (!live.length) return labels.empty;
+    const decisionNodes = live.filter(n => n.t === 'D');
+    const decisionIds = new Set(decisionNodes.map(n => n.id));
+    const nearby = neighborsOf(decisionIds);
+    const fileNodes = live.filter(n => n.t === 'F' && nearby.has(n.id));
+    const toolNodes = live.filter(n => n.t === 'T' && nearby.has(n.id));
+    const resultNodes = live.filter(n => n.t === 'R').sort((a, b) => b.ts - a.ts).slice(0, 3);
+    const lines = [];
+    if (decisionNodes.length) {
+      lines.push(`### ${labels.decisions}`);
+      for (const n of decisionNodes.slice(-8)) lines.push(`- ${n.n}${n.by ? ` _(by ${n.by})_` : ''}`);
+    }
+    if (fileNodes.length) {
+      lines.push(`### ${labels.touched}`);
+      for (const n of fileNodes.slice(-6)) lines.push(`- ${n.n}`);
+    }
+    if (toolNodes.length) {
+      lines.push(`### ${labels.tools}`);
+      for (const n of toolNodes.slice(-6)) lines.push(`- ${n.n}`);
+    }
+    if (resultNodes.length) {
+      lines.push(`### ${labels.results}`);
+      for (const n of resultNodes) lines.push(`- ${n.n}${n.by ? ` _(${n.by})_` : ''}`);
+    }
+    let out = lines.join('\n');
+    if (Buffer.byteLength(out, 'utf8') > maxBytes) out = out.slice(0, maxBytes - 4) + '\n...';
+    return out;
+  }
+
+  function entitiesFromText(text, { by = '', kind = 'utterance' } = {}) {
+    const t = String(text || '');
+    if (!t.trim()) return { nodes: [], edges: [] };
+    const nodes = [];
+    const edges = [];
+    const seenFile = new Set();
+    const seenTool = new Set();
+    const seenDecision = new Set();
+    for (const match of t.matchAll(FILE_RE)) {
+      const name = match[0];
+      if (seenFile.has(name)) continue;
+      seenFile.add(name);
+      nodes.push({ id: `f_${name}`, t: 'F', n: name, by });
+    }
+    for (const match of t.matchAll(TOOL_RE)) {
+      const tool = match[0].toLowerCase();
+      if (seenTool.has(tool)) continue;
+      seenTool.add(tool);
+      nodes.push({ id: `t_${tool}`, t: 'T', n: tool, by });
+    }
+    for (const match of t.matchAll(DECISION_RE)) {
+      const decision = match[0];
+      if (seenDecision.has(decision)) continue;
+      seenDecision.add(decision);
+      const id = `d_${decision}`;
+      nodes.push({ id, t: 'D', n: decision, by });
+      for (const fn of seenFile) edges.push({ s: id, p: 't', o: `f_${fn}` });
+      for (const tn of seenTool) edges.push({ s: id, p: 'u', o: `t_${tn}` });
+    }
+    if (kind === 'result' && t.trim()) {
+      const summary = t.trim().replace(/\s+/g, ' ').slice(0, 80);
+      nodes.push({ id: `r_${nowSec()}_${Math.random().toString(16).slice(2, 8)}`, t: 'R', n: summary, by });
+    }
+    return { nodes, edges };
+  }
+
+  function save() {
+    try {
+      fsApi.mkdirSync(root, { recursive: true });
+      const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+      fsApi.writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+      fsApi.renameSync(tmp, filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function load() {
+    try {
+      const raw = fsApi.readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && parsed.v === SCHEMA_VERSION && parsed.channelKey === channel) {
+        state = parsed;
+        for (const node of state.nodes) {
+          const m = String(node.id || '').match(/^n(\d+)$/);
+          if (m) nextId = Math.max(nextId, Number(m[1]) + 1);
+        }
+        return true;
+      }
+    } catch {}
+    state = emptyState(channel);
+    return false;
+  }
+  function snapshot() { return JSON.parse(JSON.stringify(state)); }
+  function reset() { state = emptyState(channel); nextId = 1; }
+
+  return {
+    add, entitiesFromText, serializeForHandoff, save, load, snapshot, reset,
+    get nodeCount() { return state.nodes.length; },
+    get edgeCount() { return state.edges.length; },
+    get filePath() { return filePath; },
+    get typeLabels() { return TYPE_LABELS; },
+  };
+}