@sema-agent/client-core 0.11.17 → 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.17
+**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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.17",
+  "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",