dsh-working-activity 0.2.6 → 0.3.2

package/src/status.ts

@@ -1,501 +1,706 @@
-/**
- * Pure activity state machine for the working-activity status line. Consumes
- * session events (turn/step/tool/stream) plus agent running/idle transitions
- * and renders a human-readable status line at any wall-clock instant. No I/O,
- * no timers, no cordis — deterministic given the event stream and a clock.
- * @module @deepseek-ai/dsh-working-activity/status
- */
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import {
-  actionFor, fmtDuration, isGitTool, isNight, pickPhrase, thinkingPhrase,
-  WAITING_PHRASES, DONE_PHRASES, FAIL_PHRASES,
-} from './phrases.js'
-
-/** Public status phases a UI can render. */
-export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
-
-/** One snapshot of the model's activity, renderable by any UI. */
-export interface ActivityState {
-  /** Which activity phase the model is in right now. */
-  readonly phase: ActivityPhase
-  /** Full human-readable status line (plain text, no ANSI). */
-  readonly line: string
-  /** Short label of the current work (tool action or stage), when any. */
-  readonly label?: string
-  /** Detail fragment (path / command / search pattern), when any. */
-  readonly detail?: string
-  /** The playful phrase currently shown. */
-  readonly phrase?: string
-  /** Tools completed in the current turn. */
-  readonly toolCount: number
-  /** Wall-clock milliseconds since the current turn started (0 when idle). */
-  readonly turnElapsedMs: number
-  /** Wall-clock time the current phase started, for animations. */
-  readonly phaseStartedAt: number
-}
-
-/** Per-turn thinking/tooling split, exposed for done summaries and stats. */
-export interface TurnStats {
-  /** Milliseconds the model was thinking (between turn start and first tool / turn end). */
-  readonly thinkingMs: number
-  /** Milliseconds spent inside tool executions. */
-  readonly toolMs: number
-  /** Tools completed in the turn. */
-  readonly toolCount: number
-}
-
-/** Configuration knobs for the state machine (subset of plugin Config). */
-export interface TrackerConfig {
-  /** Playful copy pool on/off; false renders plain functional labels. */
-  readonly phrases: boolean
-  /** Maximum characters of a detail fragment (paths/commands). */
-  readonly detailLimit: number
-  /** Hide the status line while idle. */
-  readonly showIdle: boolean
-}
-
-/** A tool execution in flight. */
-interface ActiveTool {
-  readonly callId: string
-  readonly name: string
-  readonly action: string
-  readonly detail: string
-  readonly isGit: boolean
-  readonly startedAt: number
-  /** Whether the tool failed; set on tool/result while the card lingers. */
-  failed: boolean
-  /** tool/result time when settled, else undefined. */
-  endedAt?: number
-}
-
-/** A tool that finished but keeps its card in the replay queue. */
-interface DoneTool {
-  readonly action: string
-  readonly detail: string
-  readonly failed: boolean
-  readonly endedAt: number
-}
-
-/** Format one tool into its display fragment (`跑个命令 npm test`). */
-function toolFragment(tool: { action: string; detail: string }): string {
-  return tool.detail.length === 0 ? tool.action : `${tool.action} ${tool.detail}`
-}
-
-/** Simple non-ANSI string shortener by grapheme count. */
-function shorten(value: string, limit: number): string {
-  const graphemes = Array.from(value)
-  if (graphemes.length <= limit) return value
-  return `${graphemes.slice(0, Math.max(0, limit - 1)).join('')}…`
-}
-
-/**
- * Extract a displayable detail fragment from a tool call's parsed arguments.
- * @param toolName - Registry tool name.
- * @param args - Parsed tool arguments (lossless JSON by registry contract).
- */
-export function detailFor(toolName: string, args: Readonly<Record<string, unknown>> | undefined, limit: number): string {
-  if (args === undefined) return ''
-  const pickString = (...keys: readonly string[]): string => {
-    for (const key of keys) {
-      const value = args[key]
-      if (typeof value === 'string' && value.trim().length > 0) return value.trim()
-    }
-    return ''
-  }
-  const normalized = toolName.toLowerCase()
-  if (normalized === 'mcp' || normalized.startsWith('mcp__') || normalized.includes('__')) {
-    const action = pickString('action', 'tool', 'server', 'connect', 'describe')
-    return shorten(action, limit)
-  }
-  const path = pickString('path', 'file', 'file_path', 'filepath', 'target')
-  if (path.length > 0) return shorten(path, limit)
-  const command = pickString('command', 'cmd', 'cmdline')
-  if (command.length > 0) return shorten(command, limit)
-  const pattern = pickString('pattern', 'query', 'search')
-  if (pattern.length > 0) return shorten(pattern, limit)
-  const url = pickString('url')
-  if (url.length > 0) return shorten(url, limit)
-  if (/^(?:subagent|agent|task)$/i.test(toolName)) {
-    const description = pickString('description')
-    if (description.length > 0) return shorten(description, limit)
-    const prompt = pickString('prompt')
-    if (prompt.length > 0) return shorten(prompt, limit)
-  }
-  const named = pickString('name', 'server', 'tool', 'id', 'goal')
-  if (named.length > 0) return shorten(named, limit)
-  return ''
-}
-
-/**
- * Track one agent's activity from its durable session events. Events from
- * other sessions are ignored (the owning plugin feeds only the agent it
- * displays). The tracker is deliberately single-agent: multi-session UIs
- * instantiate one tracker per agent.
- */
-export class ActivityTracker {
-  private phase: ActivityPhase = 'idle'
-  private phaseStartedAt = 0
-  private turnStartedAt = 0
-  private thinkingStartedAt = 0
-  private thinkingMs = 0
-  private toolMs = 0
-  private toolCount = 0
-  private activeTools = new Map<string, ActiveTool>()
-  private doneQueue: DoneTool[] = []
-  private previousPhrase: string | undefined
-  private phraseChangedAt = 0
-  private waitingFirstToken = false
-  /** Latest `⏵` self-narration line extracted from the stream, or null. */
-  private narratedText: string | null = null
-  /** Wall-clock time of the most recent stream delta (narration freshness). */
-  private lastChunkAt = 0
-  /** Rolling stream buffer (reasoning + text deltas) for `⏵` extraction. */
-  private recentStream = ''
-  /** Total tokens reported across the turn's assistant messages. */
-  private turnTokens = 0
-  /** Completion prefix drawn ONCE at turn end so the done line stays stable. */
-  private donePrefix = '搞定 ✓'
-
-  /**
-   * @param config - Behavioral knobs.
-   * @param now - Wall-clock supplier (injectable for tests).
-   * @param customActions - Exact-name custom action pools for {@link actionFor}.
-   */
-  constructor(
-    private readonly config: TrackerConfig,
-    private readonly now: () => number = Date.now,
-    private readonly customActions?: Readonly<Record<string, readonly string[]>>,
-  ) {}
-
-  /** Agent transitioned to running/idle. */
-  onAgentStatus(status: 'idle' | 'running'): void {
-    if (status === 'idle') {
-      // The turn end already moved us to the done phase; idle only clears the
-      // lingering done card after its display window.
-      if (this.phase !== 'done') this.phase = 'idle'
-      return
-    }
-    if (this.phase === 'idle') {
-      this.phase = 'waiting'
-      this.phaseStartedAt = this.now()
-      this.waitingFirstToken = true
-    }
-  }
-
-  /** Consume one durable session event (turn/step/tool/stream). */
-  onSessionEvent(event: SessionEvent): void {
-    switch (event.type) {
-      case 'turn/start': {
-        const at = event.time
-        this.turnStartedAt = at
-        this.thinkingStartedAt = at
-        this.thinkingMs = 0
-        this.toolMs = 0
-        this.toolCount = 0
-        this.turnTokens = 0
-        this.activeTools.clear()
-        this.doneQueue = []
-        this.waitingFirstToken = true
-        this.narratedText = null
-        this.lastChunkAt = 0
-        this.recentStream = ''
-        this.setPhase('waiting', at)
-        return
-      }
-      case 'step/start':
-        if (this.phase === 'waiting' && !this.waitingFirstToken) {
-          // A new step without streamed output yet — stay waiting.
-        }
-        return
-      case 'assistant/chunk': {
-        const chunk = event.data.chunk
-        this.lastChunkAt = event.time
-        if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
-          if (this.waitingFirstToken) {
-            this.waitingFirstToken = false
-            this.setPhase('thinking', event.time)
-            this.thinkingStartedAt = event.time
-          }
-          this.recentStream = (this.recentStream + chunk.text).slice(-STREAM_BUFFER_CHARS)
-          const narration = extractNarration(this.recentStream)
-          if (narration !== null) this.narratedText = narration
-        }
-        return
-      }
-      case 'assistant/message': {
-        const usage = event.data.usage
-        if (usage !== undefined) {
-          this.turnTokens += usage.inputTokens + usage.outputTokens
-            + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
-        }
-        return
-      }
-      case 'tool/call': {
-        const at = event.time
-        if (this.phase === 'thinking' || this.phase === 'waiting') {
-          this.thinkingMs += at - this.thinkingStartedAt
-        }
-        const parsed = parseArguments(event.data.arguments)
-        const action = this.config.phrases ? actionFor(event.data.name, this.customActions) : event.data.name
-        const detail = detailFor(event.data.name, parsed, this.config.detailLimit)
-        const active: ActiveTool = {
-          callId: event.data.callId,
-          name: event.data.name,
-          action,
-          detail,
-          isGit: isGitTool(event.data.name, parsed),
-          startedAt: at,
-          failed: false,
-        }
-        this.activeTools.set(event.data.callId, active)
-        this.setPhase('tool', at)
-        return
-      }
-      case 'tool/result': {
-        const at = event.time
-        // `ToolResultMessage.content` is the single-block `[ToolResultBlock]`
-        // tuple, so `block` is never absent and always a tool-result block.
-        const block = event.data.message.content[0]
-        const active = this.activeTools.get(block.toolCallId)
-        if (active === undefined) return
-        active.failed = event.data.error !== undefined || block.isError === true
-        active.endedAt = at
-        this.toolMs += at - active.startedAt
-        this.toolCount += 1
-        this.doneQueue.push({
-          action: active.action,
-          detail: active.detail,
-          failed: active.failed,
-          endedAt: at,
-        })
-        if (this.doneQueue.length > DONE_QUEUE_MAX) this.doneQueue.shift()
-        this.activeTools.delete(block.toolCallId)
-        if (this.activeTools.size === 0) {
-          // Back to thinking (or a trailing done card if the turn just closed).
-          this.setPhase('thinking', at)
-          this.thinkingStartedAt = at
-        }
-        return
-      }
-      case 'turn/end': {
-        const at = event.time
-        if (this.activeTools.size > 0) {
-          // Tools still running at turn end: count their elapsed time as tool time.
-          for (const tool of this.activeTools.values()) {
-            this.toolMs += Math.max(0, at - tool.startedAt)
-          }
-          this.activeTools.clear()
-        } else if (this.phase === 'thinking' || this.phase === 'waiting') {
-          this.thinkingMs += Math.max(0, at - this.thinkingStartedAt)
-        }
-        // Draw the completion prefix ONCE so repeated renders of the done line
-        // stay stable (a fresh random per render would make it flicker).
-        const lastTool = this.doneQueue.at(-1)
-        if (this.config.phrases) {
-          this.donePrefix = lastTool?.failed ? pickPhrase(FAIL_PHRASES) : pickPhrase(DONE_PHRASES)
-        } else {
-          this.donePrefix = '搞定 ✓'
-        }
-        this.setPhase('done', at)
-        return
-      }
-      default:
-        return
-    }
-  }
-
-  /** Render the current status snapshot at a wall-clock instant. */
-  render(nowMs: number = this.now()): ActivityState {
-    switch (this.phase) {
-      case 'idle':
-        return {
-          phase: 'idle',
-          line: '',
-          toolCount: 0,
-          turnElapsedMs: 0,
-          phaseStartedAt: this.phaseStartedAt,
-        }
-      case 'done': {
-        const summary = this.doneSummary(nowMs)
-        return {
-          phase: 'done',
-          line: summary.line,
-          toolCount: this.toolCount,
-          turnElapsedMs: this.turnElapsedMs(nowMs),
-          phaseStartedAt: this.phaseStartedAt,
-          ...(summary.phrase === undefined ? {} : { phrase: summary.phrase }),
-        }
-      }
-      case 'tool': {
-        const tool = this.primaryTool()
-        if (tool === undefined) {
-          return this.renderThinking(nowMs)
-        }
-        const fragment = toolFragment(tool)
-        const elapsed = fmtDuration(Math.max(0, nowMs - tool.startedAt))
-        const git = tool.isGit ? ' · git' : ''
-        const narration = this.freshNarration(nowMs)
-        const line = narration === null
-          ? `${fragment} · ${elapsed}${git}`
-          : `⏵ ${narration} · ${fragment} · ${elapsed}${git}`
-        return {
-          phase: 'tool',
-          line,
-          label: tool.action,
-          detail: tool.detail,
-          ...(narration === null ? {} : { phrase: narration }),
-          toolCount: this.toolCount,
-          turnElapsedMs: this.turnElapsedMs(nowMs),
-          phaseStartedAt: this.phaseStartedAt,
-        }
-      }
-      case 'waiting':
-      case 'thinking': {
-        const rendered = this.renderThinking(nowMs)
-        if (this.phase === 'waiting') {
-          return { ...rendered, phase: 'waiting' }
-        }
-        return rendered
-      }
-    }
-  }
-
-  /** Per-turn thinking/tooling split for stats consumers. */
-  stats(): TurnStats {
-    return {
-      thinkingMs: this.thinkingMs,
-      toolMs: this.toolMs,
-      toolCount: this.toolCount,
-    }
-  }
-
-  private renderThinking(nowMs: number): ActivityState {
-    const thinkingMs = this.phase === 'waiting'
-      ? 0
-      : this.thinkingMs + Math.max(0, nowMs - this.thinkingStartedAt)
-    const elapsed = fmtDuration(this.turnElapsedMs(nowMs))
-    const narration = this.freshNarration(nowMs)
-    if (narration !== null) {
-      return {
-        phase: this.phase,
-        line: `⏵ ${narration} · 总${elapsed}`,
-        phrase: narration,
-        toolCount: this.toolCount,
-        turnElapsedMs: this.turnElapsedMs(nowMs),
-        phaseStartedAt: this.phaseStartedAt,
-      }
-    }
-    if (this.config.phrases) {
-      if (nowMs - this.phraseChangedAt >= PHRASE_ROTATE_MS) {
-        // Waiting (pre-first-token) draws from the waiting pool; thinking
-        // rotates the playful copy pool with night mixing.
-        this.previousPhrase = this.phase === 'waiting'
-          ? pickPhrase(WAITING_PHRASES, this.previousPhrase)
-          : thinkingPhrase(thinkingMs, this.previousPhrase, isNight(new Date(nowMs).getHours()))
-        this.phraseChangedAt = nowMs
-      }
-      const phrase = this.previousPhrase ?? (this.phase === 'waiting'
-        ? pickPhrase(WAITING_PHRASES)
-        : thinkingPhrase(thinkingMs, undefined, isNight(new Date(nowMs).getHours())))
-      return {
-        phase: this.phase,
-        line: `${phrase} · 总${elapsed}`,
-        phrase,
-        toolCount: this.toolCount,
-        turnElapsedMs: this.turnElapsedMs(nowMs),
-        phaseStartedAt: this.phaseStartedAt,
-      }
-    }
-    const label = this.phase === 'waiting' ? '等待模型响应' : '思考中'
-    return {
-      phase: this.phase,
-      line: `${label} · 总${elapsed}`,
-      label,
-      toolCount: this.toolCount,
-      turnElapsedMs: this.turnElapsedMs(nowMs),
-      phaseStartedAt: this.phaseStartedAt,
-    }
-  }
-
-  private doneSummary(nowMs: number): { line: string; phrase?: string } {
-    const { thinkingMs, toolMs, toolCount } = this.stats()
-    const tokens = this.turnTokens > 0 ? ` · 🔥 ${fmtTokens(this.turnTokens)}` : ''
-    const base = `${this.donePrefix} · ${toolCount} 工具 · 想${fmtDuration(thinkingMs)} 干${fmtDuration(toolMs)}${tokens}`
-    if (!this.config.phrases) {
-      return { line: `搞定 ✓ · ${toolCount} 工具 · 想${fmtDuration(thinkingMs)} 干${fmtDuration(toolMs)}${tokens}` }
-    }
-    const last = this.doneQueue.at(-1)
-    if (last !== undefined && nowMs - last.endedAt < DONE_FRAGMENT_MS) {
-      const fragment = toolFragment(last)
-      return { line: `${this.donePrefix} · ${fragment} · ${toolCount} 工具${tokens}`, phrase: this.donePrefix }
-    }
-    return { line: base, ...(this.donePrefix === '搞定 ✓' ? {} : { phrase: this.donePrefix }) }
-  }
-
-  /** The fresh self-narration line, or null once the stream has been quiet. */
-  private freshNarration(nowMs: number): string | null {
-    if (this.narratedText === null) return null
-    if (nowMs - this.lastChunkAt > NARRATE_GRACE_MS) return null
-    return this.narratedText
-  }
-
-  private primaryTool(): ActiveTool | undefined {
-    let primary: ActiveTool | undefined
-    for (const tool of this.activeTools.values()) {
-      if (primary === undefined || tool.startedAt < primary.startedAt) primary = tool
-    }
-    return primary
-  }
-
-  private turnElapsedMs(nowMs: number): number {
-    return this.turnStartedAt === 0 ? 0 : Math.max(0, nowMs - this.turnStartedAt)
-  }
-
-  private setPhase(phase: ActivityPhase, atMs: number): void {
-    this.phase = phase
-    this.phaseStartedAt = atMs
-  }
-}
-
-/** Rotate the thinking phrase every N render ticks (render cadence ≈ 500ms → ~4s). */
-const PHRASE_ROTATE_MS = 4000
-/** Cap on replayed done cards; older entries drop. */
-const DONE_QUEUE_MAX = 6
-/** Show the last tool's fragment in the done line for this long after it ends. */
-const DONE_FRAGMENT_MS = 3000
-/** Rolling stream buffer size for `⏵` narration extraction. */
-const STREAM_BUFFER_CHARS = 300
-/** A narration stays visible this long after the stream went quiet. */
-const NARRATE_GRACE_MS = 5000
-
-/** Extract the latest `⏵` self-narration line from a stream buffer. */
-export function extractNarration(buffer: string): string | null {
-  const matches = [...buffer.matchAll(/⏵\s*([^\n⏵]{1,40})/g)]
-  if (matches.length === 0) return null
-  const latest = matches[matches.length - 1]?.[1]
-  if (latest === undefined) return null
-  const text = latest.replace(/[。．.!！,，、;；]+$/, '').trim()
-  return text.length === 0 ? null : text
-}
-
-/** Format a token count compactly (`12.3k`, `1.2M`). */
-function fmtTokens(tokens: number): string {
-  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
-  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`
-  return String(tokens)
-}
-
-/** Parse a tool call's raw arguments JSON defensively. */
-function parseArguments(raw: string): Readonly<Record<string, unknown>> | undefined {
-  if (raw.trim().length === 0) return undefined
-  try {
-    const parsed: unknown = JSON.parse(raw)
-    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      return parsed as Readonly<Record<string, unknown>>
-    }
-    return undefined
-  } catch {
-    return undefined
-  }
-}
+/**
+ * Pure activity state machine for the working-activity status line. Consumes
+ * session events (turn/step/tool/stream) plus agent running/idle transitions
+ * and renders a human-readable status line at any wall-clock instant. No I/O,
+ * no timers, no cordis — deterministic given the event stream and a clock.
+ * @module @deepseek-ai/dsh-working-activity/status
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import {
+  actionFor, compactPhrase, continuePhrase, donePhrase, failPhrase, fmtDuration,
+  holidayPhrase, isGitTool, isNight, isWeekend, modelQuip, overflowPhrase, rarePhrase,
+  RARE_CHANCE, RARE_PHRASES, EN_RARE_PHRASES, thinkingPhrase, weekendPhrase, waitingPhrase,
+} from './phrases.js'
+import { t } from './lang.js'
+
+/** Public status phases a UI can render. */
+export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+
+/** One snapshot of the model's activity, renderable by any UI. */
+export interface ActivityState {
+  /** Which activity phase the model is in right now. */
+  readonly phase: ActivityPhase
+  /** Full human-readable status line (plain text, no ANSI). */
+  readonly line: string
+  /** Short label of the current work (tool action or stage), when any. */
+  readonly label?: string
+  /** Detail fragment (path / command / search pattern), when any. */
+  readonly detail?: string
+  /** The playful phrase currently shown. */
+  readonly phrase?: string
+  /** Tools completed in the current turn. */
+  readonly toolCount: number
+  /** Wall-clock milliseconds since the current turn started (0 when idle). */
+  readonly turnElapsedMs: number
+  /** Wall-clock time the current phase started, for animations. */
+  readonly phaseStartedAt: number
+}
+
+/** Per-turn thinking/tooling split, exposed for done summaries and stats. */
+export interface TurnStats {
+  /** Milliseconds the model was thinking (between turn start and first tool / turn end). */
+  readonly thinkingMs: number
+  /** Milliseconds spent inside tool executions. */
+  readonly toolMs: number
+  /** Tools completed in the turn. */
+  readonly toolCount: number
+}
+
+/** Easter-egg toggles for the thinking phrase (pi extension parity). */
+export interface TrackerFeatures {
+  /** Rare 1/150 easter eggs. */
+  readonly rareEggs?: boolean
+  /** Weekend greetings on Sat/Sun. */
+  readonly weekend?: boolean
+  /** Date-matched holiday / Lunar New Year copy. */
+  readonly holidays?: boolean
+  /** Night-owl copy between 00:00 and 06:00. */
+  readonly nightPhrases?: boolean
+}
+
+/** Configuration knobs for the state machine (subset of plugin Config). */
+export interface TrackerConfig {
+  /** Playful copy pool on/off; false renders plain functional labels. */
+  readonly phrases: boolean
+  /** Maximum characters of a detail fragment (paths/commands). */
+  readonly detailLimit: number
+  /** Hide the status line while idle. */
+  readonly showIdle: boolean
+  /** Easter-egg toggles; absent flags default to on. */
+  readonly features?: TrackerFeatures
+  /** User custom phrases appended to the base thinking pool. */
+  readonly customPhrases?: readonly string[]
+  /** Show an estimated tokens/s prefix while streaming (pi parity). */
+  readonly showTokPerSec?: boolean
+  /** Work reminder after this many turn-hours (0 = off). */
+  readonly workRemindAt?: number
+}
+
+/** A tool execution in flight. */
+interface ActiveTool {
+  readonly callId: string
+  readonly name: string
+  readonly action: string
+  readonly detail: string
+  readonly isGit: boolean
+  readonly startedAt: number
+  /** Whether the tool failed; set on tool/result while the card lingers. */
+  failed: boolean
+  /** tool/result time when settled, else undefined. */
+  endedAt?: number
+}
+
+/** A tool that finished but keeps its card in the replay queue. */
+interface DoneTool {
+  readonly action: string
+  readonly detail: string
+  readonly failed: boolean
+  readonly endedAt: number
+}
+
+/** Format one tool into its display fragment (`跑个命令 npm test`). */
+function toolFragment(tool: { action: string; detail: string }): string {
+  return tool.detail.length === 0 ? tool.action : `${tool.action} ${tool.detail}`
+}
+
+/** Simple non-ANSI string shortener by grapheme count. */
+function shorten(value: string, limit: number): string {
+  const graphemes = Array.from(value)
+  if (graphemes.length <= limit) return value
+  return `${graphemes.slice(0, Math.max(0, limit - 1)).join('')}…`
+}
+
+/**
+ * Extract a displayable detail fragment from a tool call's parsed arguments.
+ * @param toolName - Registry tool name.
+ * @param args - Parsed tool arguments (lossless JSON by registry contract).
+ */
+export function detailFor(toolName: string, args: Readonly<Record<string, unknown>> | undefined, limit: number): string {
+  if (args === undefined) return ''
+  const pickString = (...keys: readonly string[]): string => {
+    for (const key of keys) {
+      const value = args[key]
+      if (typeof value === 'string' && value.trim().length > 0) return value.trim()
+    }
+    return ''
+  }
+  const normalized = toolName.toLowerCase()
+  if (normalized === 'mcp' || normalized.startsWith('mcp__') || normalized.includes('__')) {
+    const action = pickString('action', 'tool', 'server', 'connect', 'describe')
+    return shorten(action, limit)
+  }
+  const path = pickString('path', 'file', 'file_path', 'filepath', 'target')
+  if (path.length > 0) return shorten(path, limit)
+  const command = pickString('command', 'cmd', 'cmdline')
+  if (command.length > 0) return shorten(command, limit)
+  const pattern = pickString('pattern', 'query', 'search')
+  if (pattern.length > 0) return shorten(pattern, limit)
+  const url = pickString('url')
+  if (url.length > 0) return shorten(url, limit)
+  if (/^(?:subagent|agent|task)$/i.test(toolName)) {
+    const description = pickString('description')
+    if (description.length > 0) return shorten(description, limit)
+    const prompt = pickString('prompt')
+    if (prompt.length > 0) return shorten(prompt, limit)
+  }
+  const named = pickString('name', 'server', 'tool', 'id', 'goal')
+  if (named.length > 0) return shorten(named, limit)
+  return ''
+}
+
+/**
+ * Track one agent's activity from its durable session events. Events from
+ * other sessions are ignored (the owning plugin feeds only the agent it
+ * displays). The tracker is deliberately single-agent: multi-session UIs
+ * instantiate one tracker per agent.
+ */
+export class ActivityTracker {
+  private phase: ActivityPhase = 'idle'
+  private phaseStartedAt = 0
+  private turnStartedAt = 0
+  private thinkingStartedAt = 0
+  private thinkingMs = 0
+  private toolMs = 0
+  private toolCount = 0
+  private activeTools = new Map<string, ActiveTool>()
+  private doneQueue: DoneTool[] = []
+  private previousPhrase: string | undefined
+  private phraseChangedAt = 0
+  private waitingFirstToken = false
+  /** Latest `⏵` self-narration line extracted from the stream, or null. */
+  private narratedText: string | null = null
+  /** Wall-clock time of the most recent stream delta (narration freshness). */
+  private lastChunkAt = 0
+  /** Rolling stream buffer (reasoning + text deltas) for `⏵` extraction. */
+  private recentStream = ''
+  /** Total tokens reported across the turn's assistant messages. */
+  private turnTokens = 0
+  /** Completion prefix drawn ONCE at turn end so the done line stays stable. */
+  private donePrefix = t('done-prefix')
+  /** Easter eggs shown once per turn (holiday / rare / weekend). */
+  private holidayShown = false
+  private rareShown = false
+  private weekendShown = false
+  /** One-off copy pinned by an external event (interrupt / model switch /
+   *  compaction / work reminder), shown until it expires. */
+  private pendingPhrase: string | null = null
+  private pendingUntil = 0
+  /** Git branch of the session cwd (fed by the host, best-effort). */
+  private gitBranch: string | undefined
+  /** Consecutive fast tool streak (combo). */
+  private streak = 0
+  private lastToolEndAt = 0
+  private maxStreak = 0
+  /** Subagent (agent/task) calls in the current turn. */
+  private subagentCount = 0
+  /** Work-reminder fired once per turn. */
+  private reminded = false
+  /** Streaming token estimate for the tps prefix. */
+  private tokBuf = 0
+  private tokWindowStart = 0
+
+  /**
+   * @param config - Behavioral knobs.
+   * @param now - Wall-clock supplier (injectable for tests).
+   * @param customActions - Exact-name custom action pools for {@link actionFor}.
+   */
+  constructor(
+    private readonly config: TrackerConfig,
+    private readonly now: () => number = Date.now,
+    private readonly customActions?: Readonly<Record<string, readonly string[]>>,
+  ) {}
+
+  /** Agent transitioned to running/idle. */
+  onAgentStatus(status: 'idle' | 'running'): void {
+    if (status === 'idle') {
+      // The turn end already moved us to the done phase; idle only clears the
+      // lingering done card after its display window.
+      if (this.phase !== 'done') this.phase = 'idle'
+      return
+    }
+    if (this.phase === 'idle') {
+      this.phase = 'waiting'
+      this.phaseStartedAt = this.now()
+      this.waitingFirstToken = true
+    }
+  }
+
+  /** The user interrupted the running turn: show a comeback quip next. */
+  onInterrupted(): void {
+    if (!this.config.phrases) return
+    this.pendingPhrase = continuePhrase()
+    this.pendingUntil = this.now() + PENDING_MS
+  }
+
+  /** The model was switched: quip for the new model id. */
+  onModelSwitch(modelId: string): void {
+    if (!this.config.phrases) return
+    const quip = modelQuip(modelId)
+    if (quip !== null) {
+      this.pendingPhrase = quip
+      this.pendingUntil = this.now() + PENDING_MS
+    }
+  }
+
+  /** A context compaction finished (or overflowed): quip about it. */
+  onCompact(kind: 'done' | 'overflow'): void {
+    if (!this.config.phrases) return
+    this.pendingPhrase = kind === 'overflow' ? overflowPhrase() : compactPhrase()
+    this.pendingUntil = this.now() + PENDING_MS
+  }
+
+  /** Feed the session cwd's git branch (best-effort, host-resolved). */
+  onGitBranch(branch: string | undefined): void {
+    this.gitBranch = branch
+  }
+
+  /** Consume one durable session event (turn/step/tool/stream). */
+  onSessionEvent(event: SessionEvent): void {
+    switch (event.type) {
+      case 'turn/start': {
+        const at = event.time
+        this.turnStartedAt = at
+        this.thinkingStartedAt = at
+        this.thinkingMs = 0
+        this.toolMs = 0
+        this.toolCount = 0
+        this.turnTokens = 0
+        this.activeTools.clear()
+        this.doneQueue = []
+        this.waitingFirstToken = true
+        this.narratedText = null
+        this.lastChunkAt = 0
+        this.recentStream = ''
+        // Easter eggs are once-per-turn: a fresh turn can roll them again.
+        this.holidayShown = false
+        this.rareShown = false
+        this.weekendShown = false
+        // Per-turn stats reset; the pending quip (interrupt/model/compact)
+        // survives across the turn boundary so it shows on the next think.
+        this.streak = 0
+        this.maxStreak = 0
+        this.subagentCount = 0
+        this.reminded = false
+        this.tokBuf = 0
+        this.tokWindowStart = at
+        this.setPhase('waiting', at)
+        return
+      }
+      case 'step/start':
+        if (this.phase === 'waiting' && !this.waitingFirstToken) {
+          // A new step without streamed output yet — stay waiting.
+        }
+        return
+      case 'assistant/chunk': {
+        const chunk = event.data.chunk
+        this.lastChunkAt = event.time
+        if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
+          if (this.waitingFirstToken) {
+            this.waitingFirstToken = false
+            this.setPhase('thinking', event.time)
+            this.thinkingStartedAt = event.time
+          }
+          this.recentStream = (this.recentStream + chunk.text).slice(-STREAM_BUFFER_CHARS)
+          const narration = extractNarration(this.recentStream)
+          if (narration !== null) this.narratedText = narration
+          // Streaming token estimate for the tps prefix (pi parity).
+          this.tokBuf += estimateTokens(chunk.text)
+        }
+        return
+      }
+      case 'assistant/message': {
+        const usage = event.data.usage
+        if (usage !== undefined) {
+          this.turnTokens += usage.inputTokens + usage.outputTokens
+            + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+        }
+        return
+      }
+      case 'tool/call': {
+        const at = event.time
+        if (this.phase === 'thinking' || this.phase === 'waiting') {
+          this.thinkingMs += at - this.thinkingStartedAt
+        }
+        // Combo streak: consecutive tools within COMBO_GAP_MS count up.
+        this.streak = (this.lastToolEndAt > 0 && at - this.lastToolEndAt <= COMBO_GAP_MS)
+          ? this.streak + 1
+          : 1
+        if (this.streak > this.maxStreak) this.maxStreak = this.streak
+        if (/^(?:subagent|agent|task)$/i.test(event.data.name)) this.subagentCount += 1
+        const parsed = parseArguments(event.data.arguments)
+        const action = this.config.phrases ? actionFor(event.data.name, this.customActions) : event.data.name
+        const detail = detailFor(event.data.name, parsed, this.config.detailLimit)
+        const active: ActiveTool = {
+          callId: event.data.callId,
+          name: event.data.name,
+          action,
+          detail,
+          isGit: isGitTool(event.data.name, parsed),
+          startedAt: at,
+          failed: false,
+        }
+        this.activeTools.set(event.data.callId, active)
+        this.setPhase('tool', at)
+        return
+      }
+      case 'tool/result': {
+        const at = event.time
+        // `ToolResultMessage.content` is the single-block `[ToolResultBlock]`
+        // tuple, so `block` is never absent and always a tool-result block.
+        const block = event.data.message.content[0]
+        const active = this.activeTools.get(block.toolCallId)
+        if (active === undefined) return
+        active.failed = event.data.error !== undefined || block.isError === true
+        active.endedAt = at
+        this.toolMs += at - active.startedAt
+        this.toolCount += 1
+        this.lastToolEndAt = at
+        this.doneQueue.push({
+          action: active.action,
+          detail: active.detail,
+          failed: active.failed,
+          endedAt: at,
+        })
+        if (this.doneQueue.length > DONE_QUEUE_MAX) this.doneQueue.shift()
+        this.activeTools.delete(block.toolCallId)
+        if (this.activeTools.size === 0) {
+          // Back to thinking (or a trailing done card if the turn just closed).
+          this.setPhase('thinking', at)
+          this.thinkingStartedAt = at
+        }
+        return
+      }
+      case 'turn/end': {
+        const at = event.time
+        if (this.activeTools.size > 0) {
+          // Tools still running at turn end: count their elapsed time as tool time.
+          for (const tool of this.activeTools.values()) {
+            this.toolMs += Math.max(0, at - tool.startedAt)
+          }
+          this.activeTools.clear()
+        } else if (this.phase === 'thinking' || this.phase === 'waiting') {
+          this.thinkingMs += Math.max(0, at - this.thinkingStartedAt)
+        }
+        // Draw the completion prefix ONCE so repeated renders of the done line
+        // stay stable (a fresh random per render would make it flicker). The
+        // pools are language-aware, so the line matches the language the turn
+        // ended in.
+        const lastTool = this.doneQueue.at(-1)
+        if (this.config.phrases) {
+          this.donePrefix = lastTool?.failed ? failPhrase() : donePhrase()
+        } else {
+          this.donePrefix = t('done-prefix')
+        }
+        this.setPhase('done', at)
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  /** Render the current status snapshot at a wall-clock instant. */
+  render(nowMs: number = this.now()): ActivityState {
+    switch (this.phase) {
+      case 'idle':
+        return {
+          phase: 'idle',
+          line: '',
+          toolCount: 0,
+          turnElapsedMs: 0,
+          phaseStartedAt: this.phaseStartedAt,
+        }
+      case 'done': {
+        const summary = this.doneSummary(nowMs)
+        return {
+          phase: 'done',
+          line: summary.line,
+          toolCount: this.toolCount,
+          turnElapsedMs: this.turnElapsedMs(nowMs),
+          phaseStartedAt: this.phaseStartedAt,
+          ...(summary.phrase === undefined ? {} : { phrase: summary.phrase }),
+        }
+      }
+      case 'tool': {
+        const tool = this.primaryTool()
+        if (tool === undefined) {
+          return this.renderThinking(nowMs)
+        }
+        const fragment = toolFragment(tool)
+        const elapsed = fmtDuration(Math.max(0, nowMs - tool.startedAt))
+        const git = tool.isGit
+          ? (this.gitBranch !== undefined ? ` · git ${this.gitBranch}` : ' · git')
+          : ''
+        const combo = this.streak >= COMBO_SHOW_AT ? ` · 🔥x${this.streak}` : ''
+        const narration = this.freshNarration(nowMs)
+        const line = narration === null
+          ? `${fragment} · ${elapsed}${git}${combo}`
+          : `⏵ ${narration} · ${fragment} · ${elapsed}${git}${combo}`
+        return {
+          phase: 'tool',
+          line,
+          label: tool.action,
+          detail: tool.detail,
+          ...(narration === null ? {} : { phrase: narration }),
+          toolCount: this.toolCount,
+          turnElapsedMs: this.turnElapsedMs(nowMs),
+          phaseStartedAt: this.phaseStartedAt,
+        }
+      }
+      case 'waiting':
+      case 'thinking': {
+        const rendered = this.renderThinking(nowMs)
+        if (this.phase === 'waiting') {
+          return { ...rendered, phase: 'waiting' }
+        }
+        return rendered
+      }
+    }
+  }
+
+  /** Per-turn thinking/tooling split for stats consumers. */
+  stats(): TurnStats {
+    return {
+      thinkingMs: this.thinkingMs,
+      toolMs: this.toolMs,
+      toolCount: this.toolCount,
+    }
+  }
+
+  private renderThinking(nowMs: number): ActivityState {
+    const thinkingMs = this.phase === 'waiting'
+      ? 0
+      : this.thinkingMs + Math.max(0, nowMs - this.thinkingStartedAt)
+    const elapsed = fmtDuration(this.turnElapsedMs(nowMs))
+    const elapsedLine = t('line-elapsed', { elapsed })
+    const narration = this.freshNarration(nowMs)
+    if (narration !== null) {
+      return {
+        phase: this.phase,
+        line: `⏵ ${narration} · ${elapsedLine}`,
+        phrase: narration,
+        toolCount: this.toolCount,
+        turnElapsedMs: this.turnElapsedMs(nowMs),
+        phaseStartedAt: this.phaseStartedAt,
+      }
+    }
+    if (this.config.phrases) {
+      const pending = this.pendingPhraseAt(nowMs)
+      // Rare eggs linger longer (pi RARE_PHRASE_TICKS ≈ 7.5s).
+      const rotateMs = this.previousPhrase !== undefined && this.isRarePhrase(this.previousPhrase)
+        ? RARE_ROTATE_MS
+        : PHRASE_ROTATE_MS
+      if (pending !== null) {
+        this.previousPhrase = pending
+        this.phraseChangedAt = nowMs
+      } else if (nowMs - this.phraseChangedAt >= rotateMs) {
+        // Waiting (pre-first-token) draws from the waiting pool; thinking
+        // rotates the egg-aware lively pool (holiday / rare / weekend /
+        // night). Both pools are language-aware, so a `/lang` switch shows
+        // on the next rotation.
+        this.previousPhrase = this.phase === 'waiting'
+          ? waitingPhrase(this.previousPhrase)
+          : this.livelyPhrase(thinkingMs, nowMs)
+        this.phraseChangedAt = nowMs
+      }
+      const phrase = this.previousPhrase ?? (this.phase === 'waiting'
+        ? waitingPhrase()
+        : this.livelyPhrase(thinkingMs, nowMs))
+      // Ellipsis breathing (pi DOT_FRAMES) + optional estimated tps prefix.
+      const dots = DOT_FRAMES[Math.floor(nowMs / TICK_MS) % DOT_FRAMES.length]
+      const tps = this.tpsPrefix(nowMs)
+      return {
+        phase: this.phase,
+        line: `${tps}${phrase}${dots} · ${elapsedLine}`,
+        phrase,
+        toolCount: this.toolCount,
+        turnElapsedMs: this.turnElapsedMs(nowMs),
+        phaseStartedAt: this.phaseStartedAt,
+      }
+    }
+    const label = this.phase === 'waiting' ? t('waiting-label') : t('thinking-label')
+    return {
+      phase: this.phase,
+      line: `${label} · ${elapsedLine}`,
+      label,
+      toolCount: this.toolCount,
+      turnElapsedMs: this.turnElapsedMs(nowMs),
+      phaseStartedAt: this.phaseStartedAt,
+    }
+  }
+
+  /**
+   * Pick the next thinking phrase with the pi extension's egg order:
+   * holiday (once per turn) → rare 1/150 (once per turn) → weekend greeting
+   * (once per turn) → elapsed-time tiers with night mixing. Every egg is
+   * gated by `config.features` (absent flags default to on).
+   */
+  private livelyPhrase(thinkingMs: number, nowMs: number): string {
+    const features = this.config.features ?? {}
+    const now = new Date(nowMs)
+    if (features.holidays !== false && !this.holidayShown) {
+      const holiday = holidayPhrase(now)
+      if (holiday !== null) {
+        this.holidayShown = true
+        return holiday
+      }
+    }
+    if (features.rareEggs !== false && !this.rareShown && Math.random() < RARE_CHANCE) {
+      this.rareShown = true
+      return rarePhrase(this.previousPhrase)
+    }
+    if (features.weekend !== false && !this.weekendShown && isWeekend(now)) {
+      this.weekendShown = true
+      return weekendPhrase(this.previousPhrase)
+    }
+    return thinkingPhrase(
+      thinkingMs,
+      this.previousPhrase,
+      features.nightPhrases !== false && isNight(now.getHours()),
+      this.config.customPhrases,
+    )
+  }
+
+  /** The pending one-off quip (interrupt / model / compact / work reminder)
+   *  while it is still fresh; expired pending is cleared here. */
+  private pendingPhraseAt(nowMs: number): string | null {
+    if (this.pendingPhrase !== null) {
+      if (nowMs < this.pendingUntil) return this.pendingPhrase
+      this.pendingPhrase = null
+    }
+    const remindAt = this.config.workRemindAt ?? 0
+    if (!this.reminded && remindAt > 0) {
+      const hours = this.turnElapsedMs(nowMs) / 3_600_000
+      if (hours >= remindAt) {
+        this.reminded = true
+        return t('work-remind', { hours: Math.floor(hours) })
+      }
+    }
+    return null
+  }
+
+  /** Whether a phrase comes from the rare pool (longer display window). */
+  private isRarePhrase(phrase: string): boolean {
+    return RARE_PHRASES.includes(phrase) || EN_RARE_PHRASES.includes(phrase)
+  }
+
+  /** Estimated tokens/s while the stream is fresh (pi parity, opt-in). */
+  private tpsPrefix(nowMs: number): string {
+    if (!this.config.showTokPerSec || this.tokBuf <= 0) return ''
+    if (nowMs - this.lastChunkAt > TPS_WINDOW_MS) return ''
+    const windowSec = Math.max(1, (nowMs - this.tokWindowStart) / 1000)
+    const tps = Math.round(this.tokBuf / windowSec)
+    return tps > 0 ? `~${tps} tok/s · ` : ''
+  }
+
+  private doneSummary(nowMs: number): { line: string; phrase?: string } {
+    const { thinkingMs, toolMs, toolCount } = this.stats()
+    const tokens = this.turnTokens > 0 ? ` · 🔥 ${fmtTokens(this.turnTokens)}` : ''
+    const sub = this.subagentCount > 0 ? ` · ${t('subagent-count', { count: this.subagentCount })}` : ''
+    const combo = this.maxStreak >= COMBO_SHOW_AT ? ` · 🔥x${this.maxStreak}` : ''
+    const tools = t(toolCount === 1 ? 'tool-count-one' : 'tool-count-many', { count: toolCount })
+    const summary = t('done-summary', {
+      tools,
+      thinking: fmtDuration(thinkingMs),
+      tooling: fmtDuration(toolMs),
+    })
+    if (!this.config.phrases) {
+      return { line: `${t('done-prefix')} · ${summary}${sub}${combo}${tokens}` }
+    }
+    const last = this.doneQueue.at(-1)
+    if (last !== undefined && nowMs - last.endedAt < DONE_FRAGMENT_MS) {
+      const fragment = toolFragment(last)
+      return { line: `${this.donePrefix} · ${fragment} · ${tools}${sub}${combo}${tokens}`, phrase: this.donePrefix }
+    }
+    return { line: `${this.donePrefix} · ${summary}${sub}${combo}${tokens}`, phrase: this.donePrefix }
+  }
+
+  /** The fresh self-narration line, or null once the stream has been quiet. */
+  private freshNarration(nowMs: number): string | null {
+    if (this.narratedText === null) return null
+    if (nowMs - this.lastChunkAt > NARRATE_GRACE_MS) return null
+    return this.narratedText
+  }
+
+  private primaryTool(): ActiveTool | undefined {
+    let primary: ActiveTool | undefined
+    for (const tool of this.activeTools.values()) {
+      if (primary === undefined || tool.startedAt < primary.startedAt) primary = tool
+    }
+    return primary
+  }
+
+  private turnElapsedMs(nowMs: number): number {
+    return this.turnStartedAt === 0 ? 0 : Math.max(0, nowMs - this.turnStartedAt)
+  }
+
+  private setPhase(phase: ActivityPhase, atMs: number): void {
+    this.phase = phase
+    this.phaseStartedAt = atMs
+  }
+}
+
+/** Rotate the thinking phrase every N render ticks (render cadence ≈ 500ms → ~4s). */
+const PHRASE_ROTATE_MS = 4000
+/** Rare easter-egg phrases linger this long before rotation (pi ≈ 7.5s). */
+const RARE_ROTATE_MS = 7500
+/** One-off quips (interrupt / model / compact) display window. */
+const PENDING_MS = 6000
+/** Tools closer than this count as one combo streak. */
+const COMBO_GAP_MS = 10_000
+/** Streak at which the combo badge shows. */
+const COMBO_SHOW_AT = 2
+/** The tps estimate stays fresh this long after the last chunk. */
+const TPS_WINDOW_MS = 3500
+/** Render tick cadence (matches the TUI's 500ms activity timer). */
+const TICK_MS = 500
+/** Ellipsis breathing frames appended to thinking lines (pi parity). */
+const DOT_FRAMES = ['', ' ·', ' ··', ' ···', ' ··', ' ·']
+/** Cap on replayed done cards; older entries drop. */
+const DONE_QUEUE_MAX = 6
+/** Show the last tool's fragment in the done line for this long after it ends. */
+const DONE_FRAGMENT_MS = 3000
+/** Rolling stream buffer size for `⏵` narration extraction. */
+const STREAM_BUFFER_CHARS = 300
+/** A narration stays visible this long after the stream went quiet. */
+const NARRATE_GRACE_MS = 5000
+
+/** Extract the latest `⏵` self-narration line from a stream buffer. */
+export function extractNarration(buffer: string): string | null {
+  const matches = [...buffer.matchAll(/⏵\s*([^\n⏵]{1,40})/g)]
+  if (matches.length === 0) return null
+  const latest = matches[matches.length - 1]?.[1]
+  if (latest === undefined) return null
+  const text = latest.replace(/[。．.!！,，、;；]+$/, '').trim()
+  return text.length === 0 ? null : text
+}
+
+/** Format a token count compactly (`12.3k`, `1.2M`). */
+function fmtTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`
+  return String(tokens)
+}
+
+/** Coarse streaming token estimate (pi parity: CJK ×1.5, others ÷4). */
+function estimateTokens(text: string): number {
+  const compact = text.replace(/\s/g, '')
+  if (compact.length === 0) return 0
+  const cjkCount = (compact.match(/[\u3400-\u9fff]/g) ?? []).length
+  return Math.max(1, Math.ceil(cjkCount * 1.5 + (compact.length - cjkCount) / 4))
+}
+
+/** Parse a tool call's raw arguments JSON defensively. */
+function parseArguments(raw: string): Readonly<Record<string, unknown>> | undefined {
+  if (raw.trim().length === 0) return undefined
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Readonly<Record<string, unknown>>
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}