@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/operator/node/boardInteraction.ts

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+import type { WorkspaceHandlers } from '../../core/provider';
+import type { CliEvent } from '../../core/store';
+import type { Quote } from './composerDraft';
+export type OperatorBoardTab = 'files' | 'changes' | 'context' | 'preview' | 'browser';
+export interface OperatorBoardOptions extends WorkspaceHandlers { watchFiles?:boolean; fileWatchIntervalMs?:number; onEvent?:(event:CliEvent)=>void; tabs?: OperatorBoardTab[]; availableTabs?: OperatorBoardTab[]; defaultTab?: OperatorBoardTab; autoContext?: boolean }
+export type OperatorBoardTarget = { kind: 'file'; taskId: string; path: string } | { kind: 'browser'; taskId: string };
+export interface OperatorBoardRequest { sequence: number; target: OperatorBoardTarget }
+export const OperatorBoardContext = createContext<((target: OperatorBoardTarget) => boolean) | null>(null);
+
+export const OperatorBoardQuoteContext = createContext<((quote:Quote)=>void)|null>(null);
+
+const surfaces=new Set<(target:OperatorBoardTarget)=>boolean>();
+export function registerOperatorBoard(surface:(target:OperatorBoardTarget)=>boolean):()=>void {surfaces.add(surface);return()=>{surfaces.delete(surface);};}
+export function openOperatorBoard(target:OperatorBoardTarget):boolean {for(const surface of [...surfaces].reverse())if(surface(target))return true;return false;}

package/src/operator/node/boardState.ts

@@ -0,0 +1,74 @@
+import { useSyncExternalStore } from 'react';
+import type { BoardFile, BoardView } from '../../board/workspace';
+import { rememberBoardFile, cloneBoardView, reportBoardOwner, activateBoardOwner, selectedBoardOwner } from '../../board/context';
+import { notifyCallback } from '../../core/callbacks';
+const cache=new Map<string,{stamp:string;view:BoardView|null}>();
+const listeners=new Map<string,Set<()=>void>>();
+const owners=new Map<string,Map<string,BoardView>>();
+// Mounted directory identity is transient; it must not become retained browsing history.
+const directorySources=new Map<string,Map<string,string>>();
+const key=(id:string)=>`cli-ui:operator-board:${id}`;
+const stamp=(id:string)=>{try{return sessionStorage.getItem(key(id))??'';}catch{return 'blocked';}};
+const validFile=(value:unknown):value is BoardFile=>!!value&&typeof value==='object'&&typeof (value as BoardFile).path==='string'&&!!(value as BoardFile).path&&((value as BoardFile).sourceId===undefined||typeof (value as BoardFile).sourceId==='string');
+const recent=(items:BoardFile[]=[])=>{
+ return items.filter(validFile).reduce((history,file)=>rememberBoardFile(history,file),[] as BoardFile[]);
+};
+export function readBoardState(taskId:string):BoardView|null {
+ const saved=stamp(taskId),known=cache.get(taskId);if(known?.stamp===saved)return known.view;
+ let view:BoardView|null=null;
+ try{
+  const value=JSON.parse(saved||'null');
+  if(value&&typeof value.tab==='string'&&typeof value.dir==='string'&&Array.isArray(value.files))view={...value,file:typeof value.file==='string'?value.file:null,files:value.files.filter((path:unknown)=>typeof path==='string'),current:validFile(value.current)?{...value.current}:null,opened:recent(value.opened),history:recent(value.history),visible:false};
+ }catch{/* Broken preferences cannot stop the workspace. */}
+ cache.set(taskId,{stamp:saved,view});return view;
+}
+/** Internal: background refresh covers every visible owner, not just the selected board. */
+export function readVisibleBoardSources(taskId:string):string[] {
+ const active=owners.get(taskId);
+ const views=active?.size?[...active]:[['',readBoardState(taskId)] as const];
+ const sources=new Set<string>();
+ for(const [owner,view] of views){
+  if(!view||view.visible===false)continue;
+  for(const file of view.opened??[])sources.add(file.sourceId??taskId);
+  const directory=directorySources.get(taskId)?.get(owner);if(directory)sources.add(directory);
+ }
+ return [...sources];
+}
+export function subscribeBoardState(taskId:string,listener:()=>void):()=>void {
+ const set=listeners.get(taskId)??new Set<()=>void>();set.add(listener);listeners.set(taskId,set);return()=>{set.delete(listener);if(!set.size)listeners.delete(taskId);};
+}
+export function publishBoardState(taskId:string,view:BoardView):void {
+ const next=cloneBoardView({...view,current:view.current??null,opened:recent(view.opened),history:recent(view.history)});
+ if(JSON.stringify(readBoardState(taskId))===JSON.stringify(next))return;
+ try{sessionStorage.setItem(key(taskId),JSON.stringify(next));}catch{/* In-memory state still reaches Chat. */}
+ cache.set(taskId,{stamp:stamp(taskId),view:next});for(const listener of [...listeners.get(taskId)??[]])notifyCallback(listener,undefined);
+}
+export function useBoardState(taskId:string):BoardView|null {
+ return useSyncExternalStore(listener=>subscribeBoardState(taskId,listener),()=>readBoardState(taskId),()=>null);
+}
+export function visitBoardFile(taskId:string,file:BoardFile):void {
+ const current=readBoardState(taskId)??{tab:'files',dir:'',file:null,files:[]};
+ publishBoardState(taskId,{...current,history:recent([...(current.history??[]),file])});
+}
+export function reportBoardState(taskId:string,owner:string,view:BoardView,directorySource?:string):void {
+ const sources=owners.get(taskId)??new Map<string,BoardView>();
+ if(directorySource){const directories=directorySources.get(taskId)??new Map<string,string>();directories.set(owner,directorySource);directorySources.set(taskId,directories);}
+ else{const directories=directorySources.get(taskId);directories?.delete(owner);if(!directories?.size)directorySources.delete(taskId);}
+ const history=readBoardState(taskId)?.history??view.history??[];
+ const selected=reportBoardOwner(sources,owner,{...view,history});owners.set(taskId,sources);
+ if(selected)publishBoardState(taskId,{...selected[1],history});
+}
+export function activateBoardState(taskId:string,owner:string):void {
+ const sources=owners.get(taskId);if(!sources)return;
+ const selected=activateBoardOwner(sources,owner);if(!selected)return;
+ const previous=readBoardState(taskId),file=selected[1].current;
+ const history=file?rememberBoardFile(previous?.history??[],file):previous?.history??[];
+ publishBoardState(taskId,{...selected[1],history});
+}
+export function releaseBoardState(taskId:string,owner:string):void {
+ const sources=owners.get(taskId);sources?.delete(owner);if(!sources?.size)owners.delete(taskId);
+ const directories=directorySources.get(taskId);directories?.delete(owner);if(!directories?.size)directorySources.delete(taskId);
+ const previous=readBoardState(taskId);if(!previous)return;
+ const remaining=sources?.size?selectedBoardOwner(sources)?.[1]:null;
+ publishBoardState(taskId,remaining?{...remaining,history:previous.history,visible:remaining.visible!==false}:{...previous,visible:false});
+}

package/src/operator/node/boardWorkspace.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceRefreshOptions } from '../../board/fileWatch';
+import { createWorkspace } from '../../board/workspace';
+import { cloneBoardView } from '../../board/context';
+import { getOperatorBoardBackend } from './boardBackend';
+import { readBoardState } from './boardState';
+import { openOperatorBoard } from './boardInteraction';
+import { refreshOperatorWorkspaceFiles } from './boardEvents';
+/** Host API for the node workspace. Uses the same cloud-facing file API as the board. */
+export function createOperatorWorkspace(taskId:string){
+ const workspace=createWorkspace({backend:getOperatorBoardBackend(),key:taskId,
+  view:()=>{const view=readBoardState(taskId);return view?.visible?cloneBoardView(view):undefined;},
+  context:()=>{const view=readBoardState(taskId);return view?cloneBoardView(view):null;},
+  open:path=>openOperatorBoard({kind:'file',taskId,path})});
+ return {...workspace,refresh:(options?:WorkspaceRefreshOptions)=>refreshOperatorWorkspaceFiles(taskId,options)};
+}

package/src/operator/node/boundedPoll.ts

@@ -0,0 +1,47 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+/**
+ * Re-check something that settles elsewhere (a browser-side login approval, a
+ * server job) — without an unbounded polling loop:
+ *   · while `active`, call `check` every `intervalMs`, but only for `windowMs`
+ *     after it became active (or after the last wake);
+ *   · when the user comes back — the tab visible again, the window focused,
+ *     back online — check once right away and open a fresh window. That is when
+ *     a login approved in another tab is most likely to have settled.
+ * Nothing runs while the tab is hidden, and nothing at all once `active` is false.
+ */
+export function useBoundedPoll(active: boolean, check: () => void, intervalMs: number, windowMs: number): void {
+  const latest = useRef(check);
+  latest.current = check;
+  useEffect(() => {
+    if (!active) return;
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let deadline = 0;
+    const stop = () => { if (timer) { clearInterval(timer); timer = undefined; } };
+    const start = () => {
+      deadline = Date.now() + windowMs;
+      if (timer) return;
+      timer = setInterval(() => {
+        if (Date.now() > deadline) { stop(); return; }
+        if (document.visibilityState !== "hidden") latest.current();
+      }, intervalMs);
+    };
+    const wake = () => {
+      if (document.visibilityState === "hidden") return;
+      latest.current();
+      start();
+    };
+    start();
+    window.addEventListener("focus", wake);
+    window.addEventListener("online", wake);
+    document.addEventListener("visibilitychange", wake);
+    return () => {
+      stop();
+      window.removeEventListener("focus", wake);
+      window.removeEventListener("online", wake);
+      document.removeEventListener("visibilitychange", wake);
+    };
+  }, [active, intervalMs, windowMs]);
+}

package/src/operator/node/branchFlow.ts

@@ -0,0 +1 @@
+export * from "../branchFlow";

package/src/operator/node/composerDraft.ts

@@ -0,0 +1,78 @@
+import type { UploadPhase } from "../../core/documentUpload";
+import { withoutBoardContext } from "../../board/context";
+import { ORIGINALS_NOTE } from "../../core/blocks";
+import { clientId } from "../../core/id";
+import { splitAttachments } from "./format";
+
+export type Quote = { id: string; author: string; text: string; sourceTaskId?: string };
+export type Attachment = {
+  progress?: number;
+  phase?: UploadPhase; bytes?: number; size?: number;
+  key: string; kind: "image" | "file"; name: string; preview: string; path: string;
+  status: "uploading" | "ready" | "error"; error?: string;
+};
+export type ForkSource = { id: string; title: string };
+export type ComposerDraft = { sources?: ForkSource[]; forkRequest?: { id: string; signature: string; payload?: string }; text: string; attachments: Attachment[]; quote: Quote | null };
+const memory=new Map<string,{stamp:string;draft:ComposerDraft}>();
+const stamp=(id:string)=>{try{return JSON.stringify([localStorage.getItem(key(id)),localStorage.getItem(`orch:draft:${id}`)]);}catch{return "blocked";}};
+const key = (id: string) => `orch:composer:${id}`;
+export const emptyDraft = (): ComposerDraft => ({ text: "", attachments: [], quote: null });
+export function readDraft(id: string): ComposerDraft {
+  const cached=memory.get(id);if(cached?.stamp===stamp(id)) return cached.draft;
+  try {
+    const raw = localStorage.getItem(key(id));
+    if (raw) {
+      const d = JSON.parse(raw) as ComposerDraft;
+      if (typeof d.text === "string" && Array.isArray(d.attachments)) return { ...d, attachments: d.attachments.map((a) => a.status === "uploading" ? { ...a, preview: "", status: "error", error: "上传已中断，请重新选择文件。" } : a) };
+    }
+    return { ...emptyDraft(), text: localStorage.getItem(`orch:draft:${id}`) ?? "" };
+  } catch { return emptyDraft(); }
+}
+export const DRAFT_EVENT = "orch:composer-change";
+const sendingTasks = new Set<string>();
+export const isTaskSending = (id: string) => sendingTasks.has(id);
+export function setTaskSending(id: string, sending: boolean) {
+  if (sending) sendingTasks.add(id); else sendingTasks.delete(id);
+  window.dispatchEvent(new CustomEvent(DRAFT_EVENT, { detail: { id, sending } }));
+}
+export function writeDraft(id: string, draft: ComposerDraft) {
+  try {
+    if (draft.text || draft.attachments.length || draft.quote || draft.sources?.length) localStorage.setItem(key(id), JSON.stringify(draft));
+    else localStorage.removeItem(key(id));
+    localStorage.removeItem(`orch:draft:${id}`);
+  } catch { /* Storage may be unavailable; the in-memory draft remains usable. */ }
+  memory.set(id,{stamp:stamp(id),draft});
+  window.dispatchEvent(new CustomEvent(DRAFT_EVENT, { detail: { id, draft } }));
+}
+/**
+ * 编辑排队消息：撤回成功后放回输入框。文字（含引用）和附件原件在前，输入框里还没发的草稿接在后面——两边都不丢。
+ * 去掉发送时会自动重新附带的部分：「看板正在看」的被动背景、带原件时自动加的那句提示。
+ */
+export function restoreQueuedDraft(taskId: string, content: string): void {
+  const { text, attachments } = splitAttachments(withoutBoardContext(content));
+  const body = text.split("\n").filter((line) => line.trim() !== ORIGINALS_NOTE).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  const current = readDraft(taskId);
+  writeDraft(taskId, {
+    ...current,
+    text: [body, current.text].filter((value) => value.trim()).join("\n\n"),
+    attachments: [
+      ...attachments.map((a): Attachment => ({ key: clientId(), kind: a.kind, name: a.name, path: a.path, preview: a.kind === "image" ? a.url : "", status: "ready" })),
+      ...current.attachments,
+    ],
+  });
+}
+
+export function quoteText(quote: Quote): string {
+  return `引用 ${quote.author}：\n${quote.text.split("\n").map((line) => `> ${line}`).join("\n")}`;
+}
+
+/** Remove only the content acknowledged by the server; preserve edits/quotes added during the request. */
+export function acknowledgeDraft(current: ComposerDraft, sent: ComposerDraft): ComposerDraft {
+  const attachments=new Set(sent.attachments.map(a=>a.key));
+  const sources=new Set(sent.sources?.map(s=>s.id));
+  return {...current,text:current.text===sent.text?"":current.text,
+    attachments:current.attachments.filter(a=>!attachments.has(a.key)),
+    sources:current.sources?.filter(s=>!sources.has(s.id)),
+    quote:JSON.stringify(current.quote)===JSON.stringify(sent.quote)?null:current.quote,
+    forkRequest:undefined};
+}

package/src/operator/node/fileLinks.ts

@@ -0,0 +1,81 @@
+// 把智能体消息里指向本地文件的链接改写成能打开的地址。
+//
+// 智能体给的是它工作目录下的路径：[报告](report.md)、[报告](/Users/…/worktree/report.md)、
+// file:///…、带行号的 src/a.ts:12。原样渲染时浏览器把它当成网站根目录下的地址，
+// 打不开。这里改写到 /api/tasks/<id>/files/…（服务端见 lib/taskFiles.ts），
+// Markdown 则改到 /view 预览页渲染。
+import { createContext } from "react";
+
+/** 当前渲染的 Markdown 属于哪个任务、相对哪个目录（预览页里是 md 文件所在目录）。 */
+export type FileLinkScope = { taskId: string; baseDir?: string } | null;
+export const FileLinkContext = createContext<FileLinkScope>(null);
+
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const WIN_ABS = /^[a-z]:[\\/]/i;
+
+function normalize(p: string): string {
+  const abs = p.startsWith("/");
+  const out: string[] = [];
+  for (const seg of p.split("/")) {
+    if (!seg || seg === ".") continue;
+    if (seg === ".." && out.length && out[out.length - 1] !== "..") out.pop();
+    else if (seg === ".." && abs) continue;
+    else out.push(seg);
+  }
+  return (abs ? "/" : "") + out.join("/");
+}
+
+export function isMarkdownPath(p: string): boolean {
+  return /\.(md|markdown)$/i.test(p);
+}
+
+/** 文件在服务端的地址：相对路径用路径式（HTML 的相对资源能解析），绝对路径走 ?path=。 */
+export function taskFileApiUrl(taskId: string, p: string): string {
+  const id = encodeURIComponent(taskId);
+  if (p.startsWith("/") || p.startsWith("~") || WIN_ABS.test(p)) return `/api/tasks/${id}/files?path=${encodeURIComponent(p)}`;
+  return `/api/tasks/${id}/files/${p.split("/").filter(Boolean).map(encodeURIComponent).join("/")}`;
+}
+
+export function markdownViewUrl(taskId: string, p: string): string {
+  return `/view?task=${encodeURIComponent(taskId)}&path=${encodeURIComponent(p)}`;
+}
+
+/**
+ * 链接指向本地文件时，返回它的路径（相对任务工作目录，或绝对路径）；
+ * 网址、锚点、应用自己的地址等返回 null（保持原样）。
+ */
+export function localFilePath(href: string | undefined | null, baseDir = ""): string | null {
+  let h = String(href ?? "").trim();
+  if (!h || h.startsWith("#") || h.startsWith("//") || h.startsWith("/api/") || h.startsWith("/view?")) return null;
+  if (/^file:/i.test(h)) h = h.replace(/^file:(\/\/localhost)?(\/\/)?/i, "");
+  else if (SCHEME.test(h) && !WIN_ABS.test(h)) return null;
+  // 去掉查询和锚点（#L12 之类），再解码（Markdown 解析器会把中文转成 %XX）。
+  h = h.replace(/[?#].*$/, "");
+  try {
+    h = decodeURI(h);
+  } catch {
+    // 保持原样
+  }
+  h = h.replace(/\\/g, "/");
+  // 编辑器风格的行号：src/a.ts:12 或 :12:5
+  h = h.replace(/:(\d+)(:\d+)?$/, "");
+  if (!h) return null;
+  if (h === "~" || h.startsWith("~/")) return h;
+  if (h.startsWith("/") || WIN_ABS.test(h)) return WIN_ABS.test(h) ? h : normalize(h);
+  return normalize(baseDir ? `${baseDir.replace(/\/+$/, "")}/${h}` : h);
+}
+
+/** 链接改写的最终结果：Markdown → 预览页；其他文件 → 文件接口；不是本地文件 → null。 */
+export function rewriteFileHref(scope: FileLinkScope, href: string | undefined | null): string | null {
+  if (!scope) return null;
+  const p = localFilePath(href, scope.baseDir);
+  if (!p) return null;
+  return isMarkdownPath(p) ? markdownViewUrl(scope.taskId, p) : taskFileApiUrl(scope.taskId, p);
+}
+
+/** 图片等内嵌资源：总是直接取文件。 */
+export function rewriteFileSrc(scope: FileLinkScope, src: string | undefined | null): string | null {
+  if (!scope) return null;
+  const p = localFilePath(src, scope.baseDir);
+  return p ? taskFileApiUrl(scope.taskId, p) : null;
+}

package/src/operator/node/format.ts

@@ -0,0 +1,292 @@
+// Pure formatting + derivation helpers shared across the orchestrator modules.
+import type { AskQuestion, AskAnswers } from "./protocol/types";
+import type { Msg, TaskRow, AgentCapabilities, AgentInfo } from "./types";
+import type { InternalUsageEstimate } from "./types";
+
+// Compact token count: 1234 → "1.2k", 1_200_000 → "1.2M".
+export function fmtTokens(n: number): string {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(n >= 1e4 ? 0 : 1)}k`;
+  return String(n);
+}
+// Human byte size: 1536 → "1.5 KB", 5_242_880 → "5.0 MB". Base-1024.
+export function fmtBytes(n: number): string {
+  if (n <= 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(units.length - 1, Math.floor(Math.log(n) / Math.log(1024)));
+  const v = n / 1024 ** i;
+  return `${i === 0 ? v : v.toFixed(v >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+}
+// Dollar cost: sub-cent shows "<$0.01"; otherwise 2–3 sig digits after the point.
+export function fmtCost(n: number): string {
+  if (n <= 0) return "$0.00";
+  if (n < 0.01) return "<$0.01";
+  return `$${n < 1 ? n.toFixed(3) : n.toFixed(2)}`;
+}
+
+export function fmtJobCost(e: InternalUsageEstimate): string {
+  const cost = e.cost_usd <= 0 ? "$0.00" : e.cost_usd < 0.01 ? "<$0.01" : `$${e.cost_usd.toFixed(2)}`;
+  return `约 ${fmtTokens(e.tokens)} tokens（约 ${cost}）`;
+}
+
+// ---------- the usage chip (tokens + cost, honestly) ----------
+
+// A task's cumulative tokens split by what they actually represent. The raw
+// `total_tokens` sums all four buckets, and in real sessions ~90%+ of it is
+// prompt-cache READS — the same context re-sent on every turn and billed at ~10%
+// of the input rate. Leading with that reads as "this task burned 3.8M tokens"
+// when the model only ever processed ~250k of new material, which is what scares
+// people off. So the chip leads with `fresh` (tokens seen for the first time:
+// in/out plus cache WRITES, which are billed above input rate) and carries cache
+// reads as secondary detail. Defensive ?? 0s: a task row can predate the fields.
+export interface UsageSplit {
+  total: number;      // every bucket summed — what task.total_tokens holds
+  fresh: number;      // in/out + cache writes: material the model processed anew
+  inOut: number;      // prompt + completion tokens, uncached
+  cacheWrite: number; // context written into the cache (billed ~1.25× input)
+  cacheRead: number;  // context re-read from the cache (billed ~0.1× input)
+}
+export function usageSplit(t: Pick<TaskRow, "total_tokens" | "cache_read_tokens" | "cache_creation_tokens">): UsageSplit {
+  const total = t.total_tokens ?? 0;
+  const cacheRead = t.cache_read_tokens ?? 0;
+  const cacheWrite = t.cache_creation_tokens ?? 0;
+  return { total, cacheRead, cacheWrite, inOut: Math.max(0, total - cacheRead - cacheWrite), fresh: Math.max(0, total - cacheRead) };
+}
+
+/**
+ * How to present an agent's dollar figure. Two independent questions:
+ *
+ * - Is the number a MEASUREMENT or an estimate? `costIsEstimated` answers that
+ *   (Codex reports tokens only, so its figure is tokens × published prices).
+ * - Is the number MONEY THE USER SPENDS? Only under api-key auth. On a Max/Pro
+ *   (or ChatGPT) subscription the marginal cost of a turn is $0 — the SDK's
+ *   `total_cost_usd` is what the same tokens would have cost through the API,
+ *   and what's actually consumed is plan quota. Showing a bare "$4.20" there
+ *   reads as a bill for something that was included.
+ *
+ * Either one makes the figure approximate-in-meaning, so both get an `~` plus a
+ * tooltip clause saying which it is. An unknown account (bundle still loading,
+ * agent not connected) keeps the plain billed presentation — we won't claim a
+ * turn was covered by a plan we can't see.
+ */
+export interface CostDisplay {
+  show: boolean;   // render a dollar figure at all
+  approx: boolean; // prefix it with ~
+  note: string;    // tooltip clause explaining what the figure means ("" = a plain billed charge)
+}
+export function costDisplay(agent: AgentInfo | undefined): CostDisplay {
+  const caps = agent?.capabilities;
+  const estimated = caps?.costIsEstimated === true;
+  const show = caps?.reportsCostUsd !== false || estimated;
+  const subscription = agent?.account?.method === "subscription";
+  const bedrock = agent?.account?.method === "bedrock";
+  const plan = agent?.account?.plan;
+  // "Max"/"Pro"/"ChatGPT Plus" → "your Max plan"; unknown/"API" → "your plan".
+  const planName = plan && !/^api$/i.test(plan) ? `你的 ${plan} 订阅` : "你的订阅";
+  const source = estimated ? "按 token 数 × 官方 API 价格估算" : "等同 API 价格的折算值";
+  const note = bedrock
+    ? "由 Claude Code 根据 token 用量与公开价格估算；请以你的 AWS 账单为准"
+    : subscription
+    ? `${source}：本次使用 ${planName} 登录运行，消耗的是套餐额度，并非实际账单`
+    : estimated
+      ? source
+      : "";
+  return { show, approx: subscription || bedrock || estimated, note };
+}
+
+// The usage chip's tooltip: the full breakdown the compact chip can't fit, one
+// fact per line. Exact counts here (the chip rounds) — this is the view someone
+// opens precisely because the rounded number surprised them.
+export function usageTooltip(split: UsageSplit, costUsd: number, cost: CostDisplay): string {
+  const n = (v: number) => v.toLocaleString();
+  const lines = [
+    `本任务新增 ${n(split.fresh)} tokens：输入/输出 ${n(split.inOut)} · 写入缓存 ${n(split.cacheWrite)}`,
+  ];
+  if (split.cacheRead > 0) {
+    lines.push(`缓存读取 ${n(split.cacheRead)}（每轮重复读取的上下文，按输入价格的约 10% 计费）`);
+    lines.push(`合计 ${n(split.total)} tokens`);
+  }
+  if (cost.show && costUsd > 0) {
+    lines.push(`${cost.approx ? "约 " : ""}${fmtCost(costUsd)}${cost.note ? `（${cost.note}）` : "（实际计费）"}`);
+  }
+  return lines.join("\n");
+}
+
+// Context window: the input-side tokens of the latest turn ≈ how full that
+// window currently is. The size comes from the agent's capability descriptor
+// (capabilities.models[].contextWindow) — Codex windows differ from Claude's, so
+// it can't be a static Claude-only table. `caps.models` is looked up by the
+// task's configured model value; unknown/Default falls back to the widest model
+// the agent offers, then a conservative constant.
+export const DEFAULT_CONTEXT_WINDOW = 200_000;
+export function contextWindowOf(model: string | null | undefined, caps?: AgentCapabilities): number {
+  const models = caps?.models ?? [];
+  if (model) {
+    const hit = models.find((m) => m.value === model);
+    if (hit) return hit.contextWindow;
+    const id = model.toLowerCase();
+    if (id.includes("[1m]") || id.includes("claude-sonnet-5") || id.includes("claude-fable-5")) return 1_000_000;
+    return DEFAULT_CONTEXT_WINDOW;
+  }
+  // Default (null) model → the driver picks its own; approximate with the widest
+  // window it offers so the gauge doesn't over-report fullness.
+  const widest = models.reduce((mx, m) => Math.max(mx, m.contextWindow), 0);
+  return widest || DEFAULT_CONTEXT_WINDOW;
+}
+export function contextPct(tokens: number, model: string | null | undefined, caps?: AgentCapabilities): number {
+  return Math.round((tokens / contextWindowOf(model, caps)) * 1000) / 10;
+}
+
+// Friendly name for a resolved model id — the badge that answers "which model
+// did this turn actually run on?". The VERSION is the point: family aliases move
+// (today "opus" resolves to claude-opus-5, last month claude-opus-4-8), so a bare
+// "Opus" badge tells you nothing. Parse family + version out of the id first
+// ("claude-opus-5" -> "Opus 5", "claude-opus-4-8-20251101" -> "Opus 4.8") and
+// keep the `[1m]` marker, since the 1M variant is a distinct run mode.
+// Non-Claude ids (Codex's "gpt-5.1-codex-max") carry no such version shape —
+// those fall through to the agent's capability labels, matched longest-first so
+// a shorter value can't shadow a more specific one. Raw id is the last resort.
+export function modelLabel(id: string | null, caps?: AgentCapabilities): string {
+  if (!id) return "";
+  const s = id.toLowerCase();
+  const long = s.includes("[1m]") ? " (1M)" : "";
+  const fam = ["fable", "opus", "sonnet", "haiku"].find((f) => s.includes(f));
+  if (fam) {
+    const cap = fam[0].toUpperCase() + fam.slice(1);
+    const v = s.match(new RegExp(`${fam}-(\\d+)(?:-(\\d+))?`));
+    // Deliberately NOT the capability label here: an id we can't read a version
+    // out of shouldn't be badged with a version we're only guessing at.
+    return v ? `${cap} ${v[1]}${v[2] ? `.${v[2]}` : ""}${long}` : `${cap}${long}`;
+  }
+  const hit = (caps?.models ?? [])
+    .filter((o) => s.includes(o.value.toLowerCase()))
+    .sort((a, b) => b.value.length - a.value.length)[0];
+  return hit ? hit.label : id;
+}
+
+// Phrase AskUserQuestion answers as a reply, for the reload fallback where the
+// turn is no longer parked and we resume the session with a normal message.
+export function formatAnswersText(questions: AskQuestion[], answers: AskAnswers): string {
+  const lines = questions.map((q, i) => {
+    const picked = (answers[i] ?? []).filter((s) => s && s.trim());
+    return `- ${q.header || q.question}：${picked.length ? picked.join("、") : "（未选择）"}`;
+  });
+  return `回答你的问题：\n${lines.join("\n")}`;
+}
+// Absolute wall-clock stamp for a transcript message ("3:42 PM", locale-aware).
+// Messages from an earlier day prefix the date, so a task resumed days later
+// still reads right. Absolute on purpose: MessageView is memoized, so a
+// relative "2m ago" would freeze at whatever it said when the row rendered.
+export function clockTime(ts: number): string {
+  const d = new Date(ts);
+  const time = d.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+  if (d.toDateString() === new Date().toDateString()) return time;
+  return `${d.toLocaleDateString([], { month: "short", day: "numeric" })}, ${time}`;
+}
+export function relTime(ts: number): string {
+  const d = Date.now() - ts;
+  const m = Math.floor(d / 60000);
+  if (m < 1) return "刚刚";
+  if (m < 60) return `${m} 分钟前`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h} 小时前`;
+  return `${Math.floor(h / 24)} 天前`;
+}
+// How long a task has been waiting on the user, spelled out for the "need you"
+// dropdown ("waiting for 3 hours"). Coarser and more verbose than relTime — this
+// is the only subline a row gets, so it reads as prose rather than a chip.
+export function waitedFor(since: number): string {
+  const s = Math.max(0, Math.round((Date.now() - since) / 1000));
+  if (s < 45) return "几秒";
+  const m = Math.round(s / 60);
+  if (m < 1) return "1 分钟";
+  if (m < 60) return `${m} 分钟`;
+  const h = Math.round(m / 60);
+  if (h < 24) return `${h} 小时`;
+  const d = Math.round(h / 24);
+  return `${d} 天`;
+}
+export function duration(start: number, end: number | null): string {
+  if (!end) return "进行中";
+  const s = Math.max(0, Math.round((end - start) / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
+// A task is "waiting on you" when its awaiting_input flag is set — Claude either
+// ended its turn mid-task or is parked on an AskUserQuestion. The flag is the
+// single source of truth (cleared the instant the next turn starts / a question
+// is answered), so this holds even while the turn is technically still live and
+// parked on the question — that's exactly the case the task list must surface.
+export const isAwaiting = (t: TaskRow) =>
+  t.status === "in_progress" && !!t.awaiting_input;
+
+// The titles of a task's unfinished blockers (dependencies not yet 'done'). A
+// task with any of these is "blocked" and can't be started until they complete.
+// A cancelled dependency doesn't block — it's terminal and will never finish,
+// so waiting on it would deadlock the dependent task forever.
+export const blockerTitles = (t: TaskRow, byId: Map<string, TaskRow>): string[] =>
+  (t.depends_on ?? [])
+    .map((id) => byId.get(id))
+    .filter((b): b is TaskRow => !!b && b.status !== "done" && b.status !== "cancelled")
+    .map((b) => b.title);
+
+// add/del/ctx class for a diff line's sign — shared by the peek and full views.
+export const diffCls = (sign: "+" | "-" | " ") => (sign === "+" ? "add" : sign === "-" ? "del" : "ctx");
+
+// group flat messages into per-generation sessions, pulling out the /clear summaries
+export function buildSessions(messages: Msg[]) {
+  const summaryByGen: Record<number, string> = {};
+  for (const m of messages) if (m.role === "session_break") summaryByGen[m.generation] = m.content;
+  // Queued follow-ups are excluded here — they haven't run yet, so SessionView
+  // renders them in a pinned block below the live "thinking" indicator instead
+  // of interleaved with the committed transcript.
+  const committed = messages.filter((m) => m.role !== "queued");
+  const gens = Array.from(new Set(committed.filter((m) => m.role !== "session_break").map((m) => m.generation))).sort((a, b) => a - b);
+  return gens.map((n) => ({
+    n,
+    summaryBefore: summaryByGen[n - 1] ?? null,
+    messages: committed.filter((m) => m.generation === n && m.role !== "session_break"),
+  }));
+}
+
+// ---------- chat attachments (images + large text pastes) ----------
+// An upload travels inside the message text as one marker line per file:
+// "[Attached image: /abs/path.png]" for images, "[Attached file: /abs/path.txt]"
+// for a big text paste diverted to a file (see PASTE_ATTACH_THRESHOLD). The
+// same string serves both sides — Claude Code opens the absolute path with its
+// Read tool (rendering images natively, reading text files as text), and the
+// transcript strips the marker back out to render an inline thumbnail (image)
+// or a file chip (text). The serving URL is derived from the path's
+// uploads/<task>/<file> tail, so no extra columns or event fields are needed.
+export const attachmentMarker = (absPath: string) => `[Attached image: ${absPath}]`;
+export const fileAttachmentMarker = (absPath: string) => `[Attached file: ${absPath}]`;
+const ATTACHMENT_RE = /^\[Attached (image|file): (.+)\]$/;
+
+export interface MsgAttachment { path: string; url: string; kind: "image" | "file"; name: string }
+
+// Split a user message into displayable text + attachment chips. Marker lines
+// whose path doesn't end in uploads/<task>/<file> (hand-typed lookalikes) stay
+// in the text untouched.
+export function splitAttachments(content: string): { text: string; attachments: MsgAttachment[] } {
+  if (!content.includes("[Attached image: ") && !content.includes("[Attached file: ")) {
+    return { text: content, attachments: [] };
+  }
+  const attachments: MsgAttachment[] = [];
+  const kept: string[] = [];
+  for (const line of content.split("\n")) {
+    const m = ATTACHMENT_RE.exec(line.trim());
+    const parts = m ? m[2].split(/[\\/]/).filter(Boolean) : [];
+    const upload = parts.length >= 3 && parts[parts.length - 3] === "uploads";
+    const managed = parts.length >= 4 && parts[parts.length - 4] === ".workspace" && parts[parts.length - 3] === "attachments";
+    if (m && (upload || managed) && parts.slice(-2).every(part => part !== "." && part !== "..")) {
+      const [taskId, file] = parts.slice(-2);
+      attachments.push({ path: m[2], url: `/api/tasks/${encodeURIComponent(taskId)}/uploads/${encodeURIComponent(file)}`, kind: m[1] === "image" ? "image" : "file", name: file });
+    } else {
+      kept.push(line);
+    }
+  }
+  return { text: kept.join("\n").trim(), attachments };
+}