agentworkshop 0.7.3 → 0.7.5

package/tui/components/chat-log.mjs

@@ -0,0 +1,42 @@
+// ============================================================
+// ChatLog 组件 —— 会话时间线(AEP 归约后的 log 行渲染)。
+// 每次 render 全量输出(有界 400 行),增量绘制由 TuiMainScreen 差分完成。
+// 输出经 truncateToWidth 兜底(CJK 宽字符行宽;pi-tui 对超宽行直接 crash)。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const TONE_OF = {
+  'system': s => theme.faint(s),
+  'user': s => `${theme.info('◆ 你')} ${s}`,
+  'agent': s => `${theme.accent('◆ Agent')} ${s}`,
+  'stream': s => theme.faint(s),
+  'task': s => theme.info(s),
+  'hitl': s => theme.warn(s),
+  'hitl-resolved': s => theme.accent(s),
+  'error': s => theme.error(`✗ ${s}`),
+  'notice': s => theme.faint(`· ${s}`),
+  'monitor': s => s,
+}
+
+export class ChatLog {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const w = Math.max(width, 20)
+    const lines = []
+    for (const row of this.state.log) {
+      const paint = TONE_OF[row.kind] ?? (s => s)
+      const prefix = row.kind === 'agent' && row.agentName ? `${theme.faint(`[${row.agentName}]`)} ` : ''
+      const wrapped = wrapTextWithAnsi(paint(`${prefix}${row.text}`), w)
+      lines.push(...wrapped)
+    }
+    if (this.state.statusMsg && Date.now() - this.state.statusAt < 15_000) {
+      lines.push('')
+      lines.push(theme.faint(this.state.statusMsg))
+    }
+    return lines.map(l => truncateToWidth(l, w))
+  }
+}

package/tui/components/hitl-card.mjs

@@ -0,0 +1,36 @@
+// ============================================================
+// HitlCard —— 作答模式卡片(state.hitlAnswering 非空时渲染于输入框上方)。
+// 作答约定:confirm → y/n;select → 选项序号;input/editor → 自由文本;
+// /hitl off 放弃作答(等价 Esc)。提交经 POST /api/workshop/hitl/respond。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const HINT = {
+  confirm: '输入 y 批准 / n 拒绝',
+  select: '输入选项序号(如 1)',
+  input: '输入回答文本',
+  editor: '输入回答文本',
+}
+
+export class HitlCard {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const item = this.state.hitlAnswering
+    if (!item) return []
+    const w = Math.max(width - 4, 20)
+    const lines = []
+    lines.push(theme.warn(`⏸ HITL 作答 · ${item.agentName} · ${item.kind === 'omp-dialog' ? 'omp 对话框' : '下发审批'}`))
+    lines.push(truncateToWidth(theme.bold(String(item.title ?? '')), w))
+    if (item.detail) lines.push(...wrapTextWithAnsi(theme.faint(item.detail), w))
+    if (item.message) lines.push(...wrapTextWithAnsi(String(item.message), w))
+    if (item.method === 'select' && Array.isArray(item.options)) {
+      item.options.forEach((opt, i) => lines.push(`  ${theme.accent(`${i + 1}.`)} ${opt}`))
+    }
+    lines.push(theme.faint(`${HINT[item.method] ?? '输入回答'} · /hitl off 放弃`))
+    return lines.map(l => truncateToWidth(l, Math.max(width, 20)))
+  }
+}

package/tui/components/monitor-pane.mjs

@@ -0,0 +1,39 @@
+// ============================================================
+// MonitorPane —— 右侧 agent 终端镜像面板(term 帧 → 行)。
+// 行来源:aw-tui 的终端 WS 接线把 term.* 帧写入 state.monitor。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { wrapTextWithAnsi, truncateToWidth } from '@earendil-works/pi-tui'
+
+const TONE = {
+  dim: s => theme.faint(s),
+  info: s => theme.info(s),
+  warn: s => theme.warn(s),
+  error: s => theme.error(s),
+  accent: s => theme.accent(s),
+  monitor: s => s,
+}
+
+export class MonitorPane {
+  constructor(state, width = 44) {
+    this.state = state
+    this.width = width
+  }
+
+  render() {
+    const m = this.state.monitor
+    const w = Math.max(this.width - 2, 16)
+    const head = theme.info(`┌─ 监控 ${m.name ?? m.agentId?.slice(0, 8) ?? ''} ${m.streaming ? '· 流式中' : ''}`)
+    const lines = [head]
+    if (m.waiting) lines.push(theme.warn('omp 进程未启动,等待首个任务…'))
+    if (!m.agentId) lines.push(theme.faint('(未开启 —— /monitor <agent名|序号>)'))
+    for (const l of m.lines) {
+      const paint = TONE[l.tone] ?? (s => s)
+      lines.push(...wrapTextWithAnsi(paint(l.text), w))
+    }
+    if (m.streamText) {
+      lines.push(...wrapTextWithAnsi(theme.faint(m.streamText.slice(-600)), w))
+    }
+    return lines.slice(0, 200).map(l => truncateToWidth(l, w))
+  }
+}

package/tui/components/root.mjs

@@ -0,0 +1,53 @@
+// ============================================================
+// Root —— 组件树组装:双栏(会话流 | 监控面板) + HITL 卡 + 状态条 + 编辑器。
+// 双栏为手工列合成(pi-tui Container 只做纵向;列宽恒定防抖动)。
+// 列宽计算必须用 CJK 感知的 visibleWidth(中文占 2 列;stripAnsi().length 会低估)。
+// ============================================================
+import { visibleWidth, truncateToWidth } from '@earendil-works/pi-tui'
+import { theme } from '../theme.mjs'
+
+/**
+ * 双栏容器:左栏自适应,右栏固定宽;任一为空退化为单栏。
+ * left/right 需实现 render(width) → string[](Component duck-typing)。
+ */
+export class Columns {
+  constructor(left, right = null, rightWidth = 46) {
+    this.left = left
+    this.right = right
+    this.rightWidth = rightWidth
+  }
+
+  render(width) {
+    const gutter = 3
+    const leftWidth = this.right ? width - this.rightWidth - gutter : width
+    const leftLines = this.left.render(leftWidth).map(l => truncateToWidth(l, leftWidth))
+    if (!this.right || this.right.render === undefined) return leftLines
+    const rightLines = this.right.render(this.rightWidth).map(l => truncateToWidth(l, this.rightWidth - 1))
+    const height = Math.max(leftLines.length, rightLines.length)
+    const out = []
+    for (let i = 0; i < height; i++) {
+      const l = leftLines[i] ?? ''
+      const r = rightLines[i] ?? ''
+      const padL = ' '.repeat(Math.max(leftWidth - visibleWidth(l), 0))
+      out.push(`${l}${padL}${theme.faint(' │ ')}${r}`)
+    }
+    return out
+  }
+}
+
+/** 组装整棵组件树(aw-tui 调用;返回可挂到 TUI 的顶层组件) */
+export function buildTree({ state, chatLog, monitorPane, hitlCard, statusBar, editor }) {
+  const columns = new Columns(chatLog, monitorPane)
+  const stack = {
+    render(width) {
+      return [
+        ...columns.render(width),
+        ...hitlCard.render(width),
+        ...statusBar.render(width),
+      ]
+    },
+  }
+  void state
+  void editor
+  return { stack, editor }
+}

package/tui/components/status-bar.mjs

@@ -0,0 +1,33 @@
+// ============================================================
+// StatusBar —— 底部状态条:频道/成员忙碌/HITL 待办/连接态。
+// ============================================================
+import { theme } from '../theme.mjs'
+import { truncateToWidth } from '@earendil-works/pi-tui'
+
+const CONN_LABEL = { open: '实时', connecting: '连接中', closed: '离线' }
+
+export class StatusBar {
+  constructor(state) {
+    this.state = state
+  }
+
+  render(width) {
+    const s = this.state
+    const channel = s.channels.find(c => c.id === s.activeChannelId)
+    const members = s.agents.length
+    const busy = Object.values(s.agentStates).filter(a => a.state === 'busy').length
+    const target = s.target
+      ? theme.info(`@${s.target.name}(通信)`)
+      : theme.accent('频道(任务)')
+    const parts = [
+      theme.accent(`▣ ${channel?.name ?? '未选择频道'}`),
+      `${theme.faint('输入→')} ${target}`,
+      members > 0 ? theme.faint(`成员 ${members}(忙 ${busy})`) : theme.faint('成员 0'),
+      s.hitl.length > 0 ? theme.warn(`⏸ HITL 待处理 ${s.hitl.length}(/hitl)`) : theme.faint('HITL 0'),
+      s.monitor.agentId ? theme.info(`监控:${s.monitor.waiting ? '等待进程' : s.monitor.name}`) : null,
+      s.connState === 'open' ? theme.faint(`● ${CONN_LABEL[s.connState]}`) : theme.warn(`● ${CONN_LABEL[s.connState] ?? s.connState}`),
+    ].filter(Boolean)
+    const line = parts.join(theme.faint(' · '))
+    return [truncateToWidth(line, Math.max(width, 20))]
+  }
+}

package/tui/lib/api.mjs

@@ -0,0 +1,82 @@
+// ============================================================
+// TUI REST 客户端 —— 统一信封 { code, message, data } 解包 + Bearer 注入。
+// 与 sdk/api.mjs 同语义(轻量自包含:TUI 不依赖构建产物,保持 .mjs 直跑)。
+// ============================================================
+
+/**
+ * 创建 API 客户端
+ * @param {object} opts
+ * @param {string} opts.baseUrl   形如 http://127.0.0.1:3000
+ * @param {string} opts.token     用户 token(ut-*)
+ */
+export function createApi({ baseUrl, token, timeoutMs = 15_000 }) {
+  const base = String(baseUrl ?? '').replace(/\/+$/, '')
+  // 动态 token:登录/运行中换凭据即时生效(避免实例化时闭包捕获 undefined)
+  let currentToken = token ?? ''
+
+  async function request(path, { method = 'GET', body, query } = {}) {
+    const url = new URL(base + path)
+    if (query) for (const [k, v] of Object.entries(query)) url.searchParams.set(k, String(v))
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          ...(currentToken ? { authorization: `Bearer ${currentToken}` } : {}),
+          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: ctrl.signal,
+      })
+      const json = await res.json().catch(() => null)
+      if (!json || json.code === undefined) {
+        throw new Error(`HTTP ${res.status}(响应非标准信封)`)
+      }
+      if (json.code !== 0) {
+        const err = new Error(json.message ?? String(json.code))
+        err.code = json.code
+        throw err
+      }
+      return json.data
+    }
+    finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return {
+    request,
+    /** 运行中更新凭据(登录后/换号) */
+    setToken(t) {
+      currentToken = t ?? ''
+    },
+
+    // ── 登录(无 token 引导;成功自动记住 token) ──
+    async login(email, password) {
+      const res = await request('/api/users/login', { method: 'POST', body: { email, password } })
+      currentToken = res.token
+      return res
+    },
+    get: (path, query) => request(path, { query }),
+    post: (path, body) => request(path, { method: 'POST', body }),
+
+    // ── channel/agent/task 管理面 ──
+    listChannels: () => request('/api/workshop/channels'),
+    createChannel: body => request('/api/workshop/channels', { method: 'POST', body }),
+    listAgents: channelId => request(`/api/workshop/channels/${channelId}/agents`),
+    addAgent: (channelId, body) => request(`/api/workshop/channels/${channelId}/agents`, { method: 'POST', body }),
+    listTemplates: () => request('/api/workshop/agents'),
+    listMessages: (channelId, limit = 50) => request(`/api/workshop/channels/${channelId}/messages`, { query: { limit } }),
+    sendMessage: (channelId, body) => request(`/api/workshop/channels/${channelId}/messages`, { method: 'POST', body }),
+    listTasks: channelId => request(`/api/workshop/channels/${channelId}/tasks`),
+    submitTask: (channelId, body) => request(`/api/workshop/channels/${channelId}/tasks`, { method: 'POST', body }),
+
+    // ── HITL 统一面(pending 响应为 { items: [...] },此处解包为数组) ──
+    hitlPending: async (channelId) => {
+      const data = await request('/api/workshop/hitl/pending', { query: channelId ? { channelId } : {} })
+      return data?.items ?? []
+    },
+    hitlRespond: body => request('/api/workshop/hitl/respond', { method: 'POST', body }),
+  }
+}

package/tui/lib/config.mjs

@@ -0,0 +1,58 @@
+// ============================================================
+// TUI 认证/连接配置 —— 落配置根 .AgentWorkShop/tui-auth.json(0600)。
+// 解析口径与服务端一致:cwd 向上找 config.yml → <repo>/.AgentWorkShop,
+// 找不到(全局安装任意 cwd)→ ~/.AgentWorkShop。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve, dirname } from 'node:path'
+
+/** 向上查找文件(repo 模式判定) */
+function findUp(startDir, filename) {
+  let dir = resolve(startDir)
+  for (;;) {
+    const candidate = join(dir, filename)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** 配置根(repo 内 cwd → <repo>/.AgentWorkShop;否则 ~/.AgentWorkShop) */
+export function configRoot(cwd = process.cwd()) {
+  const marker = findUp(cwd, 'config.yml')
+  if (marker) return join(dirname(marker), '.AgentWorkShop')
+  return join(homedir(), '.AgentWorkShop')
+}
+
+const authPath = cwd => join(configRoot(cwd), 'tui-auth.json')
+
+/** 读取已存凭据({ baseUrl, token, email? } 或 null) */
+export function loadAuth(cwd = process.cwd()) {
+  try {
+    const raw = JSON.parse(readFileSync(authPath(cwd), 'utf8'))
+    if (raw && typeof raw.token === 'string' && typeof raw.baseUrl === 'string') return raw
+  }
+  catch { /* 无凭据/损坏 → 重新登录 */ }
+  return null
+}
+
+/** 持久化凭据(0600;路径加入 .gitignore) */
+export function saveAuth(auth, cwd = process.cwd()) {
+  const file = authPath(cwd)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(auth, null, 2)}\n`, 'utf8')
+  try {
+    chmodSync(file, 0o600)
+  }
+  catch { /* Windows FAT 卷 chmod 无效,忽略 */ }
+}
+
+/** 清除凭据(登出) */
+export function clearAuth(cwd = process.cwd()) {
+  try {
+    existsSync(authPath(cwd)) && (writeFileSync(authPath(cwd), '{}\n', 'utf8'), true)
+  }
+  catch { /* 尽力而为 */ }
+}

package/tui/lib/pickers.mjs

@@ -0,0 +1,102 @@
+// ============================================================
+// 交互选择器(浮层)—— 频道选择 / Agent 选择。
+// 基于 pi-tui showOverlay + SelectList:方向键移动、Enter 选择、Esc 取消。
+// ============================================================
+import { SelectList } from '@earendil-works/pi-tui'
+import { theme } from '../theme.mjs'
+
+/** 组合"标题 + SelectList"的浮层组件。返回 handle { hide, list, component, __bindHandle } */
+function pickerComponent(title, items, maxVisible, onSelect, onCancel) {
+  const list = new SelectList(items, maxVisible, theme.editor.selectList)
+  const wrap = {
+    render(width) {
+      return [theme.accent(`┌─ ${title}`), ...list.render(Math.max(width - 2, 24))]
+    },
+  }
+  const handle = { hide() {}, list, component: wrap }
+  list.onSelect = (item) => {
+    handle.hide()
+    onSelect(item)
+  }
+  list.onCancel = () => {
+    handle.hide()
+    onCancel?.()
+  }
+  // 二次装配:showOverlay 返回真实 handle 后回填 hide(调用方调 picker.__bindHandle(real))
+  handle.__bindHandle = (h) => {
+    handle.hide = () => h.hide()
+  }
+  return handle
+}
+
+/**
+ * 频道选择浮层。Enter 选择并切换;Esc 取消(fallback 频道由调用方决定)。
+ * @returns handle { close }
+ */
+export function openChannelPicker(tui, state, { onSelect, onCancel } = {}) {
+  const items = state.channels.map(c => ({
+    value: c.id,
+    label: c.name,
+    description: c.leadAgentId ? 'lead 已配置' : '无 lead(仅收发消息)',
+  }))
+  const picker = pickerComponent('选择要进入的频道(↑↓ 移动 · Enter 进入 · Esc 取消)', items, Math.min(10, items.length),
+    (item) => {
+      state.channelPickerOpen = false
+      onSelect?.(item.value)
+    },
+    () => {
+      state.channelPickerOpen = false
+      onCancel?.()
+    })
+  state.channelPickerOpen = true
+  const handle = tui.showOverlay(picker.component, { anchor: 'center' })
+  picker.__bindHandle(handle)
+  tui.setFocus(picker.list)
+  return handle
+}
+
+/**
+ * Agent/对话目标选择浮层(Tab 触发)。首项 = 频道(发布任务模式);
+ * 选具体成员 = 切换通信目标并自动打开其独立监控。
+ */
+export function openTargetPicker(tui, state, { onPick, onCancel } = {}) {
+  const s = state.agents
+    .filter(a => a.enabled !== 0)
+    .map(a => ({
+      value: a.id,
+      label: `${a.name}${a.role === 'lead' ? '(lead)' : ''}`,
+      description: `通信对话 + 独立监控 · ${state.agentStates[a.id]?.state ?? 'idle'}`,
+    }))
+  const items = [{ value: '__channel__', label: '频道(发布任务)', description: '普通文本 = 向频道发布正式任务' }, ...s]
+  if (items.length === 1 && s.length === 0) {
+    onCancel?.()
+    return null
+  }
+  const picker = pickerComponent('选择对话目标(Tab 呼出 · ↑↓ 移动 · Enter 确认 · Esc 取消)', items, Math.min(10, items.length),
+    (item) => {
+      if (process.env.AW_TUI_DEBUG) console.error('[picker-debug] item=', JSON.stringify(item), 'agentIds=', JSON.stringify(s.map(x => x.value)))
+      state.targetPickerOpen = false
+      if (item.value === '__channel__') {
+        state.target = null
+        onPick?.(null)
+      }
+      else {
+        const a = state.agents.find(x => x.id === item.value)
+        if (!a) {
+          onCancel?.()
+          return
+        }
+        state.target = { agentId: a.id, name: a.name }
+        onPick?.(a)
+      }
+    },
+    () => {
+      state.targetPickerOpen = false
+      onCancel?.()
+    })
+  state.targetPickerOpen = true
+  const handle = tui.showOverlay(picker.component, { anchor: 'center' })
+  picker.__bindHandle(handle)
+  tui.setFocus(picker.list)
+  return handle
+}

package/tui/lib/reducers.mjs

@@ -0,0 +1,218 @@
+// ============================================================
+// AEP 帧归约(纯函数式:输入 state+信封 → 原地更新 state 与 log 行)。
+// 与 WebUI 的 events.store 同一套语义:agent.delta 聚合进流式块,落定
+// agent.message 携带全文定稿(去重);hitl 增删幂等(kind+id)。
+// 可被 tsx/单测与 scripts/tui-smoke.mjs 无头驱动。
+// ============================================================
+import { pushLog } from './state.mjs'
+
+const STREAM_TAIL = 4000
+
+/** 从信封/消息提取展示名 */
+function agentNameOf(state, agentId, fallback = '') {
+  if (!agentId) return fallback
+  const a = state.agents.find(x => x.id === agentId)
+  return a?.name ?? fallback ?? agentId.slice(0, 8)
+}
+
+/** 消息 parts → 纯文本 */
+function partsText(message) {
+  const parts = message?.parts ?? []
+  return parts.map((p) => {
+    if (typeof p === 'string') return p
+    if (p && typeof p === 'object' && typeof p.text === 'string') return p.text
+    return ''
+  }).join('').trim()
+}
+
+/**
+ * 归约一帧 AEP 信封。返回 'handled' | 'ignored'(测试断言用)。
+ * 流式块键 = agentId+taskId(agent.message 到达即定稿替换全文)。
+ */
+export function reduceEnvelope(state, e) {
+  switch (e.type) {
+    case 'agent.status': {
+      const p = e.payload
+      state.agentStates[p.agentId] = {
+        state: p.state,
+        currentTaskId: p.currentTaskId ?? null,
+        queued: p.queued ?? 0,
+        completed: p.completed ?? 0,
+      }
+      return 'handled'
+    }
+    case 'agent.delta': {
+      const text = e.payload?.delta ?? ''
+      if (!text) return 'ignored'
+      const row = findStreamRow(state, e.agentId, e.taskId)
+      if (row) {
+        row.text = (row.text + text).slice(-STREAM_TAIL)
+      }
+      else {
+        pushLog(state, 'stream', text, { agentName: agentNameOf(state, e.agentId), agentId: e.agentId, taskId: e.taskId ?? null })
+      }
+      return 'handled'
+    }
+    case 'agent.message': {
+      const msg = e.payload ?? {}
+      const text = partsText(msg)
+      if (!text) return 'ignored'
+      const agentId = e.agentId ?? msg.metadata?.['x-aw-from-agent'] ?? ''
+      const name = agentNameOf(state, agentId, msg.metadata?.['x-aw-from-label'] ?? '')
+      const row = findStreamRow(state, agentId, e.taskId)
+      if (row) {
+        // 定稿:流式增量替换为全文,并升级为正式 agent 行(渲染带名高亮)
+        row.text = text
+        row.kind = 'agent'
+        row.agentName = name
+      }
+      else {
+        pushLog(state, 'agent', text, { agentName: name, agentId, taskId: e.taskId ?? null })
+      }
+      return 'handled'
+    }
+    case 'a2a.message': {
+      const msg = e.payload ?? {}
+      const meta = msg.metadata ?? {}
+      const fromLabel = meta['x-aw-from-label'] ?? ''
+      const fromAgent = meta['x-aw-from-agent'] ?? e.agentId ?? ''
+      const text = partsText(msg)
+      if (!text) return 'ignored'
+      const cross = meta['x-aw-cross-channel'] === 'true'
+      const prefix = cross ? '[跨频道] ' : ''
+      if (fromAgent) {
+        pushLog(state, 'agent', prefix + text, { agentName: agentNameOf(state, fromAgent, fromLabel), agentId: fromAgent, taskId: msg.taskId ?? null })
+      }
+      else {
+        // 人类消息(服务端盖章 from-label;本端发出的回显也走这里)
+        pushLog(state, 'user', prefix + text, { agentName: fromLabel || '用户' })
+      }
+      return 'handled'
+    }
+    case 'agent.status.message': {
+      const text = (e.payload?.text ?? '').trim()
+      if (text) pushLog(state, 'notice', text, { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'task.status': {
+      const p = e.payload ?? {}
+      upsertTask(state, p)
+      const title = p.title ?? state.tasks.find(t2 => t2.taskId === p.taskId)?.title ?? ''
+      pushLog(state, 'task', `任务 ${p.taskId?.slice(0, 8)}${title ? `「${title}」` : ''} → ${p.state}${p.progress != null ? ` ${p.progress}%` : ''}`)
+      return 'handled'
+    }
+    case 'task.progress': {
+      const p = e.payload ?? {}
+      upsertTask(state, p)
+      return 'handled'
+    }
+    case 'a2a.artifact': {
+      const art = e.payload?.artifact
+      const name = art?.name ?? art?.kind ?? 'artifact'
+      pushLog(state, 'notice', `交付物:${name}`, { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'error': {
+      pushLog(state, 'error', e.payload?.message ?? '未知错误', { agentName: agentNameOf(state, e.agentId) })
+      return 'handled'
+    }
+    case 'hitl.request': {
+      upsertHitl(state, e.payload)
+      const it = e.payload
+      pushLog(state, 'hitl', `⏸ 需要人工处理:${it.title}(${it.agentName})—— /hitl 查看并作答`)
+      return 'handled'
+    }
+    case 'hitl.resolved': {
+      const r = e.payload
+      state.hitl = state.hitl.filter(i => !(i.kind === r.kind && i.id === r.id))
+      if (state.hitlAnswering && state.hitlAnswering.kind === r.kind && state.hitlAnswering.id === r.id) state.hitlAnswering = null
+      pushLog(state, 'hitl-resolved', `✔ 待办已落定:${r.id}(outcome=${r.outcome}${r.by ? `, by ${r.by}` : ''})`)
+      return 'handled'
+    }
+    default:
+      return 'ignored'
+  }
+}
+
+function findStreamRow(state, agentId, taskId) {
+  for (let i = state.log.length - 1; i >= 0; i--) {
+    const row = state.log[i]
+    if (row.kind === 'stream' && row.agentId === agentId && (row.taskId ?? null) === (taskId ?? null)) return row
+  }
+  return null
+}
+
+function upsertTask(state, p) {
+  if (!p.taskId) return
+  const idx = state.tasks.findIndex(t => t.taskId === p.taskId)
+  if (idx >= 0) state.tasks[idx] = { ...state.tasks[idx], ...p }
+  else state.tasks.unshift(p)
+  state.tasks = state.tasks.slice(0, 100)
+}
+
+function upsertHitl(state, item) {
+  if (!item?.id) return
+  const idx = state.hitl.findIndex(i => i.kind === item.kind && i.id === item.id)
+  if (idx >= 0) state.hitl[idx] = item
+  else state.hitl.push(item)
+}
+
+// ===== 终端镜像帧 → monitor 行(纯部分;ws 接线在 aw-tui) =====
+
+/** term 帧 → monitor 行描述;返回 { lines:[{text,tone}], streamAppend?, streamEnd?, statePatch? } */
+export function reduceTermFrame(frame) {
+  const out = { lines: [], streamAppend: '', streamEnd: null, statePatch: null }
+  const type = frame?.type
+  switch (type) {
+    case 'agent_start':
+      out.lines.push({ text: '── 回合开始 ──', tone: 'dim' })
+      break
+    case 'agent_end':
+      out.lines.push({ text: '── 回合结束 ──', tone: 'dim' })
+      break
+    case 'message_end': {
+      const text = String(frame.text ?? '').trim()
+      if (text) out.lines.push({ text, tone: 'monitor' })
+      break
+    }
+    case 'tool_execution_start':
+      out.lines.push({ text: `🔧 ${frame.toolName ?? ''}${brief(frame.args, 80)}`, tone: 'info' })
+      break
+    case 'tool_execution_end':
+      out.lines.push({ text: `${frame.isError ? '✗' : '✔'} ${frame.toolName ?? ''}${brief(frame.result, 120)}`, tone: frame.isError ? 'error' : 'dim' })
+      break
+    case 'host_tool_call':
+      out.lines.push({ text: `🛠 host ${frame.toolName ?? ''}${brief(frame.args, 80)}`, tone: 'info' })
+      break
+    case 'extension_ui_request':
+      if (frame.method && frame.method !== 'cancel') {
+        out.lines.push({ text: `⏸ HITL ${frame.method}「${String(frame.title ?? '').slice(0, 60)}」(/hitl 作答)`, tone: 'warn' })
+      }
+      break
+    case '__human_input':
+      out.lines.push({ text: `⌨ ${String(frame.text ?? '').slice(0, 120)}`, tone: 'info' })
+      break
+    case '__terminal_notice':
+      out.lines.push({ text: String(frame.message ?? ''), tone: frame.level === 'error' ? 'error' : frame.level === 'warning' ? 'warn' : 'dim' })
+      break
+    default:
+      break
+  }
+  return out
+}
+
+function brief(value, max) {
+  if (value == null) return ''
+  let s = typeof value === 'string'
+    ? value
+    : (() => {
+        try {
+          return JSON.stringify(value) ?? ''
+        }
+        catch {
+          return String(value)
+        }
+      })()
+  s = s.replace(/\s+/g, ' ').trim()
+  return s ? ` ${s.slice(0, max)}${s.length > max ? '…' : ''}` : ''
+}