verbalcoding 0.2.11 → 0.2.12

package/app-node/notify.mjs

@@ -0,0 +1,73 @@
+const SECRET_RE = /\b(?:token|api[_-]?key|password|secret|authorization|bearer)\b\s*[:=]?\s*\S+/gi;
+const SK_RE = /\bsk-[a-zA-Z0-9_-]{8,}\b/g;
+const NTFY_BASE_DEFAULT = 'https://ntfy.sh';
+
+function redact(text) {
+  return String(text || '')
+    .replace(SECRET_RE, '$& [REDACTED]')
+    .replace(/(\[REDACTED\]\s*)+/g, '[REDACTED] ')
+    .replace(SK_RE, '[REDACTED]');
+}
+
+export function buildDiscordDeepLink({ guildId, channelId } = {}) {
+  if (!guildId || !channelId) return '';
+  return `https://discord.com/channels/${guildId}/${channelId}`;
+}
+
+export function createNotifier({
+  provider = 'ntfy',
+  topic = '',
+  fetchImpl = globalThis.fetch,
+  ntfyBase = NTFY_BASE_DEFAULT,
+  pushoverUser = '',
+  pushoverToken = '',
+} = {}) {
+  async function sendNtfy({ title, body, deepLink }) {
+    if (!topic) return { skipped: true, reason: 'no topic' };
+    const headers = { Title: title };
+    if (deepLink) headers.Click = deepLink;
+    const res = await fetchImpl(`${ntfyBase}/${encodeURIComponent(topic)}`, {
+      method: 'POST',
+      headers,
+      body,
+    });
+    return { ok: !!res?.ok, status: res?.status };
+  }
+
+  async function sendPushover({ title, body, deepLink }) {
+    if (!pushoverUser || !pushoverToken) return { skipped: true, reason: 'no pushover creds' };
+    const payload = {
+      user: pushoverUser,
+      token: pushoverToken,
+      title,
+      message: body,
+    };
+    if (deepLink) {
+      payload.url = deepLink;
+      payload.url_title = 'Open Discord';
+    }
+    const res = await fetchImpl('https://api.pushover.net/1/messages.json', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return { ok: !!res?.ok, status: res?.status };
+  }
+
+  async function send({ title = 'VerbalCoding', body = '', deepLink = '' } = {}) {
+    const safeBody = redact(body).slice(0, 200);
+    const safeTitle = redact(title).slice(0, 80);
+    if (provider === 'ntfy') return sendNtfy({ title: safeTitle, body: safeBody, deepLink });
+    if (provider === 'pushover') return sendPushover({ title: safeTitle, body: safeBody, deepLink });
+    if (provider === 'noop') return { ok: true };
+    throw new Error(`unknown notify provider ${provider}`);
+  }
+
+  function shouldNotify({ humanCount = 0, taskMs = 0, minTaskMs = 60_000, userOptIn = false } = {}) {
+    if (taskMs < minTaskMs) return false;
+    if (userOptIn) return true;
+    return humanCount === 0;
+  }
+
+  return { send, shouldNotify };
+}

package/app-node/notify.test.mjs

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotifier, buildDiscordDeepLink } from './notify.mjs';
+
+test('ntfy provider posts to topic URL with title body and click headers', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push({ url, opts }); return { ok: true, status: 200 }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'verbalcoding-test', fetchImpl });
+  const res = await n.send({ title: 'Done', body: 'All green.', deepLink: 'discord://x' });
+  assert.equal(res.ok, true);
+  assert.equal(calls.length, 1);
+  assert.match(calls[0].url, /ntfy\.sh\/verbalcoding-test/);
+  assert.equal(calls[0].opts.headers.Title, 'Done');
+  assert.equal(calls[0].opts.headers.Click, 'discord://x');
+  assert.equal(calls[0].opts.body, 'All green.');
+});
+
+test('ntfy returns skipped when topic missing', async () => {
+  const n = createNotifier({ provider: 'ntfy', fetchImpl: async () => ({ ok: true }) });
+  const res = await n.send({ title: 't', body: 'b' });
+  assert.equal(res.skipped, true);
+});
+
+test('shouldNotify true when zero humans and task long enough', () => {
+  const n = createNotifier({ provider: 'noop' });
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 10_000, minTaskMs: 1000 }), true);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 0, taskMs: 100, minTaskMs: 1000 }), false);
+  assert.equal(n.shouldNotify({ humanCount: 1, taskMs: 10_000, minTaskMs: 1000, userOptIn: true }), true);
+});
+
+test('redacts secret patterns from body', async () => {
+  const calls = [];
+  const fetchImpl = async (u, o) => { calls.push(o); return { ok: true }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl });
+  await n.send({ title: 't', body: 'token=abc123 finished. sk-fooBar12 also.', deepLink: '' });
+  assert.match(calls[0].body, /\[REDACTED\]/);
+  assert.doesNotMatch(calls[0].body, /sk-fooBar12/);
+});
+
+test('truncates long body to 200 chars', async () => {
+  const calls = [];
+  const fetchImpl = async (u, o) => { calls.push(o); return { ok: true }; };
+  const n = createNotifier({ provider: 'ntfy', topic: 'x', fetchImpl });
+  await n.send({ title: 't', body: 'x'.repeat(500) });
+  assert.equal(calls[0].body.length, 200);
+});
+
+test('pushover posts json payload with url', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => { calls.push({ url, opts }); return { ok: true, status: 200 }; };
+  const n = createNotifier({ provider: 'pushover', pushoverUser: 'u', pushoverToken: 'tk', fetchImpl });
+  await n.send({ title: 'Done', body: 'all good', deepLink: 'discord://x' });
+  assert.match(calls[0].url, /pushover\.net/);
+  const body = JSON.parse(calls[0].opts.body);
+  assert.equal(body.user, 'u');
+  assert.equal(body.url, 'discord://x');
+});
+
+test('buildDiscordDeepLink composes web URL', () => {
+  assert.equal(buildDiscordDeepLink({ guildId: '1', channelId: '2' }), 'https://discord.com/channels/1/2');
+  assert.equal(buildDiscordDeepLink({}), '');
+});
+
+test('unknown provider throws', async () => {
+  const n = createNotifier({ provider: 'unknown' });
+  await assert.rejects(() => n.send({ title: 't', body: 'b' }), /unknown notify provider/);
+});

package/app-node/plan_mode.mjs

@@ -0,0 +1,174 @@
+const PLAN_RE = /PLAN_BEGIN\s*\n([\s\S]*?)\nPLAN_END/;
+const DECISIONS_RE = /DECISIONS_BEGIN\s*\n([\s\S]*?)\nDECISIONS_END/;
+
+const SKIP_EN = /\bskip\s+step\s+(\d+)\b/i;
+const SKIP_KO = /step\s*(\d+)\s*건너뛰/i;
+const ADD_EN = /\badd\s+(.+?)\s+after\s+step\s+(\d+)\b/i;
+const ADD_KO = /step\s*(\d+)\s*다음에\s+(.+?)\s*추가/i;
+const APPROVE_EN = /\b(approve|go\s*ahead|let'?s\s+go|run\s+it|proceed)\b/i;
+const APPROVE_KO = /(실행|진행|승인)/i;
+const CANCEL_EN = /\b(cancel|stop|nevermind|never\s+mind)\b/i;
+const CANCEL_KO = /(취소|그만)/i;
+const ENTER_EN = /\b(plan\s+(it\s+)?first|make\s+a\s+plan)\b/i;
+const ENTER_KO = /(먼저\s*계획|계획\s*먼저|계획부터)/i;
+
+export function parsePlanOutput(text) {
+  const planMatch = String(text || '').match(PLAN_RE);
+  if (!planMatch) return { steps: [], decisions: [] };
+  const steps = planMatch[1]
+    .split(/\r?\n/)
+    .map(line => line.match(/^\s*(\d+)\.\s*(.+)$/))
+    .filter(Boolean)
+    .map(m => ({ id: Number(m[1]), text: m[2].trim(), status: 'pending' }));
+  const decisions = parseDecisions(String(text || ''));
+  return { steps, decisions };
+}
+
+export function parseDecisions(text) {
+  const match = String(text || '').match(DECISIONS_RE);
+  if (!match) return [];
+  const out = [];
+  let counter = 1;
+  for (const raw of match[1].split(/\r?\n/)) {
+    const line = raw.replace(/^\s*-\s*/, '').trim();
+    if (!line) continue;
+    const parts = line.split('|').map(s => s.trim()).filter(Boolean);
+    if (parts.length < 3) continue;
+    const [slot, question, ...options] = parts;
+    out.push({
+      slot: slot || `decision_${counter++}`,
+      question,
+      options: options.filter(Boolean),
+    });
+  }
+  return out;
+}
+
+const ORDINAL_EN = { first: 1, second: 2, third: 3, fourth: 4, fifth: 5, '1st': 1, '2nd': 2, '3rd': 3 };
+const ORDINAL_KO = { '첫': 1, '첫번째': 1, '첫 번째': 1, '두번째': 2, '두 번째': 2, '세번째': 3, '세 번째': 3, '네번째': 4 };
+const DEFER_RE = /\b(either|whatever|you\s+(decide|pick|choose)|agent\s+(decides|picks)|up\s+to\s+you|no\s+preference)\b|아무거나|네가\s*골라|마음대로|상관없|알아서/i;
+
+export function parseDecisionAnswer(utterance, decision, language = 'en') {
+  const text = String(utterance || '').trim();
+  if (!text || !decision || !Array.isArray(decision.options) || decision.options.length === 0) {
+    return { type: 'unknown', choice: null };
+  }
+  const lower = text.toLowerCase();
+  if (DEFER_RE.test(text)) return { type: 'auto', choice: null };
+  for (const opt of decision.options) {
+    const optLower = String(opt).toLowerCase();
+    if (lower.includes(optLower) && optLower.length >= 2) return { type: 'option', choice: opt };
+  }
+  const numMatch = text.match(/\b(\d+)\b/);
+  if (numMatch) {
+    const idx = Number(numMatch[1]);
+    if (idx >= 1 && idx <= decision.options.length) return { type: 'option', choice: decision.options[idx - 1] };
+  }
+  for (const [word, idx] of Object.entries(ORDINAL_EN)) {
+    if (lower.includes(word)) {
+      if (idx <= decision.options.length) return { type: 'option', choice: decision.options[idx - 1] };
+    }
+  }
+  for (const [word, idx] of Object.entries(ORDINAL_KO)) {
+    if (text.includes(word)) {
+      if (idx <= decision.options.length) return { type: 'option', choice: decision.options[idx - 1] };
+    }
+  }
+  return { type: 'unknown', choice: null };
+}
+
+export function renderDecisionPrompt(decision, language = 'en') {
+  if (!decision) return '';
+  const opts = decision.options.map((o, i) => `${i + 1}) ${o}`).join('  ');
+  if (/^en/i.test(String(language || ''))) {
+    return `${decision.question} Options: ${opts}. Or say "either" to let me pick.`;
+  }
+  return `${decision.question} 옵션: ${opts}. "아무거나"라고 하면 내가 고를게.`;
+}
+
+export function renderResolvedDecisions(resolved, language = 'en') {
+  const keys = Object.keys(resolved || {});
+  if (!keys.length) return '';
+  const parts = keys.map(k => `${k}=${resolved[k] === null ? '(agent picks)' : resolved[k]}`);
+  return /^en/i.test(String(language || ''))
+    ? `Resolved decisions: ${parts.join(', ')}.`
+    : `결정 사항: ${parts.join(', ')}.`;
+}
+
+export function isPlanEntryUtterance(text, language = 'en') {
+  const t = String(text || '');
+  if (language === 'ko') return ENTER_KO.test(t) || ENTER_EN.test(t);
+  return ENTER_EN.test(t) || ENTER_KO.test(t);
+}
+
+export function parseVoiceCommand(text, language = 'en') {
+  const t = String(text || '').trim();
+  let m = t.match(SKIP_EN) || t.match(SKIP_KO);
+  if (m) return { type: 'skip', index: Number(m[1]) };
+  m = t.match(ADD_EN);
+  if (m) return { type: 'insert', after: Number(m[2]), text: m[1].trim() };
+  m = t.match(ADD_KO);
+  if (m) return { type: 'insert', after: Number(m[1]), text: m[2].trim() };
+  if (APPROVE_EN.test(t) || APPROVE_KO.test(t)) return { type: 'approve' };
+  if (CANCEL_EN.test(t) || CANCEL_KO.test(t)) return { type: 'cancel' };
+  return { type: 'unknown' };
+}
+
+export function applyCommand(steps, cmd) {
+  if (!Array.isArray(steps)) return [];
+  if (cmd.type === 'skip') {
+    return steps.map(s => (s.id === cmd.index ? { ...s, status: 'skipped' } : s));
+  }
+  if (cmd.type === 'insert') {
+    const out = [];
+    for (const s of steps) {
+      out.push(s);
+      if (s.id === cmd.after) {
+        out.push({ id: s.id + 0.5, text: cmd.text, status: 'added' });
+      }
+    }
+    return out;
+  }
+  return steps;
+}
+
+export function renderFinalPlan(steps) {
+  const active = (steps || []).filter(s => s.status !== 'skipped');
+  return active.map((s, i) => `${i + 1}. ${s.text}`).join('\n');
+}
+
+export function planModePreamble(language = 'en') {
+  if (language === 'ko') {
+    return [
+      '지금은 PLAN MODE다. 파일을 절대 수정하지 마라.',
+      '아래 형식으로 짧은 계획을 답하고, 결정이 필요한 분기마다 DECISIONS 블록에 질문을 적어라.',
+      'PLAN_BEGIN',
+      '1. ...',
+      '2. ...',
+      'PLAN_END',
+      'DECISIONS_BEGIN',
+      '- <slot> | <한 문장 질문> | <옵션1> | <옵션2> | ...',
+      'DECISIONS_END',
+      '각 단계는 12단어 이하 한국어 한 줄. slot은 oauth_provider, session_store 같은 짧은 영문 키.',
+      '결정이 필요 없으면 DECISIONS 블록 자체를 생략해라.',
+    ].join('\n');
+  }
+  return [
+    'You are in PLAN MODE. Do NOT modify any files.',
+    'Reply with a short plan AND list any forks/decisions you would normally pick yourself.',
+    'PLAN_BEGIN',
+    '1. ...',
+    '2. ...',
+    'PLAN_END',
+    'DECISIONS_BEGIN',
+    '- <slot> | <one-sentence question> | <option1> | <option2> | ...',
+    'DECISIONS_END',
+    'Each step under 12 words. slot is a short snake_case key (e.g. oauth_provider).',
+    'Omit the DECISIONS block entirely if there is nothing to ask.',
+  ].join('\n');
+}
+
+export function planExecutionPreamble(language = 'en') {
+  if (language === 'ko') return '아래 계획에 따라 작업을 실행해라. 각 단계가 끝나면 다음으로 진행해라.';
+  return 'Execute the following plan. Move to the next step as each one completes.';
+}

package/app-node/plan_mode.test.mjs

@@ -0,0 +1,153 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  parsePlanOutput,
+  parseDecisions,
+  parseDecisionAnswer,
+  renderDecisionPrompt,
+  renderResolvedDecisions,
+  parseVoiceCommand,
+  applyCommand,
+  renderFinalPlan,
+  isPlanEntryUtterance,
+  planModePreamble,
+} from './plan_mode.mjs';
+
+test('parsePlanOutput extracts numbered steps between markers', () => {
+  const out = parsePlanOutput('intro\nPLAN_BEGIN\n1. Read auth.ts\n2. Add login route\n3. Write test\nPLAN_END\nthanks');
+  assert.deepEqual(out.steps.map(s => s.text), ['Read auth.ts', 'Add login route', 'Write test']);
+  assert.equal(out.steps[0].status, 'pending');
+  assert.equal(out.steps[0].id, 1);
+  assert.deepEqual(out.decisions, []);
+});
+
+test('parsePlanOutput returns empty steps when markers missing', () => {
+  assert.deepEqual(parsePlanOutput('no plan here'), { steps: [], decisions: [] });
+});
+
+test('parsePlanOutput extracts decisions block', () => {
+  const text = [
+    'PLAN_BEGIN',
+    '1. Add OAuth',
+    '2. Wire callback',
+    'PLAN_END',
+    'DECISIONS_BEGIN',
+    '- oauth_provider | Which OAuth provider? | google | github | both',
+    '- session_store | Where to store sessions? | redis | memory',
+    'DECISIONS_END',
+  ].join('\n');
+  const out = parsePlanOutput(text);
+  assert.equal(out.steps.length, 2);
+  assert.equal(out.decisions.length, 2);
+  assert.equal(out.decisions[0].slot, 'oauth_provider');
+  assert.deepEqual(out.decisions[0].options, ['google', 'github', 'both']);
+  assert.equal(out.decisions[1].slot, 'session_store');
+});
+
+test('parseDecisions skips malformed lines', () => {
+  const text = 'DECISIONS_BEGIN\n- bad line\n- ok | question | a | b\nDECISIONS_END';
+  const out = parseDecisions(text);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].slot, 'ok');
+});
+
+test('parseDecisionAnswer matches option by name', () => {
+  const decision = { slot: 'x', question: 'Pick one', options: ['redis', 'memory'] };
+  assert.deepEqual(parseDecisionAnswer('use redis', decision), { type: 'option', choice: 'redis' });
+  assert.deepEqual(parseDecisionAnswer('go with memory', decision), { type: 'option', choice: 'memory' });
+});
+
+test('parseDecisionAnswer matches by number and ordinal', () => {
+  const decision = { slot: 'x', question: 'Pick one', options: ['alpha', 'beta', 'gamma'] };
+  assert.deepEqual(parseDecisionAnswer('option 2', decision), { type: 'option', choice: 'beta' });
+  assert.deepEqual(parseDecisionAnswer('the first one', decision), { type: 'option', choice: 'alpha' });
+  assert.deepEqual(parseDecisionAnswer('세번째', decision), { type: 'option', choice: 'gamma' });
+});
+
+test('parseDecisionAnswer detects defer phrases', () => {
+  const decision = { slot: 'x', question: 'q', options: ['a', 'b'] };
+  assert.equal(parseDecisionAnswer('either is fine', decision).type, 'auto');
+  assert.equal(parseDecisionAnswer('you decide', decision).type, 'auto');
+  assert.equal(parseDecisionAnswer('아무거나', decision).type, 'auto');
+});
+
+test('parseDecisionAnswer returns unknown on no match', () => {
+  const decision = { slot: 'x', question: 'q', options: ['alpha', 'beta'] };
+  assert.equal(parseDecisionAnswer('hello world', decision).type, 'unknown');
+});
+
+test('renderDecisionPrompt formats question with numbered options', () => {
+  const decision = { slot: 'x', question: 'Pick auth?', options: ['google', 'github'] };
+  assert.match(renderDecisionPrompt(decision, 'en'), /Pick auth\?\s+Options:\s+1\) google\s+2\) github/);
+});
+
+test('renderResolvedDecisions handles auto choices', () => {
+  const resolved = { provider: 'github', store: null };
+  const out = renderResolvedDecisions(resolved, 'en');
+  assert.match(out, /provider=github/);
+  assert.match(out, /store=\(agent picks\)/);
+});
+
+test('parseVoiceCommand recognizes skip in en and ko', () => {
+  assert.deepEqual(parseVoiceCommand('skip step 3', 'en'), { type: 'skip', index: 3 });
+  assert.deepEqual(parseVoiceCommand('step 2 건너뛰어', 'ko'), { type: 'skip', index: 2 });
+});
+
+test('parseVoiceCommand recognizes insert in en', () => {
+  assert.deepEqual(parseVoiceCommand('add write a test after step 1', 'en'), { type: 'insert', after: 1, text: 'write a test' });
+});
+
+test('parseVoiceCommand recognizes insert in ko', () => {
+  assert.deepEqual(parseVoiceCommand('step 2 다음에 테스트 작성 추가', 'ko'), { type: 'insert', after: 2, text: '테스트 작성' });
+});
+
+test('parseVoiceCommand recognizes approve in both languages', () => {
+  assert.deepEqual(parseVoiceCommand('approve', 'en'), { type: 'approve' });
+  assert.deepEqual(parseVoiceCommand('go ahead', 'en'), { type: 'approve' });
+  assert.deepEqual(parseVoiceCommand('실행', 'ko'), { type: 'approve' });
+});
+
+test('parseVoiceCommand recognizes cancel', () => {
+  assert.deepEqual(parseVoiceCommand('cancel', 'en'), { type: 'cancel' });
+  assert.deepEqual(parseVoiceCommand('취소', 'ko'), { type: 'cancel' });
+});
+
+test('parseVoiceCommand falls through to unknown', () => {
+  assert.deepEqual(parseVoiceCommand('what is the meaning of life', 'en'), { type: 'unknown' });
+});
+
+test('applyCommand skip marks status', () => {
+  const steps = [{ id: 1, text: 'a', status: 'pending' }, { id: 2, text: 'b', status: 'pending' }];
+  const after = applyCommand(steps, { type: 'skip', index: 2 });
+  assert.equal(after[1].status, 'skipped');
+});
+
+test('applyCommand insert places new step after target', () => {
+  const steps = [{ id: 1, text: 'a', status: 'pending' }, { id: 2, text: 'b', status: 'pending' }];
+  const after = applyCommand(steps, { type: 'insert', after: 1, text: 'extra' });
+  assert.equal(after.length, 3);
+  assert.equal(after[1].text, 'extra');
+  assert.equal(after[1].status, 'added');
+  assert.equal(after[2].text, 'b');
+});
+
+test('renderFinalPlan skips skipped steps and renumbers', () => {
+  const steps = [
+    { id: 1, text: 'a', status: 'pending' },
+    { id: 2, text: 'b', status: 'skipped' },
+    { id: 3, text: 'c', status: 'pending' },
+  ];
+  assert.equal(renderFinalPlan(steps), '1. a\n2. c');
+});
+
+test('isPlanEntryUtterance detects entry phrases', () => {
+  assert.equal(isPlanEntryUtterance('plan it first', 'en'), true);
+  assert.equal(isPlanEntryUtterance('make a plan', 'en'), true);
+  assert.equal(isPlanEntryUtterance('먼저 계획 짜줘', 'ko'), true);
+  assert.equal(isPlanEntryUtterance('just do it', 'en'), false);
+});
+
+test('planModePreamble contains PLAN_BEGIN marker', () => {
+  assert.match(planModePreamble('en'), /PLAN_BEGIN/);
+  assert.match(planModePreamble('ko'), /PLAN_BEGIN/);
+});

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 = 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']);
+});