saeeol 1.3.0 → 1.4.0

package/specs/v2/message-shape.md

@@ -0,0 +1,136 @@
+# Message Shape
+
+Problem:
+
+- stored messages need enough data to replay and resume a session later
+- prompt hooks often just want to append a synthetic user/assistant message
+- today that means faking ids, timestamps, and request metadata
+
+## Option 1: Two Message Shapes
+
+Keep `User` / `Assistant` for stored history, but clean them up.
+
+```ts
+type User = {
+  role: "user"
+  time: { created: number }
+  request: {
+    agent: string
+    model: ModelRef
+    variant?: string
+    format?: OutputFormat
+    system?: string
+    tools?: Record<string, boolean>
+  }
+}
+
+type Assistant = {
+  role: "assistant"
+  run: { agent: string; model: ModelRef; path: { cwd: string; root: string } }
+  usage: { cost: number; tokens: Tokens }
+  result: { finish?: string; error?: Error; structured?: unknown; kind: "reply" | "summary" }
+}
+```
+
+Add a separate transient `PromptMessage` for prompt surgery.
+
+```ts
+type PromptMessage = {
+  role: "user" | "assistant"
+  parts: PromptPart[]
+}
+```
+
+Plugin hook example:
+
+```ts
+prompt.push({
+  role: "user",
+  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
+})
+```
+
+Tradeoff: prompt hooks get easy lightweight messages, but there are now two message shapes.
+
+## Option 2: Prompt Mutators
+
+Keep `User` / `Assistant` as the stored history model.
+
+Prompt hooks do not build messages directly. The runtime gives them prompt mutators.
+
+```ts
+type PromptEditor = {
+  append(input: { role: "user" | "assistant"; parts: PromptPart[] }): void
+  prepend(input: { role: "user" | "assistant"; parts: PromptPart[] }): void
+  appendTo(target: "last-user" | "last-assistant", parts: PromptPart[]): void
+  insertAfter(messageID: string, input: { role: "user" | "assistant"; parts: PromptPart[] }): void
+  insertBefore(messageID: string, input: { role: "user" | "assistant"; parts: PromptPart[] }): void
+}
+```
+
+Plugin hook examples:
+
+```ts
+prompt.append({
+  role: "user",
+  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
+})
+```
+
+```ts
+prompt.appendTo("last-user", [{ type: "text", text: BUILD_SWITCH }])
+```
+
+Tradeoff: avoids a second full message type and avoids fake ids/timestamps, but moves more magic into the hook API.
+
+## Option 3: Separate Turn State
+
+Move execution settings out of `User` and into a separate turn/request object.
+
+```ts
+type Turn = {
+  id: string
+  request: {
+    agent: string
+    model: ModelRef
+    variant?: string
+    format?: OutputFormat
+    system?: string
+    tools?: Record<string, boolean>
+  }
+}
+
+type User = {
+  role: "user"
+  turnID: string
+  time: { created: number }
+}
+
+type Assistant = {
+  role: "assistant"
+  turnID: string
+  usage: { cost: number; tokens: Tokens }
+  result: { finish?: string; error?: Error; structured?: unknown; kind: "reply" | "summary" }
+}
+```
+
+Examples:
+
+```ts
+const turn = {
+  request: {
+    agent: "build",
+    model: { providerID: "openai", modelID: "gpt-5" },
+  },
+}
+```
+
+```ts
+const msg = {
+  role: "user",
+  turnID: turn.id,
+  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
+}
+```
+
+Tradeoff: stored messages get much smaller and cleaner, but replay now has to join messages with turn state and prompt hooks still need a way to pick which turn they belong to.

package/src/acp/agent-message.ts

@@ -1,4 +1,4 @@
-import { parse as parseDataUrl } from "@saeeol/boxes/dataurl"
+import { parse as parseDataUrl } from "@/boxes/dataurl"
 import { pathToFileURL } from "url"
 import type { Role, ToolCallContent } from "@agentclientprotocol/sdk"
 import type { SessionMessageResponse, ToolPart } from "@saeeol/sdk/v2"

package/src/acp/agent-utils.ts

@@ -1,4 +1,4 @@
-import { parse as parseDataUrl } from "@saeeol/boxes/dataurl"
+import { parse as parseDataUrl } from "@/boxes/dataurl"
 import { RequestError, type Role, type ToolKind, type Usage, type PlanEntry } from "@agentclientprotocol/sdk"
 import * as Log from "@saeeol/core/util/log"
 import { pathToFileURL } from "url"

package/src/boxes/ansi.ts

@@ -0,0 +1,17 @@
+/**
+ * ansi.ts — Terminal color: hex → ANSI escape sequence
+ * Zero deps.
+ *
+ * bold("#ff6600") → "\x1b[38;2;255;102;0m\x1b[1m"
+ */
+export function valid(hex?: string): hex is string { return !!hex && /^#[0-9a-fA-F]{6}$/.test(hex) }
+
+export function rgb(hex: string) {
+  return { r: parseInt(hex.slice(1, 3), 16), g: parseInt(hex.slice(3, 5), 16), b: parseInt(hex.slice(5, 7), 16) }
+}
+
+export function bold(hex?: string): string | undefined {
+  if (!valid(hex)) return undefined
+  const { r, g, b } = rgb(hex)
+  return `\x1b[38;2;${r};${g};${b}m\x1b[1m`
+}

package/src/boxes/atomic-write.ts

@@ -0,0 +1,35 @@
+/**
+ * atomic-write.ts — tmp→rename atomic file write with ENOENT recovery
+ * Pattern from abtop (MIT)
+ * Deps: fs/promises, path (Node built-ins)
+ */
+
+import { writeFile, rename, unlink, mkdir } from "fs/promises"
+import { join, extname, dirname } from "path"
+
+function isEnoent(e: unknown): e is { code: "ENOENT" } {
+  return typeof e === "object" && e !== null && "code" in e && (e as { code: string }).code === "ENOENT"
+}
+
+export async function atomicWrite(filePath: string, content: string | Buffer, mode?: number): Promise<void> {
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
+  const doWrite = async () => {
+    if (mode) {
+      await writeFile(tmp, content, { mode })
+    } else {
+      await writeFile(tmp, content)
+    }
+    await rename(tmp, filePath)
+  }
+  try {
+    await doWrite()
+  } catch (e) {
+    if (isEnoent(e)) {
+      await mkdir(dirname(filePath), { recursive: true })
+      await doWrite()
+      return
+    }
+    try { await unlink(tmp) } catch { /* ignore */ }
+    throw e
+  }
+}

package/src/boxes/b64.ts

@@ -0,0 +1,58 @@
+/**
+ * b64.ts — URL-safe Base64 + FNV-1a checksum
+ *
+ * ⚠ b64Enc normalizes `\` → `/` for cross-platform path fingerprinting.
+ *   If `\` must be preserved, pre-encode manually.
+ * ⚠ Uses atob/btoa (Bun/Node safe, may chunk-fail on >100KB in browsers).
+ */
+
+export function b64Enc(val: string): string {
+  const norm = val.replace(/\\/g, "/") // path normalization
+  const bytes = new TextEncoder().encode(norm)
+  const bin = Array.from(bytes, (b) => String.fromCharCode(b)).join("")
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "")
+}
+
+export function b64EncBytes(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer)
+  const bin = String.fromCharCode(...bytes)
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+export function b64Dec(val: string): string {
+  const bin = atob(val.replace(/-/g, "+").replace(/_/g, "/"))
+  const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))
+  return new TextDecoder().decode(bytes)
+}
+
+/** FNV-1a 32-bit hash as base-36. Returns undefined for empty input. */
+export function fnv1a(s: string): string | undefined {
+  if (!s) return undefined
+  let h = 0x811c9dc5
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(36)
+}
+
+/** Hashes 5 evenly-spaced 4KB windows for large strings. Returns `"len:h1:h2:..."`. */
+export function sampledHash(s: string, limit = 500_000): string | undefined {
+  if (!s) return undefined
+  if (s.length <= limit) return fnv1a(s)
+  const sz = 4096
+  const pts = [
+    0,
+    (s.length * 0.25) | 0,
+    (s.length * 0.5) | 0,
+    (s.length * 0.75) | 0,
+    s.length - sz,
+  ]
+  const parts = pts
+    .map((p) => {
+      const start = Math.max(0, Math.min(s.length - sz, p - (sz >> 1)))
+      return fnv1a(s.slice(start, start + sz)) ?? ""
+    })
+    .join(":")
+  return `${s.length}:${parts}`
+}

package/src/boxes/bash-security.ts

@@ -0,0 +1,129 @@
+/**
+ * bash-security.ts — 23-item shell command security validator
+ * Deps: none (pure TS + regex)
+ * Ported from Claude Code bashSecurity.ts
+ */
+
+const BLOCKED = new Set([
+  "dd", "shred", "wipefs", "sudo", "su", "pkexec", "gksudo", "kdesudo",
+  "sudoedit", "keylogger", "insmod", "rmmod", "modprobe",
+])
+const BLOCKED_PREFIXES = ["mkfs"]
+const DANGEROUS = new Set([
+  "rm", "rmdir", "format", "del", "erase", "remove-item", "rd",
+  "kill", "killall", "pkill", "taskkill",
+  "curl", "wget", "nc", "ncat", "socat",
+  "npm", "npx", "pip", "pip3", "gem", "cargo", "go",
+  "docker", "aws", "gcloud", "az",
+])
+
+const INJECTION = [
+  /;\s*(rm|sudo|mkfs|dd|shred|format|del)\b/i,
+  /&&\s*(rm|sudo|mkfs|dd|shred|format|del)\b/i,
+  /\|\s*(rm|sudo|mkfs|dd|shred|format|del)\b/i,
+  /\$\([^)]*\)/, /`[^`]*`/, />\s*\/dev\//i,
+  /chmod\s+777/i, /chmod\s+[+-].*s/i, /chown\s+.*root/i,
+  /\\x[0-9a-f]{2}/i, /\\u[0-9a-f]{4}/i, /\\[0-7]{3}/, /\$'\x/,
+  />\s*\/etc\/passwd/i, />\s*\/etc\/shadow/i,
+  /cat\s+\/etc\/shadow/i, /cat\s+\/etc\/passwd.*>/i,
+]
+const TRAVERSAL = [/\.\.[\\/]/, /\.\.[\\/]|\.\.$/]
+const EXFIL = [
+  /curl.*\$\{?HOME/i, /curl.*\$HOME/i, /wget.*\$HOME/i,
+  /curl.*\$\{?AWS/i, /curl.*\$\{?API_KEY/i, /curl.*\$\{?SECRET/i,
+  /curl.*\$\{?TOKEN/i, /curl.*\$\{?PASSWORD/i,
+  /echo.*\$.*\|.*nc/i, /echo.*\$.*\|.*curl/i,
+]
+const SHELL_ATK = [
+  /exec\s+rm/i, /eval\s+.*rm/i, /\bsource\s+\/dev\//i, /\.\s+\/dev\//i,
+  /unset\s+PATH/i, /PATH\s*=\s*""/i, /export\s+PATH\s*=\s*""/i, /\bsudoedit\b/i,
+]
+
+export interface SecurityResult {
+  safe: boolean
+  blocked: boolean
+  reasons: string[]
+  risk: "low" | "medium" | "high" | "critical"
+}
+
+function baseCmd(cmd: string): string {
+  const m = cmd.trim().match(/^([A-Za-z_.\-/][A-Za-z0-9_.\-/]*)/)
+  if (!m) return cmd.trim().split(/\s+/)[0]?.toLowerCase() ?? ""
+  const parts = m[1].split("/")
+  return parts[parts.length - 1].toLowerCase()
+}
+
+function pipedDestructive(cmd: string): boolean {
+  return cmd.split(/[|;&]/).some(p => {
+    const b = baseCmd(p)
+    if (BLOCKED.has(b)) return true
+    return BLOCKED_PREFIXES.some(pre => b.startsWith(pre + ".") || b === pre)
+  })
+}
+
+function sensitivePath(t: string): boolean {
+  const paths = [
+    "/etc/passwd", "/etc/shadow", "/etc/ssh", "/root/.ssh", "/.ssh",
+    "\\ssh", "/boot/", "\\boot\\", "/efi/", "\\efi\\",
+    "/proc/sys/", "/sys/", "\\sys\\", "/dev/", "\\dev\\",
+    "C:\\Windows\\System32", "C:\\Windows\\SysWOW64",
+  ]
+  const lower = t.toLowerCase()
+  return paths.some(s => lower.includes(s.toLowerCase()))
+}
+
+function matchPats(cmd: string, pats: RegExp[], label: string, reasons: string[]): boolean {
+  return pats.some(p => { if (p.test(cmd)) { reasons.push(`${label}: matched ${p.source}`); return true }; return false })
+}
+
+export function validate(command: string): SecurityResult {
+  const reasons: string[] = []
+  let risk: SecurityResult["risk"] = "low"
+  const base = baseCmd(command)
+
+  if (BLOCKED.has(base))
+    return { safe: false, blocked: true, reasons: [`Blocked command: "${base}" is not allowed`], risk: "critical" }
+  for (const pre of BLOCKED_PREFIXES)
+    if (base.startsWith(pre + ".") || base === pre)
+      return { safe: false, blocked: true, reasons: [`Blocked command: "${base}" matches blocked prefix "${pre}"`], risk: "critical" }
+  if (pipedDestructive(command))
+    return { safe: false, blocked: true, reasons: ["Destructive command detected in pipe/chain"], risk: "critical" }
+  if (matchPats(command, INJECTION, "Potential injection", reasons)) risk = "high"
+  if (matchPats(command, SHELL_ATK, "Shell attack vector", reasons)) risk = "high"
+  if (matchPats(command, EXFIL, "Credential exfiltration", reasons)) risk = "critical"
+  if (DANGEROUS.has(base) && TRAVERSAL.some(p => p.test(command))) { reasons.push("Path traversal in destructive command context"); risk = "high" }
+  if (sensitivePath(command) && (base === "rm" || base === "remove-item" || base === "del")) { reasons.push("Attempting to modify sensitive system path"); risk = "critical" }
+
+  const recursive = (base === "rm" && /-rf\b|--recursive\b/.test(command)) || (base === "remove-item" && /-recurse\b/.test(command))
+  if (recursive) {
+    if (/[/~\\]\s*$/.test(command.trim()) || sensitivePath(command)) { reasons.push("Recursive delete targeting root or sensitive directory"); risk = "critical" }
+    else { if (risk === "low") risk = "medium"; reasons.push("Recursive delete — verify target") }
+  }
+
+  if (DANGEROUS.has(base) && /--force\b|-f\b/i.test(command)) { if (risk === "low") risk = "medium"; reasons.push("Force flag on potentially destructive command") }
+  if ((base === "curl" || base === "wget") && /\|\s*(bash|sh|zsh|fish|powershell|pwsh|cmd)/i.test(command)) { reasons.push("Download and execute pattern detected"); risk = "critical" }
+  if (base === "docker" && /--privileged\b/.test(command)) { reasons.push("Docker privileged mode — host access risk"); risk = "high" }
+  if (base === "docker" && /-v\s+\/:/i.test(command)) { reasons.push("Docker mounting root filesystem"); risk = "critical" }
+  if (/export\s+LD_PRELOAD/i.test(command) || /LD_PRELOAD\s*=/i.test(command)) { reasons.push("LD_PRELOAD manipulation — code injection risk"); risk = "critical" }
+  if (/crontab\s+-r/i.test(command)) { reasons.push("Removing all crontab entries"); risk = "high" }
+  if (/ssh-keygen/i.test(command) && /-N\s+""/i.test(command)) { reasons.push("Generating SSH key with empty passphrase"); if (risk === "low") risk = "medium" }
+  if (/\biptables\b/.test(command) && /-F\b|--flush\b/.test(command)) { reasons.push("Flushing all firewall rules"); risk = "high" }
+  if (/\bsystemctl\b/.test(command) && /(?:stop|disable|mask)\s+/i.test(command) && /\bsshd?\b|\bfirewalld?\b/i.test(command)) { reasons.push("Stopping/disabling critical system service"); risk = "high" }
+  if (/\bdd\s+.*of=\/dev\//i.test(command)) { reasons.push("dd writing directly to device — disk destruction risk"); risk = "critical" }
+  if (/encodedcommand/i.test(command) || (/\b-enc\b/i.test(command) && /\bpowershell\b|\bpwsh\b/i.test(command))) { reasons.push("PowerShell encoded command — obfuscation risk"); risk = "high" }
+  if (/executionpolicy\s+bypass/i.test(command) || /executionpolicy\s+unrestricted/i.test(command)) { reasons.push("PowerShell execution policy bypass"); risk = "high" }
+  if (/>\s*.*\/\.bashrc/i.test(command) || />\s*.*\/\.zshrc/i.test(command) || />\s*.*\/\.profile/i.test(command) || />\s*.*\/\.bash_profile/i.test(command)) { reasons.push("Overwriting shell configuration file"); risk = "high" }
+  if ((/\/etc\/resolv\.conf/i.test(command) || /\/etc\/hosts/i.test(command)) && (base === "rm" || base === "remove-item" || />/.test(command))) { reasons.push("Modifying DNS/network configuration"); risk = "high" }
+
+  return { safe: reasons.length === 0, blocked: risk === "critical", reasons, risk }
+}
+
+export function isCommandSafe(cmd: string) { return validate(cmd).safe }
+
+export function getSecurityReport(cmd: string): string {
+  const r = validate(cmd)
+  if (r.safe) return "✓ No security concerns"
+  const lines = [`Security: ${r.risk.toUpperCase()}`, ...r.reasons.map(x => `  - ${x}`)]
+  if (r.blocked) lines.push("  BLOCKED: This command cannot be executed.")
+  return lines.join("\n")
+}

package/src/boxes/bom.ts

@@ -0,0 +1,18 @@
+/**
+ * bom.ts — UTF-8 BOM split/join
+ * Zero deps.
+ *
+ * split("\uFEFFhello") → { bom: true, text: "hello" }
+ * join("hello", true) → "\uFEFFhello"
+ */
+const BOM = 0xfeff
+
+export function split(text: string) {
+  if (text.charCodeAt(0) !== BOM) return { bom: false as const, text }
+  return { bom: true as const, text: text.slice(1) }
+}
+
+export function join(text: string, bom: boolean) {
+  const t = split(text).text
+  return bom ? String.fromCharCode(BOM) + t : t
+}

package/src/boxes/cancel.ts

@@ -0,0 +1,16 @@
+/**
+ * cancel.ts — Auto-aborting AbortController + signal combiner
+ * Zero deps.
+ *
+ * const { signal, clearTimeout } = cancelAfter(5000)
+ */
+export function cancelAfter(ms: number) {
+  const ctrl = new AbortController()
+  const id = setTimeout(ctrl.abort.bind(ctrl), ms)
+  return { controller: ctrl, signal: ctrl.signal, clearTimeout: () => globalThis.clearTimeout(id) }
+}
+
+export function cancelAny(ms: number, ...signals: AbortSignal[]) {
+  const t = cancelAfter(ms)
+  return { signal: AbortSignal.any([t.signal, ...signals]), clearTimeout: t.clearTimeout }
+}

package/src/boxes/chop.ts

@@ -0,0 +1,12 @@
+export function chop(s: string, max: number, marker = "…"): string {
+  if (s.length <= max) return s
+  return s.slice(0, max - marker.length) + marker
+}
+
+export function chopMid(s: string, max = 35): string {
+  if (s.length <= max) return s
+  const half = max - 1
+  const a = Math.ceil(half / 2)
+  const b = Math.floor(half / 2)
+  return s.slice(0, a) + "…" + s.slice(-b)
+}

package/src/boxes/clamp.ts

@@ -0,0 +1,3 @@
+export function clamp(v: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, v))
+}

package/src/boxes/compact.ts

@@ -0,0 +1,9 @@
+export function compact(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M"
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + "K"
+  return String(n)
+}
+
+export function filterTruthy<T>(arr: (T | false | null | undefined | 0 | "")[]): T[] {
+  return arr.filter(Boolean as any) as T[]
+}

package/src/boxes/cost-tracker.ts

@@ -0,0 +1,116 @@
+/**
+ * cost-tracker.ts — Token usage & USD cost per model (session-scoped)
+ * Deps: none (pure TS)
+ * Ported from Claude Code cost-tracker.ts
+ */
+
+export interface TokenUsage {
+  input_tokens: number
+  output_tokens: number
+  cache_read_input_tokens?: number
+  cache_creation_input_tokens?: number
+  server_tool_use?: { web_search_requests?: number }
+}
+
+export interface ModelUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadInputTokens: number
+  cacheCreationInputTokens: number
+  webSearchRequests: number
+  costUSD: number
+  contextWindow: number
+  maxOutputTokens: number
+}
+
+interface CostState {
+  totalCostUSD: number
+  totalAPIDuration: number
+  totalAPIDurationWithoutRetries: number
+  totalToolDuration: number
+  totalLinesAdded: number
+  totalLinesRemoved: number
+  totalDuration: number
+  lastDuration: number | undefined
+  modelUsage: Record<string, ModelUsage>
+}
+
+function empty(): CostState {
+  return {
+    totalCostUSD: 0, totalAPIDuration: 0, totalAPIDurationWithoutRetries: 0,
+    totalToolDuration: 0, totalLinesAdded: 0, totalLinesRemoved: 0,
+    totalDuration: 0, lastDuration: undefined, modelUsage: {},
+  }
+}
+
+const state: CostState = empty()
+
+export function reset() { Object.assign(state, empty()) }
+export function getTotalCost() { return state.totalCostUSD }
+export function getDuration() { return state.totalDuration }
+export function getAPIDuration() { return state.totalAPIDuration }
+export function getLines() { return { added: state.totalLinesAdded, removed: state.totalLinesRemoved } }
+export function getModelUsage() { return state.modelUsage }
+export function getUsageForModel(model: string) { return state.modelUsage[model] }
+export function addLines(added: number, removed: number) {
+  state.totalLinesAdded += added; state.totalLinesRemoved += removed
+}
+export function addAPIDuration(ms: number, withoutRetries: number) {
+  state.totalAPIDuration += ms; state.totalAPIDurationWithoutRetries += withoutRetries
+}
+export function addToolDuration(ms: number) { state.totalToolDuration += ms }
+
+export function addSessionCost(cost: number, usage: TokenUsage, model: string): number {
+  if (!state.modelUsage[model]) {
+    state.modelUsage[model] = {
+      inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 0, webSearchRequests: 0,
+      costUSD: 0, contextWindow: 0, maxOutputTokens: 0,
+    }
+  }
+  const m = state.modelUsage[model]
+  m.inputTokens += usage.input_tokens
+  m.outputTokens += usage.output_tokens
+  m.cacheReadInputTokens += usage.cache_read_input_tokens ?? 0
+  m.cacheCreationInputTokens += usage.cache_creation_input_tokens ?? 0
+  m.webSearchRequests += usage.server_tool_use?.web_search_requests ?? 0
+  m.costUSD += cost
+  state.totalCostUSD += cost
+  return cost
+}
+
+export function formatCost(cost: number, decimals = 4) {
+  return `$${cost > 0.5 ? cost.toFixed(2) : cost.toFixed(decimals)}`
+}
+
+function fmtDur(ms: number) {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const s = ms / 1000
+  if (s < 60) return `${s.toFixed(1)}s`
+  return `${Math.floor(s / 60)}m${Math.round(s % 60)}s`
+}
+
+function fmtNum(n: number) { return n.toLocaleString() }
+
+export function formatTotalCost() {
+  const l = state
+  const usageLines = Object.keys(l.modelUsage).length === 0
+    ? "Usage:                 0 input, 0 output, 0 cache read, 0 cache write"
+    : [
+        "Usage by model:",
+        ...Object.entries(l.modelUsage).map(([model, u]) =>
+          `${model}:`.padStart(21) +
+          `${fmtNum(u.inputTokens)} input, ${fmtNum(u.outputTokens)} output, ` +
+          `${fmtNum(u.cacheReadInputTokens)} cache read, ${fmtNum(u.cacheCreationInputTokens)} cache write` +
+          (u.webSearchRequests > 0 ? `, ${fmtNum(u.webSearchRequests)} web search` : "") +
+          ` (${formatCost(u.costUSD)})`
+        ),
+      ].join("\n")
+  return [
+    `Total cost:            ${formatCost(l.totalCostUSD)}`,
+    `Total duration (API):  ${fmtDur(l.totalAPIDuration)}`,
+    `Total duration (wall): ${fmtDur(l.totalDuration)}`,
+    `Total code changes:    ${l.totalLinesAdded} ${l.totalLinesAdded === 1 ? "line" : "lines"} added, ${l.totalLinesRemoved} ${l.totalLinesRemoved === 1 ? "line" : "lines"} removed`,
+    usageLines,
+  ].join("\n")
+}

package/src/boxes/dataurl.ts

@@ -0,0 +1,29 @@
+/**
+ * dataurl.ts — Encode/decode data: URLs
+ * Zero deps (uses Buffer for base64).
+ *
+ * decode("data:text/plain;base64,aGVsbG8=") → "hello"
+ * encode("text/plain", buf) → "data:text/plain;base64,aGVsbG8="
+ * parse("data:text/plain;base64,aGVsbG8=") → { mime: "text/plain", base64: "aGVsbG8=" }
+ */
+export function decode(url: string): string {
+  const i = url.indexOf(",")
+  if (i === -1) return ""
+  const head = url.slice(0, i)
+  const body = url.slice(i + 1)
+  if (head.includes(";base64")) return Buffer.from(body, "base64").toString("utf8")
+  return decodeURIComponent(body)
+}
+
+export function encode(mime: string, data: string | ArrayBuffer | Uint8Array): string {
+  const base64 = typeof data === "string"
+    ? Buffer.from(data).toString("base64")
+    : Buffer.from(data instanceof Uint8Array ? data : new Uint8Array(data)).toString("base64")
+  return `data:${mime};base64,${base64}`
+}
+
+export function parse(url: string): { mime: string; base64: string; data: string } | undefined {
+  const match = url.match(/^data:([^;]+);base64,(.*)$/)
+  if (!match) return undefined
+  return { mime: match[1], base64: match[2], data: decode(url) }
+}

package/src/boxes/delay.ts

@@ -0,0 +1,27 @@
+/**
+ * delay.ts — Abort-aware setTimeout
+ * Ported from gemini-cli (Apache-2.0)
+ * Deps: none
+ */
+export function createAbortError(): Error {
+  const e = new Error("Aborted")
+  e.name = "AbortError"
+  return e
+}
+
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) return new Promise(r => setTimeout(r, ms))
+  if (signal.aborted) return Promise.reject(createAbortError())
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(tid)
+      signal.removeEventListener("abort", onAbort)
+      reject(createAbortError())
+    }
+    const tid = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    signal.addEventListener("abort", onAbort, { once: true })
+  })
+}