verbalcoding 0.2.11 → 0.2.13

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; },
+  };
+}

package/app-node/session_ontology.test.mjs

@@ -0,0 +1,130 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createSessionOntology, buildExtractionPrompt, parseExtractionJson } from './session_ontology.mjs';
+
+const __tempRoots = [];
+test.after(() => {
+  for (const root of __tempRoots) try { fs.rmSync(root, { recursive: true, force: true }); } catch {}
+});
+
+function tmpDir(label) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `vc-onto-${label}-`));
+  __tempRoots.push(root);
+  return root;
+}
+
+test('add inserts nodes and dedupes by (type, lowercase name)', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('dedup'), channelKey: 'voice/1' });
+  ontology.add({ nodes: [{ t: 'D', n: 'OAUTH_PROVIDER=github' }, { t: 'D', n: 'oauth_provider=github' }] });
+  assert.equal(ontology.nodeCount, 1);
+});
+
+test('add applies supersede edges without deleting old node', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('supersede'), channelKey: 'voice/2' });
+  ontology.add({
+    nodes: [
+      { id: 'a', t: 'D', n: 'session_store=memory' },
+      { id: 'b', t: 'D', n: 'session_store=redis' },
+    ],
+    supersedes: [{ old: 'a', new: 'b' }],
+  });
+  assert.equal(ontology.nodeCount, 2);
+  const md = ontology.serializeForHandoff({ language: 'en' });
+  assert.match(md, /session_store=redis/);
+  assert.doesNotMatch(md, /session_store=memory/);
+});
+
+test('LRU eviction keeps decisions sticky', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('lru'), channelKey: 'voice/3', maxNodes: 3 });
+  ontology.add({ nodes: [{ t: 'D', n: 'a=1' }, { t: 'F', n: 'app.mjs' }, { t: 'F', n: 'lib.mjs' }] });
+  assert.equal(ontology.nodeCount, 3);
+  ontology.add({ nodes: [{ t: 'F', n: 'main.mjs' }] });
+  assert.equal(ontology.nodeCount, 3);
+  const snap = ontology.snapshot();
+  assert.ok(snap.nodes.some(n => n.t === 'D'), 'decision survives eviction');
+});
+
+test('entitiesFromText extracts files, tools, decisions', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('extract'), channelKey: 'voice/4' });
+  const out = ontology.entitiesFromText(
+    'Updated app/main.mjs and ran npm test. We settled oauth_provider=github.',
+    { by: 'claude' },
+  );
+  const types = out.nodes.map(n => n.t).sort();
+  assert.ok(types.includes('F'), 'has file node');
+  assert.ok(types.includes('T'), 'has tool node');
+  assert.ok(types.includes('D'), 'has decision node');
+  const decision = out.nodes.find(n => n.t === 'D');
+  assert.match(decision.n, /oauth_provider=github/);
+});
+
+test('serializeForHandoff returns empty marker on empty ontology', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('empty'), channelKey: 'voice/5' });
+  assert.match(ontology.serializeForHandoff({ language: 'en' }), /no prior session context/);
+  assert.match(ontology.serializeForHandoff({ language: 'ko' }), /이전 세션 컨텍스트 없음/);
+});
+
+test('serializeForHandoff groups decisions, files, tools, results', () => {
+  const ontology = createSessionOntology({ rootDir: tmpDir('serialize'), channelKey: 'voice/6' });
+  const { nodes, edges } = ontology.entitiesFromText(
+    'Touched app-node/main.mjs with git commit. oauth_provider=github decided.',
+    { by: 'claude' },
+  );
+  ontology.add({ nodes, edges });
+  ontology.add({ nodes: [{ t: 'R', n: 'OAuth wired up successfully', by: 'codex' }] });
+  const md = ontology.serializeForHandoff({ language: 'en' });
+  assert.match(md, /Active decisions/);
+  assert.match(md, /oauth_provider=github/);
+  assert.match(md, /Relevant files/);
+  assert.match(md, /main\.mjs/);
+  assert.match(md, /Recent results/);
+});
+
+test('buildExtractionPrompt mentions the schema and the message body', () => {
+  const p = buildExtractionPrompt({ text: 'Routed to codex for the auth refactor', language: 'en' });
+  assert.match(p, /JSON of shape/);
+  assert.match(p, /D=Decision/);
+  assert.match(p, /auth refactor/);
+});
+
+test('parseExtractionJson recovers JSON from fenced output', () => {
+  const raw = '```json\n{"nodes":[{"t":"D","n":"db=postgres"}],"edges":[]}\n```';
+  const out = parseExtractionJson(raw);
+  assert.equal(out.nodes.length, 1);
+  assert.equal(out.nodes[0].t, 'D');
+  assert.equal(out.nodes[0].n, 'db=postgres');
+});
+
+test('parseExtractionJson tolerates surrounding prose', () => {
+  const raw = 'Sure, here is the graph: {"nodes":[{"t":"F","n":"app.mjs"}],"edges":[]} let me know if you need more.';
+  const out = parseExtractionJson(raw);
+  assert.equal(out.nodes.length, 1);
+});
+
+test('parseExtractionJson resolves edge endpoints by name to canonical node ids', () => {
+  const raw = '{"nodes":[{"t":"D","n":"db=postgres"},{"t":"F","n":"schema.sql"}],"edges":[{"s":"db=postgres","p":"t","o":"schema.sql"}]}';
+  const out = parseExtractionJson(raw);
+  assert.equal(out.nodes.length, 2);
+  assert.equal(out.edges.length, 1);
+  assert.equal(out.edges[0].s, 'e_D_db=postgres');
+  assert.equal(out.edges[0].o, 'e_F_schema.sql');
+});
+
+test('parseExtractionJson returns empty on garbage input', () => {
+  const out = parseExtractionJson('totally not json');
+  assert.deepEqual(out, { nodes: [], edges: [] });
+});
+
+test('save/load round-trips state to disk', () => {
+  const root = tmpDir('persist');
+  const ontology = createSessionOntology({ rootDir: root, channelKey: 'voice/7' });
+  ontology.add({ nodes: [{ t: 'D', n: 'db=postgres', by: 'claude' }] });
+  assert.ok(ontology.save());
+  const restored = createSessionOntology({ rootDir: root, channelKey: 'voice/7' });
+  assert.ok(restored.load());
+  assert.equal(restored.nodeCount, 1);
+  assert.match(restored.serializeForHandoff({ language: 'en' }), /db=postgres/);
+});

package/app-node/smart_progress.mjs

@@ -0,0 +1,94 @@
+import { EventEmitter } from 'node:events';
+
+const DEFAULT_BASE = 'https://api.groq.com/openai/v1';
+
+export function createSmartProgressSummarizer({
+  apiKey = '',
+  baseUrl = DEFAULT_BASE,
+  model = 'llama-3.1-8b-instant',
+  windowMs = 4000,
+  language = 'en',
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 1500,
+  cacheMs = 60_000,
+  maxBatch = 8,
+} = {}) {
+  const ee = new EventEmitter();
+  let buffer = [];
+  let timer = null;
+  const cache = new Map();
+
+  function emitRaw(events) {
+    for (const e of events) ee.emit('summary', e);
+  }
+
+  async function summarize(events) {
+    const key = `${language}::${events.join('|')}`;
+    const cached = cache.get(key);
+    if (cached && Date.now() - cached.t < cacheMs) return cached.text;
+    const ctl = new AbortController();
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        try { ctl.abort(); } catch {}
+        reject(new Error('smart_progress timeout'));
+      }, timeoutMs);
+    });
+    const sysLang = language === 'ko' ? 'Korean' : 'English';
+    const requestPromise = (async () => {
+      const res = await fetchImpl(`${baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+        signal: ctl.signal,
+        body: JSON.stringify({
+          model,
+          temperature: 0.2,
+          max_tokens: 40,
+          messages: [
+            { role: 'system', content: `Summarize a coding agent's recent actions in one short ${sysLang} sentence. No file paths unless essential. No quotes.` },
+            { role: 'user', content: events.join('\n') },
+          ],
+        }),
+      });
+      const data = await res.json();
+      return String(data?.choices?.[0]?.message?.content || '').trim();
+    })();
+    try {
+      const text = await Promise.race([requestPromise, timeoutPromise]);
+      if (text) cache.set(key, { text, t: Date.now() });
+      return text;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  function flush() {
+    timer = null;
+    const events = buffer;
+    buffer = [];
+    if (!events.length) return;
+    if (!apiKey || typeof fetchImpl !== 'function') {
+      emitRaw(events);
+      return;
+    }
+    summarize(events)
+      .then(text => ee.emit('summary', text || events[events.length - 1]))
+      .catch(() => emitRaw(events));
+  }
+
+  return {
+    on: (event, fn) => ee.on(event, fn),
+    ingest(event) {
+      const e = String(event || '').trim();
+      if (!e) return;
+      buffer.push(e);
+      if (buffer.length >= maxBatch) {
+        if (timer) { clearTimeout(timer); timer = null; }
+        flush();
+        return;
+      }
+      if (!timer) timer = setTimeout(flush, windowMs);
+    },
+    setLanguage(lang) { language = lang; },
+  };
+}

package/app-node/smart_progress.test.mjs

@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createSmartProgressSummarizer } from './smart_progress.mjs';
+
+test('falls back to raw events when no apiKey', async () => {
+  const out = [];
+  const s = createSmartProgressSummarizer({ windowMs: 10 });
+  s.on('summary', t => out.push(t));
+  s.ingest('reading files routes.ts');
+  s.ingest('editing files routes.ts');
+  await new Promise(r => setTimeout(r, 40));
+  assert.ok(out.includes('reading files routes.ts'));
+  assert.ok(out.includes('editing files routes.ts'));
+});
+
+test('calls fetch with correct headers and body when apiKey is set', async () => {
+  const calls = [];
+  const fakeFetch = async (url, opts) => {
+    calls.push({ url, opts });
+    return { json: async () => ({ choices: [{ message: { content: 'Wiring the new login endpoint.' } }] }) };
+  };
+  const out = [];
+  const s = createSmartProgressSummarizer({
+    apiKey: 'k',
+    fetchImpl: fakeFetch,
+    windowMs: 10,
+    timeoutMs: 200,
+  });
+  s.on('summary', t => out.push(t));
+  s.ingest('reading auth.ts');
+  s.ingest('editing routes.ts');
+  await new Promise(r => setTimeout(r, 80));
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].url, /chat\/completions$/);
+  assert.equal(calls[0].opts.headers.authorization, 'Bearer k');
+  assert.deepEqual(out, ['Wiring the new login endpoint.']);
+});
+
+test('timeout falls back to raw events', async () => {
+  const slowFetch = () => new Promise(() => {});
+  const out = [];
+  const s = createSmartProgressSummarizer({
+    apiKey: 'k',
+    fetchImpl: slowFetch,
+    windowMs: 10,
+    timeoutMs: 30,
+  });
+  s.on('summary', t => out.push(t));
+  s.ingest('reading auth.ts');
+  s.ingest('editing routes.ts');
+  await new Promise(r => setTimeout(r, 120));
+  assert.ok(out.length >= 2);
+  assert.ok(out.includes('reading auth.ts'));
+});
+
+test('maxBatch triggers immediate flush', async () => {
+  const out = [];
+  const s = createSmartProgressSummarizer({ windowMs: 999999, maxBatch: 3 });
+  s.on('summary', t => out.push(t));
+  s.ingest('a');
+  s.ingest('b');
+  assert.equal(out.length, 0);
+  s.ingest('c');
+  await new Promise(r => setTimeout(r, 5));
+  assert.deepEqual(out, ['a', 'b', 'c']);
+});

package/app-node/stream_sentencer.mjs

@@ -0,0 +1,91 @@
+import { EventEmitter } from 'node:events';
+
+const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const BOX_RE = /[╭╮╰╯│┊─]/g;
+const PROGRESS_LINE_RE = /^VERBALCODING_PROGRESS\s*:.*$/i;
+const TERMINAL_RE = /(?<!\b(?:e\.g|i\.e|etc|cf|Mr|Mrs|Dr|Sr|Jr|St|Mt|vs|approx|al|aka|fig|eqn|inc|ltd|co))[.!?。！？…]+["'\)\]\}」』]*(?=\s|$)/;
+
+function clean(text) {
+  return String(text || '')
+    .replace(ANSI_RE, '')
+    .split(/\r?\n/)
+    .filter(line => !PROGRESS_LINE_RE.test(line.trim()))
+    .join('\n')
+    .replace(BOX_RE, '')
+    .replace(/[ \t]+/g, ' ');
+}
+
+export function createSentencer({ minChars = 40, maxLatencyMs = 800 } = {}) {
+  const ee = new EventEmitter();
+  let buffer = '';
+  let inFence = false;
+  let pendingFenceTail = '';
+  let lastEmit = Date.now();
+
+  function emit(text) {
+    const trimmed = String(text || '').trim();
+    if (!trimmed) return;
+    ee.emit('sentence', trimmed);
+    lastEmit = Date.now();
+  }
+
+  function trailingBackticks(text) {
+    let n = 0;
+    for (let i = text.length - 1; i >= 0 && text[i] === '`' && n < 2; i -= 1) n += 1;
+    return n;
+  }
+
+  function ingest(text) {
+    let remaining = pendingFenceTail + text;
+    pendingFenceTail = '';
+    while (remaining.length > 0) {
+      const fence = remaining.indexOf('```');
+      if (fence === -1) {
+        const heldCount = trailingBackticks(remaining);
+        const safe = heldCount > 0 ? remaining.slice(0, remaining.length - heldCount) : remaining;
+        pendingFenceTail = heldCount > 0 ? remaining.slice(remaining.length - heldCount) : '';
+        if (!inFence) buffer += safe;
+        return;
+      }
+      const before = remaining.slice(0, fence);
+      if (!inFence) buffer += before;
+      inFence = !inFence;
+      remaining = remaining.slice(fence + 3);
+    }
+  }
+
+  function scan() {
+    while (true) {
+      const match = buffer.match(TERMINAL_RE);
+      if (!match) break;
+      const end = match.index + match[0].length;
+      const sentence = buffer.slice(0, end);
+      buffer = buffer.slice(end).replace(/^\s+/, '');
+      emit(sentence);
+    }
+    if (buffer.length >= minChars && Date.now() - lastEmit >= maxLatencyMs) {
+      const cut = buffer.lastIndexOf(' ');
+      if (cut > Math.floor(minChars / 2)) {
+        emit(buffer.slice(0, cut));
+        buffer = buffer.slice(cut).trim();
+      }
+    }
+  }
+
+  return {
+    on: (event, fn) => ee.on(event, fn),
+    push(text) {
+      const cleaned = clean(text);
+      if (!cleaned) return;
+      ingest(cleaned);
+      scan();
+    },
+    flush() {
+      if (!inFence) buffer += pendingFenceTail;
+      pendingFenceTail = '';
+      emit(buffer);
+      buffer = '';
+      inFence = false;
+    },
+  };
+}