polygram 0.9.0 → 0.10.0-rc.2

package/lib/tmux/log-tail.js

@@ -0,0 +1,324 @@
+/**
+ * LogTail — generic append-only file tailer. Emits 'line' events as
+ * new lines arrive.
+ *
+ * Used by TmuxProcess to follow claude's per-session JSONL conversation
+ * file (`~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl`) so we can
+ * surface structured assistant + tool + usage + stop_reason events on
+ * the tmux backend. The class itself is backend-agnostic — it just
+ * tails a file.
+ *
+ * (Originally named DebugLogTail when the design assumed we'd parse
+ * `--debug-file` output. The v9 probe showed that channel carries only
+ * MDM/MCP infra messages and zero conversation events; the JSONL
+ * session file is the real channel. Class renamed to match what it
+ * actually does.)
+ *
+ * Design:
+ *   - Default mode `useWatch: 'auto'` uses `fs.watch` on the parent
+ *     directory + filename filter — near-zero steady-state IO. Falls
+ *     back to polling automatically if `fs.watch` fails (sandboxed
+ *     environment, unsupported FS). A slow 1s safety-net poll runs
+ *     alongside the watcher to catch any missed events.
+ *   - `useWatch: false` forces polling — for environments where
+ *     fs.watch is known broken.
+ *   - `useWatch: true` requires fs.watch to work — throws on failure.
+ *     Use for testing the watch path deterministically.
+ *   - Tolerates the file not existing yet (claude may take ~100ms to
+ *     create it after spawn). The directory watcher fires once it
+ *     appears.
+ *   - Carries a partial-line buffer across reads so a line split
+ *     across two reads still emits exactly once.
+ *   - Safety cap on per-line size (MAX_BUF_BYTES) so a hostile or
+ *     corrupted multi-MB single-line write can't OOM the daemon or
+ *     stall the event loop on a sync JSON.parse.
+ *   - Idempotent .close().
+ *
+ * @see lib/tmux/session-log-parser.js — JSONL line → typed event
+ */
+
+'use strict';
+
+const EventEmitter = require('events');
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_INTERVAL_MS = 100;
+// Slow safety-net poll when fs.watch is active. Catches any events
+// the watcher missed (rare on Linux/macOS, more common on networked
+// or fuse filesystems). 1s is more than enough for backstop.
+const WATCH_SAFETY_NET_MS = 1000;
+const DEFAULT_CHUNK_BYTES = 64 * 1024;
+// Safety cap: a single line with no \n must not grow `_buf` without
+// bound. claude TUI doesn't emit lines this big in normal operation;
+// hitting this is a sign of corruption or a hostile tool result that
+// could OOM the daemon and stall the event loop with a sync JSON.parse.
+const MAX_BUF_BYTES = 16 * 1024 * 1024;
+
+class LogTail extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.path             — log file path
+   * @param {number} [opts.intervalMs=100] — poll interval when in
+   *   polling mode (also used as the initial-tick delay in watch mode).
+   * @param {boolean} [opts.skipExisting]  — start at current file size,
+   *   only emit lines added AFTER start(). Used for `--resume` on the
+   *   tmux backend so historic JSONL events aren't replayed.
+   * @param {'auto'|true|false} [opts.useWatch='auto']
+   *   - 'auto' (default): try fs.watch; fall back to polling on error.
+   *   - true:  require fs.watch to work; throw on failure.
+   *   - false: force polling.
+   * @param {object} [opts.fs]             — test seam (override fs)
+   * @param {object} [opts.logger=console]
+   */
+  constructor({
+    path: filePath,
+    intervalMs = DEFAULT_INTERVAL_MS,
+    skipExisting = false,
+    useWatch = 'auto',
+    fs: fsOverride,
+    logger = console,
+  } = {}) {
+    super();
+    if (typeof filePath !== 'string' || !filePath) {
+      throw new TypeError('LogTail: path required');
+    }
+    this.path = filePath;
+    this.intervalMs = intervalMs;
+    this.skipExisting = skipExisting;
+    this.useWatch = useWatch;
+    this.logger = logger;
+    this.fs = fsOverride || fs;
+    this._offset = 0;
+    this._buf = '';
+    this._closed = false;
+    this._timer = null;
+    this._watcher = null;
+    this._mode = null;       // 'watch' | 'poll' after start()
+    this._initialised = false;
+    this._readInFlight = false; // debounce concurrent _readNew triggers
+    this._readPending = false;
+  }
+
+  start() {
+    if (this._closed) throw new Error('LogTail: closed');
+    if (this._mode) return; // idempotent
+    // Snapshot offset at start() time when skipExisting is requested.
+    // Doing this on first read instead would race: if content is
+    // appended between start() and the first read, the offset jump
+    // would skip those bytes too.
+    if (this.skipExisting) {
+      try {
+        const stat = this.fs.statSync(this.path);
+        this._offset = stat.size;
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+        // File doesn't exist yet — offset stays 0, all future content
+        // is "new" by definition.
+      }
+      this._initialised = true;
+    }
+    // Decide watch vs poll. In 'auto' mode we attempt fs.watch and
+    // silently fall back; in 'true' mode we throw on failure; in
+    // 'false' mode we skip the attempt entirely.
+    if (this.useWatch !== false) {
+      if (this._tryStartWatch()) {
+        this._mode = 'watch';
+        // Trigger an immediate first read (existing content + warmup),
+        // then add a slow safety-net poll on top of the watcher to
+        // catch any missed events.
+        setImmediate(() => this._triggerRead());
+        this._startSafetyNetPoll();
+        return;
+      }
+      if (this.useWatch === true) {
+        throw new Error('LogTail: useWatch:true requested but fs.watch failed');
+      }
+      this.logger.log?.(`[log-tail] fs.watch unavailable for ${this.path}; falling back to polling`);
+    }
+    this._mode = 'poll';
+    this._startPolling();
+  }
+
+  /**
+   * Try to install fs.watch on the parent directory. We watch the dir
+   * (not the file) because the file may not exist yet — claude TUI
+   * creates it a moment after spawn. Returns true on success.
+   */
+  _tryStartWatch() {
+    try {
+      const dir = path.dirname(this.path);
+      const base = path.basename(this.path);
+      // Ensure the parent exists so fs.watch can attach. If the
+      // ~/.claude/projects/<cwd> dir hasn't been created yet, claude
+      // will create it on first turn; we make it now so the watcher
+      // can attach immediately.
+      this.fs.mkdirSync(dir, { recursive: true });
+      this._watcher = this.fs.watch(dir, { persistent: false }, (eventType, filename) => {
+        if (this._closed) return;
+        if (filename !== base) return;
+        this._triggerRead();
+      });
+      this._watcher.on('error', (err) => {
+        // Watcher errored mid-flight (e.g. dir removed). Fall back to
+        // polling instead of stopping entirely.
+        this.logger.warn?.(`[log-tail] watcher error for ${this.path}: ${err.message}; falling back to polling`);
+        try { this._watcher.close(); } catch {}
+        this._watcher = null;
+        if (!this._closed) {
+          this._mode = 'poll';
+          this._startPolling();
+        }
+      });
+      return true;
+    } catch (err) {
+      // EPERM (sandbox), ENOSYS (unsupported), ENOENT (path gone) — all fall back.
+      this.logger.log?.(`[log-tail] fs.watch attempt failed: ${err.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Schedule a `_readNew()` call. Multiple triggers between reads are
+   * coalesced into a single read — debounces watcher event storms when
+   * claude writes many lines in quick succession.
+   */
+  _triggerRead() {
+    if (this._closed) return;
+    if (this._readInFlight) {
+      this._readPending = true;
+      return;
+    }
+    this._readInFlight = true;
+    this._readNew()
+      .catch((err) => this.emit('error', err))
+      .finally(() => {
+        this._readInFlight = false;
+        if (this._readPending && !this._closed) {
+          this._readPending = false;
+          // Re-enter once more to catch anything that arrived during
+          // the previous read.
+          setImmediate(() => this._triggerRead());
+        }
+      });
+  }
+
+  _startSafetyNetPoll() {
+    if (this._closed) return;
+    const tick = () => {
+      if (this._closed) return;
+      this._triggerRead();
+      this._timer = setTimeout(tick, WATCH_SAFETY_NET_MS);
+      this._timer.unref?.();
+    };
+    this._timer = setTimeout(tick, WATCH_SAFETY_NET_MS);
+    this._timer.unref?.();
+  }
+
+  _startPolling() {
+    const tick = () => {
+      if (this._closed) return;
+      this._triggerRead();
+      if (!this._closed) {
+        this._timer = setTimeout(tick, this.intervalMs);
+        // Don't keep the event loop alive solely for tailing. In
+        // production the polygram daemon has many other refs (Telegram
+        // polling, IPC, the tmux session itself) keeping it up.
+        this._timer.unref?.();
+      }
+    };
+    // Fire the first tick immediately so existing content (if any)
+    // is consumed without waiting `intervalMs`. setImmediate is NOT
+    // unref'd here — we want at least one read of existing content to
+    // complete before the loop is allowed to exit.
+    this._timer = setImmediate(tick);
+  }
+
+  async _readNew() {
+    let stat;
+    try {
+      stat = await this.fs.promises.stat(this.path);
+    } catch (err) {
+      if (err.code === 'ENOENT') return; // not created yet
+      throw err;
+    }
+    if (stat.size < this._offset) {
+      // File truncated (rare for claude debug-file but possible on log
+      // rotation). Reset offset and re-read from the beginning.
+      this.emit('truncated', { previous: this._offset, current: stat.size });
+      this._offset = 0;
+      this._buf = '';
+    }
+    if (stat.size <= this._offset) return; // unchanged
+    const fd = await this.fs.promises.open(this.path, 'r');
+    try {
+      const bytesToRead = stat.size - this._offset;
+      const buffer = Buffer.alloc(Math.min(bytesToRead, DEFAULT_CHUNK_BYTES));
+      let totalRead = 0;
+      while (totalRead < bytesToRead && !this._closed) {
+        const remaining = bytesToRead - totalRead;
+        const readSize = Math.min(remaining, buffer.length);
+        const { bytesRead } = await fd.read(buffer, 0, readSize, this._offset + totalRead);
+        if (bytesRead === 0) break;
+        this._buf += buffer.slice(0, bytesRead).toString('utf8');
+        totalRead += bytesRead;
+      }
+      this._offset += totalRead;
+    } finally {
+      await fd.close();
+    }
+    // Split on newlines, keeping any trailing partial line in _buf.
+    const parts = this._buf.split(/\r?\n/);
+    this._buf = parts.pop() ?? '';
+    // Safety: drop the trailing partial line if it grew past
+    // MAX_BUF_BYTES without a newline. claude TUI doesn't write lines
+    // this large in normal operation; continuing would risk OOM.
+    if (this._buf.length > MAX_BUF_BYTES) {
+      this.emit('line-too-long', {
+        bytes: this._buf.length,
+        max: MAX_BUF_BYTES,
+        location: 'trailing-partial',
+      });
+      this._buf = '';
+    }
+    for (const line of parts) {
+      if (this._closed) return;
+      // Skip empty lines (common in debug logs).
+      if (line.length === 0) continue;
+      // Safety: drop completed lines that exceed the cap. JSON.parse
+      // on a 100MB line synchronously blocks the event loop.
+      if (line.length > MAX_BUF_BYTES) {
+        this.emit('line-too-long', {
+          bytes: line.length,
+          max: MAX_BUF_BYTES,
+          location: 'completed-line',
+        });
+        continue;
+      }
+      this.emit('line', line);
+    }
+  }
+
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._timer) {
+      clearTimeout(this._timer);
+      clearImmediate(this._timer);
+      this._timer = null;
+    }
+    if (this._watcher) {
+      try { this._watcher.close(); } catch {}
+      this._watcher = null;
+    }
+    // Flush any trailing buffered partial line as a final 'line' so
+    // consumers don't lose data on shutdown.
+    if (this._buf.length > 0) {
+      this.emit('line', this._buf);
+      this._buf = '';
+    }
+    this.emit('close');
+  }
+}
+
+module.exports = { LogTail };

package/lib/tmux/orphan-sweep.js

@@ -0,0 +1,79 @@
+/**
+ * Boot-time tmux orphan sweep — kill any `polygram-<botName>-*` tmux
+ * sessions left over from a prior daemon.
+ *
+ * Why this exists:
+ *   - `lib/process-guard.js#claimPidFile` (rc.50) kills the prior
+ *     polygram daemon at boot, but tmux sessions OUTLIVE their parent
+ *     process — they're owned by the tmux server, not by polygram.
+ *   - When the new daemon's TmuxProcess.start() tries to spawn a
+ *     session with the bot-prefixed name, `tmux new-session` fails
+ *     with EEXIST because the old session is still there.
+ *   - The old session is unrecoverable: claudeSessionId is fresh per
+ *     turn, the daemon writing to JSONL was SIGKILLed mid-turn, and
+ *     any user-visible reply was already lost to the dead daemon.
+ *
+ * Strategy: list, kill, log. Best-effort — if tmux isn't running or
+ * the kill races a concurrent operator, swallow the error and proceed.
+ *
+ * @see lib/process-guard.js (claimPidFile)
+ * @see lib/tmux/tmux-runner.js (listPolygramSessions, killSession)
+ */
+
+'use strict';
+
+const { createTmuxRunner } = require('./tmux-runner');
+
+/**
+ * Sweep all `polygram-<botName>-*` tmux sessions on the host.
+ *
+ * @param {object} opts
+ * @param {string} opts.botName       — only sweep sessions for THIS bot
+ * @param {object} [opts.runner]      — injected TmuxRunner (for tests)
+ * @param {object} [opts.logger=console]
+ * @returns {Promise<{ swept: string[], errors: Array<{name:string, error:string}> }>}
+ */
+async function sweepTmuxOrphans({ botName, runner, logger = console } = {}) {
+  if (!botName) throw new TypeError('sweepTmuxOrphans: botName required');
+  // SECURITY (audit M2): dashes in bot names risk prefix-match
+  // collision when two bots share a prefix (e.g. `shumabit` matches
+  // `polygram-shumabit-prod-*` too). Warn so the operator can rename.
+  // The trailing `-` in the listPolygramSessions filter prevents an
+  // exact-prefix collision but DOES NOT prevent `shumabit` vs
+  // `shumabit-prod`. Defense-in-depth: surface it.
+  if (typeof botName === 'string' && botName.includes('-')) {
+    logger.warn?.(
+      `[orphan-sweep] bot name "${botName}" contains '-'; orphan-sweep `
+      + `prefix matching could collide with other bot names sharing a `
+      + `prefix. Consider renaming (e.g. use _ instead).`,
+    );
+  }
+  const r = runner || createTmuxRunner({ logger });
+  let names;
+  try {
+    names = await r.listPolygramSessions(botName);
+  } catch (err) {
+    // Most common: tmux not running. Best-effort = no-op.
+    logger.log?.(`[orphan-sweep] list-sessions failed (${err.message}); assuming no orphans`);
+    return { swept: [], errors: [] };
+  }
+  if (names.length === 0) {
+    logger.log?.(`[orphan-sweep] no polygram-${botName}-* orphans`);
+    return { swept: [], errors: [] };
+  }
+  logger.log?.(`[orphan-sweep] killing ${names.length} orphan tmux session(s): ${names.join(', ')}`);
+  const errors = [];
+  const swept = [];
+  for (const name of names) {
+    try {
+      await r.killSession(name);
+      swept.push(name);
+    } catch (err) {
+      errors.push({ name, error: err.message });
+      logger.warn?.(`[orphan-sweep] kill ${name} failed: ${err.message}`);
+    }
+  }
+  return { swept, errors };
+}
+
+module.exports = { sweepTmuxOrphans };

package/lib/tmux/poll-scheduler.js

@@ -0,0 +1,110 @@
+/**
+ * PollScheduler — shared tick generator for TmuxProcess polling loops.
+ *
+ * Each in-flight tmux turn polls `tmux capture-pane` every ~250ms to
+ * detect READY / STREAMING / approval-prompt state changes. Without
+ * coordination, N concurrent in-flight chats run N independent
+ * `setTimeout` chains. PollScheduler collapses these into a SINGLE
+ * `setInterval` whose firing wakes all registered waiters at once.
+ *
+ * Wins:
+ *   - One timer regardless of how many tmux chats are running.
+ *   - Tick-aligned bursts: all capture-pane subprocess spawns happen
+ *     in the same JS turn, then the loop idles until the next tick.
+ *     Linux/macOS handle bursty fork+exec better than smeared.
+ *   - Single shutdown point — `release()` from each process cleanly
+ *     stops the timer when nothing is in flight.
+ *
+ * Usage:
+ *   const sched = new PollScheduler({ intervalMs: 250 });
+ *   await proc.send(...);   // internally calls:
+ *   //   sched.acquire();
+ *   //   while (not done) { ...; await sched.waitTick(); }
+ *   //   sched.release();
+ *
+ * Each `waitTick()` returns a Promise that resolves at the NEXT tick.
+ * Multiple waiters on the same tick all resolve simultaneously.
+ */
+
+'use strict';
+
+class PollScheduler {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.intervalMs=250]  — global poll cadence
+   */
+  constructor({ intervalMs = 250 } = {}) {
+    this.intervalMs = intervalMs;
+    this._timer = null;
+    this._refCount = 0;
+    this._waiters = new Set();
+  }
+
+  /**
+   * Register a polling lifetime. Increments refCount and starts the
+   * shared interval if not already running. Pair every acquire() with
+   * a release() in a try/finally.
+   */
+  acquire() {
+    this._refCount++;
+    if (!this._timer) {
+      this._timer = setInterval(() => this._tick(), this.intervalMs);
+      // Don't keep the event loop alive solely for polling. The
+      // polygram daemon has many other refs (Telegram, IPC, the tmux
+      // sessions themselves) keeping it up.
+      this._timer.unref?.();
+    }
+  }
+
+  /**
+   * Drop a polling lifetime. When refCount hits zero we stop the
+   * interval AND resolve any lingering waiters so their loops can
+   * exit cleanly (e.g. process killed mid-tick).
+   */
+  release() {
+    if (this._refCount <= 0) return;
+    this._refCount--;
+    if (this._refCount === 0 && this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+      // Wake any leftover waiters so their polling loops can observe
+      // closed state and exit.
+      this._drainWaiters();
+    }
+  }
+
+  /**
+   * Resolves at the next scheduler tick. Cheap — no setTimeout
+   * allocation per call, just a Set insertion. Caller MUST have
+   * called acquire() before its first waitTick() and call release()
+   * after its last.
+   */
+  waitTick() {
+    return new Promise((resolve) => {
+      this._waiters.add(resolve);
+    });
+  }
+
+  /**
+   * Number of registered polling lifetimes (active in-flight turns).
+   * Useful for observability + tests.
+   */
+  get activeCount() {
+    return this._refCount;
+  }
+
+  _tick() {
+    this._drainWaiters();
+  }
+
+  _drainWaiters() {
+    if (this._waiters.size === 0) return;
+    const fns = [...this._waiters];
+    this._waiters.clear();
+    for (const fn of fns) {
+      try { fn(); } catch { /* swallow */ }
+    }
+  }
+}
+
+module.exports = { PollScheduler };

package/lib/tmux/session-log-parser.js

@@ -0,0 +1,173 @@
+/**
+ * SessionLogParser — converts claude's per-session JSONL file
+ * (`~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl`) into the
+ * Process abstraction's event surface.
+ *
+ * This is the REAL structured-event channel for the tmux backend.
+ * Previously the plan called for parsing `--debug-file` debug logs,
+ * but the v9 probe (one $0.02 haiku turn) revealed that channel
+ * emits ONLY infra messages (MDM settings, MCP/LSP lifecycle); the
+ * actual conversation events live in the per-session JSONL claude
+ * writes to disk for /resume to work.
+ *
+ * Each JSONL line is a JSON object with `type` discriminator:
+ *
+ *   { type: 'user',           message: {...} }
+ *   { type: 'assistant',      message: {... content: [...], stop_reason: 'end_turn'} }
+ *   { type: 'attachment',     attachment: {...} }
+ *   { type: 'last-prompt',    lastPrompt: '...' }
+ *   { type: 'queue-operation', operation: 'enqueue', content: '...' }
+ *
+ * # Mapping to Process events
+ *
+ * - assistant with `content[].type === 'text'`   → emit 'assistant-chunk' { text }
+ * - assistant with `content[].type === 'tool_use'` → emit 'tool-use' { name, input }
+ * - assistant with `message.stop_reason`         → emit 'result' { subtype, text, ... }
+ * - last-prompt                                  → emit 'last-prompt' (fallback complete signal)
+ *
+ * Robust against malformed lines: returns null and skips.
+ *
+ * @see lib/tmux/log-tail.js — generic file tailer
+ * @see docs/0.10.0-process-manager-abstraction-plan.md v9
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+/**
+ * Encode an absolute cwd path the way claude does for its
+ * ~/.claude/projects/<cwd-encoded> directory. Replaces `/` with `-`
+ * and strips leading `-` (since `/Users/x` → `Users-x` per filesystem
+ * but claude prepends `-` for absolute paths → `-Users-x`).
+ *
+ * Example:
+ *   /Users/ivanshumkov/Projects/polygram
+ *   → -Users-ivanshumkov-Projects-polygram
+ */
+function encodeCwd(cwd) {
+  // Replace path separator with dash; leading dash signals absolute path.
+  return cwd.replace(/\//g, '-');
+}
+
+// SECURITY (audit L3): sessionId is interpolated into a filesystem
+// path. Today it always comes from crypto.randomUUID() or DB
+// `chat_state.last_session_id`, but a defensive assert prevents
+// future path-traversal regressions if either source ever gets
+// tainted (malformed import, etc).
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/**
+ * Build the JSONL session file path for a given cwd + sessionId.
+ *
+ * @param {string} cwd        — absolute path
+ * @param {string} sessionId  — UUID v4
+ * @param {string} [homeDir]  — defaults to os.homedir()
+ */
+function sessionLogPath(cwd, sessionId, homeDir = os.homedir()) {
+  if (typeof sessionId !== 'string' || !UUID_RE.test(sessionId)) {
+    throw new TypeError(`sessionLogPath: sessionId must be a UUID, got ${JSON.stringify(sessionId)}`);
+  }
+  return path.join(homeDir, '.claude', 'projects', encodeCwd(cwd), `${sessionId}.jsonl`);
+}
+
+/**
+ * Parse one JSONL line into a Process-shaped event, OR null when the
+ * line carries nothing observable. Malformed JSON → null.
+ *
+ * Events returned (each with `type` field):
+ *   - 'assistant-chunk' { text }
+ *   - 'tool-use'        { name, input, id }
+ *   - 'result'          { subtype, text, stopReason }
+ *   - 'last-prompt'     { text }
+ *
+ * @param {string} line
+ * @returns {object[]} array of events (a single line CAN produce
+ *   multiple — e.g. an assistant message with both text and tool_use
+ *   content blocks emits both 'assistant-chunk' and 'tool-use').
+ */
+function parseLine(line) {
+  if (!line || typeof line !== 'string') return [];
+  let obj;
+  try { obj = JSON.parse(line); }
+  catch { return []; }
+  if (!obj || typeof obj !== 'object') return [];
+
+  const out = [];
+
+  if (obj.type === 'assistant' && obj.message) {
+    const content = obj.message.content;
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (!block || typeof block !== 'object') continue;
+        if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0) {
+          out.push({ type: 'assistant-chunk', text: block.text });
+        } else if (block.type === 'tool_use' && block.name) {
+          out.push({
+            type: 'tool-use',
+            name: block.name,
+            input: block.input ?? null,
+            id: block.id ?? null,
+          });
+        }
+      }
+    }
+    // Token-usage telemetry. Every assistant message carries the
+    // cumulative usage snapshot — input_tokens + cache_creation +
+    // cache_read = current context size. TmuxProcess uses the latest
+    // such event to implement getContextUsage().
+    if (obj.message.usage) {
+      const u = obj.message.usage;
+      out.push({
+        type: 'usage',
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+        cacheReadTokens: u.cache_read_input_tokens ?? 0,
+        cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+        model: obj.message.model ?? null,
+      });
+    }
+    // stop_reason marks end of an assistant turn segment. 'end_turn'
+    // is the canonical complete; 'tool_use' / 'max_tokens' / etc. are
+    // partial-with-continuation. We forward all stop_reasons so the
+    // caller can decide.
+    if (obj.message.stop_reason) {
+      // Collect all text from the message for the result.text field.
+      const text = Array.isArray(content)
+        ? content.filter((b) => b?.type === 'text').map((b) => b.text || '').join('')
+        : '';
+      out.push({
+        type: 'result',
+        subtype: obj.message.stop_reason === 'end_turn' ? 'success' : obj.message.stop_reason,
+        text,
+        stopReason: obj.message.stop_reason,
+        sessionId: obj.sessionId ?? null,
+      });
+    }
+  } else if (obj.type === 'last-prompt') {
+    out.push({ type: 'last-prompt', text: obj.lastPrompt ?? '' });
+  }
+
+  return out;
+}
+
+/**
+ * Wrap a LogTail (or any EventEmitter that emits 'line') and
+ * forward parsed events via 'event'. Returns the emitter so callers
+ * can chain `.on('event', ...)`.
+ */
+function pipeToParser(tail) {
+  tail.on('line', (line) => {
+    const events = parseLine(line);
+    for (const ev of events) tail.emit('event', ev);
+  });
+  return tail;
+}
+
+module.exports = {
+  encodeCwd,
+  sessionLogPath,
+  parseLine,
+  pipeToParser,
+};