@sema-agent/client-core 0.11.16 → 0.11.18

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.11.16
+**Version:** 0.11.18
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver

package/dist/adapt.js

@@ -705,6 +705,11 @@ class WireToCcAdapterImpl {
         // 代价是失去 for-await 的隐式 cleanup ⇒ finally 里手动 return()(T58,少了它 = SSE 不拆)。
         const iterator = frames[Symbol.asyncIterator]();
         let iteratorDone = false;
+        // R1(clay 五报 07-31):retry 覆盖层的四个清除点全在 turn 边界,缺「重试成功→清」的转移 ——
+        // 引擎重试成功那一刻什么都不发(BrainStatusPhase 无恢复终态,候 core [2163]),所以恢复只能由
+        // 「主 lane 又有内容在流」这个事实来证明。挂旗后首个主 lane 内容帧即清,CC 同位 = 重试循环
+        // 退出即 onRetryStatus(null)(pretty220 finally 清)。
+        let retryOverlayActive = false;
         try {
             for (;;) {
                 const nextPromise = iterator.next();
@@ -755,6 +760,19 @@ class WireToCcAdapterImpl {
                 const m = rawFrame;
                 if (m === null || typeof m !== 'object')
                     continue;
+                if (retryOverlayActive &&
+                    (m.type === 'stream_event' ||
+                        m.type === 'assistant' ||
+                        m.type === 'tool_end_result' ||
+                        m.type === 'turn_usage') &&
+                    typeof m.parentToolCallId !== 'string' &&
+                    // stream_event 的子流标记在 event 里(:1230 thinking 臂同款判位),帧顶层没有。
+                    typeof m.event?.parentToolCallId !== 'string') {
+                    // 恢复即清:主 lane 内容帧到达 = 引擎那次重试已成功;子流帧(parentToolCallId)不算证据
+                    // (主 brain 仍可能在退避等待,#47 矩阵 #5 同族判别)。
+                    retryOverlayActive = false;
+                    yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+                }
                 if (m.type === 'stream_event' && !messageStartEmitted) {
                     messageStartEmitted = true;
                     yield chrome({
@@ -1362,6 +1380,7 @@ class WireToCcAdapterImpl {
                                 ...(typeof m.retryInSec === 'number' ? { retryInSec: m.retryInSec } : {}),
                             }, ctx.now()),
                         });
+                        retryOverlayActive = true;
                         break;
                     }
                     default:

package/dist/engineAgentPanelStore.d.ts

@@ -88,6 +88,12 @@ export type EngineAgentPanelEvent = {
      * 修「详情页 Prompt 段恒空」。缺席 ⇒ 维持现状(诚实留白)。
      */
     transcriptId?: string;
+    /**
+     * server 1.250 起行帧带的 launch 真锚(epoch ms)。R4(clay 五报 07-31):此前投影层丢弃它,
+     * 详情页 elapsed 只能锚「壳建行时刻」(createTaskStateBase 的 Date.now())——遗留/重挂行上
+     * 渲出 1h+ 假时长。消费端拿到即覆盖行的 startTime;缺席 ⇒ 老引擎,维持现状。
+     */
+    startedAt?: number;
 } | {
     kind: 'end';
     taskId: string;

package/dist/fleetAgentPanelProjection.d.ts

@@ -17,6 +17,9 @@ export interface FleetAgentRowLike {
         toolName: string;
         target?: string;
     };
+    /** server 1.250 起行带的 launch 真锚(epoch ms)。R4(clay 五报 07-31):此前投影载荷丢弃它,
+     *  详情页 elapsed 只能锚「壳建行时刻」——遗留行上渲出 1h+ 的假时长。缺席=老引擎,消费端保持现状。 */
+    startedAt?: number;
 }
 /** 行从投影集消失多久之后按 completed 兜底 settle(重连空窗 / snapshot 清表远小于此)。 */
 export declare const ABSENT_SETTLE_MS = 30000;

package/dist/fleetAgentPanelProjection.js

@@ -80,6 +80,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
         // 🔴 三态直取:`row.toolUses` 缺席就是 undefined,这里**不许**兜 0(见 FleetAgentRowLike 注)。
         const toolUses = typeof row.toolUses === 'number' ? row.toolUses : undefined;
         const transcriptId = row.transcriptId || undefined;
+        const startedAt = typeof row.startedAt === 'number' && row.startedAt > 0 ? row.startedAt : undefined;
         const currentTool = currentToolKeyOf(row.currentTool) !== undefined ? row.currentTool : undefined;
         const currentToolKey = currentToolKeyOf(row.currentTool);
         const prev = seen.get(taskId);
@@ -89,7 +90,8 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
                 // 终态行也把最后一拍的累计工具数/转录锚带上:详情页在行翻终态后仍要显示真计数与
                 // 委派 prompt,而终态帧常常是这一行**唯一**带全 usage 的一帧(bg lane 只在活动边界发行帧)。
                 if ((toolUses !== undefined && prev?.toolUses !== toolUses) ||
-                    (transcriptId !== undefined && prev?.transcriptId !== transcriptId)) {
+                    (transcriptId !== undefined && prev?.transcriptId !== transcriptId) ||
+                    (startedAt !== undefined && prev?.startedAt !== startedAt)) {
                     publishEngineAgentPanelEvent({
                         kind: 'fleet-row',
                         taskId,
@@ -98,6 +100,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
                         totalTokens: tokens,
                         ...(toolUses !== undefined ? { toolUses } : {}),
                         ...(transcriptId !== undefined ? { transcriptId } : {}),
+                        ...(startedAt !== undefined ? { startedAt } : {}),
                     });
                 }
                 publishEngineAgentPanelEvent({
@@ -111,6 +114,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
                 tokens,
                 toolUses: toolUses !== undefined ? toolUses : prev?.toolUses,
                 transcriptId: transcriptId !== undefined ? transcriptId : prev?.transcriptId,
+                startedAt: startedAt !== undefined ? startedAt : prev?.startedAt,
                 currentToolKey: currentToolKey !== undefined ? currentToolKey : prev?.currentToolKey,
                 lastSeenAt: nowMs,
                 settled: true,
@@ -127,6 +131,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
             prev.tokens !== tokens ||
             (toolUses !== undefined && prev.toolUses !== toolUses) ||
             (transcriptId !== undefined && prev.transcriptId !== transcriptId) ||
+            (startedAt !== undefined && prev.startedAt !== startedAt) ||
             (currentToolKey !== undefined && prev.currentToolKey !== currentToolKey)) {
             publishEngineAgentPanelEvent({
                 kind: 'fleet-row',
@@ -137,6 +142,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
                 // 🔴 缺席即不落键(消费端据「键在不在」判三态)。
                 ...(toolUses !== undefined ? { toolUses } : {}),
                 ...(transcriptId !== undefined ? { transcriptId } : {}),
+                ...(startedAt !== undefined ? { startedAt } : {}),
                 ...(currentTool !== undefined ? { currentTool } : {}),
             });
         }
@@ -146,6 +152,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
             tokens,
             toolUses: toolUses !== undefined ? toolUses : prev?.toolUses,
             transcriptId: transcriptId !== undefined ? transcriptId : prev?.transcriptId,
+            startedAt: startedAt !== undefined ? startedAt : prev?.startedAt,
             currentToolKey: currentToolKey !== undefined ? currentToolKey : prev?.currentToolKey,
             lastSeenAt: nowMs,
             settled: false,

package/dist/hitl/askGateWire.js

@@ -2,7 +2,7 @@ import { HitlBridge } from './hitlBridge.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { isFsApprovalGate, toolNameIsFsWrite, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
+import { isToolApprovalGate, toolNameIsFsWrite, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
 import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 // W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层(cli 装配不动)。
 const hostSurfaceByKey = createSessionSlot();
@@ -69,8 +69,9 @@ function isAskGatePark(result) {
         typeof r.taskId === 'string' &&
         r.taskId.length > 0);
 }
-/** done 帧的 fs 写权限 park 形状([816] 放宽腿):status suspended + checkpointGate 指 fs 写工具
- *  (Write/Edit/NotebookEdit)或一等 kind==='tool_approval'。Ask gate 恒先判(问答 overlay 原路)。 */
+/** done 帧的工具审批 park 形状([816] 放宽腿 + [2150] Bash 半场):status suspended +
+ *  checkpointGate 指 fs 写三件 / Bash / 一等 kind==='tool_approval'(超集谓词 isToolApprovalGate,
+ *  decide 腿对两族同构、卡形归壳分发)。Ask gate 恒先判(问答 overlay 原路)。 */
 function isFsApprovalPark(result) {
     const r = result;
     return (!!r &&
@@ -78,7 +79,7 @@ function isFsApprovalPark(result) {
         typeof r.taskId === 'string' &&
         r.taskId.length > 0 &&
         !isAskTool(r.checkpointGate?.toolName) &&
-        isFsApprovalGate(r.checkpointGate));
+        isToolApprovalGate(r.checkpointGate));
 }
 /** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
  *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
@@ -477,7 +478,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
                     park = { gate: 'ask' };
                     break;
                 }
-                if (ev.gate && isFsApprovalGate(ev.gate) && realTaskId) {
+                if (ev.gate && isToolApprovalGate(ev.gate) && realTaskId) {
                     park = { gate: 'fs' };
                     break;
                 }

package/dist/hitl/toolApprovalWire.d.ts

@@ -6,6 +6,17 @@ export declare function isFsApprovalGate(gate: {
     toolName?: unknown;
 } | undefined | null): boolean;
 export declare function toolNameIsFsWrite(name: string): boolean;
+/** shell 执行工具判定(Bash)。[2150] S1 半场:引擎对 Bash 发 durable park 时,fs 谓词不认 ⇒
+ *  park 落「其余 gate 透传」= run 留 suspended、session 锁死(r1 E5 fail-stuck 实例)。 */
+export declare function toolNameIsShellExec(name: string): boolean;
+/** 工具审批 gate 判定(durable park 分诊用的**超集**谓词):一等 kind / fs 写三件 / shell 执行。
+ *  decide 腿(approvals.decide)对两族同构;卡形分发归壳 ApprovalCardPort(toolForName 已含
+ *  bash → BashPermissionRequest 映射,sema-cli a35e2b2)。`isFsApprovalGate` 保留原语义不动
+ *  (公开面消费者按 fs 写理解它,把 Bash 塞进去是撒谎)。 */
+export declare function isToolApprovalGate(gate: {
+    kind?: unknown;
+    toolName?: unknown;
+} | undefined | null): boolean;
 export type FsApprovalOutcome = {
     kind: 'decided';
     gatedCallId?: string;

package/dist/hitl/toolApprovalWire.js

@@ -15,6 +15,20 @@ export function toolNameIsFsWrite(name) {
     const n = name.replace(/[\s_-]+/g, '').toLowerCase();
     return (n === 'write' || n === 'filewrite' || n === 'edit' || n === 'fileedit' || n === 'multiedit' || n === 'notebookedit');
 }
+/** shell 执行工具判定(Bash)。[2150] S1 半场:引擎对 Bash 发 durable park 时,fs 谓词不认 ⇒
+ *  park 落「其余 gate 透传」= run 留 suspended、session 锁死(r1 E5 fail-stuck 实例)。 */
+export function toolNameIsShellExec(name) {
+    return name.replace(/[\s_-]+/g, '').toLowerCase() === 'bash';
+}
+/** 工具审批 gate 判定(durable park 分诊用的**超集**谓词):一等 kind / fs 写三件 / shell 执行。
+ *  decide 腿(approvals.decide)对两族同构;卡形分发归壳 ApprovalCardPort(toolForName 已含
+ *  bash → BashPermissionRequest 映射,sema-cli a35e2b2)。`isFsApprovalGate` 保留原语义不动
+ *  (公开面消费者按 fs 写理解它,把 Bash 塞进去是撒谎)。 */
+export function isToolApprovalGate(gate) {
+    if (isFsApprovalGate(gate))
+        return true;
+    return typeof gate?.toolName === 'string' && toolNameIsShellExec(gate.toolName);
+}
 /** 结构等值(键序无关深比较)——updatedInput「真编辑过」判定用。zod parse 会产新引用与重排,
  *  引用比较/JSON.stringify 串比较都会假报「编辑过」。 */
 export function structurallyEqual(a, b) {
@@ -115,7 +129,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     try {
         const rows = (await deps.client.approvals.list(signal ? { signal } : undefined)).pending;
         pending =
-            rows.find(r => r.taskId === taskId && typeof r.toolName === 'string' && toolNameIsFsWrite(r.toolName)) ??
+            rows.find(r => r.taskId === taskId && typeof r.toolName === 'string' && (toolNameIsFsWrite(r.toolName) || toolNameIsShellExec(r.toolName))) ??
                 rows.find(r => r.taskId === taskId);
     }
     catch (e) {

package/dist/index.d.ts

@@ -220,3 +220,4 @@ export * from './request/printNotification.js';
 export * from './seatContract.js';
 export * from './agentSession/contract.js';
 export * from './agentSession/backgroundView.js';
+export * from './model/catalog.js';

package/dist/index.js

@@ -302,3 +302,11 @@ export * from './agentSession/contract.js';
 // 两源(assistant.tasks 跨 session 调度总览 + fleet 常驻 SSE 快照)独立拉取独立降级的归一投影;
 // 两张 status 映射表 never 卫兵穷举;'not-configured' 判别姿势见文件头注。
 export * from './agentSession/backgroundView.js';
+// ── design/160 需求②:模型 provider 目录公用化(2026-07-31)──────────────────────────────────
+// 三层源解析(线上 URL 可配 → 包内 providerPresets 兜底 → 用户自定义覆盖)+ **来源标注**。
+// 🔴 零 Node、零全局 fetch:线上腿的取数走注入的 `CatalogFetchJson` 端口,宿主没给 ⇒ 线上腿
+//    整条不启用(`online.reason = 'no-fetch-port'`),与 host.ts 的缺席语义同一条纪律。
+// 🔴 本文件零默认 URL:目录仓位候裁(设计档待裁点 3),机制先行、地址由调用方传。
+// 🔴 绝不半解析:schemaVersion 超区间/任一行形状坏 ⇒ 整份弃用走兜底(端渲「内置版本(离线)」
+//    靠 `source` + `online.reason`,所以「静默用兜底」在本层是可观测的)。
+export * from './model/catalog.js';

package/dist/model/catalog.d.ts

@@ -0,0 +1,158 @@
+/**
+ * catalog.ts — **模型 provider 目录的三层源解析**(design/160 需求②,2026-07-31)。
+ *
+ * ## 它解决什么
+ *
+ * `providerPresets.json` 是**编译进包的静态表**:加一家 provider、改一个 model 的 cap,都得发一次
+ * client-core。而三端(CLI / web / 桌面)要的是同一份目录、可在线更新、离线仍能用。本模块把
+ * 设计档 §需求② 的三层源做成一个**纯解析器**:
+ *
+ * ```
+ *   ① 线上目录(URL 由调用方传入 —— 本文件零默认地址,见下「为什么不写死 URL」)
+ *        ↓ 拉取失败 / 离线 / 校验不过(整份弃用)
+ *   ② 包内兜底 = PROVIDER_PRESETS(零改动即兜底)
+ *        ↓
+ *   ③ 用户本地覆盖(自定义 provider,合并语义:同 id 用户 > 线上 > 包内)
+ * ```
+ *
+ * ## 四条设计纪律(每条都在 pure 门 MC 段有断言)
+ *
+ * 1. **零 Node、零自发网络**:本文件不 import 任何 `node:*`,也**不碰全局 `fetch`** ——
+ *    网络能力由调用方注入 `fetchJson` 端口。宿主没给 ⇒ 线上腿整条不启用(`reason: 'no-fetch-port'`),
+ *    而不是「偷偷换个方式做」(与 host.ts 的缺席语义同一条纪律)。
+ *    ⇒ 桌面渲染进程 / 浏览器 / TUI 用同一份代码,各自注入自己的传输。
+ * 2. **绝不半解析**(设计档明写):`schemaVersion` 超出支持区间、`providers` 不是数组、
+ *    **任何一行**形状不合格 ⇒ **整份**线上目录弃用走兜底。半解析 = 用户拿到一张自己也说不清
+ *    是哪一版的表。
+ * 3. **来源标注是产品位不是调试位**:返回值恒带 `source` 与 `online.{ok,reason}`。端据此渲
+ *    「目录为内置版本(离线)」——「静默用兜底」在本层必须是**可观测**的,否则用户会以为看到的
+ *    是最新表([honest-absence-not-fabricated-zero])。
+ * 4. **诚实缺席**:`staleness` 只在真吃到线上目录时在场;`ageMs` 只在调用方给了 `nowMs`
+ *    且 `generatedAt` 可解析时在场。不知道就是键缺席,绝不 `?? 0`,也绝不偷读时钟
+ *    (时钟是宿主资产,与 `AdapterContext.now` 同一条口径)。
+ *
+ * ## 为什么不写死线上 URL
+ *
+ * 目录仓位(设计档待裁点 3:`sema-agent/model-catalog` 公开仓 or release asset)**候 clay 裁**。
+ * 机制先行、地址后填:URL 由调用方从配置/settings 传入。本文件里出现任何默认地址,都会让
+ * 「还没定的仓位」提前变成事实契约。https-only 是硬校验(目录是会被下载并影响**出站地址**的
+ * 数据,明文信道下可被改写成钓鱼网关)。
+ *
+ * ## 本批不做(留口注释,别当遗漏)
+ *
+ * · **缓存与 ETag**:`~/.sema/cache/model-catalog.json` + ETag/304 + 新鲜窗 + `localGeneratedAt`
+ *   防降级(设计档 pi 调研节)。落盘是宿主能力(fs 在 host.ts 的 `FsPort`),所以缓存层应当是
+ *   **本模块之上**的一层:调用方拿 `resolveModelCatalog` 的结果自行落盘,并把上次的 `generatedAt`
+ *   与新拉到的比较后决定是否替换。⇒ 加缓存时**不需要**改本文件的形状,只需在 `fetchJson` 注入
+ *   处做 ETag,并在外层加一个「旧远端压不过新包」的比较。
+ * · **签名 / sha256**:同上,属传输层与目录产出方的约定(设计档待裁点 3)。
+ * · **`oauth` / `subscribe` 字段**:设计档待裁点 3b。本批只加纯链接位 `consoleUrl`/`signupUrl`
+ *   (见 providerPresets.ts),授权码流/设备码流一律不进。
+ *
+ * ## probe 复用面评估(设计档 §需求②-C「复用面」;只评估不搬,搬迁下一批做)
+ *
+ * 桌面端 onboard 要「选 provider → 填 key → 探活」,探活那一步现在只在壳树。按
+ * [multiclient-migration-batch-discipline](模块级状态与读写口同包)逐个评估,结论如下 ——
+ * 这是下一批的搬迁清单,坐标为壳树 `src/sema/onboard/`:
+ *
+ * | 文件 | 结论 | 依据 |
+ * |---|---|---|
+ * | `probePlan.ts`(139 行) | ✅ **整搬,零改造** | 零 import、零模块级状态、纯函数四件(`buildVerdictRequest` / `extractApiError` / `looksLikeModelError` / `judgeMessagesProbe`)。判决表本身就是「三端必须一致」的那部分。 |
+ * | `probeProvider.ts`(223 行) | ⚠️ **拆搬**:判定+请求编排进包、传输与 TLS 留端 | ①裸 `fetch`/`AbortController`/`setTimeout` ⇒ 改注入 `fetchImpl`(本包既有姿势:`limitsWire`/`detachWire`/`liveInitToolFace` 的 `opts.fetchImpl`);②`ensureProxyBootstrap()` 动态 import 壳的 `utils/proxy.js`(`configureGlobalAgents`)= **Node undici 专属**,浏览器无此概念 ⇒ 留端,做成可选的「拨号前置钩子」端口;③`isCertError`/`applySystemTlsTrust`(壳 `tlsTrust.ts`,读系统钥匙串 + 设 `NODE_EXTRA_CA_CERTS`)= 纯 Node ⇒ 留端,做成可选的「一次性重试钩子」;④`nearestListed()` 与 `unwrapFetchError()` 是纯函数 ⇒ 直接进包。搬后包内出口 ≈ `probeProvider({ baseUrl, api, apiKey, modelId }, { fetchImpl, beforeDial?, retryOnCertError? })`。 |
+ * | `detectSources.ts`(524 行) | ❌ **本批不搬** | 它整个是**宿主文件系统扫描器**:`node:fs`(existsSync/readdirSync/readFileSync/statSync)+ `node:os` homedir + `node:path` + `process.env` + 两个外部解析器(`jsonc-parser`/`yaml`)+ 壳内 `ccConfigFallback`。可搬的只有「读到的配置 → `ImportableProvider` 的分类/归一逻辑」那一小半,而它与扫描代码是逐行交织的。⇒ 要搬得先在壳里把「扫描(IO)」与「分类(纯)」拆开,是独立一批的量。**桌面端不阻塞**:桌面 onboard 的导入源探测本就该是主进程的活(与 CLI 同为 Node 侧),复用价值远低于 probe 两件。 |
+ * | `onboardZeroModel.ts`(2.8K) | 🔶 **顺路可搬** | 已有独立单测(`onboardZeroModel.test.ts`),看形状是纯判定;搬前需确认零壳态依赖。 |
+ * | `applyOnboard.ts` / `OnboardWizard.tsx` / `BigStepTitle.tsx` / `ccSwitchReader.ts` | ❌ 属端 | 落盘编排 / Ink 渲染 / 读 cc-switch sqlite —— 宿主辖区,桌面端各写各的渲染器(设计档 §C 与 pi 的 `AuthInteraction` seam 同一心智)。 |
+ *
+ * 搬迁批建议顺序:`probePlan`(零风险打头,先让包里有判决表)→ `probeProvider` 拆搬(带
+ * fetchImpl 注入 + 两个可选钩子端口)→ `onboardZeroModel` → detectSources 拆分单列一批。
+ */
+import { type ProviderPreset } from './providerPresets.js';
+/** 支持的目录 schemaVersion 区间(闭区间)。产目录那一方按这个区间发版。 */
+export declare const CATALOG_SCHEMA_VERSION_MIN = 1;
+export declare const CATALOG_SCHEMA_VERSION_MAX = 1;
+/** 线上目录文档的信封形。`providers` 与包内表**同形**(ProviderPreset),所以两层可直接按 id 合并。 */
+export interface OnlineCatalogDoc {
+    schemaVersion: number;
+    /** 目录生成时刻(ISO8601)。用于端渲新鲜度;不可解析也不弃用整份(它不是契约位)。 */
+    generatedAt: string;
+    providers: ProviderPreset[];
+}
+/**
+ * 结果的来源标注 = **最高优先级的在场层**:
+ * · `merged` —— 用户覆盖层真的贡献了行(不管线上腿成没成);
+ * · `online` —— 线上目录被接受且无用户覆盖;
+ * · `bundled` —— 只有包内表(离线 / 线上被拒 / 没配 URL)。
+ */
+export type CatalogSource = 'online' | 'bundled' | 'merged';
+/** 线上腿被拒的**具体**理由(端可据此分诊:是没配、是离线、还是目录本身坏了)。 */
+export type CatalogRejectReason = 'no-online-url' | 'no-fetch-port' | 'insecure-url' | 'fetch-failed' | 'payload-not-object' | 'schema-version-missing' | 'schema-version-unsupported' | 'generated-at-missing' | 'providers-not-array' | 'provider-row-invalid';
+/** 线上腿的结局。`ok: true` 时不带 `reason`(枚举互斥)。 */
+export interface CatalogOnlineOutcome {
+    ok: boolean;
+    reason?: CatalogRejectReason;
+    /**
+     * 拒绝细节(人话,给分诊用)。🔴 只放判决相关的短语与被截断的错误 message,
+     * **绝不回显载荷本身**([credential-error-path-leak]:错误路径是凭证外泄的经典入口;
+     * 目录 URL 本身是公开物,但宿主注入的 fetchJson 可能带鉴权头,所以异常只取 message 前段)。
+     */
+    detail?: string;
+}
+/** 线上目录的新鲜度。只在真吃到线上目录时在场。 */
+export interface CatalogStaleness {
+    /** 目录自述的生成时刻,原样透传(烂串也原样给端,由端决定怎么说)。 */
+    generatedAt: string;
+    /** 距今毫秒。只在调用方给了 `nowMs` 且 `generatedAt` 可解析时在场 —— 不知道就键缺席。 */
+    ageMs?: number;
+}
+export interface ModelCatalogResult {
+    /** 合并后的 provider 表(新数组;包内表绝不被就地改写)。 */
+    providers: ProviderPreset[];
+    source: CatalogSource;
+    staleness?: CatalogStaleness;
+    online: CatalogOnlineOutcome;
+    /** 用户覆盖层真正贡献的 provider id(替换的 + 新增的)。无覆盖 ⇒ 空数组。 */
+    overrideIds: string[];
+}
+/**
+ * 注入式取 JSON 端口 —— **本包唯一的线上目录取数口**。
+ * 约定:2xx ⇒ resolve 已解析的 JSON;其它一切(网络错 / 非 2xx / 解析失败)⇒ reject。
+ * ETag/304、超时、代理、鉴权头全归宿主(它们各端形态不同,见文件头「本批不做」)。
+ */
+export type CatalogFetchJson = (url: string) => Promise<unknown>;
+export interface ResolveModelCatalogOptions {
+    /** 线上目录 URL。缺席 ⇒ 线上腿不启用(本包零默认地址)。必须是 https。 */
+    onlineUrl?: string;
+    /** 取数口。缺席 ⇒ 线上腿不启用(本包绝不自己碰 fetch)。 */
+    fetchJson?: CatalogFetchJson;
+    /** 用户本地覆盖(自定义 provider)。同 id 恒赢线上与包内。 */
+    overrides?: readonly ProviderPreset[];
+    /** 当前时刻(宿主时钟)。缺席 ⇒ 不算 ageMs(而不是自己读 Date.now)。 */
+    nowMs?: number;
+}
+/** schemaVersion 是否落在支持区间内(非整数一律否)。 */
+export declare function isSupportedCatalogSchemaVersion(v: unknown): boolean;
+export type ValidateCatalogResult = {
+    ok: true;
+    doc: OnlineCatalogDoc;
+} | {
+    ok: false;
+    reason: CatalogRejectReason;
+    detail?: string;
+};
+/**
+ * 校验线上载荷 —— **纯同步**,端可以单用(比如「刷新目录」按钮先本地校验再落盘)。
+ * 🔴 全或无:任何一条不合格 ⇒ 整份拒,绝不半解析。
+ */
+export declare function validateOnlineCatalog(payload: unknown): ValidateCatalogResult;
+/**
+ * 按 id 分层合并:**后来的层赢**,行序 = 首见序(包内序稳定在前,新家按层依次追加)。
+ * 纯函数,端可以单用(比如只合并「包内 + 用户覆盖」的离线路径)。
+ */
+export declare function mergeProviderLayers<T extends {
+    id: string;
+}>(...layers: readonly (readonly T[])[]): T[];
+/**
+ * 解析出一份可用的 provider 目录 —— 三层源 + 来源标注。**永不 reject**:线上腿的任何失败都
+ * 收敛成 `online.ok === false` 并回落包内表(离线可用是硬需求)。
+ */
+export declare function resolveModelCatalog(opts?: ResolveModelCatalogOptions): Promise<ModelCatalogResult>;

package/dist/model/catalog.js

@@ -0,0 +1,224 @@
+/**
+ * catalog.ts — **模型 provider 目录的三层源解析**(design/160 需求②,2026-07-31)。
+ *
+ * ## 它解决什么
+ *
+ * `providerPresets.json` 是**编译进包的静态表**:加一家 provider、改一个 model 的 cap,都得发一次
+ * client-core。而三端(CLI / web / 桌面)要的是同一份目录、可在线更新、离线仍能用。本模块把
+ * 设计档 §需求② 的三层源做成一个**纯解析器**:
+ *
+ * ```
+ *   ① 线上目录(URL 由调用方传入 —— 本文件零默认地址,见下「为什么不写死 URL」)
+ *        ↓ 拉取失败 / 离线 / 校验不过(整份弃用)
+ *   ② 包内兜底 = PROVIDER_PRESETS(零改动即兜底)
+ *        ↓
+ *   ③ 用户本地覆盖(自定义 provider,合并语义:同 id 用户 > 线上 > 包内)
+ * ```
+ *
+ * ## 四条设计纪律(每条都在 pure 门 MC 段有断言)
+ *
+ * 1. **零 Node、零自发网络**:本文件不 import 任何 `node:*`,也**不碰全局 `fetch`** ——
+ *    网络能力由调用方注入 `fetchJson` 端口。宿主没给 ⇒ 线上腿整条不启用(`reason: 'no-fetch-port'`),
+ *    而不是「偷偷换个方式做」(与 host.ts 的缺席语义同一条纪律)。
+ *    ⇒ 桌面渲染进程 / 浏览器 / TUI 用同一份代码,各自注入自己的传输。
+ * 2. **绝不半解析**(设计档明写):`schemaVersion` 超出支持区间、`providers` 不是数组、
+ *    **任何一行**形状不合格 ⇒ **整份**线上目录弃用走兜底。半解析 = 用户拿到一张自己也说不清
+ *    是哪一版的表。
+ * 3. **来源标注是产品位不是调试位**:返回值恒带 `source` 与 `online.{ok,reason}`。端据此渲
+ *    「目录为内置版本(离线)」——「静默用兜底」在本层必须是**可观测**的,否则用户会以为看到的
+ *    是最新表([honest-absence-not-fabricated-zero])。
+ * 4. **诚实缺席**:`staleness` 只在真吃到线上目录时在场;`ageMs` 只在调用方给了 `nowMs`
+ *    且 `generatedAt` 可解析时在场。不知道就是键缺席,绝不 `?? 0`,也绝不偷读时钟
+ *    (时钟是宿主资产,与 `AdapterContext.now` 同一条口径)。
+ *
+ * ## 为什么不写死线上 URL
+ *
+ * 目录仓位(设计档待裁点 3:`sema-agent/model-catalog` 公开仓 or release asset)**候 clay 裁**。
+ * 机制先行、地址后填:URL 由调用方从配置/settings 传入。本文件里出现任何默认地址,都会让
+ * 「还没定的仓位」提前变成事实契约。https-only 是硬校验(目录是会被下载并影响**出站地址**的
+ * 数据,明文信道下可被改写成钓鱼网关)。
+ *
+ * ## 本批不做(留口注释,别当遗漏)
+ *
+ * · **缓存与 ETag**:`~/.sema/cache/model-catalog.json` + ETag/304 + 新鲜窗 + `localGeneratedAt`
+ *   防降级(设计档 pi 调研节)。落盘是宿主能力(fs 在 host.ts 的 `FsPort`),所以缓存层应当是
+ *   **本模块之上**的一层:调用方拿 `resolveModelCatalog` 的结果自行落盘,并把上次的 `generatedAt`
+ *   与新拉到的比较后决定是否替换。⇒ 加缓存时**不需要**改本文件的形状,只需在 `fetchJson` 注入
+ *   处做 ETag,并在外层加一个「旧远端压不过新包」的比较。
+ * · **签名 / sha256**:同上,属传输层与目录产出方的约定(设计档待裁点 3)。
+ * · **`oauth` / `subscribe` 字段**:设计档待裁点 3b。本批只加纯链接位 `consoleUrl`/`signupUrl`
+ *   (见 providerPresets.ts),授权码流/设备码流一律不进。
+ *
+ * ## probe 复用面评估(设计档 §需求②-C「复用面」;只评估不搬,搬迁下一批做)
+ *
+ * 桌面端 onboard 要「选 provider → 填 key → 探活」,探活那一步现在只在壳树。按
+ * [multiclient-migration-batch-discipline](模块级状态与读写口同包)逐个评估,结论如下 ——
+ * 这是下一批的搬迁清单,坐标为壳树 `src/sema/onboard/`:
+ *
+ * | 文件 | 结论 | 依据 |
+ * |---|---|---|
+ * | `probePlan.ts`(139 行) | ✅ **整搬,零改造** | 零 import、零模块级状态、纯函数四件(`buildVerdictRequest` / `extractApiError` / `looksLikeModelError` / `judgeMessagesProbe`)。判决表本身就是「三端必须一致」的那部分。 |
+ * | `probeProvider.ts`(223 行) | ⚠️ **拆搬**:判定+请求编排进包、传输与 TLS 留端 | ①裸 `fetch`/`AbortController`/`setTimeout` ⇒ 改注入 `fetchImpl`(本包既有姿势:`limitsWire`/`detachWire`/`liveInitToolFace` 的 `opts.fetchImpl`);②`ensureProxyBootstrap()` 动态 import 壳的 `utils/proxy.js`(`configureGlobalAgents`)= **Node undici 专属**,浏览器无此概念 ⇒ 留端,做成可选的「拨号前置钩子」端口;③`isCertError`/`applySystemTlsTrust`(壳 `tlsTrust.ts`,读系统钥匙串 + 设 `NODE_EXTRA_CA_CERTS`)= 纯 Node ⇒ 留端,做成可选的「一次性重试钩子」;④`nearestListed()` 与 `unwrapFetchError()` 是纯函数 ⇒ 直接进包。搬后包内出口 ≈ `probeProvider({ baseUrl, api, apiKey, modelId }, { fetchImpl, beforeDial?, retryOnCertError? })`。 |
+ * | `detectSources.ts`(524 行) | ❌ **本批不搬** | 它整个是**宿主文件系统扫描器**:`node:fs`(existsSync/readdirSync/readFileSync/statSync)+ `node:os` homedir + `node:path` + `process.env` + 两个外部解析器(`jsonc-parser`/`yaml`)+ 壳内 `ccConfigFallback`。可搬的只有「读到的配置 → `ImportableProvider` 的分类/归一逻辑」那一小半,而它与扫描代码是逐行交织的。⇒ 要搬得先在壳里把「扫描(IO)」与「分类(纯)」拆开,是独立一批的量。**桌面端不阻塞**:桌面 onboard 的导入源探测本就该是主进程的活(与 CLI 同为 Node 侧),复用价值远低于 probe 两件。 |
+ * | `onboardZeroModel.ts`(2.8K) | 🔶 **顺路可搬** | 已有独立单测(`onboardZeroModel.test.ts`),看形状是纯判定;搬前需确认零壳态依赖。 |
+ * | `applyOnboard.ts` / `OnboardWizard.tsx` / `BigStepTitle.tsx` / `ccSwitchReader.ts` | ❌ 属端 | 落盘编排 / Ink 渲染 / 读 cc-switch sqlite —— 宿主辖区,桌面端各写各的渲染器(设计档 §C 与 pi 的 `AuthInteraction` seam 同一心智)。 |
+ *
+ * 搬迁批建议顺序:`probePlan`(零风险打头,先让包里有判决表)→ `probeProvider` 拆搬(带
+ * fetchImpl 注入 + 两个可选钩子端口)→ `onboardZeroModel` → detectSources 拆分单列一批。
+ */
+import { PROVIDER_PRESETS } from './providerPresets.js';
+/** 支持的目录 schemaVersion 区间(闭区间)。产目录那一方按这个区间发版。 */
+export const CATALOG_SCHEMA_VERSION_MIN = 1;
+export const CATALOG_SCHEMA_VERSION_MAX = 1;
+/** schemaVersion 是否落在支持区间内(非整数一律否)。 */
+export function isSupportedCatalogSchemaVersion(v) {
+    return (typeof v === 'number' &&
+        Number.isInteger(v) &&
+        v >= CATALOG_SCHEMA_VERSION_MIN &&
+        v <= CATALOG_SCHEMA_VERSION_MAX);
+}
+function isProviderRow(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const r = v;
+    return (typeof r.id === 'string' &&
+        r.id.length > 0 &&
+        typeof r.name === 'string' &&
+        typeof r.baseUrl === 'string' &&
+        (r.api === 'anthropic-messages' || r.api === 'openai-completions') &&
+        typeof r.authEnv === 'string' &&
+        Array.isArray(r.models));
+}
+/**
+ * 校验线上载荷 —— **纯同步**,端可以单用(比如「刷新目录」按钮先本地校验再落盘)。
+ * 🔴 全或无:任何一条不合格 ⇒ 整份拒,绝不半解析。
+ */
+export function validateOnlineCatalog(payload) {
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+        return { ok: false, reason: 'payload-not-object', detail: 'catalog payload is not a JSON object' };
+    }
+    const doc = payload;
+    if (typeof doc.schemaVersion !== 'number' || !Number.isInteger(doc.schemaVersion)) {
+        return { ok: false, reason: 'schema-version-missing', detail: 'schemaVersion missing or not an integer' };
+    }
+    if (!isSupportedCatalogSchemaVersion(doc.schemaVersion)) {
+        return {
+            ok: false,
+            reason: 'schema-version-unsupported',
+            detail: `schemaVersion ${doc.schemaVersion} outside supported range ${CATALOG_SCHEMA_VERSION_MIN}..${CATALOG_SCHEMA_VERSION_MAX}`,
+        };
+    }
+    if (typeof doc.generatedAt !== 'string' || doc.generatedAt.length === 0) {
+        return { ok: false, reason: 'generated-at-missing', detail: 'generatedAt missing' };
+    }
+    if (!Array.isArray(doc.providers)) {
+        return { ok: false, reason: 'providers-not-array', detail: 'providers is not an array' };
+    }
+    const bad = doc.providers.findIndex((row) => !isProviderRow(row));
+    if (bad >= 0) {
+        return {
+            ok: false,
+            reason: 'provider-row-invalid',
+            // 只报**位置**不报内容:载荷是外部数据,回显 = 把不可信内容带进日志面。
+            detail: `provider row #${bad} failed the shape gate (whole document rejected — no partial parse)`,
+        };
+    }
+    return {
+        ok: true,
+        doc: {
+            schemaVersion: doc.schemaVersion,
+            generatedAt: doc.generatedAt,
+            providers: doc.providers,
+        },
+    };
+}
+/**
+ * 按 id 分层合并:**后来的层赢**,行序 = 首见序(包内序稳定在前,新家按层依次追加)。
+ * 纯函数,端可以单用(比如只合并「包内 + 用户覆盖」的离线路径)。
+ */
+export function mergeProviderLayers(...layers) {
+    const order = [];
+    const byId = new Map();
+    for (const layer of layers) {
+        for (const row of layer) {
+            if (!row || typeof row.id !== 'string' || row.id.length === 0)
+                continue;
+            if (!byId.has(row.id))
+                order.push(row.id);
+            byId.set(row.id, row);
+        }
+    }
+    const out = [];
+    for (const id of order) {
+        const row = byId.get(id);
+        if (row !== undefined)
+            out.push(row);
+    }
+    return out;
+}
+/** https-only(目录会影响出站地址,明文信道可被改写成钓鱼网关)。 */
+function isHttpsUrl(u) {
+    return /^https:\/\/\S+$/i.test(u.trim());
+}
+/** 异常 → 短 detail(只取 message 前段,绝不带栈、绝不带载荷)。 */
+function shortError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return msg.slice(0, 160);
+}
+/**
+ * 解析出一份可用的 provider 目录 —— 三层源 + 来源标注。**永不 reject**:线上腿的任何失败都
+ * 收敛成 `online.ok === false` 并回落包内表(离线可用是硬需求)。
+ */
+export async function resolveModelCatalog(opts) {
+    const overrides = opts?.overrides ?? [];
+    let onlineDoc = null;
+    let online;
+    const url = opts?.onlineUrl?.trim();
+    if (!url) {
+        online = { ok: false, reason: 'no-online-url', detail: 'no online catalog URL configured' };
+    }
+    else if (typeof opts?.fetchJson !== 'function') {
+        online = { ok: false, reason: 'no-fetch-port', detail: 'host did not install a fetchJson port' };
+    }
+    else if (!isHttpsUrl(url)) {
+        // 🔴 校验在拨号**之前**:非 https 连请求都不发。
+        online = { ok: false, reason: 'insecure-url', detail: 'online catalog URL must be https' };
+    }
+    else {
+        // 单发不重试:重试/超时预算属宿主传输层(注入的 fetchJson 自己带)。
+        let payload;
+        let dialFailure = null;
+        try {
+            payload = await opts.fetchJson(url);
+        }
+        catch (e) {
+            dialFailure = { ok: false, reason: 'fetch-failed', detail: shortError(e) };
+        }
+        if (dialFailure !== null) {
+            online = dialFailure;
+        }
+        else {
+            const v = validateOnlineCatalog(payload);
+            if (v.ok) {
+                onlineDoc = v.doc;
+                online = { ok: true };
+            }
+            else {
+                online = { ok: false, reason: v.reason, ...(v.detail !== undefined ? { detail: v.detail } : {}) };
+            }
+        }
+    }
+    const providers = mergeProviderLayers(PROVIDER_PRESETS, onlineDoc?.providers ?? [], overrides);
+    const overrideIds = mergeProviderLayers(overrides).map((p) => p.id);
+    const source = overrideIds.length > 0 ? 'merged' : onlineDoc !== null ? 'online' : 'bundled';
+    const result = { providers, source, online, overrideIds };
+    if (onlineDoc !== null) {
+        const parsed = Date.parse(onlineDoc.generatedAt);
+        const ageMs = opts?.nowMs !== undefined && Number.isFinite(parsed) ? opts.nowMs - parsed : undefined;
+        result.staleness = {
+            generatedAt: onlineDoc.generatedAt,
+            ...(ageMs !== undefined ? { ageMs } : {}),
+        };
+    }
+    return result;
+}

package/dist/model/providerPresets.d.ts

@@ -14,6 +14,17 @@ export type ProviderPreset = {
     models: PresetModel[];
     /** Aggregator gateways (OpenRouter): model id is hand-typed, ctx/maxtok via family table. */
     modelViaFamily?: boolean;
+    /**
+     * 🆕 design/160 需求②-B(2026-07-31):**去哪拿 key** 的控制台页(纯链接,离线也能显示)。
+     *
+     * 🔴 **诚实缺席**:只填能可靠确认的官网控制台地址;拿不准的家**不填**,绝不编 URL —— 这个字段
+     * 会被 onboard 直接拿去开浏览器,编一个 = 把用户送到错误的地方。本地/自建家(ollama /
+     * lmstudio / vllm / sglang / litellm)按定义没有控制台页,缺席是正确答案不是遗漏。
+     * 设计档待裁点 3b:`oauth` / `subscribe` 两类**本批不加**(授权码流/设备码流单独排)。
+     */
+    consoleUrl?: string;
+    /** 没账号时的注册入口。与 `consoleUrl` 同页的家不重复填(缺席 = 用 consoleUrl 那条)。 */
+    signupUrl?: string;
 };
 export type ModelFamily = {
     id: string;

package/dist/model/providerPresets.json

@@ -6,6 +6,8 @@
             "baseUrl": "https://api.anthropic.com",
             "api": "anthropic-messages",
             "authEnv": "ANTHROPIC_API_KEY",
+            "consoleUrl": "https://console.anthropic.com/settings/keys",
+            "signupUrl": "https://console.anthropic.com/",
             "models": [
                 {
                     "id": "claude-fable-5",
@@ -53,6 +55,8 @@
             "baseUrl": "https://api.openai.com/v1",
             "api": "openai-completions",
             "authEnv": "OPENAI_API_KEY",
+            "consoleUrl": "https://platform.openai.com/api-keys",
+            "signupUrl": "https://platform.openai.com/signup",
             "models": [
                 {
                     "id": "gpt-5.5",
@@ -106,6 +110,8 @@
             "baseUrl": "https://api.deepseek.com/v1",
             "api": "openai-completions",
             "authEnv": "DEEPSEEK_API_KEY",
+            "consoleUrl": "https://platform.deepseek.com/api_keys",
+            "signupUrl": "https://platform.deepseek.com/sign_up",
             "models": [
                 {
                     "id": "deepseek-v4-pro",
@@ -137,6 +143,7 @@
             "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
             "api": "openai-completions",
             "authEnv": "DASHSCOPE_API_KEY",
+            "consoleUrl": "https://bailian.console.aliyun.com/",
             "models": [
                 {
                     "id": "qwen3.5-plus",
@@ -179,6 +186,7 @@
             "baseUrl": "https://api.moonshot.cn/v1",
             "api": "openai-completions",
             "authEnv": "MOONSHOT_API_KEY",
+            "consoleUrl": "https://platform.moonshot.cn/console/api-keys",
             "models": [
                 {
                     "id": "kimi-k3",
@@ -220,6 +228,7 @@
             "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
             "api": "openai-completions",
             "authEnv": "ZHIPU_API_KEY",
+            "consoleUrl": "https://open.bigmodel.cn/usercenter/apikeys",
             "models": [
                 {
                     "id": "glm-5.2",
@@ -267,6 +276,7 @@
             "baseUrl": "https://api.z.ai/api/paas/v4",
             "api": "openai-completions",
             "authEnv": "ZAI_API_KEY",
+            "consoleUrl": "https://z.ai/manage-apikey/apikey-list",
             "models": [
                 {
                     "id": "glm-5.2",
@@ -309,6 +319,7 @@
             "baseUrl": "https://api.minimax.io/anthropic",
             "api": "anthropic-messages",
             "authEnv": "MINIMAX_API_KEY",
+            "consoleUrl": "https://platform.minimax.io/",
             "models": [
                 {
                     "id": "MiniMax-M3",
@@ -335,6 +346,7 @@
             "baseUrl": "https://api.minimaxi.com/anthropic",
             "api": "anthropic-messages",
             "authEnv": "MINIMAX_CN_API_KEY",
+            "consoleUrl": "https://platform.minimaxi.com/",
             "models": [
                 {
                     "id": "MiniMax-M3",
@@ -355,6 +367,7 @@
             "baseUrl": "https://api.moonshot.ai/v1",
             "api": "openai-completions",
             "authEnv": "MOONSHOT_API_KEY",
+            "consoleUrl": "https://platform.moonshot.ai/console/api-keys",
             "models": [
                 {
                     "id": "kimi-k2.6",
@@ -401,6 +414,7 @@
             "baseUrl": "https://qianfan.baidubce.com/v2",
             "api": "openai-completions",
             "authEnv": "QIANFAN_API_KEY",
+            "consoleUrl": "https://console.bce.baidu.com/qianfan/",
             "models": [
                 {
                     "id": "ernie-5.0-thinking-preview",
@@ -421,6 +435,7 @@
             "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
             "api": "openai-completions",
             "authEnv": "VOLCANO_ENGINE_API_KEY",
+            "consoleUrl": "https://console.volcengine.com/ark",
             "models": [
                 {
                     "id": "doubao-seed-code-preview-251028",
@@ -504,6 +519,8 @@
             "baseUrl": "https://openrouter.ai/api/v1",
             "api": "openai-completions",
             "authEnv": "OPENROUTER_API_KEY",
+            "consoleUrl": "https://openrouter.ai/keys",
+            "signupUrl": "https://openrouter.ai/",
             "models": [
                 {
                     "id": "openrouter/auto",
@@ -525,6 +542,7 @@
             "baseUrl": "https://api.x.ai/v1",
             "api": "openai-completions",
             "authEnv": "XAI_API_KEY",
+            "consoleUrl": "https://console.x.ai/",
             "models": [
                 {
                     "id": "grok-4.3",
@@ -552,6 +570,7 @@
             "baseUrl": "https://api.mistral.ai/v1",
             "api": "openai-completions",
             "authEnv": "MISTRAL_API_KEY",
+            "consoleUrl": "https://console.mistral.ai/api-keys",
             "models": [
                 {
                     "id": "mistral-large-latest",
@@ -589,6 +608,7 @@
             "baseUrl": "https://api.groq.com/openai/v1",
             "api": "openai-completions",
             "authEnv": "GROQ_API_KEY",
+            "consoleUrl": "https://console.groq.com/keys",
             "models": [
                 {
                     "id": "groq/compound",
@@ -615,6 +635,7 @@
             "baseUrl": "https://api.together.xyz/v1",
             "api": "openai-completions",
             "authEnv": "TOGETHER_API_KEY",
+            "consoleUrl": "https://api.together.xyz/settings/api-keys",
             "models": [
                 {
                     "id": "moonshotai/Kimi-K2.6",
@@ -645,6 +666,7 @@
             "baseUrl": "https://api.fireworks.ai/inference/v1",
             "api": "openai-completions",
             "authEnv": "FIREWORKS_API_KEY",
+            "consoleUrl": "https://fireworks.ai/account/api-keys",
             "models": [
                 {
                     "id": "accounts/fireworks/models/kimi-k2p6",
@@ -691,6 +713,7 @@
             "baseUrl": "https://ark.ap-southeast.bytepluses.com/api/v3",
             "api": "openai-completions",
             "authEnv": "BYTEPLUS_API_KEY",
+            "consoleUrl": "https://console.byteplus.com/",
             "models": [
                 {
                     "id": "seed-1-8-251228",
@@ -717,6 +740,7 @@
             "baseUrl": "https://api.cerebras.ai/v1",
             "api": "openai-completions",
             "authEnv": "CEREBRAS_API_KEY",
+            "consoleUrl": "https://cloud.cerebras.ai/",
             "models": [
                 {
                     "id": "zai-glm-4.7",
@@ -775,6 +799,7 @@
             "baseUrl": "https://api.cohere.ai/compatibility/v1",
             "api": "openai-completions",
             "authEnv": "COHERE_API_KEY",
+            "consoleUrl": "https://dashboard.cohere.com/api-keys",
             "models": [
                 {
                     "id": "command-a-03-2025",
@@ -790,6 +815,7 @@
             "baseUrl": "https://api.deepinfra.com/v1/openai",
             "api": "openai-completions",
             "authEnv": "DEEPINFRA_API_KEY",
+            "consoleUrl": "https://deepinfra.com/dash/api_keys",
             "models": [
                 {
                     "id": "deepseek-ai/DeepSeek-V4-Flash",
@@ -842,6 +868,8 @@
             "baseUrl": "https://router.huggingface.co/v1",
             "api": "openai-completions",
             "authEnv": "HF_TOKEN",
+            "consoleUrl": "https://huggingface.co/settings/tokens",
+            "signupUrl": "https://huggingface.co/join",
             "models": [
                 {
                     "id": "deepseek-ai/DeepSeek-V3.1",
@@ -947,6 +975,7 @@
             "baseUrl": "https://integrate.api.nvidia.com/v1",
             "api": "openai-completions",
             "authEnv": "NVIDIA_API_KEY",
+            "consoleUrl": "https://build.nvidia.com/",
             "models": [
                 {
                     "id": "nvidia/nemotron-3-ultra-550b-a55b",
@@ -1064,6 +1093,7 @@
             "baseUrl": "https://api.stepfun.com/v1",
             "api": "openai-completions",
             "authEnv": "STEPFUN_API_KEY",
+            "consoleUrl": "https://platform.stepfun.com/",
             "models": [
                 {
                     "id": "step-3.5-flash",
@@ -1143,6 +1173,7 @@
             "baseUrl": "https://ai-gateway.vercel.sh",
             "api": "anthropic-messages",
             "authEnv": "AI_GATEWAY_API_KEY",
+            "consoleUrl": "https://vercel.com/dashboard",
             "models": [
                 {
                     "id": "anthropic/claude-opus-4.6",

package/dist/notifications.d.ts

@@ -182,9 +182,11 @@ type BgTaskStatusProbe = (taskId: string) => Promise<{
     terminal: boolean;
     status: string;
 } | null>;
+/** 委派 prompt 取件口(行消费端建行/详情页兜底用)。未登记 ⇒ undefined(诚实缺席)。 */
+export declare function outstandingBgTaskPrompt(taskId: string): string | undefined;
 export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void;
 /** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
-export declare function registerOutstandingBgTask(taskId: string, description: string): void;
+export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string): void;
 export declare function isOwnWorkflowRun(runId: string): boolean;
 /** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
  *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */

package/dist/notifications.js

@@ -388,12 +388,31 @@ export function installWorkflowStatusProbe(probe) {
 }
 const outstandingBgTasks = new Map();
 let bgStatusProbe = null;
+/**
+ * R4(clay 五报 07-31)委派 prompt 台账:`async_launched` 回执带全 {task_id, description, prompt}
+ * 三件,但此前 prompt 只进消息 payload(ctrl+o expand 那条腿),任务行/详情页(↓ manage)取不到,
+ * 只能绕道等引擎 running 期不发的 transcriptId 去转录读面捞 ⇒ Prompt 节恒空。
+ * 这里按行 id 记一份(与 fleet 行 rowIdTail 同 keyspace),行消费端建行时取用。
+ * 与 outstandingBgTasks 分开存:后者随通知摘除,prompt 在行的整个生命周期都要可取。
+ * process-lifetime 有界:bg 子代数量 = 人手派发量级,不设逐出。
+ */
+const bgTaskPrompts = new Map();
+/** 委派 prompt 取件口(行消费端建行/详情页兜底用)。未登记 ⇒ undefined(诚实缺席)。 */
+export function outstandingBgTaskPrompt(taskId) {
+    return bgTaskPrompts.get(taskId);
+}
 export function installBgTaskStatusProbe(probe) {
     bgStatusProbe = probe;
 }
 /** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
-export function registerOutstandingBgTask(taskId, description) {
-    if (!taskId || notifiedRunIds.has(taskId) || outstandingBgTasks.has(taskId))
+export function registerOutstandingBgTask(taskId, description, prompt) {
+    if (!taskId)
+        return;
+    // prompt 台账先记(与 watcher 登记的幂等早退解耦:重复回执/已通知任务的 prompt 仍要可取)。
+    if (typeof prompt === 'string' && prompt.length > 0 && !bgTaskPrompts.has(taskId)) {
+        bgTaskPrompts.set(taskId, prompt);
+    }
+    if (notifiedRunIds.has(taskId) || outstandingBgTasks.has(taskId))
         return;
     outstandingBgTasks.set(taskId, { registeredAt: Date.now(), description });
     ensureWatchTimer();

package/dist/toolResult.js

@@ -75,6 +75,13 @@ export const STRUCTURED_DETAIL_TYPES = new Set([
     'fork',
     'enter-plan-mode',
     'exit-plan-mode',
+    // core 2.7.0 跟车四型(engine-vocab 等值门抓获,[dep-bump-follow-on] 计数钉族):本表只判
+    // 「structured 在场」,switch 认不得的照旧走 text 回落 —— 加型=让正则反解对新卡退位,不加型
+    // =把引擎的结构化当裸对象。
+    'file_unchanged',
+    'worktree',
+    'monitor-start',
+    'path_not_in_root',
 ]);
 /** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
 export function structuredDetailType(structured) {
@@ -610,7 +617,7 @@ modelText) {
             if (agentId === undefined || typeof s.description !== 'string' || typeof s.prompt !== 'string') {
                 return null;
             }
-            registerOutstandingBgTask(agentId, s.description);
+            registerOutstandingBgTask(agentId, s.description, s.prompt);
             return {
                 toolUseResult: {
                     isAsync: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.16",
+  "version": "0.11.18",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",