hilos-agent 0.9.0 → 0.9.2

package/src/agent-events.mjs

@@ -25,13 +25,25 @@
  * @typedef {object} AgentEvent
  * A normalized, render-ready step. Exactly one of these per meaningful thing the
  * coding agent did. Small on purpose — the LiveRunCard maps `t` to a label.
- * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'} t
+ * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'|'usage'|'websearch'|'webfetch'|'subagent'} t
  *   - 'session' → { sessionId }        the CLI's resumable session id (init only)
  *   - 'edit'    → { path }             wrote/edited a file
  *   - 'read'    → { path }             read a file
  *   - 'run'     → { cmd }              ran a shell command
  *   - 'note'    → { text }             the agent's narration / thinking (think→note)
+ *   - 'websearch' → { query }          searched the web (0789)
+ *   - 'webfetch'  → { target }         read a web page — host + path ONLY, the
+ *                                      query string is stripped before it gets
+ *                                      here (0789)
+ *   - 'subagent'  → { text }           spawned a helper; ONE line per spawn, the
+ *                                      helper's own steps never surface (0789)
  *   - 'result'  → { ok, summary? }     the run finished (ok=false on error)
+ *   - 'usage'   → { inputTokens, outputTokens, cacheReadTokens,
+ *                   cacheCreationTokens, costUsd?, model? }
+ *                                      what the turn cost, as the CLI itself
+ *                                      reported it (0787). Never a step — the
+ *                                      ring and the activity fold skip it; it
+ *                                      rides home on the report instead.
  *   - 'phase'   → { name }             reserved lifecycle marker (unused by v1
  *                                       parsers; kept so 0274 can add start/end
  *                                       phases without widening the type)
@@ -39,9 +51,17 @@
  * @property {string} [path]
  * @property {string} [cmd]
  * @property {string} [text]
+ * @property {string} [query]
+ * @property {string} [target]
  * @property {string} [name]
  * @property {boolean} [ok]
  * @property {string} [summary]
+ * @property {number} [inputTokens]
+ * @property {number} [outputTokens]
+ * @property {number} [cacheReadTokens]
+ * @property {number} [cacheCreationTokens]
+ * @property {number} [costUsd]
+ * @property {string} [model]
  */
 
 // --- Security: sanitize everything that reaches the UI ---------------------
@@ -93,6 +113,239 @@ function tryParse(line) {
   }
 }
 
+// --- Usage (0787) ----------------------------------------------------------
+//
+// Both live-verified streams already carry what a run cost; before 0787 the
+// parsers read those very lines and threw the numbers away. The rule here is
+// the module's rule everywhere else: a vendor that reports nothing produces
+// NOTHING (no zero-filled event, no invented model), because an honest silence
+// degrades to "Tokens unavailable" on the card while a fabricated zero reads as
+// a free run.
+
+/** A finite, non-negative number, or 0. Never throws, never returns NaN. */
+function posNum(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+/** Token counts are whole numbers. */
+function tokenNum(value) {
+  return Math.floor(posNum(value));
+}
+
+/**
+ * Build a `usage` event, or null when the CLI reported nothing usable. `model`
+ * is optional — plenty of streams price a turn without naming the model, and
+ * the daemon fills that in from the model it resolved at spawn.
+ */
+function usageEvent({
+  inputTokens,
+  outputTokens,
+  cacheReadTokens,
+  cacheCreationTokens,
+  costUsd,
+  model,
+} = {}) {
+  const ev = {
+    t: "usage",
+    inputTokens: tokenNum(inputTokens),
+    outputTokens: tokenNum(outputTokens),
+    cacheReadTokens: tokenNum(cacheReadTokens),
+    cacheCreationTokens: tokenNum(cacheCreationTokens),
+  };
+  if (typeof costUsd === "number" && Number.isFinite(costUsd) && costUsd >= 0) {
+    ev.costUsd = costUsd;
+  }
+  const id = sanitizeText(typeof model === "string" ? model.trim() : "");
+  if (id) ev.model = id;
+  const tokens =
+    ev.inputTokens + ev.outputTokens + ev.cacheReadTokens + ev.cacheCreationTokens;
+  if (!tokens && ev.costUsd == null) return null; // nothing was reported
+  return ev;
+}
+
+/**
+ * Which model a Claude `result` frame credits the work to. Live-verified: the
+ * frame carries a `modelUsage` map keyed by model id (a run that spawns
+ * subagents lists several), so we credit the id that did the most work rather
+ * than whichever key happens to be first.
+ */
+function claudeResultModel(obj) {
+  const map = obj.modelUsage && typeof obj.modelUsage === "object" ? obj.modelUsage : null;
+  if (!map) return "";
+  let best = "";
+  let bestTokens = -1;
+  for (const [id, entry] of Object.entries(map)) {
+    if (!id || !entry || typeof entry !== "object") continue;
+    const tokens =
+      posNum(entry.inputTokens) +
+      posNum(entry.outputTokens) +
+      posNum(entry.cacheReadInputTokens) +
+      posNum(entry.cacheCreationInputTokens);
+    if (tokens > bestTokens) {
+      bestTokens = tokens;
+      best = id;
+    }
+  }
+  return best;
+}
+
+/**
+ * Accumulate `usage` events into one total.
+ *
+ * DELTA CONTRACT: `take()` returns everything folded SINCE THE LAST TAKE and
+ * resets. Reports are additive on the server (each one writes its own ledger
+ * row), so a run that reports twice — a proposal card and then a shipped card,
+ * or one revision round per loop — must send what is new each time. Sending a
+ * running total would bill the same tokens over and over. The model id is
+ * sticky: it is a label, not a quantity, so every take carries the last one seen.
+ */
+export function createUsageFold() {
+  let pending = null;
+  let model = "";
+
+  const empty = () => ({
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    costUsd: null,
+  });
+
+  return {
+    /** @param {AgentEvent} ev */
+    push(ev) {
+      if (!ev || typeof ev !== "object" || ev.t !== "usage") return;
+      if (!pending) pending = empty();
+      pending.inputTokens += tokenNum(ev.inputTokens);
+      pending.outputTokens += tokenNum(ev.outputTokens);
+      pending.cacheReadTokens += tokenNum(ev.cacheReadTokens);
+      pending.cacheCreationTokens += tokenNum(ev.cacheCreationTokens);
+      if (typeof ev.costUsd === "number" && Number.isFinite(ev.costUsd) && ev.costUsd >= 0) {
+        pending.costUsd = posNum(pending.costUsd) + ev.costUsd;
+      }
+      if (typeof ev.model === "string" && ev.model) model = ev.model;
+    },
+    /** Peek at what is pending without consuming it. */
+    total() {
+      return pending ? { ...pending, ...(model ? { model } : {}) } : null;
+    },
+    /** Consume everything folded since the last take. */
+    take() {
+      const out = pending ? { ...pending, ...(model ? { model } : {}) } : null;
+      pending = null;
+      return out;
+    },
+  };
+}
+
+// --- Web + subagent steps (0789) --------------------------------------------
+//
+// Before 0789 every mapper dropped WebSearch / WebFetch / Grep / Glob / Task, so
+// a run could spend two minutes reading the web and hiring a helper while the
+// room watched a card that said nothing. Web calls and subagent spawns now get
+// ONE quiet line each.
+//
+// GREP AND GLOB STAY DROPPED — deliberately, not by omission. The audit listed
+// them alongside the web tools, but the card is an EIGHT-STEP recency window:
+// a run that greps thirty times would spend the whole ring on searches nobody
+// is waiting on and push the edits and the test run off the top. A web call or
+// a helper spawn is rare and each one is news; a grep is the agent clearing its
+// throat.
+//
+// The subagent's INTERIOR stays invisible too (0537's rule): the helper's own
+// steps reach the room as narration when it reports, never as steps on the
+// parent's card. One line per spawn, at the spawn.
+
+/** Longest a query / target / description may be on a card line, before the
+ *  300-char sanitize cap. Same budget describeRun gives a command. */
+const WEB_LABEL_MAX = 60;
+
+/** Collapse whitespace, cap to a card line, then strip token-shaped secrets. */
+function webPhrase(value) {
+  const raw = typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  if (!raw) return "";
+  // Redact BEFORE truncating (lockstep with lib/hosted-progress.ts): a token
+  // cut at the cap loses the suffix the redactor keys on, and the fragment
+  // would render.
+  const clean = sanitizeText(raw);
+  if (!clean) return "";
+  return clean.length > WEB_LABEL_MAX ? clean.slice(0, WEB_LABEL_MAX - 1) + "…" : clean;
+}
+
+/**
+ * A URL reduced to host + path. The QUERY STRING NEVER REACHES THE CARD — it is
+ * where API keys, signed-URL tokens and session ids live, and a fetched URL is
+ * attacker-influenceable (an agent follows links). The fragment goes for the
+ * same reason, and userinfo (`https://user:token@host/…`) is dropped because
+ * `URL#host` excludes it. A scheme-less string is retried as https, but ONLY if
+ * its authority carries a dot — otherwise `new URL` happily turns any bare word
+ * into a "host" and the card would narrate "Read not-a-url-at-all" instead of
+ * degrading to "Read a web page". Anything with no host (`data:`, `mailto:`,
+ * plain prose) → "".
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function webTarget(value) {
+  const raw = typeof value === "string" ? value.trim() : "";
+  if (!raw) return "";
+  let url = null;
+  try {
+    url = new URL(raw);
+  } catch {
+    if (!/^[^\s/?#@]+\.[^\s/?#@]+/.test(raw)) return "";
+    try {
+      url = new URL(`https://${raw}`);
+    } catch {
+      return ""; // not a URL — say nothing rather than echo an unparsed string
+    }
+  }
+  if (!url.host) return "";
+  const path = url.pathname && url.pathname !== "/" ? url.pathname.replace(/\/+$/, "") : "";
+  return webPhrase(`${url.host}${path}`);
+}
+
+/**
+ * Claude-family web + subagent tools → an AgentEvent, or null to fall through.
+ *
+ * Tool names captured LIVE against Claude Code 2.1.233
+ * (`claude -p --output-format stream-json --verbose`):
+ *
+ *   {"type":"assistant","message":{"content":[{"type":"tool_use",
+ *     "name":"WebSearch","input":{"query":"hilos.sh Pablo Stanley chat for agents"}}]}}
+ *   {"type":"assistant","message":{"content":[{"type":"tool_use",
+ *     "name":"WebFetch","input":{"url":"https://example.com/?token=…","prompt":"what is this page"}}]}}
+ *   {"type":"assistant","message":{"content":[{"type":"tool_use",
+ *     "name":"Agent","input":{"description":"probe subagent","prompt":"…",
+ *     "subagent_type":"general-purpose","run_in_background":false}}]}}
+ *
+ * The subagent tool is named `Agent` in this build — the audit called it `Task`,
+ * which is what older builds and the hosted sandbox's tool list use — so BOTH
+ * names map, and both carry `input.description`. The `system`/`task_started`,
+ * `task_updated` and `task_notification` frames that follow a spawn are the
+ * helper's interior and stay unmapped on purpose.
+ *
+ * LOCKSTEP: `toolEvent` in lib/hosted-progress.ts is this function's TS twin.
+ * Change one, look at the other.
+ */
+function claudeWebToolEvent(name, input) {
+  const o = input && typeof input === "object" ? input : {};
+  switch (name) {
+    case "WebSearch":
+      return { t: "websearch", query: webPhrase(o.query) };
+    case "WebFetch":
+      return { t: "webfetch", target: webTarget(o.url) };
+    case "Agent":
+    case "Task": {
+      // Only a spawn that says what it hired the helper FOR is worth a line;
+      // "Started a helper" alone tells the room nothing it can act on.
+      const text = webPhrase(o.description);
+      return text ? { t: "subagent", text } : null;
+    }
+    default:
+      return null;
+  }
+}
+
 /** Map a Claude/agent tool name to a normalized event kind (or null to skip). */
 function toolKind(name) {
   switch (name) {
@@ -106,8 +359,9 @@ function toolKind(name) {
     case "Bash":
       return "run";
     default:
-      // Grep/Glob/WebFetch/Task/etc. carry less "alive" signal; ignore in v1 so
-      // an unknown tool can never crash the parser. 0274 may promote some.
+      // Grep/Glob/etc. carry less "alive" signal; ignore so an unknown tool can
+      // never crash the parser. The web + subagent tools are handled ahead of
+      // this by claudeWebToolEvent (0789).
       return null;
   }
 }
@@ -120,6 +374,8 @@ function blockToEvent(block) {
     return text ? { t: "note", text } : null;
   }
   if (block.type === "tool_use" && typeof block.name === "string") {
+    const web = claudeWebToolEvent(block.name, block.input);
+    if (web) return web;
     const kind = toolKind(block.name);
     if (!kind) return null;
     const input = block.input && typeof block.input === "object" ? block.input : {};
@@ -139,6 +395,19 @@ function blockToEvent(block) {
  * `lib/hosted-agent.ts`: system init (session_id), assistant turns (text +
  * tool_use), and the final result. Everything else (user tool_result, unknown
  * types) → [].
+ *
+ * The result frame also prices the run (0787). Captured LIVE against Claude
+ * Code 2.1.233 (`claude -p --output-format stream-json --verbose`):
+ *
+ *   {"type":"result","subtype":"success","total_cost_usd":0.481725,
+ *    "usage":{"input_tokens":2,"cache_creation_input_tokens":23172,
+ *             "cache_read_input_tokens":16015,"output_tokens":45,…},
+ *    "modelUsage":{"claude-fable-5":{"inputTokens":2,"outputTokens":45,
+ *      "cacheReadInputTokens":16015,"cacheCreationInputTokens":23172,
+ *      "costUSD":0.481725,…}}, …}
+ *
+ * Same field names `lib/run-usage.ts` settles hosted runs on — deliberately, so
+ * both lanes meter the same numbers.
  */
 function parseClaudeLine(line) {
   const obj = tryParse(line);
@@ -149,7 +418,17 @@ function parseClaudeLine(line) {
   if (obj.type === "result") {
     const ok = obj.is_error !== true && obj.subtype !== "error";
     const summary = typeof obj.result === "string" ? sanitizeText(obj.result) : undefined;
-    return [summary ? { t: "result", ok, summary } : { t: "result", ok }];
+    const u = obj.usage && typeof obj.usage === "object" ? obj.usage : {};
+    const usage = usageEvent({
+      inputTokens: u.input_tokens,
+      outputTokens: u.output_tokens,
+      cacheReadTokens: u.cache_read_input_tokens,
+      cacheCreationTokens: u.cache_creation_input_tokens,
+      costUsd: obj.total_cost_usd,
+      model: claudeResultModel(obj),
+    });
+    const done = summary ? { t: "result", ok, summary } : { t: "result", ok };
+    return usage ? [usage, done] : [done];
   }
   if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
     const out = [];
@@ -163,50 +442,234 @@ function parseClaudeLine(line) {
 }
 
 /**
- * Parse ONE Codex `--json` item line → AgentEvent[]. Best-effort / experimental:
- * Codex's format is younger and less documented, so we read the kind from either
- * `item.type` (the `{type:"item.completed", item:{…}}` envelope) or a bare
- * top-level `type`, and pull fields from whichever object carries them. Unknown
- * kinds → [].
+ * A stateful line parser for Codex `exec --json` JSONL (0783).
+ *
+ * Shapes captured LIVE against codex-cli 0.144.1 (a real `codex exec --json`
+ * run in a scratch repo — create a file, run a command, read it back):
+ *
+ *   {"type":"thread.started","thread_id":"01a00968-…"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.completed","item":{"id":"item_1","type":"agent_message","text":"…"}}
+ *   {"type":"item.started","item":{"id":"item_2","type":"file_change",
+ *     "changes":[{"path":"/tmp/x/hello.txt","kind":"add"}],"status":"in_progress"}}
+ *   {"type":"item.completed","item":{"id":"item_2","type":"file_change",…,"status":"completed"}}
+ *   {"type":"item.started","item":{"id":"item_3","type":"command_execution",
+ *     "command":"/bin/zsh -lc 'ls -la'","exit_code":null,"status":"in_progress"}}
+ *   {"type":"item.completed","item":{"id":"item_3",…,"exit_code":0,"status":"completed"}}
+ *   {"type":"turn.completed","usage":{…}}
+ *
+ * What that stream forced, and why this parser is stateful:
+ *   - `thread.started.thread_id` IS the resumable session id — the same id
+ *     `codex exec resume <id>` takes (live-verified: a resumed run answered
+ *     from the first run's context) and the same id `thread.started` echoes
+ *     back on the resumed run. It's the ONLY place the id appears, so it is
+ *     the `session` event that 0282's resume gate records.
+ *   - EVERY tool item arrives TWICE (`item.started` then `item.completed`,
+ *     same `item.id`), so we emit AT MOST ONCE per item id — at the first
+ *     frame that carries content, which is the `started` one. Same emit-once
+ *     discipline as createAcpEventMapper; an item with no id (older/other
+ *     shapes) is never deduped, so nothing that used to emit stops emitting.
+ *   - `turn.completed` carries ONLY usage — no text. So the last
+ *     `agent_message` is remembered and becomes the result summary, which is
+ *     what the folder run reports (raw stdout is JSONL now, not prose).
+ *   - Failure has two spellings, and a real run emits BOTH: a top-level
+ *     `{"type":"error","message":…}` and a `turn.failed` carrying
+ *     `error.message`. One result per stream — but a bare stream error is HELD,
+ *     not published: codex retries some of them, and a verdict latched on the
+ *     first error would throw away the successful `turn.completed` that
+ *     follows. The turn decides: `turn.completed` clears the held error and
+ *     wins with success, `turn.failed` publishes the failure, and a stream that
+ *     just stops (flush, no terminal turn) publishes what it was holding.
+ *   - An item whose `type` is `error` is NOT a failed run — live capture shows
+ *     advisory notices there (a skills-context-budget warning). Those are
+ *     skipped; the run's real verdict comes from turn.failed / the stream error.
+ *
+ * Unknown envelopes and unknown item kinds → [] (a Codex format change
+ * degrades the card, never crashes the run).
  */
-function parseCodexLine(line) {
-  const obj = tryParse(line);
-  if (!obj) return [];
-  const item = obj.item && typeof obj.item === "object" ? obj.item : obj;
-  const kind = item.type ?? obj.type;
-  switch (kind) {
-    case "command_execution": {
-      const raw = item.command ?? item.cmd;
-      const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
-      return cmd ? [{ t: "run", cmd: sanitizeText(cmd) }] : [];
+/**
+ * Codex's token accounting → a `usage` event, or null (0787).
+ *
+ * ONE rule for both codex transports, which report the same shape in two
+ * different envelopes — `codex exec --json`'s `turn.completed.usage` and
+ * `codex mcp-server`'s `token_count.info.last_token_usage`:
+ *
+ *   {"input_tokens":21993,"cached_input_tokens":9984,
+ *    "output_tokens":5,"reasoning_output_tokens":0}
+ *
+ * `input_tokens` is the TOTAL prompt, with `cached_input_tokens` a subset of it
+ * (the OpenAI convention), so the cached half is split out to sit in the same
+ * uncached/cache-read shape Claude reports and hosted settlement already stores.
+ * `reasoning_output_tokens` is likewise a subset of `output_tokens` — adding it
+ * would double-count. Codex prices nothing and names no model, so the event
+ * carries neither; the daemon supplies the model it resolved at spawn.
+ *
+ * Exported because the MCP transport (codex-mcp-session.mjs) is not a stdout
+ * parser and cannot go through makeStreamParser, but must split cached tokens
+ * exactly the same way or the two transports would report differently.
+ */
+export function codexUsageEvent(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const total = tokenNum(usage.input_tokens);
+  const cached = Math.min(tokenNum(usage.cached_input_tokens), total);
+  return usageEvent({
+    inputTokens: total - cached,
+    cacheReadTokens: cached,
+    outputTokens: usage.output_tokens,
+  });
+}
+
+/** A Codex turn envelope → at most one `usage` event. */
+function codexUsage(obj) {
+  const ev = codexUsageEvent(obj.usage);
+  return ev ? [ev] : [];
+}
+
+function makeCodexLineParser() {
+  const emitted = new Set(); // item.id → already turned into an event
+  let lastMessage = ""; // the newest agent_message — the turn.completed summary
+  let resultSeen = false; // one verdict per stream (error + turn.failed pair up)
+  let heldError = null; // a bare stream error, waiting for the turn to rule on it
+
+  const result = (ok, summary) => {
+    if (resultSeen) return [];
+    resultSeen = true;
+    heldError = null;
+    return [summary ? { t: "result", ok, summary } : { t: "result", ok }];
+  };
+
+  function parseCodexLine(line) {
+    const obj = tryParse(line);
+    if (!obj) return [];
+
+    // --- Envelope-level events (thread/turn/stream), never items -------------
+    if (obj.type === "thread.started") {
+      const raw = obj.thread_id ?? obj.threadId ?? obj.session_id;
+      const id = typeof raw === "string" ? sanitizeText(raw) : "";
+      return id ? [{ t: "session", sessionId: id }] : [];
     }
-    case "file_change": {
-      const changes = Array.isArray(item.changes)
-        ? item.changes
-        : item.path
-          ? [{ path: item.path }]
-          : [];
-      const out = [];
-      for (const c of changes) {
-        const p = c && (c.path ?? c.file_path);
-        if (typeof p === "string" && p) out.push({ t: "edit", path: sanitizeText(p) });
-      }
+    if (obj.type === "turn.started") return [];
+    if (obj.type === "turn.completed") {
+      const out = codexUsage(obj);
+      for (const ev of result(true, lastMessage)) out.push(ev);
       return out;
     }
-    case "agent_message": {
-      const raw = item.text ?? item.message;
-      const text = typeof raw === "string" ? sanitizeText(raw.replace(/\s+/g, " ").trim()) : "";
-      return text ? [{ t: "note", text }] : [];
-    }
-    case "task_complete":
-    case "turn.completed": {
-      const raw = item.text ?? item.message ?? obj.text;
-      const summary = typeof raw === "string" ? sanitizeText(raw) : undefined;
-      return [summary ? { t: "result", ok: true, summary } : { t: "result", ok: true }];
+    if (obj.type === "turn.failed") {
+      const err = obj.error && typeof obj.error === "object" ? obj.error : {};
+      const raw = err.message ?? obj.message;
+      const summary = typeof raw === "string" ? sanitizeText(raw) : "";
+      // A failed turn still spent tokens. Codex has not been observed pricing
+      // one, so this emits only if the envelope actually carries usage.
+      const out = codexUsage(obj);
+      for (const ev of result(false, summary || heldError || "")) out.push(ev);
+      return out;
     }
-    default:
+    if (obj.type === "error" && !obj.item) {
+      // HELD, not published — see the header. The turn (or the end of the
+      // stream) decides whether this was the run's verdict or a blip it retried.
+      if (resultSeen) return [];
+      const raw = obj.message ?? (obj.error && typeof obj.error === "object" ? obj.error.message : "");
+      heldError = (typeof raw === "string" ? sanitizeText(raw) : "") || heldError || "";
       return [];
+    }
+
+    // --- Item events --------------------------------------------------------
+    const item = obj.item && typeof obj.item === "object" ? obj.item : obj;
+    const kind = item.type ?? obj.type;
+    const id = typeof item.id === "string" && item.id ? item.id : "";
+    if (id && emitted.has(id)) return []; // the started/completed twin
+    const keep = (events) => {
+      if (events.length && id) {
+        emitted.add(id);
+        if (emitted.size > 500) emitted.delete(emitted.values().next().value); // bound
+      }
+      return events;
+    };
+
+    switch (kind) {
+      case "command_execution": {
+        const raw = item.command ?? item.cmd;
+        const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
+        return keep(cmd ? [{ t: "run", cmd: sanitizeText(cmd) }] : []);
+      }
+      case "file_change": {
+        const changes = Array.isArray(item.changes)
+          ? item.changes
+          : item.path
+            ? [{ path: item.path }]
+            : [];
+        const out = [];
+        for (const c of changes) {
+          const p = c && (c.path ?? c.file_path);
+          if (typeof p === "string" && p) out.push({ t: "edit", path: sanitizeText(p) });
+        }
+        return keep(out);
+      }
+      case "web_search": {
+        // 0789, captured LIVE against codex-cli 0.144.1 (`codex exec --json
+        // -c tools.web_search=true`):
+        //
+        //   item.started   {"id":"exec-bdb…","type":"web_search","query":"",
+        //                   "action":{"type":"other"}}
+        //   item.completed {"id":"exec-bdb…","type":"web_search",
+        //                   "query":"hilos.sh Pablo Stanley",
+        //                   "action":{"type":"search","query":"hilos.sh Pablo Stanley"}}
+        //
+        // The STARTED half carries an EMPTY query — codex opens the item before
+        // the model has committed to the words. Returning [] there leaves the id
+        // unmarked (keep() only remembers ids that actually emitted), so the
+        // completed twin is the one that becomes the step. Same shape as
+        // command_execution's "no command says nothing" rule; emit-once holds.
+        const action = item.action && typeof item.action === "object" ? item.action : {};
+        const query = webPhrase(item.query || action.query);
+        return keep(query ? [{ t: "websearch", query }] : []);
+      }
+      case "agent_message": {
+        const raw = item.text ?? item.message;
+        const text = typeof raw === "string" ? sanitizeText(raw.replace(/\s+/g, " ").trim()) : "";
+        if (text) lastMessage = text; // the summary turn.completed doesn't carry
+        return keep(text ? [{ t: "note", text }] : []);
+      }
+      case "task_complete": {
+        // Legacy/other Codex builds: a terminal item rather than a turn envelope.
+        const raw = item.text ?? item.message ?? obj.text;
+        const summary = typeof raw === "string" ? sanitizeText(raw) : lastMessage;
+        return keep(result(true, summary));
+      }
+      default:
+        // `error` items are advisory notices, `reasoning` carries no step —
+        // both skipped, and an unknown kind can never crash the parser.
+        return [];
+    }
   }
+
+  /** End of stream: publish a held error nobody ever ruled on. */
+  function finish() {
+    if (resultSeen || heldError === null) return [];
+    return result(false, heldError);
+  }
+
+  return { parseCodexLine, finish };
+}
+
+/**
+ * The codex stream parser: line buffering over the stateful line parser, plus
+ * the end-of-stream finalizer that publishes a held error (see above). A
+ * `flush()` is the only place the parser learns the stream is over.
+ */
+function makeCodexParser() {
+  const codex = makeCodexLineParser();
+  const lines = makeLineBufferedParser(codex.parseCodexLine);
+  return {
+    /** @param {string} chunk @returns {AgentEvent[]} */
+    push: (chunk) => lines.push(chunk),
+    /** @returns {AgentEvent[]} */
+    flush: () => {
+      const out = lines.flush();
+      for (const ev of codex.finish()) out.push(ev);
+      return out;
+    },
+  };
 }
 
 /**
@@ -284,14 +747,29 @@ function cursorToolEvent(toolCall) {
 
 /** One opencode `tool_use` part → an AgentEvent, or null. Tool names are
  *  lowercase (`read`/`write`/`edit`/`patch`/`bash`); the arguments live under
- *  `state.input` (`filePath` for file tools, `command` for bash). Anything else
- *  (glob/grep/webfetch/task) carries less "alive" signal and is skipped, mirroring
- *  toolKind()'s v1 restraint — an unknown tool never crashes the parser. */
+ *  `state.input` (`filePath` for file tools, `command` for bash). `webfetch` and
+ *  `task` join them in 0789 — captured LIVE against opencode 1.18.5:
+ *
+ *    {"type":"tool_use","part":{"tool":"webfetch","state":{"input":
+ *      {"url":"https://example.com/?token=…"}}}}
+ *    {"type":"tool_use","part":{"tool":"task","state":{"input":
+ *      {"description":"probe subagent","prompt":"…","subagent_type":"general"}}}}
+ *
+ *  opencode ships no web SEARCH tool, so there is nothing to map for it.
+ *  glob/grep stay skipped (see the 0789 note above claudeWebToolEvent), and an
+ *  unknown tool still never crashes the parser. */
 function opencodeToolEvent(part) {
   if (!part || typeof part !== "object") return null;
   const tool = typeof part.tool === "string" ? part.tool.toLowerCase() : "";
   const state = part.state && typeof part.state === "object" ? part.state : {};
   const input = state.input && typeof state.input === "object" ? state.input : {};
+  if (tool === "webfetch") {
+    return { t: "webfetch", target: webTarget(input.url) };
+  }
+  if (tool === "task") {
+    const text = webPhrase(input.description);
+    return text ? { t: "subagent", text } : null;
+  }
   if (tool === "bash") {
     const raw = input.command;
     const cmd = typeof raw === "string" ? raw.replace(/\s+/g, " ").trim() : "";
@@ -468,7 +946,10 @@ function makeTextTailParser() {
 export function makeStreamParser(vendor) {
   const v = normalizeVendor(vendor);
   if (v === "claude") return makeLineBufferedParser(parseClaudeLine);
-  if (v === "codex") return makeLineBufferedParser(parseCodexLine);
+  // codex's parser carries per-stream state (emit-once item ids, the last
+  // agent message, one verdict, a held error) and needs the end of the stream,
+  // so it owns its own line buffering — 0783.
+  if (v === "codex") return makeCodexParser();
   if (v === "cursor") return makeLineBufferedParser(parseCursorLine);
   // opencode's line parser carries per-stream state (dedupe + last text), so
   // each parser instance gets its own.
@@ -501,6 +982,12 @@ export function stepLabel(event) {
       return event.path ? `Reading ${event.path}` : "Reading files";
     case "run":
       return describeRun(event.cmd);
+    case "websearch":
+      return event.query ? `Searched the web: ${event.query}` : "Searched the web";
+    case "webfetch":
+      return event.target ? `Read ${event.target}` : "Read a web page";
+    case "subagent":
+      return event.text ? `Started a helper: ${event.text}` : null;
     case "note":
       return event.text ? event.text : null;
     case "result":
@@ -634,6 +1121,23 @@ export function createActivityFold(limit = MAX_ACTIVITY) {
       case "run":
         add({ kind: "run", subject: event.cmd || "", status: "running", n: 1 });
         return;
+      case "websearch":
+      case "webfetch":
+      case "subagent": {
+        // Past-tense sentences that carry themselves, like `note` — the stream
+        // never tells us when a search or a helper FINISHED, so a "running" row
+        // would sit there mid-tense until some later action happened to settle
+        // it. One settled line, said once (0789).
+        const text = stepLabel(event);
+        if (!text) return;
+        add({
+          kind: event.t === "subagent" ? "task" : "web",
+          subject: text,
+          status: "done",
+          n: 1,
+        });
+        return;
+      }
       case "note":
         if (!event.text) return;
         add({ kind: "note", subject: event.text, status: "done", n: 1 });
@@ -667,3 +1171,99 @@ export function createActivityFold(limit = MAX_ACTIVITY) {
 
   return { push, settle, list };
 }
+
+// --- ACP → AgentEvent (0759 slice 3) ---------------------------------------
+
+const ACP_SEEN_LIMIT = 500;
+
+function stripBackticks(value) {
+  const s = String(value ?? "").trim();
+  const m = /^`(.*)`$/s.exec(s);
+  return m ? m[1].trim() : s;
+}
+
+/**
+ * Map ACP `session/update` tool events onto AgentEvents, statefully.
+ *
+ * The rule comes from the recorded wire logs of both live vendors: cursor's
+ * `tool_call` (status pending) already carries `rawInput.command`, so its row
+ * appears immediately — visible while a permission ask blocks; opencode's
+ * pending frame has only the tool NAME as its title ("bash"), and the real
+ * command arrives on the `in_progress` update. So: merge what each update
+ * teaches per `toolCallId`, emit AT MOST once per id — at the first update
+ * carrying a command or file path — and flush with the best-known title at a
+ * terminal status if neither ever appeared. Message/thought/usage updates are
+ * not activity; they return null.
+ *
+ * 0789 left this mapper alone on purpose: ACP's `kind` vocabulary already
+ * includes `search` and `fetch`, and both fall through to the `note` arm below
+ * carrying the vendor's own title, so web work on an ACP transport was never
+ * invisible the way the stdout parsers made it. Nothing to un-drop here.
+ */
+export function createAcpEventMapper() {
+  /** @type {Map<string, {kind: string, title: string, cmd: string, path: string, emitted: boolean}>} */
+  const seen = new Map();
+  let anonymous = 0;
+
+  function remember(id, info) {
+    if (seen.has(id)) seen.delete(id); // re-insert = most-recent, cheap LRU
+    seen.set(id, info);
+    if (seen.size > ACP_SEEN_LIMIT) {
+      const oldest = seen.keys().next().value;
+      if (oldest !== undefined) seen.delete(oldest);
+    }
+  }
+
+  function eventFor(info) {
+    if (info.kind === "edit") {
+      return { t: "edit", path: info.path || stripBackticks(info.title) };
+    }
+    if (info.kind === "read") {
+      return { t: "read", path: info.path || stripBackticks(info.title) };
+    }
+    if (info.kind === "execute") {
+      return { t: "run", cmd: info.cmd || stripBackticks(info.title) };
+    }
+    const text = stripBackticks(info.title);
+    return text ? { t: "note", text } : null;
+  }
+
+  /** @param {any} update  @returns {AgentEvent | null} */
+  function push(update) {
+    if (!update || typeof update !== "object") return null;
+    const kind = update.sessionUpdate;
+    if (kind !== "tool_call" && kind !== "tool_call_update") return null;
+    const id =
+      typeof update.toolCallId === "string" && update.toolCallId
+        ? update.toolCallId
+        : `acp_anon_${++anonymous}`;
+    const prev = seen.get(id) ?? { kind: "", title: "", cmd: "", path: "", emitted: false };
+    const rawInput =
+      update.rawInput && typeof update.rawInput === "object" ? update.rawInput : {};
+    const location = Array.isArray(update.locations)
+      ? update.locations.find((l) => l && typeof l.path === "string" && l.path)
+      : null;
+    const info = {
+      kind: typeof update.kind === "string" && update.kind ? update.kind : prev.kind,
+      title: typeof update.title === "string" && update.title ? update.title : prev.title,
+      cmd: typeof rawInput.command === "string" && rawInput.command ? rawInput.command : prev.cmd,
+      path: location ? location.path : prev.path,
+      emitted: prev.emitted,
+    };
+    const terminal = ["completed", "failed", "cancelled"].includes(update.status);
+    // A location on an execute call is its working DIRECTORY (observed on
+    // opencode's pending frame), not a target — only a real command may
+    // trigger an execute row, or the weak tool-name title would win.
+    const informative =
+      info.cmd || (info.kind !== "execute" && info.path) || (terminal && info.title);
+    let event = null;
+    if (!info.emitted && informative) {
+      event = eventFor(info);
+      if (event) info.emitted = true;
+    }
+    remember(id, info);
+    return event;
+  }
+
+  return { push };
+}