@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/tools/web.js

@@ -0,0 +1,283 @@
+// WebFetch (fetch a page, convert to markdown-ish text, answer a prompt about it with the
+// small model) and WebSearch (DuckDuckGo HTML endpoint with a Bing fallback).
+
+import { quickQuery } from '../api.js';
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36';
+const cache = new Map(); // url -> {at, text, status, bytes}; only successful responses
+
+// Limits, in one object so tests can shrink them.
+export const webLimits = {
+  timeoutMs: 30_000, // for a whole page, headers and body
+  searchTimeoutMs: 20_000,
+  maxBodyBytes: 10 * 1024 * 1024, // the rest of a bigger response is never downloaded
+  cacheMs: 15 * 60_000,
+  cacheEntries: 40,
+  cacheBytes: 60 * 1024 * 1024,
+};
+
+// Content that is not text: a page read as text would be a wall of garbage for the model.
+const BINARY_TYPE = /^(?:image\/(?!svg)|audio\/|video\/|font\/)|^application\/(?:pdf|zip|gzip|x-gzip|x-tar|x-7z-compressed|x-rar-compressed|octet-stream|msword|wasm|vnd\.ms-|vnd\.openxmlformats-)/i;
+
+// Decode a response body using the charset from the Content-Type header, a byte order mark or a
+// <meta> tag, in that order of preference (pages in GBK, Big5 or Shift_JIS are common enough).
+export function decodeBody(buf, contentType = '') {
+  let label = /charset\s*=\s*["']?([\w.:-]+)/i.exec(contentType)?.[1];
+  if (buf[0] === 0xFF && buf[1] === 0xFE) label = 'utf-16le';
+  else if (buf[0] === 0xFE && buf[1] === 0xFF) label = 'utf-16be';
+  else if (!label) label = /<meta[^>]+charset\s*=\s*["']?([\w.:-]+)/i.exec(buf.subarray(0, 4096).toString('latin1'))?.[1];
+  try {
+    return new TextDecoder(label || 'utf-8').decode(buf); // an unknown label throws
+  } catch {
+    return buf.toString('utf8');
+  }
+}
+
+// Read at most `max` bytes of a response body and stop downloading after that.
+async function readCapped(res, max) {
+  const reader = res.body?.getReader();
+  if (!reader) return Buffer.from(await res.arrayBuffer()).subarray(0, max);
+  const chunks = [];
+  let size = 0;
+  while (size < max) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    size += value.length;
+  }
+  try { await reader.cancel(); } catch { /* already finished */ }
+  return Buffer.concat(chunks).subarray(0, max);
+}
+
+function remember(url, entry) {
+  const now = Date.now();
+  for (const [key, old] of cache) if (now - old.at >= webLimits.cacheMs) cache.delete(key);
+  cache.set(url, entry);
+  let bytes = 0;
+  for (const e of cache.values()) bytes += e.text.length;
+  // Oldest first (Map keeps insertion order); the page just fetched always stays.
+  for (const key of cache.keys()) {
+    if (cache.size <= 1 || (cache.size <= webLimits.cacheEntries && bytes <= webLimits.cacheBytes)) break;
+    bytes -= cache.get(key).text.length;
+    cache.delete(key);
+  }
+}
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', copy: '©', reg: '®', rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“' };
+
+export function decodeEntities(s) {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+    if (e[0] === '#') {
+      const cp = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      try { return String.fromCodePoint(cp); } catch { return m; }
+    }
+    return ENTITIES[e.toLowerCase()] ?? m;
+  });
+}
+
+export function htmlToMarkdown(html, baseUrl) {
+  let s = html;
+  const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(s)?.[1];
+  s = s.replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(script|style|noscript|svg|iframe|template|head)[\s\S]*?<\/\1>/gi, '')
+    .replace(/<(nav|footer)[\s\S]*?<\/\1>/gi, '');
+  const abs = (href) => { try { return new URL(decodeEntities(href), baseUrl).href; } catch { return href; } };
+  s = s.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (m, code) => `\n\`\`\`\n${decodeEntities(code.replace(/<[^>]+>/g, ''))}\n\`\`\`\n`)
+    .replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (m, n, t) => `\n\n${'#'.repeat(+n)} ${t.replace(/<[^>]+>/g, '').trim()}\n\n`)
+    .replace(/<a\s[^>]*href\s*=\s*["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (m, href, t) => {
+      const text = t.replace(/<[^>]+>/g, '').trim();
+      return text ? `[${text}](${abs(href)})` : '';
+    })
+    .replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1>/gi, '**$2**')
+    .replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1>/gi, '*$2*')
+    .replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, '`$1`')
+    .replace(/<li[^>]*>/gi, '\n- ')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|section|article|ul|ol|table|tr|blockquote|h\d)>/gi, '\n\n')
+    .replace(/<(td|th)[^>]*>/gi, ' | ')
+    .replace(/<[^>]+>/g, '');
+  s = decodeEntities(s)
+    .replace(/[ \t\f\v]+/g, ' ')
+    .replace(/ *\n */g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+  return (title ? `# ${decodeEntities(title.trim())}\n\n` : '') + s;
+}
+
+async function fetchText(url, signal) {
+  const hit = cache.get(url);
+  if (hit && Date.now() - hit.at < webLimits.cacheMs) return hit;
+  const ctrl = new AbortController();
+  // A timeout must be reported as one, and must not look like the user's interrupt.
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; ctrl.abort(); }, webLimits.timeoutMs);
+  const onAbort = () => ctrl.abort();
+  if (signal?.aborted) ctrl.abort(); else signal?.addEventListener('abort', onAbort, { once: true });
+  try {
+    const res = await fetch(url, { headers: { 'User-Agent': UA, Accept: 'text/html,text/markdown,text/plain,application/json;q=0.9,*/*;q=0.8' }, redirect: 'follow', signal: ctrl.signal });
+    const buf = await readCapped(res, webLimits.maxBodyBytes);
+    const type = res.headers.get('content-type') || '';
+    const base = { at: Date.now(), status: res.status, statusText: res.statusText, bytes: buf.length, finalUrl: res.url, type };
+    // Binary content (a PDF, an image, an archive) is not shown as text.
+    if (BINARY_TYPE.test(type) || buf.subarray(0, 8000).includes(0)) return { ...base, text: '', binary: true };
+    let text = decodeBody(buf, type);
+    if (/html/i.test(type) || /^\s*<(!doctype|html)/i.test(text)) text = htmlToMarkdown(text, res.url);
+    const r = { ...base, text };
+    // Only a successful page is remembered: a 503 or a 404 must not be served for the next 15 minutes
+    // after the server has recovered.
+    if (res.ok) remember(url, r);
+    return r;
+  } catch (e) {
+    if (timedOut && !signal?.aborted) throw new Error(`timed out after ${Number((webLimits.timeoutMs / 1000).toFixed(1))}s`);
+    throw e;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', onAbort);
+  }
+}
+
+export function makeWebFetchTool(config) {
+  return {
+    name: 'WebFetch',
+    readOnly: true,
+    description: `- Fetches content from a specified URL (any scheme the network allows, including localhost and private addresses), converts HTML to markdown, and answers a prompt about it using a small, fast model
+- Takes a URL and a prompt as input
+- Set raw: true to get the converted page text itself instead of an answer: use it when you need the exact content, code, tables or the whole document (very long pages are saved to a file and previewed; read the file for the rest)
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+- The URL must be a fully-formed valid URL, used exactly as given
+- The prompt should describe what information you want to extract from the page; it is optional with raw: true
+- This tool is read-only and does not modify any files
+- Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL`,
+    input_schema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', format: 'uri', description: 'The URL to fetch content from' },
+        prompt: { type: 'string', description: 'The prompt to run on the fetched content' },
+        raw: { type: 'boolean', description: 'Return the converted page text itself instead of an answer from the small model' },
+      },
+      required: ['url'],
+    },
+    summarize(input) { return input.url; },
+    domain(input) { try { return new URL(input.url).hostname; } catch { return null; } },
+    async call(input, ctx) {
+      let url;
+      try { url = new URL(input.url); } catch { return { isError: true, content: `Invalid URL: ${input.url}` }; }
+      let page;
+      try { page = await fetchText(url.href, ctx.signal); } catch (e) {
+        if (ctx.signal?.aborted) throw e;
+        return { isError: true, content: `Failed to fetch ${url.href}: ${e.cause?.message || e.message}` };
+      }
+      const size = page.bytes > 1024 ? `${(page.bytes / 1024).toFixed(1)}KB` : `${page.bytes}B`;
+      const display = { summary: `Received ${size} (${page.status} ${page.statusText || ''})`.trim() };
+      if (page.status >= 400) return { isError: true, content: `HTTP ${page.status} ${page.statusText} fetching ${url.href}\n\n${page.text.slice(0, 2000)}`, display };
+      if (page.binary) {
+        return { isError: true, content: `${page.finalUrl || url.href} is not text (${page.type || 'binary data'}, ${size}), so WebFetch cannot read it. If you need the file, download it with curl in Bash.`, display };
+      }
+      if (input.raw) {
+        const text = page.text.length > 1_000_000 ? `${page.text.slice(0, 1_000_000)}\n\n[content truncated at 1,000,000 characters]` : page.text;
+        return { content: text || '(the page has no text content)', display };
+      }
+      const content = page.text.length > 400_000 ? page.text.slice(0, 400_000) + '\n\n[content truncated]' : page.text;
+      try {
+        const answer = await quickQuery(config, {
+          model: config.smallModel,
+          system: 'You extract information from web pages. Answer only from the provided content. Be complete and precise: include every relevant detail, exact quotes, numbers and code. Keep code blocks intact.',
+          prompt: `Web page content from ${page.finalUrl || url.href}:\n---\n${content}\n---\n\n${input.prompt || 'Summarize this page, keeping all important details, code and numbers.'}\n\nRespond based only on the content above.`,
+          maxTokens: 16_000,
+          signal: ctx.signal,
+          // Nobody is told about a pause that happens inside a tool call, so the summary is skipped
+          // instead (the page text below is returned as it is) and the main agent does the waiting.
+          waitForRateLimit: false,
+        });
+        return { content: answer || content.slice(0, 50_000), display };
+      } catch (e) {
+        if (ctx.signal?.aborted) throw e;
+        return { content: content.slice(0, 100_000), display };
+      }
+    },
+  };
+}
+
+// A search engine that never answers must not hold the tool call for minutes.
+const withTimeout = (signal) => AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(webLimits.searchTimeoutMs)]);
+
+async function searchDuckDuckGo(query, signal) {
+  const res = await fetch('https://html.duckduckgo.com/html/', {
+    method: 'POST',
+    headers: { 'User-Agent': UA, 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ q: query }).toString(),
+    signal: withTimeout(signal),
+  });
+  const html = await res.text();
+  const results = [];
+  const re = /<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?(?:<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>)?/g;
+  let m;
+  while ((m = re.exec(html)) && results.length < 10) {
+    let href = decodeEntities(m[1]);
+    const uddg = /[?&]uddg=([^&]+)/.exec(href);
+    if (uddg) href = decodeURIComponent(uddg[1]);
+    if (href.startsWith('//')) href = 'https:' + href;
+    if (/duckduckgo\.com\/y\.js/.test(href)) continue; // ads
+    results.push({ title: decodeEntities(m[2].replace(/<[^>]+>/g, '')).trim(), url: href, snippet: decodeEntities((m[3] || '').replace(/<[^>]+>/g, '')).trim() });
+  }
+  return results;
+}
+
+async function searchBing(query, signal) {
+  const res = await fetch(`https://www.bing.com/search?q=${encodeURIComponent(query)}&setlang=en`, { headers: { 'User-Agent': UA }, signal: withTimeout(signal) });
+  const html = await res.text();
+  const results = [];
+  for (const block of html.split('<li class="b_algo"').slice(1)) {
+    const a = /<h2[^>]*>\s*<a[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/.exec(block);
+    if (!a) continue;
+    const p = /<p[^>]*>([\s\S]*?)<\/p>/.exec(block);
+    results.push({ title: decodeEntities(a[2].replace(/<[^>]+>/g, '')).trim(), url: decodeEntities(a[1]), snippet: p ? decodeEntities(p[1].replace(/<[^>]+>/g, '')).trim() : '' });
+    if (results.length >= 10) break;
+  }
+  return results;
+}
+
+export const WebSearchTool = {
+  name: 'WebSearch',
+  readOnly: true,
+  description: `- Allows searching the web and using the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search results (title, URL, snippet) for the query
+- Use this tool for accessing information beyond your knowledge cutoff
+- Use WebFetch afterwards to read a promising result in full
+- After answering from search results, include a "Sources:" section listing the relevant URLs as markdown links`,
+  input_schema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', minLength: 2, description: 'The search query to use' },
+      allowed_domains: { type: 'array', items: { type: 'string' }, description: 'Only include results from these domains' },
+      blocked_domains: { type: 'array', items: { type: 'string' }, description: 'Never include results from these domains' },
+    },
+    required: ['query'],
+  },
+  summarize(input) { return `"${input.query}"`; },
+  async call(input, ctx) {
+    let results = [];
+    const errors = [];
+    for (const engine of [searchDuckDuckGo, searchBing]) {
+      try {
+        results = await engine(input.query, ctx.signal);
+        if (results.length) break;
+      } catch (e) {
+        if (ctx.signal?.aborted) throw e;
+        errors.push(e.cause?.message || e.message);
+      }
+    }
+    const host = (u) => { try { return new URL(u).hostname; } catch { return ''; } };
+    const match = (h, d) => h === d || h.endsWith('.' + d);
+    if (input.allowed_domains?.length) results = results.filter((r) => input.allowed_domains.some((d) => match(host(r.url), d)));
+    if (input.blocked_domains?.length) results = results.filter((r) => !input.blocked_domains.some((d) => match(host(r.url), d)));
+    if (!results.length) {
+      return { isError: !!errors.length, content: errors.length ? `Web search failed: ${errors.join('; ')}` : `No results found for "${input.query}"`, display: { summary: 'No results' } };
+    }
+    const text = results.map((r, i) => `${i + 1}. [${r.title}](${r.url})\n   ${r.snippet}`).join('\n\n');
+    return { content: `Web search results for query: "${input.query}"\n\n${text}`, display: { summary: `Found ${results.length} results` } };
+  },
+};

package/src/ui/ansi.js

@@ -0,0 +1,228 @@
+// Terminal primitives: colors, ANSI-aware string width (CJK / emoji aware), wrapping, truncation.
+
+const out = process.stdout;
+const depth = process.env.NO_COLOR ? 1 : (out.isTTY && out.getColorDepth ? out.getColorDepth() : (process.env.FORCE_COLOR ? 24 : 1));
+
+const sgr = (open, close) => (s) => (depth <= 1 ? String(s) : `\x1b[${open}m${s}\x1b[${close}m`);
+
+function rgbTo256(r, g, b) {
+  if (r === g && g === b) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return Math.round(((r - 8) / 247) * 24) + 232;
+  }
+  const c = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * c(r) + 6 * c(g) + c(b);
+}
+
+function rgbTo16(r, g, b) {
+  const bright = Math.max(r, g, b) > 170 ? 60 : 0;
+  const code = (b > 127 ? 4 : 0) | (g > 127 ? 2 : 0) | (r > 127 ? 1 : 0);
+  return 30 + code + bright;
+}
+
+function hex(h, bg = false) {
+  const n = parseInt(h.slice(1), 16);
+  const r = (n >> 16) & 255, g = (n >> 8) & 255, b = n & 255;
+  if (depth <= 1) return (s) => String(s);
+  if (depth >= 24) return sgr(`${bg ? 48 : 38};2;${r};${g};${b}`, bg ? 49 : 39);
+  if (depth >= 8) return sgr(`${bg ? 48 : 38};5;${rgbTo256(r, g, b)}`, bg ? 49 : 39);
+  const c = rgbTo16(r, g, b);
+  return sgr(bg ? c + 10 : c, bg ? 49 : 39);
+}
+
+export const c = {
+  bold: sgr(1, 22),
+  dim: sgr(2, 22),
+  italic: sgr(3, 23),
+  underline: sgr(4, 24),
+  inverse: sgr(7, 27),
+  strike: sgr(9, 29),
+  red: hex('#ff6b80'),
+  green: hex('#4eba65'),
+  yellow: hex('#ffc107'),
+  blue: hex('#7aa2f7'),
+  cyan: hex('#56b6c2'),
+  magenta: hex('#c678dd'),
+  gray: hex('#8a8a8a'),
+  white: hex('#ffffff'),
+  claude: hex('#d77757'), // the orange brand accent
+  permission: hex('#b1b9f9'),
+  plan: hex('#48968c'),
+  edits: hex('#af87ff'),
+  code: hex('#b1b9f9'),
+  diffAdd: hex('#225c2b', true),
+  diffDel: hex('#7a2936', true),
+  diffAddWord: hex('#38a660', true),
+  diffDelWord: hex('#b3596b', true),
+};
+
+export const colorEnabled = depth > 1;
+
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /[\u001b\u009b][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-ntqry=><~]))/g;
+
+export function stripAnsi(s) {
+  return String(s).replace(ANSI_RE, '');
+}
+
+const WIDE = [
+  [0x1100, 0x115f], [0x231a, 0x231b], [0x2329, 0x232a], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693], [0x26a1, 0x26a1],
+  [0x26aa, 0x26ab], [0x26bd, 0x26be], [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4], [0x26ea, 0x26ea],
+  [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa], [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b],
+  [0x2728, 0x2728], [0x274c, 0x274c], [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797],
+  [0x27b0, 0x27b0], [0x27bf, 0x27bf], [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+  [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf], [0x4e00, 0x9fff], [0xa000, 0xa4cf], [0xa960, 0xa97f],
+  [0xac00, 0xd7a3], [0xf900, 0xfaff], [0xfe10, 0xfe19], [0xfe30, 0xfe6f], [0xff00, 0xff60], [0xffe0, 0xffe6],
+  [0x16fe0, 0x16fe4], [0x17000, 0x18cff], [0x1b000, 0x1b2ff], [0x1f004, 0x1f004], [0x1f0cf, 0x1f0cf],
+  [0x1f18e, 0x1f18e], [0x1f191, 0x1f19a], [0x1f200, 0x1f251], [0x1f300, 0x1f64f], [0x1f680, 0x1f6ff],
+  [0x1f7e0, 0x1f7eb], [0x1f90c, 0x1f9ff], [0x1fa70, 0x1faff], [0x20000, 0x3fffd],
+];
+
+const ZERO = [
+  [0x0300, 0x036f], [0x0483, 0x0489], [0x0591, 0x05bd], [0x0610, 0x061a], [0x064b, 0x065f], [0x0e31, 0x0e31],
+  [0x0e34, 0x0e3a], [0x0e47, 0x0e4e], [0x1ab0, 0x1aff], [0x1dc0, 0x1dff], [0x200b, 0x200f], [0x2028, 0x202e],
+  [0x2060, 0x2064], [0x20d0, 0x20ff], [0xfe00, 0xfe0f], [0xfe20, 0xfe2f], [0xfeff, 0xfeff], [0xe0100, 0xe01ef],
+];
+
+function inRanges(cp, ranges) {
+  let lo = 0, hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (cp < ranges[mid][0]) hi = mid - 1;
+    else if (cp > ranges[mid][1]) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
+export function codePointWidth(cp) {
+  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0;
+  if (inRanges(cp, ZERO)) return 0;
+  if (inRanges(cp, WIDE)) return 2;
+  return 1;
+}
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+export function graphemes(s) {
+  const res = [];
+  for (const { segment } of segmenter.segment(s)) res.push(segment);
+  return res;
+}
+
+export function graphemeWidth(g) {
+  if (g === '\t') return 4;
+  const cp = g.codePointAt(0);
+  let w = codePointWidth(cp);
+  // Emoji presentation selector or ZWJ sequences render wide.
+  if (g.length > 1 && /[️‍]/.test(g) && w === 1) w = 2;
+  return w;
+}
+
+export function stringWidth(s) {
+  s = stripAnsi(s);
+  let w = 0;
+  // fast path for ASCII
+  if (/^[\x20-\x7e]*$/.test(s)) return s.length;
+  for (const g of graphemes(s)) w += graphemeWidth(g);
+  return w;
+}
+
+// Tokenize a string into ANSI escape tokens and grapheme tokens.
+function tokenize(s) {
+  const tokens = [];
+  let last = 0;
+  ANSI_RE.lastIndex = 0;
+  let m;
+  while ((m = ANSI_RE.exec(s))) {
+    if (m.index > last) for (const g of graphemes(s.slice(last, m.index))) tokens.push({ t: g, w: graphemeWidth(g) });
+    tokens.push({ t: m[0], w: 0, ansi: true });
+    last = m.index + m[0].length;
+  }
+  if (last < s.length) for (const g of graphemes(s.slice(last))) tokens.push({ t: g, w: graphemeWidth(g) });
+  return tokens;
+}
+
+// Hard-wrap a (possibly ANSI colored) single line to the given width. Returns array of lines.
+export function wrapLine(line, width) {
+  width = Math.max(1, width);
+  if (stringWidth(line) <= width) return [line];
+  const lines = [];
+  let cur = '', curW = 0;
+  for (const tok of tokenize(line)) {
+    if (tok.ansi) { cur += tok.t; continue; }
+    const tw = tok.t === '\t' ? 4 : tok.w;
+    const text = tok.t === '\t' ? '    ' : tok.t;
+    if (curW + tw > width && curW > 0) {
+      lines.push(cur);
+      cur = '';
+      curW = 0;
+    }
+    cur += text;
+    curW += tw;
+  }
+  lines.push(cur);
+  return lines;
+}
+
+// Word-aware wrap for prose; falls back to hard wrap for long words.
+export function wordWrap(line, width) {
+  width = Math.max(1, width);
+  if (stringWidth(line) <= width) return [line];
+  const words = line.split(/(\s+)/);
+  const lines = [];
+  let cur = '', curW = 0;
+  for (const word of words) {
+    if (!word) continue;
+    const w = stringWidth(word);
+    if (curW + w <= width) { cur += word; curW += w; continue; }
+    if (/^\s+$/.test(word)) { lines.push(cur); cur = ''; curW = 0; continue; }
+    if (curW > 0) { lines.push(cur); cur = ''; curW = 0; }
+    if (w > width) {
+      const parts = wrapLine(word, width);
+      lines.push(...parts.slice(0, -1));
+      cur = parts[parts.length - 1];
+      curW = stringWidth(cur);
+    } else { cur = word; curW = w; }
+  }
+  lines.push(cur);
+  return lines;
+}
+
+export function truncate(s, width, ellipsis = '…') {
+  if (stringWidth(s) <= width) return s;
+  let res = '', w = 0;
+  const ew = stringWidth(ellipsis);
+  for (const tok of tokenize(s)) {
+    if (tok.ansi) { res += tok.t; continue; }
+    if (w + tok.w > width - ew) break;
+    res += tok.t;
+    w += tok.w;
+  }
+  return res + ellipsis + (colorEnabled ? '\x1b[0m' : '');
+}
+
+export function padEnd(s, width) {
+  const w = stringWidth(s);
+  return w >= width ? s : s + ' '.repeat(width - w);
+}
+
+export function termWidth() {
+  return Math.max(20, (process.stdout.columns || 100));
+}
+
+export const ESC = {
+  hideCursor: '\x1b[?25l',
+  showCursor: '\x1b[?25h',
+  clearDown: '\x1b[0J',
+  clearLine: '\x1b[2K',
+  up: (n) => (n > 0 ? `\x1b[${n}A` : ''),
+  down: (n) => (n > 0 ? `\x1b[${n}B` : ''),
+  right: (n) => (n > 0 ? `\x1b[${n}C` : ''),
+  col0: '\r',
+  bracketedPasteOn: '\x1b[?2004h',
+  bracketedPasteOff: '\x1b[?2004l',
+  clearScreen: '\x1b[2J\x1b[3J\x1b[H',
+};

package/src/ui/dialogs.js

@@ -0,0 +1,122 @@
+// Modal dialogs rendered in the live region: selection menus (permission prompts,
+// plan approval, questions, session picker) and a free-text prompt.
+
+import { c, padEnd, stringWidth, truncate, wordWrap } from './ansi.js';
+import { Editor } from './editor.js';
+
+function box(lines, width, color) {
+  const w = Math.max(20, width - 1);
+  const inner = w - 4;
+  const out = [color('╭' + '─'.repeat(w - 2) + '╮')];
+  for (const l of lines) {
+    for (const part of stringWidth(l) > inner ? wordWrap(l, inner) : [l]) {
+      out.push(color('│') + ' ' + padEnd(part, inner) + ' ' + color('│'));
+    }
+  }
+  out.push(color('╰' + '─'.repeat(w - 2) + '╯'));
+  return out;
+}
+
+export class SelectDialog {
+  // options: [{label, value, description?}]
+  constructor({ title, body = [], question, options, color = c.permission, multi = false, footer, onResolve, cancelValue = null, otherOption = false }) {
+    this.title = title;
+    this.body = body;
+    this.question = question;
+    this.options = otherOption ? [...options, { label: 'Other (type your own answer)', value: '__other__' }] : options;
+    this.color = color;
+    this.multi = multi;
+    this.footer = footer;
+    this.onResolve = onResolve;
+    this.cancelValue = cancelValue;
+    this.selected = 0;
+    this.checked = new Set();
+    this.other = null; // Editor when typing a custom answer
+  }
+
+  resolve(value) {
+    const cb = this.onResolve;
+    this.onResolve = null;
+    cb?.(value);
+  }
+
+  handleKey(str, key = {}) {
+    if (this.other) {
+      if (key.name === 'escape') { this.other = null; return true; }
+      if (key.name === 'return' && !key.meta) {
+        const text = this.other.text.trim();
+        if (text) this.resolve(this.multi ? [...[...this.checked].map((i) => this.options[i].value), text] : text);
+        return true;
+      }
+      return this.other.handleKey(str, key);
+    }
+    const n = this.options.length;
+    if (key.name === 'up' || (key.ctrl && key.name === 'p') || str === 'k') { this.selected = (this.selected - 1 + n) % n; return true; }
+    if (key.name === 'down' || (key.ctrl && key.name === 'n') || str === 'j' || (key.name === 'tab' && !key.shift)) { this.selected = (this.selected + 1) % n; return true; }
+    if (key.name === 'escape') { this.resolve(this.cancelValue); return true; }
+    if (/^[1-9]$/.test(str || '') && +str <= n) {
+      this.selected = +str - 1;
+      if (!this.multi) return this.choose();
+      return true;
+    }
+    if (this.multi && str === ' ') {
+      if (this.options[this.selected].value === '__other__') return this.choose();
+      if (this.checked.has(this.selected)) this.checked.delete(this.selected); else this.checked.add(this.selected);
+      return true;
+    }
+    if (key.name === 'return') return this.choose();
+    return true; // modal: swallow everything else
+  }
+
+  choose() {
+    const opt = this.options[this.selected];
+    if (opt.value === '__other__') {
+      this.other = new Editor();
+      return true;
+    }
+    if (this.multi) {
+      const values = this.checked.size ? [...this.checked].sort().map((i) => this.options[i].value) : [opt.value];
+      this.resolve(values);
+    } else {
+      this.resolve(opt.value);
+    }
+    return true;
+  }
+
+  render(width, maxHeight = 40) {
+    const lines = [];
+    if (this.title) lines.push(c.bold(this.color(this.title)), '');
+    lines.push(...this.body);
+    if (this.body.length) lines.push('');
+    if (this.question) lines.push(this.question);
+    const inner = Math.max(20, width - 1) - 4;
+    // Show a window of options around the selection when they don't all fit.
+    const perOption = this.options.some((o) => o.description) ? 2 : 1;
+    const room = Math.max(3, Math.floor((maxHeight - lines.length - 4 - (this.other ? 5 : 0)) / perOption));
+    let first = 0;
+    if (this.options.length > room) first = Math.min(Math.max(0, this.selected - Math.floor(room / 2)), this.options.length - room);
+    const last = Math.min(this.options.length, first + room);
+    if (first > 0) lines.push(c.dim(`  ↑ ${first} more`));
+    for (let i = first; i < last; i++) {
+      const o = this.options[i];
+      const sel = i === this.selected;
+      const mark = this.multi ? (this.checked.has(i) ? c.green('[✔] ') : '[ ] ') : '';
+      const label = `${sel ? '❯' : ' '} ${i + 1}. ${mark}${o.label}`;
+      lines.push(sel ? this.color(truncate(label, inner)) : truncate(label, inner));
+      if (o.description) lines.push(c.dim('      ' + truncate(o.description, inner - 6)));
+    }
+    if (last < this.options.length) lines.push(c.dim(`  ↓ ${this.options.length - last} more`));
+    let cursor = null;
+    if (this.other) {
+      lines.push('');
+      const r = this.other.render(width - 4, { placeholder: 'Type your answer, Enter to submit, Esc to go back' });
+      const top = lines.length + 1; // +1 for the box's top border
+      lines.push(...r.lines.map((l) => truncate(l, inner)));
+      if (r.cursor) cursor = { row: top + r.cursor.row, col: 2 + r.cursor.col };
+    }
+    const out = box(lines, width, this.color);
+    const hint = this.footer ?? (this.multi ? 'Space to toggle · Enter to confirm · Esc to cancel' : 'Enter to confirm · Esc to cancel');
+    out.push(c.dim('  ' + hint));
+    return { lines: out, cursor };
+  }
+}