agent-board

1import {
2  agentLine,
3  countActive,
4  isActive,
5  layoutRow,
6  recordUsage,
7  shouldAutoOpen,
8  shouldStayOpen,
9  showDetailButton,
10  DETAIL_MODE_CONTEXT,
11  replyModeLabel,
12  sortAgents,
13  summarizeUsage,
14  collapsedLabel,
15} from './board-logic.js'
16
17const PANE = 'agent-board'
18
19// 計時器與快取在模組層級；reload 時 register 會重跑，狀態會歸零
20let timer = null
21let agents = []
22let nowMs = 0
23// 面板縮小時只畫一顆按鈕；記住使用者的選擇，自動開啟時沿用
24let collapsed = false
25// 依 agentId 累計的 token／金額（來自 turn.step 的 usage）
26const usageByAgent = new Map()
27// 依 agentId 記開始／結束時間與 spawn 解析後的模型：{ start, end, model }
28const metaByAgent = new Map()
29// 使用者用 /agent-board 關掉後，常駐模式就不再自動重開，直到再用 /agent-board 打開
30let userClosed = false
31// 回覆模式：'concise'（預設，照 reply-detail 的精簡版）或 'detail'（每則回覆都寫詳細版）；reload 後回到精簡
32let replyMode = 'concise'
33
34// 面板要真的放上畫面才算開著：$.ui.panes() 也會列出等待放置（isPlaced: false）的面板
35async function isShown($) {
36  const panes = await $.ui.panes()
37  return panes.some((p) => p.id === PANE && p.isPlaced !== false)
38}
39
40// 常駐模式：面板不在畫面上就重開。
41// 引擎對非使用者觸發的 ui.open 有寬度門檻（沒手動開過要 144 欄、開過要 110 欄），
42// VS Code 的聊天面板常常不夠寬，session.start 開的面板就停在未放置；
43// 畫面重連、寬度改變、回合開始與結束時都檢查一次，其中 turn.start 由使用者送出訊息觸發，不受門檻限制
44async function ensureOpen($, options) {
45  if (!shouldStayOpen(options) || userClosed) return
46  try {
47    if (!(await isShown($))) await $.ui.open({ id: PANE, title: '子 agent' })
48  } catch (err) {
49    $.ui.log('agent-board：' + err.message, { to: 'debug' })
50  }
51}
52
53// 重新讀 agent 清單、更新狀態列；有進行中的 agent 就確保計時器在跑，沒有就停掉
54async function refresh($) {
55  agents = await $.agent.list()
56  nowMs = await $.clock.now()
57  // 第一次看到不再進行中的 agent 時記下結束時間，之後經過時間就不再增加
58  for (const a of agents) {
59    const m = metaByAgent.get(a.id)
60    if (m && m.end === undefined && !isActive(a)) m.end = nowMs
61  }
62  // 狀態列附上開啟方式：面板關掉後沒有按鈕能再打開，只能靠 /agent-board
63  const line = summarizeUsage(agents, usageByAgent)
64  $.ui.status(line && line + '・/agent-board 開關')
65  $.ui.invalidate('ui.render')
66  if (countActive(agents) > 0) {
67    if (timer === null) {
68      timer = $.clock.every(1000, () => refresh($))
69    }
70  } else if (timer !== null) {
71    timer.cancel()
72    timer = null
73  }
74}
75
76export function register(on, options) {
77  on('session.start', async ($, e, next) => {
78    await $.command.register({
79      name: 'agent-board',
80      description: '開關子 agent 狀態看板',
81      // 子 agent 在跑時主對話的 turn 通常還沒結束，不設 immediate 會等到 turn 結束才開
82      immediate: true,
83    })
84    // 常駐模式：一開始就開面板（不帶 focus），沒有子 agent 時顯示「目前沒有子 agent」
85    await ensureOpen($, options)
86    return next(e)
87  })
88
89  // 畫面（VS Code webview、終端機）連上或寬度改變時，補開沒放上畫面的面板
90  on('session.attach', async ($, e, next) => {
91    const result = await next(e)
92    await ensureOpen($, options)
93    return result
94  })
95  on('session.measure', async ($, e, next) => {
96    const result = await next(e)
97    await ensureOpen($, options)
98    return result
99  })
100
101  // 子 agent 即將啟動：先開面板（不帶 focus）再交出事件，
102  // 因為文件沒寫 next 是在 agent 開始還是結束時返回，先開才保證是即時的
103  on('agent.spawn', async ($, e, next) => {
104    // 看板出錯不能影響子 agent 本身的啟動
105    try {
106      if (shouldAutoOpen(options)) {
107        await $.ui.open({ id: PANE, title: '子 agent' })
108      }
109    } catch (err) {
110      $.ui.log('agent-board：' + err.message, { to: 'debug' })
111    }
112    let startMs
113    try {
114      startMs = await $.clock.now()
115    } catch (err) {
116      $.ui.log('agent-board：' + err.message, { to: 'debug' })
117    }
118    const result = await next(e)
119    try {
120      if (result && result.agentId) {
121        metaByAgent.set(result.agentId, { start: startMs, end: undefined, model: result.model })
122      }
123      await refresh($)
124      // agent 可能還沒出現在清單上，稍後補一次，避免計時器因「沒有進行中」而停掉
125      $.clock.after(1500, () => refresh($))
126    } catch (err) {
127      $.ui.log('agent-board：' + err.message, { to: 'debug' })
128    }
129    return result
130  })
131
132  // 子 agent 的每次模型請求：完成後把 usage 累加起來。主對話（沒有 agentId）直接放行。
133  // 記錄出錯不能影響請求，結果一定原樣回傳。只讀 usage，不呼叫模型、不寫對話紀錄。
134  on('turn.step', async function* ($, e, next) {
135    const result = yield* next(e)
136    try {
137      if (e.agentId && recordUsage(usageByAgent, e.agentId, result && result.usage, e.model)) {
138        $.ui.invalidate('ui.render')
139      }
140    } catch (err) {
141      // 不能讓看板的錯誤影響請求
142    }
143    return result
144  })
145
146  // 使用者送出下一則訊息時，若沒有進行中的 agent 就收起面板（常駐模式不收）
147  on('turn.start', async ($, e, next) => {
148    if (shouldStayOpen(options)) {
149      await ensureOpen($, options)
150      return next(e)
151    }
152    agents = await $.agent.list()
153    if (countActive(agents) === 0) {
154      await $.ui.close({ id: PANE })
155    }
156    return next(e)
157  })
158
159  // 回合結束時再檢查一次（例如回合中途畫面重連過）
160  on('turn.complete', async ($, e, next) => {
161    const result = await next(e)
162    await ensureOpen($, options)
163    return result
164  })
165
166  // 回覆模式為詳細時，在使用者送出的訊息附上詳細版要求；系統產生的訊息（isMeta）不動
167  on('prompt.submit', async ($, e, next) => {
168    if (replyMode !== 'detail' || e.isMeta) return next(e)
169    return next({ ...e, context: [...(e.context || []), DETAIL_MODE_CONTEXT] })
170  })
171
172  // /agent-board：開關面板，自己處理完不呼叫 next。
173  // 用 isPlaced 判斷：看不見的面板也在清單裡，只看 id 會把它當成開著而關掉
174  on('command.run', { command: 'agent-board' }, async ($) => {
175    if (await isShown($)) {
176      userClosed = true
177      await $.ui.close({ id: PANE })
178    } else {
179      userClosed = false
180      await $.ui.open({ id: PANE, title: '子 agent', closeOnEscape: true })
181      await refresh($)
182    }
183    return {}
184  })
185
186  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
187    if (e.requestId !== PANE) return next(e)
188    const { Box, Text, Button } = $.ui.resolve(e)
189
190    const summary = summarizeUsage(agents, usageByAgent) || '目前沒有子 agent'
191    const toggle = () => {
192      collapsed = !collapsed
193      $.ui.invalidate('ui.render')
194    }
195    // 底部按鈕列：縮小／展開，加上可關掉的回覆模式切換鍵
196    const switchMode = () => {
197      replyMode = replyMode === 'detail' ? 'concise' : 'detail'
198      $.ui.invalidate('ui.render')
199    }
200    const detail = !showDetailButton(options)
201      ? []
202      : [Button({ key: 'mode', label: replyModeLabel(replyMode), onPress: switchMode })]
203    const buttonRow = (first) => Box({ flexDirection: 'row', gap: 1, children: [first, ...detail] })
204    if (collapsed) {
205      return Box({
206        flexDirection: 'column',
207        children: [buttonRow(Button({ key: 'expand', label: '▸ ' + collapsedLabel(agents, usageByAgent), onPress: toggle }))],
208      })
209    }
210
211    const columns = e.props && e.props.bodyColumns
212    const rows = sortAgents(agents).flatMap((a) =>
213      layoutRow(
214        agentLine(a, usageByAgent.get(a.id), metaByAgent.get(a.id), nowMs),
215        a.description,
216        columns
217      ).map((line, i) =>
218        Text({ key: 'row-' + a.id + '-' + i, dimColor: i > 0, children: [line] })
219      )
220    )
221
222    return Box({
223      flexDirection: 'column',
224      children: [
225        Text({ bold: true, children: [summary] }),
226        ...rows,
227        Text({ dimColor: true, children: ['金額為估計（API 牌價）'] }),
228        buttonRow(Button({ key: 'collapse', label: '▾ 縮小', onPress: toggle })),
229      ],
230    })
231  })
232}
233

1// 純函式：不碰 $，方便單獨測試
2
3// 這些狀態算「還在進行中」
4const ACTIVE = ['pending', 'running', 'waiting']
5
6export function isActive(agent) {
7  return ACTIVE.includes(agent.status)
8}
9
10export function countActive(agents) {
11  return agents.filter(isActive).length
12}
13
14// options.autoOpen 預設 true；只有明確設成 false 才不自動開
15export function shouldAutoOpen(options) {
16  return !options || options.autoOpen !== false
17}
18
19// options.detailButton 預設 true：看板底部顯示回覆模式切換鍵（設定名稱沿用舊版，避免已設定的人失效）
20export function showDetailButton(options) {
21  return !options || options.detailButton !== false
22}
23
24// 回覆模式切到「詳細」時，附在每則使用者訊息後面的要求（prompt.submit 的 context，每輪都會送出）。
25// 不用 prompt.compose：2.1.301 實測 session 段落只在第一輪生效，之後改了也不會送出
26export const DETAIL_MODE_CONTEXT =
27  '回覆模式：詳細（使用者在看板切換）：這一輪結束的回覆不用精簡版三段式，直接寫詳細版：背景、做了什麼、證據與檔案位置、取捨與風險。'
28
29// 看板上回覆模式切換鍵的文字：顯示目前模式，按下切到另一個
30export function replyModeLabel(mode) {
31  return mode === 'detail' ? '⇄ 回覆：詳細' : '⇄ 回覆：精簡'
32}
33
34// options.persistent 預設 true：session 開始就開面板，turn.start 不收起
35export function shouldStayOpen(options) {
36  return !options || options.persistent !== false
37}
38
39// 狀態列一行摘要，例如「子 agent：2 執行中・1 完成」
40export function summarize(agents) {
41  const active = countActive(agents)
42  const done = agents.filter((a) => a.status === 'completed').length
43  const failed = agents.filter((a) => a.status === 'failed' || a.status === 'killed').length
44  const parts = []
45  if (active > 0) parts.push(active + ' 執行中')
46  if (done > 0) parts.push(done + ' 完成')
47  if (failed > 0) parts.push(failed + ' 失敗')
48  return parts.length > 0 ? '子 agent：' + parts.join('・') : undefined
49}
50
51const STATUS_LABEL = {
52  pending: '等待中',
53  running: '執行中',
54  waiting: '等待輸入',
55  idle: '閒置',
56  completed: '完成',
57  failed: '失敗',
58  killed: '已終止',
59}
60
61export function statusLabel(status) {
62  return STATUS_LABEL[status] || status
63}
64
65// ---- 用量、金額與顯示格式 ----
66
67// 價格表：每百萬 token 美元，與 skills/usage-stats/usage_stats.py 的 PRICES 同值（該檔在別的外掛，不 import）。
68// 欄位順序：[input, output, cache read, 5 分鐘寫入]。模型名用前綴比對。
69const PRICES = {
70  'claude-opus-5-5': [4, 20, 0.2, 5],
71  'claude-sonnet-5-5': [2, 10, 0.2, 2.5],
72}
73// Haiku 依該次請求的 prompt（input+cache_read+cache_write）分兩段價
74const HAIKU_PREFIX = 'claude-haiku-5-5'
75const HAIKU_LOW = [0.1, 0.5, 0.01, 0.125]
76const HAIKU_HIGH = [0.5, 2.5, 0.05, 0.625]
77const HAIKU_LIMIT = 100000
78
79function n(v) {
80  return typeof v === 'number' && Number.isFinite(v) ? v : 0
81}
82
83// 單次請求的估計金額（美元）；模型不認得回傳 null。
84// 估計值：TurnUsage 沒有分 5 分鐘／1 小時寫入，cache_write 一律用 5 分鐘寫入價（1 小時寫入實際較貴）。
85export function estimateCost(usage, model) {
86  if (!usage || typeof model !== 'string') return null
87  const inp = n(usage.input_tokens)
88  const out = n(usage.output_tokens)
89  const cr = n(usage.cache_read_input_tokens)
90  const cw = n(usage.cache_creation_input_tokens)
91  let price = null
92  if (model.startsWith(HAIKU_PREFIX)) {
93    price = inp + cr + cw <= HAIKU_LIMIT ? HAIKU_LOW : HAIKU_HIGH
94  } else {
95    for (const prefix of Object.keys(PRICES)) {
96      if (model.startsWith(prefix)) {
97        price = PRICES[prefix]
98        break
99      }
100    }
101  }
102  if (price === null) return null
103  return (inp * price[0] + out * price[1] + cr * price[2] + cw * price[3]) / 1_000_000
104}
105
106export function newUsage() {
107  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, steps: 0, model: null, cost: 0, unpriced: 0 }
108}
109
110// 把一次 turn.step 的 usage 累加進 map（依 agentId）。沒有 agentId 或 usage 為 null 不動作，回傳是否有記錄。
111// 金額逐次請求計算再加總（Haiku 兩段價是看單次請求，不能用累計值算）。
112export function recordUsage(map, agentId, usage, fallbackModel) {
113  if (!agentId || !usage || typeof usage !== 'object') return false
114  const u = map.get(agentId) || newUsage()
115  const model = typeof usage.model === 'string' && usage.model ? usage.model : fallbackModel
116  u.input += n(usage.input_tokens)
117  u.output += n(usage.output_tokens)
118  u.cacheRead += n(usage.cache_read_input_tokens)
119  u.cacheWrite += n(usage.cache_creation_input_tokens)
120  u.steps += 1
121  if (typeof model === 'string' && model) u.model = model
122  const c = estimateCost(usage, model)
123  if (c === null) u.unpriced += 1
124  else u.cost += c
125  map.set(agentId, u)
126  return true
127}
128
129export function totalTokens(u) {
130  return u ? u.input + u.output + u.cacheRead + u.cacheWrite : 0
131}
132
133// 12.3k、1.2M；整數不帶 .0
134export function formatTokens(count) {
135  if (typeof count !== 'number' || !Number.isFinite(count) || count < 0) return '—'
136  if (count < 1000) return String(Math.round(count))
137  const trim = (x) => x.toFixed(1).replace(/\.0$/, '')
138  if (count < 999950) return trim(count / 1000) + 'k'
139  return trim(count / 1e6) + 'M'
140}
141
142// 45s、3m12s、1h05m
143export function formatElapsed(ms) {
144  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) return '—'
145  const s = Math.floor(ms / 1000)
146  if (s < 60) return s + 's'
147  const m = Math.floor(s / 60)
148  if (m < 60) return m + 'm' + String(s % 60).padStart(2, '0') + 's'
149  return Math.floor(m / 60) + 'h' + String(m % 60).padStart(2, '0') + 'm'
150}
151
152// claude-sonnet-5-5 → sonnet-5.5；去掉日期尾碼；認不得的原樣回傳；沒有值回傳 '—'
153export function shortModel(model) {
154  if (typeof model !== 'string' || !model) return '—'
155  const m = model.match(/^claude-([a-z]+)-(\d+)(?:-(\d{1,2}))?(?:-\d{8})?$/)
156  if (m) return m[1] + '-' + m[2] + (m[3] ? '.' + m[3] : '')
157  return model.replace(/^claude-/, '')
158}
159
160// 「約 $0.12」用的數字；null 回傳 '—'
161export function formatCost(usd) {
162  if (typeof usd !== 'number' || !Number.isFinite(usd)) return '—'
163  if (usd > 0 && usd < 0.01) return '<$0.01'
164  return '$' + usd.toFixed(2)
165}
166
167// 顯示寬度：全形／CJK 算 2 欄
168function charWidth(ch) {
169  const c = ch.codePointAt(0)
170  return (c >= 0x1100 && c <= 0x115f) || (c >= 0x2e80 && c <= 0xa4cf) || (c >= 0xac00 && c <= 0xd7a3) ||
171    (c >= 0xf900 && c <= 0xfaff) || (c >= 0xfe30 && c <= 0xfe6f) || (c >= 0xff00 && c <= 0xff60) ||
172    (c >= 0xffe0 && c <= 0xffe6) || (c >= 0x1f300 && c <= 0x1faff)
173    ? 2
174    : 1
175}
176
177export function displayWidth(str) {
178  let w = 0
179  for (const ch of String(str)) w += charWidth(ch)
180  return w
181}
182
183// 依顯示寬度截斷，超過加「…」；也會把換行壓成空白
184export function truncate(str, width) {
185  const s = String(str ?? '').replace(/\s+/g, ' ').trim()
186  if (displayWidth(s) <= width) return s
187  let w = 0
188  let out = ''
189  for (const ch of s) {
190    const cw = charWidth(ch)
191    if (w + cw > width - 1) break
192    out += ch
193    w += cw
194  }
195  return out + '…'
196}
197
198function sums(agents, usageMap) {
199  let tokens = 0
200  let cost = 0
201  let unpriced = 0
202  let seen = false
203  for (const a of agents) {
204    const u = usageMap.get(a.id)
205    if (!u) continue
206    seen = true
207    tokens += totalTokens(u)
208    cost += u.cost
209    unpriced += u.unpriced
210  }
211  return { tokens, cost, unpriced, seen }
212}
213
214// 「N 執行中・M 完成｜合計 X tokens・約 $Y」；用於面板第一行與狀態列（最多 200 字）
215export function summarizeUsage(agents, usageMap) {
216  const base = summarize(agents)
217  if (!base) return undefined
218  return withUsageTail(base, agents, usageMap)
219}
220
221// 縮小時的按鈕文字：列出執行中的類型（同類型合併成 ×N），看得出是誰在跑
222export function collapsedLabel(agents, usageMap) {
223  if (agents.length === 0) return '目前沒有子 agent'
224  const active = agents.filter(isActive)
225  if (active.length === 0) return withUsageTail('全部完成（' + agents.length + ' 個）', agents, usageMap)
226  const counts = new Map()
227  for (const a of active) counts.set(a.type || '—', (counts.get(a.type || '—') || 0) + 1)
228  const types = [...counts].map(([t, n]) => (n > 1 ? t + '×' + n : t)).join('、')
229  return withUsageTail('執行中：' + types, agents, usageMap)
230}
231
232function withUsageTail(head, agents, usageMap) {
233  const s = sums(agents, usageMap)
234  const cost = s.seen ? formatCost(s.cost) + (s.unpriced > 0 ? '+' : '') : '—'
235  const text = head + '｜合計 ' + (s.seen ? formatTokens(s.tokens) : '—') + ' tokens・約 ' + cost
236  return text.length > 200 ? text.slice(0, 199) + '…' : text
237}
238
239// 執行中的排前面，其餘維持原順序
240export function sortAgents(agents) {
241  return [...agents].sort((a, b) => Number(isActive(b)) - Number(isActive(a)))
242}
243
244// 一個 agent 的資訊行（不含描述）。meta：{ start, end, model }
245export function agentLine(agent, usage, meta, now) {
246  const m = meta || {}
247  let elapsed = '—'
248  if (typeof m.start === 'number') {
249    const end = typeof m.end === 'number' ? m.end : isActive(agent) ? now : undefined
250    if (typeof end === 'number') elapsed = formatElapsed(end - m.start)
251  }
252  const model = (usage && usage.model) || m.model
253  const tokens = usage ? formatTokens(totalTokens(usage)) : '—'
254  const cost = usage && usage.steps > 0 ? (usage.unpriced > 0 && usage.cost === 0 ? '—' : '約 ' + formatCost(usage.cost)) : '—'
255  return [agent.type || '—', shortModel(model), statusLabel(agent.status), elapsed, tokens, cost].join('｜')
256}
257
258// 依寬度排版：寬就把描述接在同一行，窄就放第二行（太窄則省略）。回傳字串陣列。
259export function layoutRow(info, description, columns) {
260  const cols = typeof columns === 'number' && columns > 0 ? columns : 60
261  const desc = String(description ?? '').trim()
262  if (!desc) return [info]
263  const room = cols - displayWidth(info) - 1
264  if (room >= 20) return [info + '｜' + truncate(desc, room - 1)]
265  if (cols < 30) return [info]
266  return [info, '  ' + truncate(desc, cols - 2)]
267}
268