@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/core/client.ts

@@ -0,0 +1,822 @@
+import type { SubagentTranscript } from "./subagents";
+import { createSseParser } from "./sse";
+import { NEW_TASK, parseConvKey } from "./conversation";
+import type {
+  BoardInfo, BrowserMessage, BrowserStatus, CenterJob, CenterTask, CenterTurn, DiffResult, DirListing, FileInfo, Message,
+  BatchStreamSnapshot, BrowserFramesState, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot, WorkspaceFileBatch,
+} from "./types";
+import { decodeText } from "./textDecode";
+import { createDocumentUploader, extractDocumentReferences, documentRequest, isTaskUploadPath, type UploadDocument, type DocumentUploadOptions, type DocumentReceipt } from "./documentUpload";
+import { syncFile, type FileSyncTransport } from "../board/fileSync";
+import { createFileSyncTransport } from "../board/fileSyncTransport";
+import type { ExecutionConfiguration, ExecutionOptions } from "./execution";
+
+/**
+ * center 服务（cli-task-center）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
+ *
+ * 怎么连：
+ *   · 推荐走同源代理（缺省 baseUrl = "/api/center"）：Vite 代理 / nginx 把 /api/center 转到 center，
+ *     并在代理里注入 `Authorization: Bearer <产品线令牌>`——令牌不进浏览器。
+ *   · 本地联调也可以直接给 token（会以 Bearer 头发出），或用 headers() 自己加头。
+ * center 本身不开 CORS，跨域直连需要代理。
+ */
+export interface CenterClientOptions {
+  /** center 的地址前缀，缺省 "/api/center"（同源代理）。 */
+  baseUrl?: string;
+  /** 产品线令牌；有代理注入时不要给。 */
+  token?: string;
+  /**
+   * 产品线（line key）。以请求头 `X-CLI-Line` 发出，给代理选用哪条产品线的令牌：
+   * 一个代理服务多条产品线时，按这个头注入对应的 Authorization（见文档「连接中枢」）。center 本身不读这个头，
+   * 产品线只由令牌决定。
+   */
+  line?: string;
+  /** 额外请求头（每次请求时取，可放会话令牌等）。 */
+  headers?: () => Record<string, string>;
+  fetch?: typeof fetch;
+  /**
+   * 看板里的文件能不能直接用地址打开（<img src>、<iframe src>、下载链接）。缺省：没给 token / headers / line 时可以
+   * （同源代理注入令牌）；否则浏览器直接请求带不上请求头，看板改为先 fetch 再用 blob 地址显示。
+   */
+  directFileLinks?: boolean;
+  /**
+   * 普通请求（不含实时流、文件下载）多久没有响应就放弃，缺省 30 秒。代理或网络挂住时组件不会一直「读取中」，
+   * 而是报「请求超时」并按各自的规则重试。打开任务浏览器另给 150 秒（节点要先启动浏览器）。
+   */
+  requestTimeoutMs?: number;
+}
+
+/** 实时流超过这么久没有任何数据（center 每 20 秒一次心跳）就当连接已断。 */
+export const STREAM_SILENCE_MS = 45_000;
+/** 读文件：这么久没回响应头（节点卡住、代理挂住）就放弃。 */
+export const FILE_HEADER_TIMEOUT_MS = 30_000;
+/** 读文件：传输中这么久一个字节都没收到就当断了（大文件慢慢传不算，只要还在动）。 */
+export const FILE_STALL_MS = 60_000;
+
+export class CenterError extends Error {
+  constructor(message: string, readonly code: string, readonly status: number, readonly detail?: unknown) {
+    super(message);
+    this.name = "CenterError";
+  }
+}
+
+/** 读改动（git diff）最多等多久：比中枢等节点的 50 秒、节点自己的 40 秒都长。 */
+const DIFF_TIMEOUT_MS = 65_000;
+
+/** center 的错误码翻成看得懂、知道怎么办的中文。 */
+const ERROR_TEXT: Record<string, string> = {
+  conversation_closed: "这个对话已经结束，不能再发消息；需要继续请新建对话",
+  conversation_queue_full: "排队的消息太多了，请等前面的回复后再发",
+  business_id_conflict: "消息编号冲突，请重新发送",
+  not_a_conversation: "这个任务不是对话任务",
+  conversation_not_found: "这个对话不在对应的对话任务里",
+  too_many_conversations: "这个对话任务里开的对话太多了，请新建对话任务",
+  not_found: "对话不存在，或不属于当前产品线",
+  unauthorized: "没有权限访问任务中心（产品线令牌缺失或失效）",
+  conversation_requires_one_task: "对话任务只能有一条首轮消息",
+  conversation_prompt_required: "第一条消息不能为空",
+  not_dispatched: "任务还没派发到执行节点",
+  node_unreachable: "执行节点暂时连不上，稍后会自动重试",
+  node_outdated: "执行节点的 Operator 版本较旧，不支持这个功能，请升级节点",
+  too_many_viewers: "同时观看这个浏览器的人太多，请稍后再试",
+  viewer_not_found: "画面连接已断开，正在重连",
+  viewer_not_ready: "画面连接还没就绪，正在重连",
+  link_expired: "文件链接已失效，请刷新",
+  task_not_found: "这个子任务不在对应的任务里",
+  task_already_finished: "当前子任务已经结束，请刷新状态后继续",
+  task_not_paused: "当前子任务没有暂停，请刷新状态后重试",
+  job_already_paused: "整个任务已暂停，请先恢复整个任务",
+  file_watch_unsupported: "当前服务不支持文件事件",
+  browser_required: "传递浏览器 YAML 手册或操作间隔时，需要同时启用 browser: true",
+  invalid_browser_playbook: "浏览器 YAML 手册校验失败，请检查格式和步骤配置",
+  invalid_browser_pacing: "浏览器操作间隔无效，请检查最小值和最大值",
+  conversation_browser_fields_fixed: "浏览器手册和操作间隔在创建对话时确定，追加消息不能修改",
+};
+
+/**
+ * 组件用到的数据后端。界面只依赖这个接口，不直接依赖 center 的地址和字段：
+ *   · 现在的实现是 center 的对话任务接口（createCenterClient）；
+ *   · 以后把组件放进 Operator 自己的界面时，换一个实现这套接口的 Operator 后端即可，界面不用改。
+ * 带 ? 的是可选能力：后端不提供，界面就按 Operator 在「没有这个能力」时的样子显示（例如提问的回答改走下一条消息）。
+ */
+export interface ConversationBackend {
+  /** 无 key 时读取新对话可用设置；有 key 时读取该对话的已保存设置。 */
+  getExecutionConfig?(key?: string | null): Promise<ExecutionConfiguration>;
+  /** 保存成功才切换界面；服务端用 revision 防止并发覆盖。 */
+  setExecutionConfig?(key: string, changes: ExecutionOptions, expectedRevision: number): Promise<ExecutionConfiguration>;
+  /** Upload original HTML/Markdown without embedding document bytes in a message. */
+  uploadDocument?: UploadDocument;
+  baseUrl: string;
+  getJob(jobId: string): Promise<CenterJob>;
+  /** taskId：只要对话任务里这一个对话的轮次。 */
+  listTurns(jobId: string, query?: { afterSeq?: number; limit?: number; taskId?: string }): Promise<{ job_id: string; turns: CenterTurn[] }>;
+  listTasks(): Promise<{ tasks: CenterTask[] }>;
+  /** 原生子代理的公开运行记录；before 用于读取更早的一页。 */
+  subagent?(jobId: string, remote: string, childId: string, generation: number, before?: string): Promise<SubagentTranscript>;
+  /**
+   * 更早的节点转录（往上翻）：remote 是流里给的节点会话，before 是手里最早那条消息的 id。
+   * 返回这一页（旧的在前）和再往前还剩几条。旧版中枢没有这个接口（实时流也就给的是全量，用不到）。
+   */
+  history?(jobId: string, remote: string, before: string, limit?: number): Promise<{ messages: Message[]; older: number }>;
+  createConversation(firstMessage: string, opts?: NewConversationOptions & { businessId?: string }): Promise<{ id: string; job_id: string; status: string; task_ids?: string[]; turn: CenterTurn }>;
+  /** taskId：发给对话任务里的哪个对话，不给 = 第一个。 */
+  sendMessage(jobId: string, text: string, opts?: { businessId?: string; timeoutSeconds?: number; taskId?: string; expectedExecutionRevision?: number }): Promise<SendResult>;
+  /**
+   * 一次性任务里的对话式子任务接着聊：续派一条 mode=conversation、continue_from 这个子任务的子任务（接在同一个 Agent 会话里）。
+   * 返回新子任务的 id。
+   */
+  continueTask?(jobId: string, taskId: string, text: string, opts?: { title?: string; businessId?: string }): Promise<{ task_id: string }>;
+  /** 暂停 / 继续一次性任务中的单个子任务。继续会重新派发该子任务。 */
+  pauseTask?(taskId: string): Promise<CenterTask>;
+  resumeTask?(taskId: string): Promise<CenterTask>;
+  /** 在对话任务里新开一个对话（同一节点、同一工作区），text 是它的第一条消息。 */
+  openConversation?(jobId: string, text: string, opts?: { title?: string; agent?: string; executionConfig?: ExecutionOptions; browser?: boolean; businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
+  cancelTurn(jobId: string, turnId: string): Promise<CenterTurn>;
+  closeConversation(jobId: string): Promise<{ id: string; status: string }>;
+  /** 只关掉对话任务里的一个对话（别的对话和对话任务照常）。 */
+  closeConversationTask?(jobId: string, taskId: string): Promise<{ job_id: string; task_id: string; status: string; closed: boolean }>;
+  /** taskId：看对话任务里的哪个对话，不给 = 第一个。 */
+  stream(jobId: string, handlers: StreamHandlers, intervalMs?: number, taskId?: string | null): () => void;
+  /**
+   * 把回答直接交给正停在提问上的回合（中枢 POST /api/jobs/:id/answer → 节点 /answer）。
+   * resolved=false 表示没有在等的回合：对话任务改用「下一条消息」发回答（中枢在 Agent 提问时已经结束那一轮）；
+   * 一次性任务的子任务提问时回合开着等，答案直接交过去。
+   */
+  answerAsk?(jobId: string, askId: string, answers: string[][]): Promise<{ resolved: boolean }>;
+  /**
+   * 提交浏览器输入卡片（验证码、账号、密码、选项；中枢 POST /api/jobs/:id/input → 节点 /input），返回错误文案或 null。
+   * 密码只交给节点上的浏览器脚本，不进模型、不进转录、中枢不落库。
+   */
+  submitInput?(jobId: string, inputId: string, values: string[]): Promise<string | null>;
+  /** 浏览器交接后交还给 AI（Operator 的 POST /api/tasks/:id/browser），返回错误文案或 null。center 不提供。 */
+  handback?(jobId: string): Promise<string | null>;
+  /** 右侧看板用到的能力（cli-board）。后端没有时看板显示「不支持」。 */
+  board?: BoardBackend;
+}
+
+/**
+ * 右侧看板（cli-board）：工作区文件、改动、任务浏览器。全部经 center 转发，浏览器不直连节点。
+ * 方法里的 jobId 也可以是对话键（"job_x#task_y"）：看对话任务里那个对话的文件、改动和浏览器。
+ */
+export interface BoardBackend {
+  /** Save an original file to this conversation without sending a message or starting the agent. */
+  uploadFile?(jobId: string, file: File, options: DocumentUploadOptions): Promise<DocumentReceipt>;
+  /** Authorized input directory of this task; browsing it never starts an agent turn. */
+  uploadDirectory?(jobId: string, signal?: AbortSignal): Promise<string | null>;
+  /** Immutable revisions and content-addressed blocks; refreshes reuse validated local blocks. */
+  fileSync?: FileSyncTransport;
+  /** One directory page only. No recursive scan or file body prefetch. */
+  listFiles?(jobId: string, dir: string, options?: { cursor?: string; limit?: number; signal?: AbortSignal }): Promise<DirListing>;
+  pollFiles?(jobId: string, scope: { paths: string[]; dirs: string[]; cursor?: string }, signal?: AbortSignal): Promise<WorkspaceFileBatch & { cursor?: string; directories: Array<{ path: string; revision: string | null }> }>;
+  /** fileUrl 给出的地址浏览器能直接打开（不需要额外请求头）。false 时看板先 fetch 再显示。 */
+  directLinks: boolean;
+  info(jobId: string): Promise<BoardInfo>;
+  /** 精准文件事件流；没有时组件明确降级为目录快照比对。 */
+  watchFiles?(jobId: string, handlers: { onEvent: (event: import("./types").WorkspaceFileBatch) => void; onClose: (error: CenterError | null) => void }): () => void;
+  /** 目录（缺省根目录）或文件的信息。 */
+  stat(jobId: string, path?: string): Promise<DirListing | FileInfo>;
+  /** 文件地址（给 <img> / <iframe> / 下载链接用）。相对路径用路径式地址，HTML 里的相对资源能跟着解析。 */
+  fileUrl(jobId: string, path: string, opts?: { download?: boolean }): string;
+  /**
+   * 浏览器能直接打开的文件地址前缀（…/files/raw，后面接相对路径或 ?path=）：directLinks 时就是 fileUrl 的前缀；
+   * 否则向中枢换一个短期令牌放进路径（<img> / <iframe> / 下载都不需要请求头，大文件流式下载、不进浏览器内存），
+   * 快过期时自动换新的。中枢不支持时返回 null（看板退回先 fetch 再显示）。
+   */
+  fileLinkBase?(jobId: string): Promise<string | null>;
+  /**
+   * 读文本（最多 maxBytes，超过的截断）。只向中枢要这一段（Range），超大文件不整个传过来。
+   * tail = 读末尾那一段（超大日志）；节点不支持只读一段时退回开头（返回的 tail 为 false）。
+   * 不是 UTF-8 的（GBK 导出的 CSV 之类）按 GB18030 解，encoding 说明按什么解的。
+   */
+  readText(jobId: string, path: string, maxBytes?: number, opts?: { tail?: boolean; signal?: AbortSignal; onBytes?: (bytes: number) => void }): Promise<TextChunk>;
+  /**
+   * 读一段原始字节：从 start 开始（缺省 0）最多 maxBytes；tail = 末尾 maxBytes。返回这段在文件里的起点和文件总大小。
+   * 看板用它在文件变长时只取新增的部分（日志、还在写的报告），不整个重读。没有这个方法的后端每次整个重读。
+   */
+  readBytes?(jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; signal?: AbortSignal; onBytes?: (bytes: number) => void }): Promise<ByteChunk>;
+  /**
+   * 读整个文件。signal 取消（打包下载点了取消）；onBytes 报已收到的字节数（大文件显示进度）。
+   * 弱网：FILE_HEADER_TIMEOUT_MS 内没回响应头、或传输中 FILE_STALL_MS 没收到数据，按网络错误（NETWORK）失败。
+   */
+  readBuffer(jobId: string, path: string, opts?: { signal?: AbortSignal; onBytes?: (bytes: number) => void }): Promise<ArrayBuffer>;
+  /** fresh：不与已在途的同一请求共用结果（轮末刷新要的是这一刻之后的改动，不是之前发出的那次）。 */
+  diff(jobId: string, options?: { fresh?: boolean }): Promise<DiffResult>;
+  browserStatus(jobId: string): Promise<BrowserStatus>;
+  browserAction(jobId: string, action: "open" | "close" | "takeover" | "handback"): Promise<BrowserStatus>;
+  /** 浏览器状态实时流；返回停止函数。onClose 在断开时调用（error 为 null 表示正常结束）。 */
+  browserEvents(jobId: string, handlers: { onStatus: (status: BrowserStatus) => void; onClose?: (error: CenterError | null) => void; /** Recoverable transport disruption; subscription remains active. */ onError?: (error: CenterError) => void }): () => void;
+  /** 浏览器实时画面；onViewer 给出发输入要用的 viewer id。 */
+  browserFrames(jobId: string, handlers: { onViewer: (viewer: string) => void; onMessage: (message: BrowserMessage) => void; onEnd?: (end: { reason: string; detail?: string }) => void; onClose?: (error: CenterError | null) => void }): () => void;
+  browserInput(jobId: string, viewer: string, events: Array<Record<string, unknown>>): Promise<void>;
+  /**
+   * 浏览器的一条实时连接（状态 + 画面 + 弹窗 + 复制出的文字，见中枢 board-live.ts）。新版中枢才有：
+   * 旧版中枢回 404（路由不存在，error 为 "Not Found"），组件退回 browserEvents + browserFrames 两条。
+   */
+  browserLive?(jobId: string, handlers: BrowserLiveHandlers): () => void;
+}
+
+/** readBytes 读到的一段。 */
+export interface ByteChunk {
+  bytes: Uint8Array<ArrayBuffer>;
+  /** 这段在文件里从第几个字节开始。 */
+  start: number;
+  /** 文件总大小。 */
+  size: number;
+}
+
+export interface TextChunk {
+  text: string;
+  /** 只读到了一部分。 */
+  truncated: boolean;
+  /** 文件总大小。 */
+  size: number;
+  contentType: string;
+  /** 读的是末尾那一段。 */
+  tail?: boolean;
+  encoding?: string;
+}
+
+export interface BrowserLiveHandlers {
+  /** 这条连接的 viewer id；ready = 输入能送到节点（画面连接已建好）。 */
+  onViewer: (viewer: string, ready: boolean) => void;
+  onStatus: (status: BrowserStatus) => void;
+  onMessage: (message: BrowserMessage) => void;
+  onFrames?: (state: BrowserFramesState) => void;
+  /** 不会再有数据（节点拒绝、中枢停机）。 */
+  onEnd?: (end: { reason: string; status?: number; detail?: string }) => void;
+  onClose?: (error: CenterError | null) => void;
+}
+
+/** 旧版中枢没有这个接口：Fastify 的「路由不存在」404（和「任务不存在」的 not_found 区分开）。 */
+export const isMissingRoute = (error: CenterError | null | undefined) => !!error && error.status === 404 && error.code === "Not Found";
+
+/** 由 fileLinkBase 给的前缀拼出文件地址。 */
+export function fileUrlFromBase(linkBase: string, path: string, download = false) {
+  const clean = path.replace(/^\.\//, "");
+  if (clean.startsWith("/") || clean.startsWith("~") || /^[a-z]:[\\/]/i.test(clean)) return `${linkBase}?path=${encodeURIComponent(clean)}${download ? "&download=1" : ""}`;
+  return `${linkBase}/${clean.split("/").filter(Boolean).map(encodeURIComponent).join("/")}${download ? "?download=1" : ""}`;
+}
+
+export function createCenterClient(options: CenterClientOptions = {}): ConversationBackend {
+  const base = (options.baseUrl ?? "/api/center").replace(/\/+$/, "");
+  const doFetch = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+
+  function headers(extra: Record<string, string> = {}) {
+    const result: Record<string, string> = { ...(options.headers?.() ?? {}), ...extra };
+    if (options.line) result["X-CLI-Line"] = options.line;
+    if (options.token) result.Authorization = `Bearer ${options.token}`;
+    return result;
+  }
+
+  // 同一时刻对同一地址的 GET 只发一次，后来的共用结果：列表、对话、看板经常同时要同一份数据（同一个任务的详情、看板概况、目录），
+  // 浏览器对一个域名的连接有限，重复请求会把真正要紧的（点开文件、发消息）挤到后面排队。
+  const inflight = new Map<string, Promise<unknown>>();
+  // fresh：不搭在途的那次（它可能在数据变化之前发出），自己发一次；之后来的共用这一次。
+  function request<T>(path: string, init: RequestInit = {}, timeoutMs = options.requestTimeoutMs ?? 30_000, fresh = false): Promise<T> {
+    if ((init.method ?? "GET") !== "GET" || init.body) return send<T>(path, init, timeoutMs);
+    const shared = fresh ? undefined : inflight.get(path);
+    if (shared) return shared as Promise<T>;
+    const p: Promise<T> = send<T>(path, init, timeoutMs).finally(() => { if (inflight.get(path) === p) inflight.delete(path); });
+    inflight.set(path, p);
+    return p;
+  }
+  async function send<T>(path: string, init: RequestInit, timeoutMs: number): Promise<T> {
+    let response: Response;
+    const ctl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; ctl.abort(); }, timeoutMs);
+    try {
+      response = await doFetch(`${base}${path}`, {
+        ...init,
+        signal: ctl.signal,
+        headers: headers(init.body ? { "Content-Type": "application/json" } : {}),
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      if (timedOut) throw new CenterError(`任务中心 ${Math.round(timeoutMs / 1000)} 秒没有响应，请稍后重试`, "NETWORK", 0);
+      throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+    }
+    // 响应体也算在时限里（代理把响应头发了、正文却挂住）。
+    let text: string | null = null;
+    let readError: unknown = null;
+    try { text = await response.text(); } catch (error) { readError = error; } finally { clearTimeout(timer); }
+    // 空正文（204、只回状态的接口）照旧当 null；有内容却不是 JSON（代理 / 单点登录的 200 网页）单独报错。
+    let body: Record<string, unknown> | null = null;
+    let unreadable = false;
+    if (text?.trim()) {
+      try { body = JSON.parse(text) as Record<string, unknown> | null; } catch { unreadable = true; }
+    }
+    if (!response.ok) {
+      // 413：消息 / 请求体超过中枢上限（中枢回的是 Fastify 的英文说明）。
+      if (response.status === 413) throw new CenterError("内容太大，超过任务中心单次请求的上限，请删减或分几条发送", "payload_too_large", 413, body);
+      const code = typeof body?.error === "string" ? body.error : `HTTP_${response.status}`;
+      const detail = typeof body?.detail === "string" ? body.detail : undefined;
+      throw new CenterError(ERROR_TEXT[code] ?? detail ?? `任务中心返回错误（HTTP ${response.status}）`, code, response.status, body);
+    }
+    // 成功状态却没读完正文 / 读到的不是数据：明确失败，不能当成「没有内容」让界面一直停在读取中。
+    if (readError) {
+      if (timedOut) throw new CenterError(`任务中心 ${Math.round(timeoutMs / 1000)} 秒没有响应，请稍后重试`, "NETWORK", 0);
+      throw new CenterError(`读取任务中心的响应时连接中断：${readError instanceof Error ? readError.message : String(readError)}`, "NETWORK", 0);
+    }
+    if (unreadable) {
+      throw new CenterError("任务中心返回的不是数据（可能是登录页或代理错误页），请刷新页面或重新登录后重试", "bad_response", response.status);
+    }
+    return body as T;
+  }
+
+  const post = <T>(path: string, body: unknown = {}) => request<T>(path, { method: "POST", body: JSON.stringify(body) });
+  const id = encodeURIComponent;
+  const executionPath = (key?: string | null) => {
+    if (!key) return "/api/execution-config";
+    const ref = parseConvKey(key);
+    return `/api/jobs/${id(ref.jobId)}/execution-config${ref.taskId && ref.taskId !== NEW_TASK ? `?task_id=${id(ref.taskId)}` : ""}`;
+  };
+
+  return {
+    baseUrl: base,
+    getExecutionConfig: key => request<ExecutionConfiguration>(executionPath(key)),
+    setExecutionConfig: (key, changes, expectedRevision) => request<ExecutionConfiguration>(executionPath(key), {
+      method: "PATCH", body: JSON.stringify({ ...changes, expected_revision: expectedRevision }),
+    }),
+    uploadDocument: createDocumentUploader(doFetch, `${base}/api/file-sync`, headers),
+    getJob: (jobId: string) => request<CenterJob>(`/api/jobs/${id(jobId)}`),
+    listTurns: (jobId: string, query: { afterSeq?: number; limit?: number; taskId?: string } = {}) => {
+      const params = new URLSearchParams();
+      if (query.afterSeq !== undefined) params.set("after_seq", String(query.afterSeq));
+      if (query.limit !== undefined) params.set("limit", String(query.limit));
+      if (query.taskId) params.set("task", query.taskId);
+      const qs = params.toString();
+      return request<{ job_id: string; turns: CenterTurn[] }>(`/api/jobs/${id(jobId)}/turns${qs ? `?${qs}` : ""}`);
+    },
+    /** 列表用：本产品线全部子任务（对话任务每个对话一条），用来发现对话。 */
+    listTasks: () => request<{ tasks: CenterTask[] }>("/api/tasks"),
+    async answerAsk(jobId: string, askId: string, answers: string[][]) {
+      try {
+        return await request<{ resolved: boolean }>(boardPath(jobId, "answer"), { method: "POST", body: JSON.stringify({ ask_id: askId, answers }) });
+      } catch (error) {
+        // 旧版中枢没有这个接口：当作没有在等的回合（对话任务照旧走下一条消息）。
+        if (error instanceof CenterError && isMissingRoute(error)) return { resolved: false };
+        throw error;
+      }
+    },
+    async submitInput(jobId: string, inputId: string, values: string[]) {
+      try {
+        await request(boardPath(jobId, "input"), { method: "POST", body: JSON.stringify({ input_id: inputId, values }) });
+        return null;
+      } catch (error) {
+        if (error instanceof CenterError && isMissingRoute(error)) return "当前任务中心版本不支持在这里填写，请升级任务中心";
+        return error instanceof Error ? error.message : String(error);
+      }
+    },
+    subagent: (jobId, remote, childId, generation, before) => request<SubagentTranscript>(`/api/jobs/${id(parseConvKey(jobId).jobId)}/subagents/${id(childId)}?remote=${id(remote)}&generation=${generation}&limit=200${before ? `&before=${id(before)}` : ""}`),
+    history: (jobId: string, remote: string, before: string, limit = 200) =>
+      request<{ messages: Message[]; older: number }>(`/api/jobs/${id(parseConvKey(jobId).jobId)}/history?remote=${id(remote)}&before=${id(before)}&limit=${limit}`),
+    createConversation: (firstMessage: string, opts: NewConversationOptions & { businessId?: string } = {}) => {
+      const title = (opts.title || firstLine(firstMessage)).slice(0, 120);
+      return post<{ id: string; job_id: string; status: string; task_ids?: string[]; turn: CenterTurn }>("/api/jobs", {
+        title,
+        mode: "conversation",
+        ...(opts.workspace ? { workspace: opts.workspace } : {}),
+        ...(opts.callback ? { callback: opts.callback } : {}),
+        tasks: [{
+          title,
+          prompt: extractDocumentReferences(firstMessage).text,
+          ...(extractDocumentReferences(firstMessage).attachments ? { attachments: extractDocumentReferences(firstMessage).attachments } : {}),
+          ...(opts.businessId ? { business_id: opts.businessId } : {}),
+          ...(opts.agent ? { agent: opts.agent } : {}),
+          ...(opts.executionConfig ? { execution_config: opts.executionConfig } : {}),
+          ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+          ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
+          ...(opts.browserPlaybook !== undefined ? { browser_playbook: opts.browserPlaybook } : {}),
+          ...(opts.browserPacing !== undefined ? { browser_pacing: opts.browserPacing } : {}),
+        }],
+      });
+    },
+    /** 带 business_id 时 center 按它去重，网络超时可以放心重发同一条。 */
+    sendMessage: (jobId: string, text: string, opts: { businessId?: string; timeoutSeconds?: number; taskId?: string; expectedExecutionRevision?: number } = {}) =>
+      post<SendResult>(`/api/jobs/${id(jobId)}/messages`, {
+        ...extractDocumentReferences(text),
+        ...(opts.taskId ? { task_id: opts.taskId } : {}),
+        ...(opts.expectedExecutionRevision !== undefined ? { expected_execution_revision: opts.expectedExecutionRevision } : {}),
+        ...(opts.businessId ? { business_id: opts.businessId } : {}),
+        ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+      }),
+    continueTask: async (jobId: string, taskId: string, text: string, opts: { title?: string; businessId?: string } = {}) => {
+      const result = await post<{ task_ids: string[] }>(`/api/jobs`, {
+        job_id: jobId, mode: "conversation",
+        tasks: [{ title: opts.title || firstLine(text, 60), prompt: extractDocumentReferences(text).text, ...(extractDocumentReferences(text).attachments ? { attachments: extractDocumentReferences(text).attachments } : {}), continue_from: taskId, ...(opts.businessId ? { business_id: opts.businessId } : {}) }],
+      });
+      return { task_id: result.task_ids[0] };
+    },
+    pauseTask: (taskId: string) => post<CenterTask>(`/api/tasks/${id(taskId)}/pause`, {}),
+    resumeTask: (taskId: string) => post<CenterTask>(`/api/tasks/${id(taskId)}/resume`, {}),
+    /** 同一个 business_id 重发只开一个对话。 */
+    openConversation: (jobId: string, text: string, opts: { title?: string; agent?: string; executionConfig?: ExecutionOptions; browser?: boolean; businessId?: string; timeoutSeconds?: number } = {}) =>
+      post<SendResult>(`/api/jobs/${id(jobId)}/conversations`, {
+        ...extractDocumentReferences(text),
+        ...(opts.title ? { title: opts.title } : {}),
+        ...(opts.agent ? { agent: opts.agent } : {}),
+        ...(opts.executionConfig ? { execution_config: opts.executionConfig } : {}),
+        ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
+        ...(opts.businessId ? { business_id: opts.businessId } : {}),
+        ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+      }),
+    /** 取消一轮：排队中的直接撤回；正在执行的会中止节点上的回合。 */
+    cancelTurn: (jobId: string, turnId: string) => post<CenterTurn>(`/api/jobs/${id(jobId)}/turns/${id(turnId)}/cancel`),
+    closeConversation: (jobId: string) => post<{ id: string; status: string }>(`/api/jobs/${id(jobId)}/close`),
+    closeConversationTask: (jobId: string, taskId: string) =>
+      post<{ job_id: string; task_id: string; status: string; closed: boolean }>(`/api/jobs/${id(jobId)}/conversations/${id(taskId)}/close`),
+    /**
+     * 订阅对话的实时流（GET /api/jobs/:id/stream）。返回关闭函数。
+     * 不自动重连：重连策略（退避、结束后不再连）由调用方决定。
+     */
+    board: createBoardClient(base, headers, doFetch, request, options.directFileLinks ?? (!options.token && !options.headers && !options.line),
+      // 改动：节点限时 40 秒、中枢等 50 秒；这里等得更久，让它们的答复（超时也有明确原因）先到。
+      Math.max(options.requestTimeoutMs ?? 30_000, DIFF_TIMEOUT_MS)),
+    stream(jobId: string, handlers: StreamHandlers, intervalMs = 300, taskId?: string | null): () => void {
+      const ctl = new AbortController();
+      let stopped = false;
+      // 心跳看门狗：center 每 20 秒发一次 `: ping`。代理 / 负载均衡在上游断掉时可能把连接挂着不关，
+      // 这时一直收不到数据却也不报错——超过 STREAM_SILENCE_MS 没有任何字节就当断线，交给调用方重连。
+      let lastByte = Date.now();
+      let silent = false;
+      let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+      const silenceError = () => new CenterError("实时连接长时间没有数据，正在重连", "NETWORK", 0);
+      // 中止请求之外还要直接取消读取：有的环境里中止信号不会让挂着的 read() 结束。
+      const cut = () => { ctl.abort(); reader?.cancel().catch(() => undefined); };
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastByte > STREAM_SILENCE_MS) { silent = true; cut(); }
+      }, 5_000);
+      void (async () => {
+        try {
+          const response = await doFetch(`${base}/api/jobs/${id(jobId)}/stream?interval_ms=${intervalMs}${taskId ? `&task=${id(taskId)}` : ""}`, {
+            headers: headers({ Accept: "text/event-stream" }),
+            signal: ctl.signal,
+          });
+          if (!response.ok || !response.body) {
+            const body = (await response.json().catch(() => null)) as { error?: string } | null;
+            const code = body?.error ?? `HTTP_${response.status}`;
+            throw new CenterError(ERROR_TEXT[code] ?? `实时流连接失败（HTTP ${response.status}）`, code, response.status);
+          }
+          handlers.onOpen?.();
+          const parser = createSseParser(({ event, data }) => {
+            let payload: unknown;
+            try { payload = JSON.parse(data); } catch { return; }
+            if (event === "snapshot") handlers.onSnapshot?.(payload as StreamSnapshot | BatchStreamSnapshot);
+            else if (event === "chunk") handlers.onChunk?.((payload as { events?: StreamItem[] }).events ?? []);
+            else if (event === "end") handlers.onEnd?.(payload as StreamEnd);
+          });
+          reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            lastByte = Date.now();
+            parser.push(decoder.decode(value, { stream: true }));
+          }
+          parser.end();
+          if (stopped) return;
+          if (silent) return handlers.onClose?.(silenceError());
+          if (!ctl.signal.aborted) handlers.onClose?.(null);
+        } catch (error) {
+          if (stopped) return;
+          if (silent) return handlers.onClose?.(silenceError());
+          if (ctl.signal.aborted) return;
+          handlers.onClose?.(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+        } finally {
+          clearInterval(watchdog);
+        }
+      })();
+      return () => { stopped = true; clearInterval(watchdog); cut(); };
+    },
+  };
+}
+
+export interface StreamHandlers {
+  onOpen?: () => void;
+  /** 对话任务是 StreamSnapshot；一次性任务（含续派）是 BatchStreamSnapshot（见 isBatchSnapshot）。 */
+  onSnapshot?: (snapshot: StreamSnapshot | BatchStreamSnapshot) => void;
+  onChunk?: (events: StreamItem[]) => void;
+  onEnd?: (end: StreamEnd) => void;
+  /** 流断了（error 为 null = 服务端正常关闭）。onEnd 之后也会触发一次。 */
+  onClose?: (error: CenterError | null) => void;
+}
+
+/** 兼容旧名字。 */
+export type CenterClient = ConversationBackend;
+
+export function firstLine(text: string, max = 40) {
+  const line = text.split("\n").map((value) => value.trim()).find(Boolean) ?? "新对话";
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+
+/** 读一条 SSE（fetch 读流，能带鉴权头），按事件名回调。返回停止函数。 */
+function openSse(
+  doFetch: typeof fetch,
+  url: string,
+  headers: Record<string, string>,
+  onEvent: (event: string, data: unknown) => void,
+  onClose?: (error: CenterError | null) => void,
+): () => void {
+  const ctl = new AbortController();
+  // 静默看门狗：center 每 20 秒发一次心跳，超过 STREAM_SILENCE_MS 什么都没收到（网络静默断开、代理挂住）就当断线。
+  let silent = false;
+  let watchdog: ReturnType<typeof setTimeout> | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  const arm = () => {
+    if (watchdog) clearTimeout(watchdog);
+    // 同时取消读取：宿主自定义的 fetch 不一定理会 signal。
+    watchdog = setTimeout(() => { silent = true; ctl.abort(); void reader?.cancel().catch(() => undefined); }, STREAM_SILENCE_MS);
+  };
+  void (async () => {
+    try {
+      arm();
+      const response = await doFetch(url, { headers: { ...headers, Accept: "text/event-stream" }, signal: ctl.signal });
+      // A host-supplied fetch may resolve after cancellation despite signal.
+      // Retire its body before acquiring a reader or restarting the watchdog.
+      if (ctl.signal.aborted) {
+        void response.body?.cancel().catch(() => undefined);
+        if (silent) onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0));
+        return;
+      }
+      if (!response.ok || !response.body) {
+        const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
+        throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? `连接失败（HTTP ${response.status}）`, body?.error ?? `HTTP_${response.status}`, response.status);
+      }
+      const parser = createSseParser(({ event, data }) => {
+        try { onEvent(event, JSON.parse(data)); } catch { /* 不是 JSON 的忽略 */ }
+      });
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        arm();
+        parser.push(decoder.decode(value, { stream: true }));
+      }
+      parser.end();
+      if (watchdog) clearTimeout(watchdog);
+      if (silent) { onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0)); return; }
+      if (!ctl.signal.aborted) onClose?.(null);
+    } catch (error) {
+      if (watchdog) clearTimeout(watchdog);
+      if (silent) { onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0)); return; }
+      if (ctl.signal.aborted) return;
+      onClose?.(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+    }
+  })();
+  return () => { if (watchdog) clearTimeout(watchdog); ctl.abort(); void reader?.cancel().catch(() => undefined); };
+}
+
+/** 看板请求的对象：对话键 → 对话任务 + 子任务（「新开」的占位不算，看对话任务缺省的那个）。 */
+function boardTarget(key: string) {
+  const { jobId, taskId } = parseConvKey(key);
+  return { job: encodeURIComponent(jobId), task: taskId && taskId !== NEW_TASK ? encodeURIComponent(taskId) : null };
+}
+
+/**
+ * 相对路径 → 路径式地址（各段编码）；绝对路径 / ~ 开头 → ?path=。jobId 可以是对话键：
+ * 指定了子任务时路径式地址带上它（/tasks/<子任务>/files/raw/…），HTML 里的相对资源也落在同一个对话上。
+ */
+export function boardFileUrl(base: string, jobId: string, path: string, download = false) {
+  const { job: id, task } = boardTarget(jobId);
+  const clean = path.replace(/^\.\//, "");
+  const absolute = clean.startsWith("/") || clean.startsWith("~") || /^[a-z]:[\\/]/i.test(clean);
+  if (absolute) return `${base}/api/jobs/${id}/files/raw?path=${encodeURIComponent(clean)}${task ? `&task=${task}` : ""}${download ? "&download=1" : ""}`;
+  const segs = clean.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+  return `${base}/api/jobs/${id}${task ? `/tasks/${task}` : ""}/files/raw/${segs}${download ? "?download=1" : ""}`;
+}
+
+/** 看板接口地址：/api/jobs/<job>/<rest>，指定了子任务时加 task 参数。 */
+function boardPath(key: string, rest: string, query = "") {
+  const { job, task } = boardTarget(key);
+  const params = [query, task ? `task=${task}` : ""].filter(Boolean).join("&");
+  return `/api/jobs/${job}/${rest}${params ? `?${params}` : ""}`;
+}
+
+function createBoardClient(
+  base: string,
+  headers: (extra?: Record<string, string>) => Record<string, string>,
+  doFetch: typeof fetch,
+  request: <T>(path: string, init?: RequestInit, timeoutMs?: number, fresh?: boolean) => Promise<T>,
+  directLinks: boolean,
+  diffTimeoutMs = DIFF_TIMEOUT_MS,
+): BoardBackend {
+  /**
+   * 取文件：响应头限时 FILE_HEADER_TIMEOUT_MS；body() 边读边看门（FILE_STALL_MS 没数据就断），
+   * limit 读够就停（大文件只要开头）。外面给的 signal 取消时一并中止。
+   */
+  const fileFetch = async (jobId: string, path: string, extra: Record<string, string> = {}, signal?: AbortSignal) => {
+    const name = path.split("/").pop() || path;
+    const aborted = () => new DOMException("已取消", "AbortError");
+    if (signal?.aborted) throw aborted();
+    const ctl = new AbortController();
+    const cancel = () => ctl.abort();
+    signal?.addEventListener("abort", cancel, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; ctl.abort(); }, FILE_HEADER_TIMEOUT_MS);
+    const release = () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); };
+    let response: Response;
+    try {
+      // 和中止赛跑：宿主自定义的 fetch 不一定理会 signal，取消 / 超时也要马上生效。
+      const stopped = new Promise<never>((_r, reject) => {
+        if (ctl.signal.aborted) reject(new DOMException("aborted", "AbortError"));
+        ctl.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")), { once: true });
+      });
+      const fetching = doFetch(boardFileUrl(base, jobId, path), { headers: headers(extra), signal: ctl.signal, cache: "no-store" });
+      // Host fetch adapters can ignore abort. Dispose a response that arrives
+      // after the caller already cancelled or timed out.
+      void fetching.then(late => { if (ctl.signal.aborted) void late.body?.cancel().catch(() => undefined); }, () => undefined);
+      response = await Promise.race([fetching, stopped]);
+    } catch (error) {
+      release();
+      if (signal?.aborted) throw aborted();
+      if (timedOut) throw new CenterError(`读取「${name}」${FILE_HEADER_TIMEOUT_MS / 1000} 秒没有响应（执行节点忙或网络慢），请稍后重试`, "NETWORK", 0);
+      throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+    }
+    clearTimeout(timer);
+    const stallError = () => new CenterError(`读取「${name}」时 ${FILE_STALL_MS / 1000} 秒没有收到数据，传输已中断，请重试`, "NETWORK", 0);
+    /** 读响应体：limit 读够就停；onBytes 报进度；FILE_STALL_MS 没数据当断线。 */
+    const body = async (opts: { limit?: number; onBytes?: (bytes: number) => void } = {}): Promise<Uint8Array<ArrayBuffer>> => {
+      if (signal?.aborted) { release(); void response.body?.cancel().catch(() => undefined); throw aborted(); }
+      // 空文件要「前 N 字节」：节点回 416，就是空的。
+      if (response.status === 416) { release(); return new Uint8Array(0); }
+      const reader = response.body?.getReader();
+      if (!reader) {
+        try { return new Uint8Array(await response.arrayBuffer()); } finally { release(); }
+      }
+      const cancelBody = () => { void reader.cancel().catch(() => undefined); };
+      ctl.signal.addEventListener("abort", cancelBody, { once: true });
+      if (ctl.signal.aborted) cancelBody();
+      const chunks: Uint8Array[] = [];
+      let got = 0;
+      let stalled = false;
+      let stall: ReturnType<typeof setTimeout> | undefined;
+      const arm = () => {
+        clearTimeout(stall);
+        stall = setTimeout(() => { stalled = true; ctl.abort(); void reader.cancel().catch(() => undefined); }, FILE_STALL_MS);
+      };
+      try {
+        arm();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (stalled) throw stallError();
+          if (done) break;
+          arm();
+          chunks.push(value);
+          got += value.length;
+          opts.onBytes?.(got);
+          if (opts.limit !== undefined && got >= opts.limit) { await reader.cancel().catch(() => undefined); break; }
+        }
+      } catch (error) {
+        if (signal?.aborted) throw aborted();
+        if (stalled) throw stallError();
+        if (error instanceof CenterError) throw error;
+        throw new CenterError(`读取「${name}」中断：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+      } finally {
+        clearTimeout(stall);
+        ctl.signal.removeEventListener("abort", cancelBody);
+        // Progress callbacks may throw too; no abandoned response should keep
+        // consuming the mobile connection after the read has failed.
+        void reader.cancel().catch(() => undefined);
+        try { reader.releaseLock(); } catch { /* already released */ }
+        release();
+      }
+      if (signal?.aborted) throw aborted();
+      const size = opts.limit !== undefined ? Math.min(got, opts.limit) : got;
+      const all = new Uint8Array(size);
+      let offset = 0;
+      for (const chunk of chunks) {
+        const take = Math.min(chunk.length, size - offset);
+        all.set(chunk.subarray(0, take), offset);
+        offset += take;
+        if (offset >= size) break;
+      }
+      return all;
+    };
+    if (!response.ok && response.status !== 416) {
+      // Error bodies need the same abort/stall bounds as file data. A proxy
+      // returning 401 headers and then hanging must not park a read forever.
+      const bytes = await body({ limit: 8192 });
+      let problem: { error?: string; detail?: string } | null = null;
+      try { problem = JSON.parse(new TextDecoder().decode(bytes)); } catch { /* use the HTTP fallback */ }
+      const fallback = response.status === 404 ? "文件不存在（可能已被任务删除或改名）" : problem?.error ?? `读取失败（HTTP ${response.status})`;
+      throw new CenterError(problem?.detail ?? ERROR_TEXT[problem?.error ?? ""] ?? fallback, problem?.error ?? `HTTP_${response.status}`, response.status);
+    }
+    return { response, body };
+  };
+  /**
+   * 读一段：开头 / 从 start 起 maxBytes，或者末尾 maxBytes（超大日志）。只向中枢要这一段（Range）；
+   * 不支持 Range 的节点回整个文件（200），这里边读边截，大文件不整个拉进浏览器。
+   */
+  const readRange = async (jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; signal?: AbortSignal; onBytes?: (bytes: number) => void }) => {
+    const from = Math.max(0, opts.start ?? 0);
+    const { maxBytes } = opts;
+    const { response, body } = await fileFetch(jobId, path, { Range: opts.tail ? `bytes=-${maxBytes}` : `bytes=${from}-${from + maxBytes - 1}` }, opts.signal);
+    const contentType = response.headers.get("content-type") ?? "text/plain";
+    const total = /\/(\d+)\s*$/.exec(response.headers.get("content-range") ?? "")?.[1];
+    // 416：要的起点不在文件里（空文件，或文件变短了）。
+    if (response.status === 416) { await body(); return { bytes: new Uint8Array(0), start: from, size: total ? Number(total) : 0, contentType }; }
+    const length = Number(response.headers.get("content-length") ?? 0);
+    if (response.status === 206) {
+      // 节点给的一段可能比要的长（不严格按 Range）：也只留 maxBytes。
+      const bytes = await body({ limit: maxBytes, onBytes: opts.onBytes });
+      const start = Number(/bytes (\d+)-/.exec(response.headers.get("content-range") ?? "")?.[1] ?? 0);
+      return { bytes, start, size: total ? Number(total) : start + bytes.length, contentType };
+    }
+    // 回了整个文件：跳过 from 之前的，留 maxBytes。
+    const all = await body({ limit: from + maxBytes, onBytes: opts.onBytes });
+    const size = length || all.length;
+    return { bytes: all.slice(Math.min(from, all.length)), start: Math.min(from, all.length), size, contentType };
+  };
+  // 文件链接令牌：按对话键缓存，离过期不到 5 分钟就换新的；同一时刻只换一次。
+  const links = new Map<string, { base: string; until: number }>();
+  const minting = new Map<string, Promise<string | null>>();
+  let linksUnsupported = false;
+  const LINK_REFRESH_MS = 5 * 60_000;
+  const uploads = new Map<string, UploadDocument>();
+  const fileSync = createFileSyncTransport(doFetch, (jobId, operation) => `${base}${boardPath(jobId, `file-sync/${operation}`)}`, headers);
+  return {
+    directLinks,
+    uploadFile(jobId, file, options) {
+      let upload = uploads.get(jobId);
+      if (!upload) {
+        const { job, task } = boardTarget(jobId);
+        upload = createDocumentUploader(doFetch, `${base}/api/jobs/${job}${task ? `/tasks/${task}` : ""}/file-sync`, headers);
+        uploads.set(jobId, upload);
+      }
+      return upload(file, options);
+    },
+    async uploadDirectory(jobId, signal) {
+      const capabilities = await documentRequest<{ uploadsPath?: string }>(doFetch, `${base}${boardPath(jobId, "file-sync/capabilities")}`, { signal }, headers);
+      return typeof capabilities.uploadsPath === "string" ? capabilities.uploadsPath : null;
+    },
+    fileSync,
+    listFiles: (jobId, dir, options = {}) => documentRequest<DirListing>(doFetch, `${base}${boardPath(jobId, "file-sync/list", new URLSearchParams({ dir: dir || ".", limit: String(options.limit ?? 200), ...(options.cursor ? { cursor: options.cursor } : {}) }).toString())}`, { signal: options.signal }, headers),
+    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
+    pollFiles: (jobId, scope, signal) => documentRequest(doFetch, `${base}${boardPath(jobId, "file-sync/changes")}`, { method: "POST", signal, headers: { "Content-Type": "application/json" }, body: JSON.stringify(scope) }, headers),
+    stat: (jobId, path = ".") => documentRequest<DirListing | FileInfo>(doFetch, `${base}${boardPath(jobId, "file-sync/stat", `path=${encodeURIComponent(path)}`)}`, {}, headers),
+    fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
+    async fileLinkBase(jobId) {
+      const { job, task } = boardTarget(jobId);
+      if (directLinks) return `${base}/api/jobs/${job}${task ? `/tasks/${task}` : ""}/files/raw`;
+      if (linksUnsupported) return null;
+      const cached = links.get(jobId);
+      if (cached && cached.until - Date.now() > LINK_REFRESH_MS) return cached.base;
+      const running = minting.get(jobId);
+      if (running) return running;
+      const work = request<{ base?: unknown; expires_at?: string }>(boardPath(jobId, "files/token"), { method: "POST", body: "{}" }).then((r) => {
+        if (typeof r?.base !== "string") { linksUnsupported = true; return null; }
+        const linkBase = `${base}${r.base}`;
+        links.set(jobId, { base: linkBase, until: Date.parse(r.expires_at ?? "") || Date.now() + 30 * 60_000 });
+        return linkBase;
+      }, (error: unknown) => {
+        if (error instanceof CenterError && isMissingRoute(error)) { linksUnsupported = true; return null; }
+        throw error;
+      }).finally(() => minting.delete(jobId));
+      minting.set(jobId, work);
+      return work;
+    },
+    async readText(jobId, path, maxBytes = 512 * 1024, opts = {}) {
+      const { bytes, start, size, contentType } = await readRange(jobId, path, { maxBytes, tail: opts.tail, signal: opts.signal, onBytes: opts.onBytes });
+      if (!size && !bytes.length) return { text: "", truncated: false, size: 0, contentType };
+      const { text, encoding } = decodeText(bytes, { fromMiddle: start > 0 });
+      return { text, truncated: bytes.length < size, size, contentType, tail: start > 0, encoding };
+    },
+    async readBytes(jobId, path, opts) {
+      const { bytes, start, size } = await readRange(jobId, path, opts);
+      return { bytes, start, size };
+    },
+    async readBuffer(jobId, path, opts = {}) {
+      if (isTaskUploadPath(path)) {
+        const file = await syncFile(fileSync, jobId, path, { signal: opts.signal, decode: false,
+          onProgress: progress => opts.onBytes?.(progress.loadedBytes) });
+        return file.bytes.buffer as ArrayBuffer;
+      }
+      const { body } = await fileFetch(jobId, path, {}, opts.signal);
+      return (await body({ onBytes: opts.onBytes })).buffer;
+    },
+    diff: (jobId, options) => request<DiffResult>(boardPath(jobId, "diff"), {}, diffTimeoutMs, options?.fresh),
+    browserStatus: (jobId) => request<BrowserStatus>(boardPath(jobId, "browser")),
+    browserAction: (jobId, action) => request<BrowserStatus>(boardPath(jobId, "browser"), { method: "POST", body: JSON.stringify({ action }) }, 150_000),
+    browserEvents: (jobId, handlers) => openSse(doFetch, `${base}${boardPath(jobId, "browser/events")}`, headers(), (event, data) => {
+      if (event === "status") handlers.onStatus(data as BrowserStatus);
+    }, handlers.onClose),
+    browserFrames: (jobId, handlers) => openSse(doFetch, `${base}${boardPath(jobId, "browser/frames")}`, headers(), (event, data) => {
+      if (event === "viewer") handlers.onViewer((data as { viewer: string }).viewer);
+      else if (event === "message") handlers.onMessage(data as BrowserMessage);
+      else if (event === "end") handlers.onEnd?.(data as { reason: string; detail?: string });
+    }, handlers.onClose),
+    async browserInput(jobId, viewer, events) {
+      await request(boardPath(jobId, "browser/input"), { method: "POST", body: JSON.stringify({ viewer, events }) });
+    },
+    browserLive: (jobId, h) => openSse(doFetch, `${base}${boardPath(jobId, "browser/live")}`, headers(), (event, data) => {
+      const d = data as Record<string, unknown>;
+      if (event === "viewer") h.onViewer(String(d.viewer), d.ready === true);
+      else if (event === "status") h.onStatus(data as BrowserStatus);
+      else if (event === "message") h.onMessage(data as BrowserMessage);
+      else if (event === "frames") h.onFrames?.(data as BrowserFramesState);
+      else if (event === "end") h.onEnd?.(data as { reason: string; status?: number; detail?: string });
+    }, h.onClose),
+  };
+}