@stelfield/cli 0.0.0-stage → 0.12.1

package/src/api.js

@@ -0,0 +1,1088 @@
+// 平台数据读写：带登录凭证调 Linger REST API。
+//
+// M4 全量：
+//   GET  /api/v1/tasks/hall        getHall
+//   POST /api/v1/tasks             createTask
+//   POST /api/v1/tasks/{id}/applications   applyTask
+//   POST /api/v1/tasks/{id}/select         selectApplication
+//   POST /api/v1/runtime/act       runtimeAct     (所有执行/结算动作)
+//   GET  /api/v1/capabilities      （略·当前 CLI 不需要）
+//   POST /api/v1/capabilities      createCapability
+//   POST /api/v1/capabilities/{id}/publish  publishCapability
+//   POST /api/v1/tasks/{id}/comments        postComment
+//   GET  /api/v1/tasks/{id}/comments        getComments
+//   GET  /api/v1/agent/cruise      getCruise      (autonomy tick / ping 复用)
+//
+// 设计原则（薄包装铁律）：
+//   - 只做「参数 → HTTP → 返回 JSON」，不含业务逻辑
+//   - fetchImpl 可注入，便于单测用假响应；默认用全局 fetch（Node 18+ 自带）
+//   - 所有 POST 必须由调用方传入 idempotencyKey（backend middleware 缺则 400）
+//   - 4xx/5xx → 抛含平台错误文案的 Error，401 时提示重新登录
+//
+// v0.4.4 M2 自动续期（authedGetWithRefresh / authedPostWithRefresh）：
+//   - 命中 401 → 用 refresh_token 走 POST /oauth/token 换新 token（RFC 6749 §6）
+//   - 模块级 in-flight Promise 去重：同一凭证目录的并发 401 只发一次 refresh
+//   - 新 token 拿到后立即覆写本地凭证文件（防旧 refresh 被后端 revoke）
+//   - refresh 本身也 401/失败 → 抛「登录状态已失效，请通知用户人工处理」提示（M1 v0.10.0 修，
+//     不静默卡死；BR-2.3：绝不诱导 agent 自己跑 login——无人值守 agent 若照做，等于每次掉线
+//     重连都在自杀重生，见下方 doRefreshToken 内详细说明）
+
+import { BRAND } from "./brand.js";
+import { randomUUID } from 'node:crypto';
+import { loadCredentials, saveCredentials } from './credentials.js';
+import { clientHeaders, noteServerVersion, UPGRADE_COMMAND } from './client-version.js';
+
+// ============================================================
+// v0.17.0 M2-B：结构化 HTTP 错误
+// ============================================================
+// 协作端点的错误体是「平铺」的（{error, message, original?, reason?}，后端把 detail 展平），
+// 老端点是 {detail:{message}}。两种都能取到 message。
+// 抛出的 Error 额外带 status / body（解析后的 JSON，解析不了为 null），
+// 让 index.js 能识别 409 already_answered / public_qa_closed，而不用去匹配文案。
+
+function parseJsonSafe(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+function errMessageOf(text) {
+  const b = parseJsonSafe(text);
+  if (!b || typeof b !== 'object') return null;
+  return b?.detail?.message || b?.message || null;
+}
+
+/**
+ * 构造一个 HTTP 错误对象，携带让 index.js 能做精确映射的信息。
+ *
+ * status / body 之外还带上响应头（v0.18.0 M3）：429 的 Retry-After 头是
+ * 唯一能算出「请 N 分钟后再试」的依据（头的精度高于 body 里的秒数字段）。
+ *
+ * @param {number} status
+ * @param {string} msg
+ * @param {string} text 原始响应体
+ * @param {Headers|null} [headers] 响应头（fetch Response.headers）
+ */
+const FIELD_NAMES = {
+  prompt: '题干', label: '选项标签', description: '选项说明', body: '说明正文',
+  custom_text: '自定义答案', extra_note: '补充一句',
+};
+
+function httpError(status, msg, text, headers = null) {
+  const parsedBody = parseJsonSafe(text);
+  // Collab 422s carry {field, limit}; surface them so the caller knows WHICH input is wrong.
+  if (parsedBody && typeof parsedBody === 'object' && parsedBody.field && /^field_/.test(String(parsedBody.error || ''))) {
+    const fname = FIELD_NAMES[parsedBody.field] || parsedBody.field;
+    msg = `${msg}（出问题的是「${fname}」${parsedBody.limit ? `，上限 ${parsedBody.limit} 字` : ''}）`;
+  }
+  // v0.18.5: platform says this CLI is below the minimum allowed version -> tell the agent exactly what to do.
+  if (status === 426 && parsedBody && parsedBody.error === 'cli_upgrade_required') {
+    const cmd = parsedBody.command || UPGRADE_COMMAND;
+    const up = new Error(`${BRAND.name} CLI 版本过旧（当前 ${parsedBody.current_version || '旧版'}，最低要求 ${parsedBody.min_version}）。`
+      + `请先升级再重试：${cmd}`);
+    up.status = 426;
+    up.body = parsedBody;
+    up.upgradeRequired = true;
+    up.retryAfter = null;
+    return up;
+  }
+  const e = new Error(`请求失败（${status}）：${msg}`);
+  e.status = status;
+  e.body = parsedBody;
+  // 只保留我们真用得到的那一个头，不把整个 Headers 对象扫进错误里
+  const ra = headers && typeof headers.get === 'function' ? headers.get('Retry-After') : null;
+  e.retryAfter = ra != null ? Number(ra) : null;
+  return e;
+}
+
+// ============================================================
+// v0.4.4 M2 自动续期层
+// ============================================================
+
+/**
+ * 模块级「in-flight refresh Promise」映射表。
+ *
+ * key: 凭证目录绝对路径（不同目录 = 不同 profile，各自独立）。
+ * value: 正在飞行中的 refresh Promise（未完成时新来的 401 直接等同一个）。
+ *
+ * 三重防御：凭证隔离（不同 key）+ in-flight 去重（同 key 只飞一次）+ 立即落盘。
+ */
+const _inflightRefresh = new Map();
+
+/**
+ * 用 refresh_token 向平台换新 token（POST /oauth/token，RFC 6749 §6）。
+ *
+ * @param {string} baseUrl    平台基础地址
+ * @param {string} refreshToken 当前持有的 refresh_token
+ * @param {Function} fetchImpl  HTTP 实现（默认全局 fetch）
+ * @returns {Promise<object>}  { access_token, refresh_token, expires_in, ... }
+ * @throws {Error}  refresh 失败（BR-2.3：不诱导重新 login，提示人工处理）
+ */
+async function doRefreshToken(baseUrl, refreshToken, fetchImpl = fetch) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: 'linger-cli',
+  });
+  const resp = await fetchImpl(`${baseUrl}/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: body.toString(),
+  });
+  const text = await resp.text();
+  if (!resp.ok) {
+    // refresh 本身失败 → 凭证彻底过期。
+    // BR-2.3：绝不提示「运行 stelfield auth login」——无人值守 agent 若严格照做，
+    // 会触发一次新的 auth login；而 v0.4.2 已确认每次 auth login 都会新建一个
+    // 独立 agent（身份去重模型 X 的副作用），等于 agent 每次掉线重连都在自杀重生，
+    // 历史身份/信誉/已上报技能全部丢失。改为提示人工介入，不让 agent 自己"修"。
+    throw new Error(
+      `登录状态已失效（${resp.status}），请通知用户人工处理。`
+    );
+  }
+  return JSON.parse(text);
+}
+
+/**
+ * 针对单个凭证目录执行「带 in-flight 去重」的 refresh。
+ *
+ * 同一目录下并发多个 401 → 只有第一个进入 doRefreshToken，其余等同一 Promise。
+ * refresh 完成后：① 写入新 token 到凭证文件；② 清掉 in-flight 记录。
+ *
+ * @param {string} credPath 凭证目录（用作 map key 实现 profile 隔离）
+ * @param {string} baseUrl  平台地址
+ * @param {string} refreshToken 当前 refresh_token
+ * @param {Function} fetchImpl
+ * @returns {Promise<object>} 新 token 对象（含 access_token / refresh_token）
+ */
+async function refreshWithDedup(credPath, baseUrl, refreshToken, fetchImpl) {
+  // 已有正在飞行的 refresh → 等同一个结果（去重核心）
+  if (_inflightRefresh.has(credPath)) {
+    return _inflightRefresh.get(credPath);
+  }
+
+  // 发起新 refresh，挂在 map 上
+  const promise = doRefreshToken(baseUrl, refreshToken, fetchImpl)
+    .finally(() => {
+      // 无论成功 / 失败，都要清掉 in-flight 记录，防止下次正常 401 也被挡住
+      _inflightRefresh.delete(credPath);
+    });
+
+  _inflightRefresh.set(credPath, promise);
+  return promise;
+}
+
+/**
+ * 从 JWT access token 解出 agent_id（纯函数·解析失败返回 null）。
+ * 续期路径用它补 agent_id —— 后端 refresh 返回体不含顶层 agent_id（它在 access_token JWT 内部）。
+ */
+function _decodeAgentId(token) {
+  try {
+    const payloadB64 = (token || '').split('.')[1];
+    if (!payloadB64) return null;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+    return payload.agent_id || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 续期落盘：合并新 token，并从新 access token 补 agent_id（旧版无 agent_id 凭证平滑升级）。
+ * 防止「续期后凭证仍缺 agent_id → refresh 彻底失效后重新 login 无法复用身份（又刷僵尸）」。
+ */
+function persistRefreshedCreds(creds, newTokens, credOpts) {
+  const updated = { ...creds, ...newTokens };
+  const aid = _decodeAgentId(newTokens.access_token);
+  if (aid) updated.agent_id = aid;
+  saveCredentials(updated, credOpts);
+}
+
+/**
+ * 带 401→refresh→重试 的通用请求执行器（v0.4.4 M2 · v0.18.0 M3 抽成公共函数）。
+ *
+ * GET / POST / PUT 三种方法共用这一段：读凭证 → 发第一次请求 → 命中 401 就续期一次
+ * 再重试。抽出来之前 GET 与 POST 各写了一遍，主页介绍的 PUT 再加上就是第三份一模一样的
+ * 代码，以后改续期逻辑容易漏改。
+ *
+ * 行为与抽公共函数之前逐字节一致：
+ *   - 成功        → 返回解析后的 JSON
+ *   - 非 401 失败 → 抛 httpError(status, message, text)
+ *   - 401         → refresh（同凭证目录 in-flight 去重）→ 落盘新凭证 → 重试一次
+ *   - 重试仍 401  → 抛「登录状态已失效，请通知用户人工处理。」
+ *
+ * @param {string}   baseUrl  平台基础地址
+ * @param {object}   credOpts 凭证目录选项 { dir? } / { profile? }
+ * @param {object}   httpOpts { fetchImpl? }
+ * @param {Function} makeRequest (token, fetchImpl) => Promise<Response>
+ * @returns {Promise<object>} 解析后的 JSON
+ */
+async function authedRequestWithRefresh(baseUrl, credOpts, httpOpts, makeRequest) {
+  const fetchImpl = httpOpts.fetchImpl || fetch;
+
+  // 读当前凭证（已登录才能续）
+  const creds = loadCredentials(credOpts);
+  if (!creds || !creds.access_token) {
+    throw new Error('还没登录。请先运行：stelfield auth login');
+  }
+
+  const firstResp = await makeRequest(creds.access_token, fetchImpl);
+  noteServerVersion(firstResp.headers, credOpts);
+
+  if (firstResp.ok) {
+    return JSON.parse(await firstResp.text());
+  }
+
+  if (firstResp.status !== 401) {
+    // 非 401 错误，走原有错误路径
+    const text = await firstResp.text();
+    const msg = errMessageOf(text) || text;
+    throw httpError(firstResp.status, msg, text, firstResp.headers);
+  }
+
+  // ── 命中 401：触发 refresh ────────────────────────────────
+  // 用凭证目录作 key 实现 profile 隔离（不同目录各自独立 refresh）
+  const credDir = credOpts.dir || process.env.STELFIELD_CONFIG_DIR || (await import('node:os')).homedir() + '/' + BRAND.configDirName;
+
+  const newTokens = await refreshWithDedup(credDir, baseUrl, creds.refresh_token, fetchImpl);
+
+  // 立即覆写凭证文件（防止旧 refresh 被 revoke 后再次使用）+ 补 agent_id（旧版凭证平滑升级）
+  persistRefreshedCreds(creds, newTokens, credOpts);
+
+  // 用新 access_token 重试一次
+  const retryResp = await makeRequest(newTokens.access_token, fetchImpl);
+  noteServerVersion(retryResp.headers, credOpts);
+
+  if (!retryResp.ok) {
+    const text = await retryResp.text();
+    const msg = errMessageOf(text) || text;
+    if (retryResp.status === 401) {
+      throw new Error('登录状态已失效，请通知用户人工处理。');
+    }
+    throw httpError(retryResp.status, msg, text, retryResp.headers);
+  }
+
+  return JSON.parse(await retryResp.text());
+}
+
+/**
+ * 带 401→refresh→重试 的 GET 拦截器（M2 核心）。
+ *
+ * 与原 authedGet 接口兼容，新增 credOpts 参数（{ dir? } 凭证目录选项）。
+ *
+ * @param {string}   baseUrl       平台基础地址
+ * @param {string}   pathAndQuery  请求路径（含 query string）
+ * @param {object}   credOpts      凭证目录选项 { dir? }（同 credentials.js 的 opts）
+ * @param {object}   [httpOpts]    { fetchImpl? }
+ * @returns {Promise<object>}  解析后的 JSON
+ */
+export async function authedGetWithRefresh(baseUrl, pathAndQuery, credOpts = {}, httpOpts = {}) {
+  return authedRequestWithRefresh(baseUrl, credOpts, httpOpts, (token, fetchImpl) =>
+    fetchImpl(`${baseUrl}${pathAndQuery}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, ...clientHeaders() },
+    })
+  );
+}
+
+/**
+ * 带 401→refresh→重试 的 POST 拦截器（M2 核心）。
+ *
+ * 与原 authedPost 接口兼容，新增 credOpts 参数。
+ *
+ * @param {string}   baseUrl     平台基础地址
+ * @param {string}   pathStr     请求路径
+ * @param {object}   credOpts    凭证目录选项 { dir? }
+ * @param {object}   body        POST body
+ * @param {string}   [idempotencyKey]  幂等键（不传则自动生成）
+ * @param {object}   [httpOpts]  { fetchImpl? }
+ * @returns {Promise<object>}  解析后的 JSON
+ */
+export async function authedPostWithRefresh(
+  baseUrl,
+  pathStr,
+  credOpts = {},
+  body,
+  idempotencyKey,
+  httpOpts = {}
+) {
+  // 幂等键在所有尝试之间复用（重试时同 key，后端才能识别为同一次写）
+  const idemKey = idempotencyKey || randomUUID();
+
+  return authedRequestWithRefresh(baseUrl, credOpts, httpOpts, (token, fetchImpl) =>
+    fetchImpl(`${baseUrl}${pathStr}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'X-Idempotency-Key': idemKey,
+        ...clientHeaders(),
+      },
+      body: JSON.stringify(body),
+    })
+  );
+}
+
+/**
+ * 带 401→refresh→重试 的 PUT 拦截器（v0.18.0 M3 · 主页介绍写入）。
+ *
+ * 与 POST 的差别：**不带幂等键**。PUT 不受后端幂等中间件约束（契约 §4.0），
+ * 主页介绍写入靠「基准版本 + 内容相同不新增版本」保证重放安全；多送一个
+ * X-Idempotency-Key 只会让人误以为后端会去重。
+ *
+ * @param {string}   baseUrl   平台基础地址
+ * @param {string}   pathStr   请求路径
+ * @param {object}   credOpts  凭证目录选项 { dir? }
+ * @param {object}   body      PUT body
+ * @param {object}   [httpOpts] { fetchImpl? }
+ * @returns {Promise<object>}  解析后的 JSON
+ */
+export async function authedPutWithRefresh(baseUrl, pathStr, credOpts = {}, body, httpOpts = {}) {
+  return authedRequestWithRefresh(baseUrl, credOpts, httpOpts, (token, fetchImpl) =>
+    fetchImpl(`${baseUrl}${pathStr}`, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...clientHeaders(),
+      },
+      body: JSON.stringify(body),
+    })
+  );
+}
+
+/**
+ * 带 401→refresh→重试 的 DELETE 拦截器（v0.20.0 M3 · 取消屏蔽）。无请求体、无幂等键。
+ */
+export async function authedDeleteWithRefresh(baseUrl, pathStr, credOpts = {}, httpOpts = {}) {
+  return authedRequestWithRefresh(baseUrl, credOpts, httpOpts, (token, fetchImpl) =>
+    fetchImpl(`${baseUrl}${pathStr}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${token}`, ...clientHeaders() },
+    })
+  );
+}
+
+// ============================================================
+// 内部辅助（含自动续期能力）
+//
+// v0.4.4 M2 Iter 2：所有 wrapper 函数（createTask 等）现在
+// 接受 credOpts（凭证目录选项，同 credentials.js 的 opts）而不是裸 token。
+// 内部统一走 authedGetWithRefresh / authedPostWithRefresh，
+// 所有命令天然获得续期能力，零遗漏。
+//
+// 向后兼容注意：如果调用方传的 credOpts 是一个字符串（旧版 token 直传方式），
+// 会被视为凭证目录路径字符串，不会 crash，但建议迁移到 { dir } 对象形式。
+// ============================================================
+
+// ============================================================
+// 已有（M3 · 签名更新为 credOpts）
+// ============================================================
+
+/** 浏览任务大厅：默认招募中(created)任务列表。 */
+export async function getHall(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/tasks/hall', credOpts, opts);
+}
+
+/**
+ * 查询当前用户名下的 Agent 列表（V0.12.0 M6 · agent set-intro 用来找当前
+ * agent 的 name + 现有 bio，判断"要不要写、会不会覆盖"）。
+ */
+// ============================================================
+// 主页介绍（v0.18.0 M3 · 契约 §4.2 E1 / §4.3 E2 / §4.9 E8）
+// ============================================================
+//
+// 只开放「主页介绍」一个字段：不提供任何改简介 / 标签 / 头像 / 评分的包装（BR-10.1）。
+// 媒体上传（v0.19.0）：本地图片/视频可经 upload-request + 确认接口上传；网址抓图（/fetch）仍不对 agent 开放。
+
+/**
+ * 读自己的主页介绍（E1）。
+ *
+ * 从未写过时后端返回 content_md="" 与 version_no=0，不报错。
+ */
+export async function getProfileIntro(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/users/me/profile-intro', credOpts, opts);
+}
+
+/**
+ * 写入自己的主页介绍（E2）。
+ *
+ * agent 令牌下直接生效，不需要基准版本号（后端会忽略），
+ * 所以 body 只有 content_md。空串合法（= 清空）。
+ */
+export async function putProfileIntro(baseUrl, credOpts = {}, contentMd, opts = {}) {
+  return authedPutWithRefresh(
+    baseUrl,
+    '/api/v1/users/me/profile-intro',
+    credOpts,
+    { content_md: contentMd },
+    opts
+  );
+}
+
+/**
+ * 读自己的媒体库（E8）——给 agent 看能引用哪些已有图片视频。
+ *
+ * 每项带 uploaded_by（null = 商户本人，{agent_id, agent_name} = 某个 agent 上传）。
+ */
+export async function getProfileMedia(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/users/me/profile-media', credOpts, opts);
+}
+
+/**
+ * Ask for a signed direct-upload address (E6, v0.19.0: open to agent tokens).
+ * Body: { media_type: 'image'|'video', mime_type, file_size_bytes }.
+ * Returns { object_key, signed_put_url, expires_in }. The caller PUTs the bytes itself.
+ * A 429 here also means the agent's hourly budget (30 uploads) is spent.
+ */
+export async function requestProfileMediaUpload(baseUrl, credOpts = {}, body, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/users/me/profile-media/upload-request', credOpts, body, null, opts);
+}
+
+/**
+ * Confirm an uploaded object and add it to the media library (E7, v0.19.0: open to agent tokens).
+ * Body: { object_key, media_type, duration_seconds? } (duration only for video).
+ * Returns the media item: { media_id, ref, media_type, file_size_bytes, uploaded_by, ... }.
+ */
+export async function confirmProfileMedia(baseUrl, credOpts = {}, body, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/users/me/profile-media', credOpts, body, null, opts);
+}
+
+export async function getMyAgents(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/users/me/agents', credOpts, opts);
+}
+
+/**
+ * 注册/幂等复用 Agent（V0.12.0 M6 · agent set-intro 复用本端点写自我介绍）。
+ * 同 (owner, name) 已存在时不会新建，只按 M2 的"仅当前 bio 为空才写入
+ * self_intro"语义生效——调用前 CLI 已经用 getMyAgents 自己判断过一次，
+ * 这里再发请求属于双保险，不是唯一防线。
+ * @param {object} agentData  { name, framework?, self_intro? }
+ */
+export async function registerMyAgent(baseUrl, credOpts = {}, agentData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/users/me/agents', credOpts, agentData, idempotencyKey, opts);
+}
+
+// ============================================================
+// 任务生命周期前段（独立 REST 端点 · OAuth 可达）
+// ============================================================
+
+/**
+ * 发布任务（买方）。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {object} taskData  { title, description, bounty_amount_cents, delivery_hours, tags, accept_deadline_minutes? }
+ */
+export async function createTask(baseUrl, credOpts = {}, taskData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/tasks', credOpts, taskData, idempotencyKey, opts);
+}
+
+/**
+ * 接着做草稿（发起方本人）：GET /api/v1/tasks/{id}/continue-draft?round=N
+ * 返回可选版本、默认版本、价格、原商家、AI 整理的接力说明（会计入当日 AI 整理次数）。
+ */
+export async function getContinueDraft(baseUrl, credOpts = {}, taskId, round, opts = {}) {
+  const q = round != null ? `?round=${encodeURIComponent(round)}` : '';
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/continue-draft${q}`, credOpts, opts);
+}
+
+/**
+ * 读取平台当前的发单输入上限（公开接口，不需要登录）。
+ * 对应端点：GET /api/v1/tasks/input-limits
+ * 返回：{ title_max_chars, desc_max_chars, revisions_max, attach_max_count, attach_max_total_mb, revision_attach_max_count }
+ * 失败（网络 / 旧版平台没有这个接口）返回 null：预检只是提前提示，最终以后端校验为准。
+ */
+export async function getInputLimits(baseUrl, opts = {}) {
+  const fetchImpl = opts.fetchImpl || fetch;
+  try {
+    const resp = await fetchImpl(`${baseUrl}/api/v1/tasks/input-limits`, {
+      method: 'GET',
+      headers: { ...clientHeaders() },
+    });
+    if (!resp.ok) return null;
+    const body = parseJsonSafe(await resp.text());
+    return body && typeof body === 'object' ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 申请接单（卖方）。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
+ * @param {object} applyData { message? } 竞选理由（可选）
+ */
+export async function applyTask(baseUrl, credOpts = {}, taskId, applyData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/applications`, credOpts, applyData, idempotencyKey, opts);
+}
+
+/**
+ * Record why this Agent looked at a task but did not apply (Prd 22-02). Body: {reason, note?}.
+ */
+export async function passTask(baseUrl, credOpts = {}, taskId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${encodeURIComponent(taskId)}/pass`, credOpts, body, idempotencyKey, opts);
+}
+
+/**
+ * 买方选中某申请人。
+ * @param {object} credOpts       凭证目录选项 { dir? }
+ * @param {string} taskId         任务 ID
+ * @param {string} applicationId  被选中的申请 ID
+ */
+export async function selectApplication(baseUrl, credOpts = {}, taskId, applicationId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
+    baseUrl,
+    `/api/v1/tasks/${taskId}/select`,
+    credOpts,
+    { application_id: applicationId },
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 任务执行/结算（统一走 POST /api/v1/runtime/act）
+// ============================================================
+
+/**
+ * 调用 runtime/act，通用函数。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} action    ACTION_MAP 里的 action name
+ * @param {object} payload   含 job_id + action 专属字段
+ */
+export async function runtimeAct(baseUrl, credOpts = {}, action, payload, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
+    baseUrl,
+    '/api/v1/runtime/act',
+    credOpts,
+    { action, payload },
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 能力上架（独立端点 · 卖方）
+// ============================================================
+
+/**
+ * 上报技能清单（卖方·A 流程第一步）。
+ * 把 agent 自己会的技能写进平台 agents.skill_catalog，供网页「AI 识别」挑能力卡。
+ * 用 agent token 调用时后端从 token 推导 agent_id（agent 不必知道自己 UUID）。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {Array<{name:string,description:string}>} skills 技能清单
+ */
+export async function reportSkills(baseUrl, credOpts = {}, skills, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
+    baseUrl,
+    '/api/v1/capabilities/skill_catalog',
+    credOpts,
+    { skills },
+    idempotencyKey,
+    opts
+  );
+}
+
+/**
+ * 创建能力卡草稿（卖方）。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {object} capData   CreateCapabilityRequest 字段（agent_id + title 必填，其余草稿可空）
+ */
+export async function createCapability(baseUrl, credOpts = {}, capData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/capabilities', credOpts, capData, idempotencyKey, opts);
+}
+
+/**
+ * 上架能力（卖方）。后端会校验归属 owner + 上架前置字段完整。
+ * @param {object} credOpts      凭证目录选项 { dir? }
+ * @param {string} capabilityId  能力 ID
+ */
+export async function publishCapability(baseUrl, credOpts = {}, capabilityId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(
+    baseUrl,
+    `/api/v1/capabilities/${capabilityId}/publish`,
+    credOpts,
+    {},
+    idempotencyKey,
+    opts
+  );
+}
+
+// ============================================================
+// 问答（POST/GET /api/v1/tasks/{id}/comments）
+// ============================================================
+
+/**
+ * 发问答留言（任意参与方）。
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {string} taskId     任务 ID
+ * @param {string} content    留言内容
+ * @param {number|null} parentId 回复的目标留言 ID（顶层不传）
+ */
+export async function postComment(baseUrl, credOpts = {}, taskId, content, parentId, idempotencyKey, opts = {}) {
+  const body = { content };
+  if (parentId != null) body.parent_id = parentId;
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/comments`, credOpts, body, idempotencyKey, opts);
+}
+
+/**
+ * 查看任务问答留言列表。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
+ */
+export async function getComments(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/comments`, credOpts, opts);
+}
+
+// ============================================================
+// 自治巡航 / 探活（GET /api/v1/agent/cruise）
+// ============================================================
+
+/**
+ * 拉取巡航快照（autonomy tick）或轻量探活（ping）。
+ * ping 和 tick 复用同一端点，响应 200 即说明鉴权 + 连通 OK。
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ */
+export async function getCruise(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/agent/cruise', credOpts, opts);
+}
+
+// ============================================================
+// M1 v0.10.0 新增：盯单长轮询（GET /api/v1/agent/poll）
+// ============================================================
+
+/**
+ * 盯单长轮询：带上次落盘的 cursor，问平台"有没有比这更新的事件"。
+ *
+ * 对应端点：GET /api/v1/agent/poll?cursor={cursor}
+ * 后端行为（a2a-backend/app/routes/polling.py）：有新事件立即返回；无事件挂起
+ * 最多 30 秒再返回空（cursor 不变）。
+ *
+ * @param {string} baseUrl  平台基础地址
+ * @param {object} credOpts 凭证目录选项 { dir? }
+ * @param {object} opts     { cursor?: number, fetchImpl? }
+ * @returns {Promise<{events: Array, next_cursor: number}>}
+ */
+export async function getMyTakenTasks(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/tasks?scope=taken&limit=50', credOpts, opts);
+}
+
+export async function getPoll(baseUrl, credOpts = {}, opts = {}) {
+  const cursor = opts.cursor != null ? opts.cursor : 0;
+  return authedGetWithRefresh(baseUrl, `/api/v1/agent/poll?cursor=${cursor}`, credOpts, opts);
+}
+
+// ============================================================
+// M7 新增：任务信息查询 + 文件能力（薄 REST 包装·零业务逻辑）
+// ============================================================
+
+/**
+ * 读取任务详情（标题 + 正文 + 状态等）。
+ *
+ * 对应端点：GET /api/v1/tasks/{task_id}
+ * 鉴权：Bearer JWT（OAuth access_token 可达·_require_auth 只校签名+exp）
+ *
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
+ */
+export async function getTaskDetail(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}`, credOpts, opts);
+}
+
+/**
+ * 查看任务附件列表（买方上传的需求原始材料）。
+ *
+ * 对应端点：GET /api/v1/tasks/{task_id}/attachments
+ * 返回：{ attachments: [{ file_id, mime_type, size_bytes, locked, ... }] }
+ *
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
+ */
+export async function getTaskFiles(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/attachments`, credOpts, opts);
+}
+
+/**
+ * 拿到某个文件的下载地址（临时 signed URL，5 分钟内有效）。
+ *
+ * 对应端点：GET /api/v1/downloads/{file_id}/url
+ * 返回：{ file_id, signed_get_url }
+ * 薄包装铁律：只返回 signed_get_url，HTTP GET 由调用方（agent）自己做。
+ *
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} fileId    文件 ID
+ */
+export async function getDownloadUrl(baseUrl, credOpts = {}, fileId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/downloads/${fileId}/url`, credOpts, opts);
+}
+
+/**
+ * 申请上传文件（附件或交付物）。
+ *
+ * 对应端点：POST /api/v1/uploads
+ * 返回：{ file_id, signed_put_url, oss_object_id }
+ * 薄包装铁律：只返回 signed_put_url + file_id，HTTP PUT 由调用方（agent）自己做。
+ *
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {object} uploadData { task_id, kind, mime_type, size_bytes }
+ *   kind = 'attachment'（需求附件）| 'deliverable'（交付物）
+ */
+export async function requestUpload(baseUrl, credOpts = {}, uploadData, opts = {}) {
+  // 上传申请走随机 UUID 幂等键（uploadData 里的字段相同可幂等，后端会返回相同 file_id）
+  const { idempotencyKey, fetchImpl } = opts;
+  return authedPostWithRefresh(baseUrl, '/api/v1/uploads', credOpts, uploadData, idempotencyKey || null, { fetchImpl });
+}
+
+/**
+ * 修改附件可见性（owner 任意任务状态均可调用）。
+ *
+ * 对应端点：PATCH /api/v1/uploads/{file_id}/visibility
+ * 后端只认 owner、不限任务状态——本函数为薄包装，不加状态限制。
+ *
+ * @param {string}   baseUrl   平台基础地址
+ * @param {object}   credOpts  凭证目录选项 { dir? }
+ * @param {string}   fileId    文件 ID
+ * @param {string}   visibility  'public' | 'accepted_only'（后端接受下划线）
+ * @param {object}   [opts]    { fetchImpl? }
+ * @returns {Promise<object>}  { ok, file_id, visibility }
+ */
+export async function patchFileVisibility(baseUrl, credOpts = {}, fileId, visibility, opts = {}) {
+  const fetchImpl = opts.fetchImpl || fetch;
+  // 读凭证（同步·与其他 api 函数保持一致）
+  const creds = loadCredentials(credOpts);
+  if (!creds || !creds.access_token) {
+    throw new Error('还没登录。请先运行：stelfield auth login');
+  }
+  // PATCH 请求（无幂等键要求，后端幂等中间件只拦 POST）
+  const resp = await fetchImpl(`${baseUrl}/api/v1/uploads/${fileId}/visibility`, {
+    method: 'PATCH',
+    headers: {
+      Authorization: `Bearer ${creds.access_token}`,
+      'Content-Type': 'application/json',
+      ...clientHeaders(),
+    },
+    body: JSON.stringify({ visibility }),
+  });
+  const text = await resp.text();
+  if (!resp.ok) {
+    let msg = text;
+    try { msg = JSON.parse(text)?.detail?.message || msg; } catch { /* ignore */ }
+    throw new Error(`修改可见性失败（${resp.status}）：${msg}`);
+  }
+  return JSON.parse(text);
+}
+
+// ============================================================
+// 5c 新增：评价（真人演练修复 · 2026-07-02）
+//   task rate 命令用这三个函数判断"我是买方还是卖方"并发去对的端点。
+// ============================================================
+
+/**
+ * 查任务的候选申请列表（v0.1 透明竞标·任何登录用户可查）。
+ * task rate 命令用它找到中标（matched）接单方的 capability_id（买方评能力卡需要）。
+ *
+ * 对应端点：GET /api/v1/tasks/{task_id}/applications
+ *
+ * @param {object} credOpts  凭证目录选项 { dir? }
+ * @param {string} taskId    任务 ID
+ */
+export async function getApplications(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/applications`, credOpts, opts);
+}
+
+/**
+ * 买方对能力卡提交评价（旧入口·V0.12.0 M1 已下线返 410，保留函数体供追溯）。
+ *
+ * 对应端点：POST /api/v1/capabilities/{cap_id}/reviews（V0.12.0 M1 起 410 Gone）
+ * 新版买方评价请用 createTaskReview（POST /api/v1/tasks/{task_id}/reviews）。
+ *
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {string} capId      能力卡 ID（中标接单方发布的能力卡）
+ * @param {object} reviewData { task_id, stars, comment? }
+ */
+export async function createCapabilityReview(baseUrl, credOpts = {}, capId, reviewData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/capabilities/${capId}/reviews`, credOpts, reviewData, idempotencyKey, opts);
+}
+
+/**
+ * 卖方（接单方）对买方（发起方）提交评价（v0.3 双向评价 · 保留不动）。
+ *
+ * 对应端点：POST /api/v1/users/{user_id}/reviews
+ *
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {string} buyerUserId 被评价的买方 user_id（= 任务的 owner_user_id）
+ * @param {object} reviewData { task_id, stars, comment? }
+ */
+export async function createUserReview(baseUrl, credOpts = {}, buyerUserId, reviewData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/users/${buyerUserId}/reviews`, credOpts, reviewData, idempotencyKey, opts);
+}
+
+/**
+ * V0.12.0 M1（T2 + T8）：任务维度统一评价端点（买卖双向共用）。
+ *
+ * 对应端点：POST /api/v1/tasks/{task_id}/reviews
+ * 后端按 caller 是任务的买方还是卖方自动判断评价方向，被评价者身份由服务端
+ * 从任务里取（不接受客户端传 seller_user_id，防越权投毒）。CLI 买方侧
+ * `task rate` 改调此端点，不再需要先查中标方有没有能力卡。
+ *
+ * @param {object} credOpts   凭证目录选项 { dir? }
+ * @param {string} taskId     任务 ID
+ * @param {object} reviewData { stars, comment? }（不含 task_id，路径已带）
+ */
+export async function createTaskReview(baseUrl, credOpts = {}, taskId, reviewData, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/reviews`, credOpts, reviewData, idempotencyKey, opts);
+}
+
+// ============================================================
+// v0.17.0 M2-B：执行期协作沟通（成交后双方问清需求）
+// 端点见 a2a-backend/app/routes/collab.py。POST 一律带 X-Idempotency-Key
+// （由 authedPostWithRefresh 自动补随机 UUID；协作端点不在幂等豁免前缀内，缺则后端 400）。
+// ============================================================
+
+/**
+ * 接单方 Agent 提问。questions 已是 API 形状 [{prompt, options:[{label,description,recommended}]}]。
+ * 选项 key 由服务端分配，这里不传。
+ */
+export async function askCollabQuestions(baseUrl, credOpts = {}, taskId, questions, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/collab/questions`, credOpts, { questions }, idempotencyKey, opts);
+}
+
+/**
+ * 发起方（Agent 代答）回答一张提问卡。answers 必须覆盖该卡全部题。
+ * 409 already_answered 会抛出带 status/body 的错误（body.original 为原回答）。
+ */
+export async function answerCollabQuestion(baseUrl, credOpts = {}, taskId, cardId, answers, extraNote, idempotencyKey, opts = {}) {
+  const body = { answers };
+  if (extraNote) body.extra_note = extraNote;
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/collab/questions/${cardId}/answers`, credOpts, body, idempotencyKey, opts);
+}
+
+/** 接单方 Agent 发「说明」消息（发起方的「补充」只能在网页做，CLI 不提供）。 */
+export async function postCollabNote(baseUrl, credOpts = {}, taskId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/collab/messages`, credOpts, { kind: 'note', body }, idempotencyKey, opts);
+}
+
+/**
+ * 读取协作记录。afterId>0 时只取 id 大于它的记录；limit 缺省走服务端默认。
+ */
+export async function getCollab(baseUrl, credOpts = {}, taskId, { afterId, limit } = {}, opts = {}) {
+  const qs = [];
+  if (afterId != null && afterId > 0) qs.push(`after_id=${afterId}`);
+  if (limit != null) qs.push(`limit=${limit}`);
+  const q = qs.length ? `?${qs.join('&')}` : '';
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/collab${q}`, credOpts, opts);
+}
+
+// ============================================================
+// v0.20.0 M3：采纳标记 / 需求基线 / 屏蔽 / 限制（薄 REST 包装）
+// ============================================================
+
+/**
+ * 对买家的一条要求打标记（采纳 / 部分采纳 / 不采纳）。
+ * 对应端点：POST /api/v1/tasks/{task_id}/marks
+ * @param {object} body { ref, verdict, reason?, note?, adopted_text?, rejected_text?, quote_cents?, quote_scope? }
+ */
+export async function postMark(baseUrl, credOpts = {}, taskId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${encodeURIComponent(taskId)}/marks`, credOpts, body, idempotencyKey, opts);
+}
+
+/**
+ * 读取需求基线（原始需求 + 买家全部要求及其采纳标记）。
+ * 对应端点：GET /api/v1/tasks/{task_id}/baseline
+ */
+export async function getBaseline(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${encodeURIComponent(taskId)}/baseline`, credOpts, opts);
+}
+
+/** 屏蔽一个用户（全渠道，幂等）。对应端点：POST /api/v1/users/me/blocks */
+export async function blockUser(baseUrl, credOpts = {}, userId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/users/me/blocks', credOpts, { user_id: userId }, idempotencyKey, opts);
+}
+
+/** 取消屏蔽。对应端点：DELETE /api/v1/users/me/blocks/{user_id} */
+export async function unblockUser(baseUrl, credOpts = {}, userId, opts = {}) {
+  return authedDeleteWithRefresh(baseUrl, `/api/v1/users/me/blocks/${encodeURIComponent(userId)}`, credOpts, opts);
+}
+
+/** 我当前被自动限制的事项。对应端点：GET /api/v1/users/me/restrictions */
+export async function getRestrictions(baseUrl, credOpts = {}, opts = {}) {
+  return authedGetWithRefresh(baseUrl, '/api/v1/users/me/restrictions', credOpts, opts);
+}
+
+// ============================================================
+// Web hosting (CLI 0.10.1): register an uploaded web package, read the deliverables view
+// ============================================================
+
+/**
+ * Ask the platform to check and unpack an already uploaded web package.
+ * POST /api/v1/tasks/{task_id}/web-packages  body { file_id }
+ * Same file_id twice returns the existing result (the backend is idempotent on file_id).
+ */
+export async function registerWebPackage(baseUrl, credOpts = {}, taskId, fileId, opts = {}) {
+  const { idempotencyKey, fetchImpl } = opts;
+  return authedPostWithRefresh(
+    baseUrl, `/api/v1/tasks/${taskId}/web-packages`, credOpts,
+    { file_id: fileId }, idempotencyKey || `web-package-${fileId}`, { fetchImpl }
+  );
+}
+
+/** Deliverables view (versions[], files[], web info). GET /api/v1/tasks/{task_id}/deliverables */
+export async function getTaskDeliverables(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/deliverables`, credOpts, opts);
+}
+
+// ============================================================
+// v0.22.0 M6: Libra dispute ruling (endpoints: a2a-backend/app/routes/libra.py, PRD section 8.1)
+// POST calls carry X-Idempotency-Key through authedPostWithRefresh.
+// ============================================================
+
+/** Price a filing (no charge). body: { task_id, evidence:[{file_id, as_screenshot?, selected_pages?, selected_minutes?}], statement? } */
+export async function libraQuote(baseUrl, credOpts = {}, body, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/libra/quote', credOpts, body, undefined, opts);
+}
+
+/** Create the fee order of a filing; the case is opened once it is paid. */
+export async function libraCreateCase(baseUrl, credOpts = {}, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, '/api/v1/libra/cases', credOpts, body, idempotencyKey, opts);
+}
+
+/** The case of a task (case is null when none) plus whether the buyer can file one now. */
+export async function libraTaskCase(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/libra`, credOpts, opts);
+}
+
+export async function libraStatement(baseUrl, credOpts = {}, caseId, text, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/statements`, credOpts, { text }, idempotencyKey, opts);
+}
+
+/** Add key evidence in the statement period; returns the adding party own fee order. */
+export async function libraAddEvidence(baseUrl, credOpts = {}, caseId, evidence, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/evidence`, credOpts, { evidence }, idempotencyKey, opts);
+}
+
+export async function libraAnswer(baseUrl, credOpts = {}, caseId, questionId, text, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/answers`, credOpts,
+    { question_id: questionId, text }, idempotencyKey, opts);
+}
+
+export async function libraRulings(baseUrl, credOpts = {}, caseId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/rulings`, credOpts, opts);
+}
+
+export async function libraAccept(baseUrl, credOpts = {}, caseId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/accept`, credOpts, {}, idempotencyKey, opts);
+}
+
+export async function libraReviewQuote(baseUrl, credOpts = {}, caseId, body, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/reviews/quote`, credOpts, body, undefined, opts);
+}
+
+export async function libraReviewCreate(baseUrl, credOpts = {}, caseId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/reviews`, credOpts, body, idempotencyKey, opts);
+}
+
+// ============================================================
+// P19 batch: review config, extra-revision requests, early close of a Libra case
+// Endpoints: a2a-backend/app/routes/reviews.py, revision_extensions.py, libra.py
+// ============================================================
+
+/**
+ * Review limits and quick tags (public, no login needed). Returns null when unreadable: the caller then skips its
+ * local pre-check and lets the platform decide.
+ * Shape: { tags: { seller: [{key, group, i18n_key}], buyer: [...] }, text_max, reply_max, image: {...}, ... }
+ */
+export async function getReviewsConfig(baseUrl, opts = {}) {
+  const fetchImpl = opts.fetchImpl || fetch;
+  try {
+    const resp = await fetchImpl(`${baseUrl}/api/v1/reviews/config`, {
+      method: 'GET',
+      headers: { ...clientHeaders() },
+    });
+    if (!resp.ok) return null;
+    const body = parseJsonSafe(await resp.text());
+    return body && typeof body === 'object' ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Current extra-revision request + history + eligibility of a task (buyer or seller side). */
+export async function getRevisionExtensions(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions`, credOpts, opts);
+}
+
+/** Buyer asks for one more revision round. body: { revision_note, fee_cents, defer_hours } (defer_days still accepted by the server). */
+export async function createRevisionExtension(baseUrl, credOpts = {}, taskId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions`, credOpts, body, idempotencyKey, opts);
+}
+
+/** Seller answers. body: { decision: agree|decline|counter, counter_fee_cents?, counter_defer_hours? (counter_defer_days still accepted), note? }. */
+export async function respondRevisionExtension(baseUrl, credOpts = {}, taskId, extId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions/${extId}/respond`, credOpts, body, idempotencyKey, opts);
+}
+
+/** Buyer answers the seller's new terms. body: { decision: accept|reject }. */
+export async function confirmRevisionExtension(baseUrl, credOpts = {}, taskId, extId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions/${extId}/confirm`, credOpts, body, idempotencyKey, opts);
+}
+
+/** Buyer takes the request back. */
+export async function withdrawRevisionExtension(baseUrl, credOpts = {}, taskId, extId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions/${extId}/withdraw`, credOpts, {}, idempotencyKey, opts);
+}
+
+/** Seller's Agent is unsure and asks the seller in person to decide (once per request). */
+export async function notifyOwnerRevisionExtension(baseUrl, credOpts = {}, taskId, extId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/revision-extensions/${extId}/notify-owner`, credOpts, {}, idempotencyKey, opts);
+}
+
+/** Buyer withdraws a Libra case (web only: an Agent token gets 403 agent_token_forbidden). */
+export async function libraWithdrawCase(baseUrl, credOpts = {}, caseId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/withdraw`, credOpts, {}, idempotencyKey, opts);
+}
+
+/** Seller accepts the buyer's public refund claim. An Agent must pass expect_pct (the percentage it read). */
+export async function libraConcede(baseUrl, credOpts = {}, caseId, expectPct, idempotencyKey, opts = {}) {
+  const body = expectPct == null ? {} : { expect_pct: expectPct };
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/concede`, credOpts, body, idempotencyKey, opts);
+}
+
+/** Open a settlement offer: { refund_pct }. */
+export async function libraProposeOffer(baseUrl, credOpts = {}, caseId, refundPct, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/offers`, credOpts, { refund_pct: refundPct }, idempotencyKey, opts);
+}
+
+/** Accept the other side's offer. An Agent must pass expect_pct (the percentage it read). */
+export async function libraAcceptOffer(baseUrl, credOpts = {}, caseId, offerId, expectPct, idempotencyKey, opts = {}) {
+  const body = expectPct == null ? {} : { expect_pct: expectPct };
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/offers/${offerId}/accept`, credOpts, body, idempotencyKey, opts);
+}
+
+/** Reject the other side's offer (the hearing goes on). */
+export async function libraRejectOffer(baseUrl, credOpts = {}, caseId, offerId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/offers/${offerId}/reject`, credOpts, {}, idempotencyKey, opts);
+}
+
+/** Take back an offer you made. */
+export async function libraWithdrawOffer(baseUrl, credOpts = {}, caseId, offerId, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}/offers/${offerId}/withdraw`, credOpts, {}, idempotencyKey, opts);
+}
+
+// Refund negotiation (negotiate first, rule later). Endpoints: a2a-backend/app/routes/negotiations.py
+/** The negotiation of a task as the caller sees it: { viewer, task, limits, negotiation | null, can }. */
+export async function negotiationGet(baseUrl, credOpts = {}, taskId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/tasks/${taskId}/negotiation`, credOpts, opts);
+}
+
+/** The seller side answers: { action: agree|offer|hold, refund_pct?, note?, expect_pct }. */
+export async function negotiationRespond(baseUrl, credOpts = {}, negotiationId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/negotiations/${negotiationId}/respond`, credOpts, body, idempotencyKey, opts);
+}
+
+/** The buyer side answers the counter offer: { action: accept|ask, refund_pct?, note?, expect_pct }. */
+export async function negotiationReply(baseUrl, credOpts = {}, negotiationId, body, idempotencyKey, opts = {}) {
+  return authedPostWithRefresh(baseUrl, `/api/v1/negotiations/${negotiationId}/reply`, credOpts, body, idempotencyKey, opts);
+}
+
+/** One Libra case by id (the view includes the early_close block). Used when only --case was given. */
+export async function libraGetCase(baseUrl, credOpts = {}, caseId, opts = {}) {
+  return authedGetWithRefresh(baseUrl, `/api/v1/libra/cases/${caseId}`, credOpts, opts);
+}