@sema-agent/client-core 0.14.0 → 0.15.0

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.13.0
+**Version:** 0.14.0
 
 - **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
@@ -232,6 +232,7 @@ public-surface guard checks that last one).
 | `scripts/run-client-core-failloud-test.mjs` | §C1/§C2: an empty `catch` with no comment anywhere inside it, a pure-swallow `catch` nobody reasoned about, and `void <write>` that really returns a Promise with no `.catch`. The exemption instrument is a comment saying why *this* failure may die; the documented-swallow count is a ratchet that only goes down |
 | `scripts/run-client-core-typeshape-test.mjs` | Type discipline as a guard rather than a build side effect: the set of enabled strict knobs (one silently switched off is red), `tsc --noEmit`, and export-surface ratchets for inline anonymous shapes (≥3 members), `unknown` leaving the surface, and bare `unknown` returns — zero slack in either direction |
 | `scripts/run-client-core-singleton-test.mjs` | Module-level singletons ⇄ `docs/refactor/p1-scan/singleton-manifest.json`, **both directions**: an unregistered singleton is red (registering it forces someone to answer "what if this got duplicated"), a stale entry is red, and the `dupRisk: high` count only goes down |
+| `scripts/run-catalog-loader-gates-test.mjs` | The model-catalog candidate chain (`loadCatalogWithSources`) and the provider device-code seam: offline ⇒ `bundled` with an honest `online.reason`, a good source ⇒ `online` plus a cache write, a second offline run ⇒ `cacheHit`; the three hostile source shapes (malformed JSON, `schemaVersion: 99`, off-domain `http`) each fall through to the bundled table, and an off-allowlist target is **never dialled** — including a `302` to another host, proven by a real loopback server's hit counter staying at zero; a one-byte edit to `catalog.sha256` drops that source while an unavailable sidecar only warns; and the device-code poller's `pending → ok` / `expired` arms run against a real loopback HTTP server with an injected clock |
 | `scripts/run-abortable-sleep-test.mjs` | The shared `abortableSleep(ms, signal)` leaf (consumed by `workflowClient.ts` and `agentSession/backgroundView.ts`'s poll backoff): normal timeout resolution, immediate wake-up on `abort` mid-wait, `clearTimeout` really firing on that path, and a post-resolve late abort staying a no-op |
 
 Each suite carries a floor that only moves up — a refactor that stops executing a group of

package/dist/index.d.ts

@@ -223,5 +223,7 @@ export * from './seatContract.js';
 export * from './agentSession/contract.js';
 export * from './agentSession/backgroundView.js';
 export * from './model/catalog.js';
+export * from './model/catalogLoader.js';
+export * from './model/providerAuth.js';
 export * from './websearch/searchProviderPresets.js';
 export * from './env/localeGeo.js';

package/dist/index.js

@@ -324,6 +324,19 @@ export * from './agentSession/backgroundView.js';
 // 🔴 绝不半解析:schemaVersion 超区间/任一行形状坏 ⇒ 整份弃用走兜底(端渲「内置版本(离线)」
 //    靠 `source` + `online.reason`,所以「静默用兜底」在本层是可观测的)。
 export * from './model/catalog.js';
+// ── design/166(2026-08-04):目录客户端消费链 —— 候选链 loader + 供应商凭证双轨 seam ──────────
+// 🔴 `model/catalogLoader.ts` 是 catalog.ts 的**宿主面**,不是第二个解析器:候选链遍历 +
+//    传输硬门(https + 域白名单,**重定向目标过同一道门**)+ `catalog.sha256` 旁签 + 缓存信封,
+//    载荷判决(schemaVersion/逐行形状/整份弃)全部委托 `resolveModelCatalog`,一行不重写。
+// 🔴 缓存**落盘**走注入口 `CatalogCachePort`(本包 index 闭包零 Node 内建是机械门守着的硬法;
+//    tmp+rename 的原子性是实现方的契约,参考实现在 catalogLoader.ts 的类型注释里)。
+export * from './model/catalogLoader.js';
+// 🔴 `model/providerAuth.ts` 与 registry SSO(cloudAuth)**物理分文件、零共享代码**
+//    ([reuse-single-sso-no-parallel-auth]:它是模型供应商凭证轨,不是 sema 登录轨)。
+//    `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假:没有我们自己名下的 client_id 之前,
+//    填别的编辑器插件的 app id = 冒用,与 §6 判 C 档出局同一条判据),因此
+//    `supportsDeviceCodeAuth` 对每一家如实返回 false、UI 不显示该选项 —— 注册一家 = 加一行。
+export * from './model/providerAuth.js';
 // ── 搜索 provider 目录 + 地域预选(2026-07-31)──────────────────────────────────────────────────
 // `websearch/searchProviderPresets` = model 目录的**同形不同表**姊妹件:数据在 json、类型与查询
 // 在 ts。它编译出来的不是模型目录而是**引擎部署 env**(`WEB_SEARCH_*`)。

package/dist/model/catalogLoader.d.ts

@@ -0,0 +1,170 @@
+/**
+ * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
+ *
+ * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
+ *
+ * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
+ * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
+ * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
+ * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
+ *
+ *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
+ *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
+ *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
+ *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
+ *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
+ *
+ * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
+ * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
+ * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
+ * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
+ *
+ * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
+ *
+ * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
+ * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
+ * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
+ * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
+ * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
+ * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
+ * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
+ * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
+ * 是两件事,[honest-absence-not-fabricated-zero])。
+ *
+ * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
+ *
+ * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
+ * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
+ * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
+ * 真要「手动刷新」,直接再调一次本函数就是最新语义。
+ *
+ * ## 时钟
+ *
+ * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
+ * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
+ */
+import { type EnvLike } from '../hostEnv.js';
+import { type ModelCatalogResult, type OnlineCatalogDoc } from './catalog.js';
+import type { ProviderPreset } from './providerPresets.js';
+/**
+ * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
+ * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
+ * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
+ */
+export declare const DEFAULT_CATALOG_SOURCES: readonly string[];
+/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
+export declare const CATALOG_DEFAULT_HOSTS: readonly string[];
+/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
+export declare const CATALOG_SOURCES_ENV = "SEMA_CATALOG_SOURCES";
+/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
+export declare const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export declare const CATALOG_CACHE_RELATIVE_PATH = "cache/model-catalog.json";
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export declare const CATALOG_CACHE_STALE_MS: number;
+/**
+ * 单源的**传输层**结局。
+ *
+ * 🔴 它**不是**第二套 origin 词表:UI 渲染「目录从哪来」恒读 `ModelCatalogResult.source` +
+ * `online.reason` + `cacheHit`。本词表只服务于 **doctor 的逐源分诊**(「两跳分别为什么没成」),
+ * 那是 `catalog.ts` 的单 URL 视角在结构上说不出来的量 —— 它只有一个 `online` 结局位。
+ */
+export type CatalogSourceOutcome = 'ok' | 'insecure-url' | 'host-not-allowed' | 'redirect-blocked' | 'redirect-opaque' | 'redirect-loop' | 'http-error' | 'network-error' | 'invalid-json' | 'sha-mismatch';
+/** 一次逐源尝试的留痕(doctor 用;🔴 绝不带载荷内容,只带判决与被截断的 message)。 */
+export interface CatalogSourceAttempt {
+    url: string;
+    outcome: CatalogSourceOutcome;
+    /** HTTP 状态码(只在真收到响应时在场)。 */
+    status?: number;
+    /** 旁签是否**真的比对过**(只在 `outcome:'ok'` 时在场;false = sha 拿不到,已记 warn 放行)。 */
+    shaChecked?: boolean;
+    /** 人话细节(判决相关短语 / 被截断的错误 message)。 */
+    detail?: string;
+}
+/** 缓存文件的信封(design/166 §3)。`fetchedAt` 缺席 = 写入时宿主没给时钟。 */
+export interface CatalogCacheEnvelope {
+    fetchedAt?: number;
+    sourceUrl: string;
+    catalog: OnlineCatalogDoc;
+}
+/**
+ * 缓存口 —— 宿主注入(本包零 `node:fs`,理由见文件头)。
+ *
+ * `writeAtomic` 的契约是**原子替换**(临时文件 + rename),不是 `writeFile` 的别名:
+ * 半截文件会让下一次冷启动读到一份坏缓存。Node 宿主的参考实现:
+ * ```js
+ * async writeAtomic(path, text) {
+ *   await mkdir(dirname(path), { recursive: true })
+ *   const tmp = `${path}.${process.pid}.tmp`
+ *   await writeFile(tmp, text, 'utf8')
+ *   await rename(tmp, path)     // 同目录 rename = 原子
+ * }
+ * ```
+ * 两个动词都允许同步或异步实现;抛异常由 loader 收成 warning(缓存是纵深,不是主路径)。
+ */
+export interface CatalogCachePort {
+    read(path: string): string | null | Promise<string | null>;
+    writeAtomic(path: string, text: string): void | Promise<void>;
+}
+/** `loadCatalogWithSources` 的入参。 */
+export interface LoadCatalogOptions {
+    /** 缓存落点的根(`configHome/cache/model-catalog.json`)。缺席 ⇒ 缓存腿不启用。 */
+    configHome?: string;
+    /** 覆盖候选链(缺省 `DEFAULT_CATALOG_SOURCES`;env 恒赢本项,见 `resolveCatalogSources`)。 */
+    sources?: readonly string[];
+    /** 宿主 env(缺省 `hostEnv()`)。 */
+    env?: EnvLike;
+    /** 每源传输预算(缺省 `DEFAULT_CATALOG_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+    /** 宿主时钟。缺席 ⇒ 不算 ageMs、不写 fetchedAt、不判 stale(绝不偷读时钟)。 */
+    nowMs?: number;
+    /** 传输注入口(缺省全局 `fetch`;本包既有姿势 = limitsWire/detachWire 的 `fetchImpl`)。 */
+    fetchImpl?: typeof fetch;
+    /** 缓存口。缺席 ⇒ 缓存腿整条不启用(`cacheHit` 键缺席)。 */
+    cache?: CatalogCachePort;
+    /** 用户本地覆盖层,原样透传给 `resolveModelCatalog`。 */
+    overrides?: readonly ProviderPreset[];
+}
+/**
+ * 结果 = `ModelCatalogResult`(来源标注/新鲜度/合并表全归 catalog.ts)+ 宿主面四位。
+ * 🔴 只**加**位不改位:端渲染仍读 `source` / `online.reason`。
+ */
+export interface LoadedModelCatalog extends ModelCatalogResult {
+    /** 真正被吃下的那一跳(线上成功或缓存自述的来源);全败 ⇒ 缺席。 */
+    sourceUrl?: string;
+    /** 这份线上载荷是不是从缓存顶上来的。**缓存口缺席 ⇒ 本键缺席**(没查过 ≠ 查过没用上)。 */
+    cacheHit?: boolean;
+    /** 缓存是否已过 30 天(照用但如实标)。只在 `cacheHit:true` 且宿主给了时钟时在场。 */
+    cacheStale?: boolean;
+    /** 逐源留痕(doctor 分诊用)。 */
+    attempts: CatalogSourceAttempt[];
+    /** 非致命的诚实记账(sha 拿不到 / 缓存读写失败 / 缓存半截)。 */
+    warnings: string[];
+}
+/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
+export declare function parseCatalogSources(raw: string | undefined | null): string[];
+/** `resolveCatalogSources` 的入参。 */
+export interface ResolveCatalogSourcesOptions {
+    env?: EnvLike;
+    sources?: readonly string[];
+}
+/**
+ * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
+ * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
+ */
+export declare function resolveCatalogSources(opts?: ResolveCatalogSourcesOptions): string[];
+/**
+ * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
+ * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
+ * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
+ */
+export declare function isAllowedCatalogUrl(url: string, allowedHosts: ReadonlySet<string>): boolean;
+/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
+export declare function catalogShaUrlFor(catalogUrl: string): string;
+/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
+export declare function catalogCachePath(configHome: string): string;
+/**
+ * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
+ * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
+ */
+export declare function loadCatalogWithSources(opts?: LoadCatalogOptions): Promise<LoadedModelCatalog>;

package/dist/model/catalogLoader.js

@@ -0,0 +1,382 @@
+/**
+ * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
+ *
+ * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
+ *
+ * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
+ * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
+ * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
+ * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
+ *
+ *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
+ *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
+ *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
+ *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
+ *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
+ *
+ * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
+ * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
+ * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
+ * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
+ *
+ * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
+ *
+ * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
+ * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
+ * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
+ * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
+ * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
+ * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
+ * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
+ * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
+ * 是两件事,[honest-absence-not-fabricated-zero])。
+ *
+ * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
+ *
+ * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
+ * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
+ * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
+ * 真要「手动刷新」,直接再调一次本函数就是最新语义。
+ *
+ * ## 时钟
+ *
+ * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
+ * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
+ */
+import { hostEnv } from '../hostEnv.js';
+import { resolveModelCatalog, } from './catalog.js';
+/**
+ * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
+ * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
+ * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
+ */
+export const DEFAULT_CATALOG_SOURCES = [
+    'https://raw.githubusercontent.com/sema-agent/sema-model-catalog/main/dist/catalog.json',
+    'https://cdn.jsdelivr.net/gh/sema-agent/sema-model-catalog@main/dist/catalog.json',
+];
+/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
+export const CATALOG_DEFAULT_HOSTS = ['raw.githubusercontent.com', 'cdn.jsdelivr.net'];
+/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
+export const CATALOG_SOURCES_ENV = 'SEMA_CATALOG_SOURCES';
+/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
+export const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export const CATALOG_CACHE_RELATIVE_PATH = 'cache/model-catalog.json';
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export const CATALOG_CACHE_STALE_MS = 30 * 24 * 60 * 60 * 1000;
+/** 单源允许的重定向跳数上限(有界:302 环不许把 onboard 转死)。 */
+const MAX_REDIRECTS = 5;
+/** 异常 → 短 detail(只取 message 前段,绝不带栈、绝不带载荷;与 catalog.ts 同一口径)。 */
+function shortError(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}
+/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
+export function parseCatalogSources(raw) {
+    if (typeof raw !== 'string')
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
+ * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
+ */
+export function resolveCatalogSources(opts) {
+    const env = opts?.env ?? hostEnv();
+    const fromEnv = parseCatalogSources(env[CATALOG_SOURCES_ENV]);
+    if (fromEnv.length > 0)
+        return fromEnv;
+    const given = (opts?.sources ?? []).map((s) => s.trim()).filter((s) => s.length > 0);
+    if (given.length > 0)
+        return given;
+    return [...DEFAULT_CATALOG_SOURCES];
+}
+/** 取 URL 的 host(含 port);解析不动 ⇒ undefined。 */
+function hostOf(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        parsed = undefined; // 解析不动 = 不是合法 URL,调用方按「拒」处理(判决在 isAllowedCatalogUrl)
+    }
+    return parsed?.host;
+}
+/**
+ * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
+ * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
+ * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
+ */
+export function isAllowedCatalogUrl(url, allowedHosts) {
+    let parsed;
+    try {
+        parsed = new URL(url.trim());
+    }
+    catch {
+        parsed = undefined; // 非法 URL ⇒ 拒(下面那一行判它)
+    }
+    if (parsed === undefined)
+        return false;
+    if (parsed.protocol !== 'https:')
+        return false;
+    return allowedHosts.has(parsed.host);
+}
+/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
+export function catalogShaUrlFor(catalogUrl) {
+    return catalogUrl.endsWith('.json') ? `${catalogUrl.slice(0, -'.json'.length)}.sha256` : `${catalogUrl}.sha256`;
+}
+/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
+export function catalogCachePath(configHome) {
+    return `${configHome.replace(/\/+$/, '')}/${CATALOG_CACHE_RELATIVE_PATH}`;
+}
+/** SHA-256 hex(WebCrypto;Node 18+ 与浏览器都有。拿不到实现 ⇒ null = 本次不比对)。 */
+async function sha256Hex(text) {
+    const g = globalThis;
+    const subtle = g.crypto?.subtle;
+    const Enc = g.TextEncoder;
+    if (subtle === undefined || Enc === undefined)
+        return null;
+    const digest = await subtle.digest('SHA-256', new Enc().encode(text));
+    let out = '';
+    for (const b of new Uint8Array(digest))
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** sha 文件内容 → hex(容忍 `<hex>  <filename>` 的 shasum 形与大小写)。认不出 ⇒ null。 */
+function parseShaFile(text) {
+    const m = /\b([0-9a-fA-F]{64})\b/.exec(text);
+    return m?.[1] === undefined ? null : m[1].toLowerCase();
+}
+async function guardedGet(url, allowedHosts, fetchImpl, timeoutMs) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (!isAllowedCatalogUrl(current, allowedHosts)) {
+            const insecure = !/^https:/i.test(current.trim());
+            return {
+                outcome: hop === 0 ? (insecure ? 'insecure-url' : 'host-not-allowed') : 'redirect-blocked',
+                detail: hop === 0
+                    ? `source rejected before dialing: ${insecure ? 'not https' : `host not allowlisted (${hostOf(current) ?? 'unparsable'})`}`
+                    : `redirect target rejected: ${hostOf(current) ?? 'unparsable'}`,
+            };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        let dialError;
+        try {
+            // 🔴 `redirect:'manual'` 是这道门的**执行体**:默认的 'follow' 会让 undici/浏览器替我们
+            //    跟到域外去(白名单被 302 绕过);手动跟 = 每一跳都回到上面那道 isAllowedCatalogUrl。
+            res = await fetchImpl(current, { method: 'GET', redirect: 'manual', signal: controller.signal });
+        }
+        catch (e) {
+            dialError = shortError(e);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res === undefined)
+            return { outcome: 'network-error', detail: dialError ?? 'dial failed' };
+        // 浏览器的 `redirect:'manual'` 给的是 opaqueredirect(status 0、无头)——看不见目标就
+        // **拒**(fail-closed):看不见的重定向恰恰是这道门要防的那种。
+        if (res.status === 0)
+            return { outcome: 'redirect-opaque', status: 0, detail: 'opaque redirect: target not inspectable' };
+        if (res.status >= 300 && res.status < 400) {
+            const loc = res.headers.get('location');
+            if (loc === null || loc.length === 0) {
+                return { outcome: 'http-error', status: res.status, detail: 'redirect without Location' };
+            }
+            let next;
+            try {
+                next = new URL(loc, current).toString();
+            }
+            catch (e) {
+                return { outcome: 'redirect-blocked', status: res.status, detail: `unparsable Location: ${shortError(e)}` };
+            }
+            current = next;
+            continue;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            return { outcome: 'http-error', status: res.status, detail: `HTTP ${res.status}` };
+        }
+        let text;
+        let readError;
+        try {
+            text = await res.text();
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (text === undefined)
+            return { outcome: 'network-error', status: res.status, detail: readError ?? 'body read failed' };
+        return { outcome: 'ok', status: res.status, finalUrl: current, text };
+    }
+    return { outcome: 'redirect-loop', detail: `more than ${MAX_REDIRECTS} redirects` };
+}
+/**
+ * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
+ * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
+ */
+export async function loadCatalogWithSources(opts) {
+    const sources = resolveCatalogSources({
+        ...(opts?.env !== undefined ? { env: opts.env } : {}),
+        ...(opts?.sources !== undefined ? { sources: opts.sources } : {}),
+    });
+    // 白名单 = 默认两域 + **用户显式配置的源 host**(显式意愿=自担;doctor 如实标 user-configured)。
+    const allowedHosts = new Set(CATALOG_DEFAULT_HOSTS);
+    for (const s of sources) {
+        const h = hostOf(s);
+        if (h !== undefined)
+            allowedHosts.add(h);
+    }
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
+    const attempts = [];
+    const warnings = [];
+    let hit = null;
+    let lastDialed;
+    for (const src of sources) {
+        if (hit !== null)
+            break;
+        const got = await guardedGet(src, allowedHosts, fetchImpl, timeoutMs);
+        if (got.outcome !== 'insecure-url' && got.outcome !== 'host-not-allowed')
+            lastDialed = src;
+        if (got.outcome !== 'ok' || got.text === undefined) {
+            attempts.push({
+                url: src,
+                outcome: got.outcome,
+                ...(got.status !== undefined ? { status: got.status } : {}),
+                ...(got.detail !== undefined ? { detail: got.detail } : {}),
+            });
+            continue;
+        }
+        const finalUrl = got.finalUrl ?? src;
+        let doc;
+        let parseError;
+        try {
+            doc = JSON.parse(got.text);
+        }
+        catch (e) {
+            parseError = shortError(e);
+        }
+        if (parseError !== undefined) {
+            attempts.push({ url: src, outcome: 'invalid-json', ...(got.status !== undefined ? { status: got.status } : {}), detail: parseError });
+            continue;
+        }
+        // 旁签:同源同路径。拿不到 ⇒ 记 warn 放行(design/165 §4:它是防传输损坏的纵深,
+        // 不是防主动篡改 —— 把「拿不到」当「篡改」会让 CDN 的半更新窗把整条链打死)。
+        const shaGot = await guardedGet(catalogShaUrlFor(finalUrl), allowedHosts, fetchImpl, timeoutMs);
+        let shaChecked = false;
+        if (shaGot.outcome === 'ok' && shaGot.text !== undefined) {
+            const expected = parseShaFile(shaGot.text);
+            const actual = await sha256Hex(got.text);
+            if (expected === null) {
+                warnings.push(`catalog sha256 sidecar for ${finalUrl} is not a hex digest — payload accepted without the checksum`);
+            }
+            else if (actual === null) {
+                warnings.push('no WebCrypto SHA-256 in this host — catalog payload accepted without the checksum');
+            }
+            else if (expected !== actual) {
+                attempts.push({ url: src, outcome: 'sha-mismatch', detail: 'catalog.sha256 does not match the payload digest' });
+                continue;
+            }
+            else {
+                shaChecked = true;
+            }
+        }
+        else {
+            warnings.push(`catalog sha256 sidecar unavailable for ${finalUrl} (${shaGot.outcome}) — payload accepted without the checksum`);
+        }
+        attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
+        hit = { url: finalUrl, doc, raw: got.text, shaChecked };
+    }
+    // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
+    const cache = opts?.cache;
+    const cachePath = opts?.configHome !== undefined ? catalogCachePath(opts.configHome) : undefined;
+    let cacheHit = cache !== undefined ? false : undefined;
+    let cacheStale;
+    let cachedSourceUrl;
+    if (hit === null && cache !== undefined && cachePath !== undefined) {
+        let text = null;
+        let readError;
+        try {
+            text = await cache.read(cachePath);
+        }
+        catch (e) {
+            readError = shortError(e);
+        }
+        if (readError !== undefined)
+            warnings.push(`catalog cache read failed: ${readError}`);
+        if (typeof text === 'string' && text.length > 0) {
+            let env;
+            let envError;
+            try {
+                env = JSON.parse(text);
+            }
+            catch (e) {
+                envError = shortError(e);
+            }
+            if (envError !== undefined)
+                warnings.push(`catalog cache is not parsable JSON (ignored): ${envError}`);
+            const doc = env?.catalog;
+            const url = env?.sourceUrl;
+            if (doc !== undefined && typeof url === 'string' && url.length > 0) {
+                // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
+                // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
+                hit = { url, doc, raw: text, shaChecked: false };
+                cacheHit = true;
+                cachedSourceUrl = url;
+                if (opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number') {
+                    cacheStale = opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS;
+                }
+            }
+            else if (envError === undefined) {
+                warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
+            }
+        }
+    }
+    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
+    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
+    // 校验与合并是它的活,两边不重叠也不互相重写。
+    const payload = hit;
+    const onlineUrl = payload?.url ?? lastDialed ?? sources[0];
+    const resolveOpts = {
+        ...(onlineUrl !== undefined ? { onlineUrl } : {}),
+        fetchJson: async () => {
+            if (payload === null)
+                throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
+            return payload.doc;
+        },
+        ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
+        ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+    };
+    const base = await resolveModelCatalog(resolveOpts);
+    // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
+    // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
+    if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {
+        const envelope = {
+            ...(opts?.nowMs !== undefined ? { fetchedAt: opts.nowMs } : {}),
+            sourceUrl: payload.url,
+            catalog: payload.doc,
+        };
+        let writeError;
+        try {
+            await cache.writeAtomic(cachePath, JSON.stringify(envelope));
+        }
+        catch (e) {
+            writeError = shortError(e);
+        }
+        if (writeError !== undefined)
+            warnings.push(`catalog cache write failed: ${writeError}`);
+    }
+    const sourceUrl = base.online.ok ? (cachedSourceUrl ?? payload?.url) : undefined;
+    return {
+        ...base,
+        ...(sourceUrl !== undefined ? { sourceUrl } : {}),
+        ...(cacheHit !== undefined ? { cacheHit } : {}),
+        ...(cacheStale !== undefined ? { cacheStale } : {}),
+        attempts,
+        warnings,
+    };
+}

package/dist/model/providerAuth.d.ts

@@ -0,0 +1,155 @@
+/**
+ * providerAuth.ts — **模型供应商凭证轨**的双轨 seam(design/166 §5「B 档:设备码流」,2026-08-04)。
+ *
+ * ## 边界(先说清楚它**不是**什么)
+ *
+ * 🔴 [reuse-single-sso-no-parallel-auth]:registry SSO(cloudAuth,「登录 sema」那条)**绝不复用、
+ * 绝不被改造**。本文件是**模型供应商**的凭证轨(拿一把 API key 去调某家模型),与 registry 登录轨
+ * 物理分文件、零共享代码。两者唯一的相似点是「都会弹一个浏览器」,那不构成复用理由。
+ *
+ * 🔴 design/166 §6 已定谳:**授权码 + PKCE(C 档)不做、不留 seam、不留枚举位** —— Anthropic 侧
+ * 条款明文禁止第三方代理其订阅凭证,而公开实现全都依赖冒用官方 client_id + 伪装 UA。本文件里
+ * 因此**只有** api_key 与 device_code 两轨,没有第三个 kind 位。
+ *
+ * ## 能力真值 = 目录键 ∧ 包内实现(两者与)
+ *
+ * 目录(design/165 §2)里的 `deviceAuth` 键**只是能力开关**,client_id 与端点**绝不目录化下发**
+ * (远端可改鉴权端点 = 钓鱼面)。所以 UI 是否显示「Sign in with device code」的判据是
+ * `supportsDeviceCodeAuth(id, preset.deviceAuth)`:
+ *   · 目录说有、包里没有 ⇒ **不显示**(防目录先行造出一个点了没反应的假 affordance);
+ *   · 包里有、目录没说 ⇒ **不显示**(那家还没被目录确认支持)。
+ *
+ * ## 🔴 `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假 —— 这是有意的,不是没写完)
+ *
+ * 设计档写「首发 1 家:GitHub Copilot 形」。落码时的事实是:device flow 需要一个 **client_id**,
+ * 而公开可查到的 Copilot client_id 全部是**别的编辑器插件自己的** app id(copilot.vim / VS Code
+ * 扩展)。把它们编进我们的包 = 以别人的 app 身份向 GitHub 发起授权,与 §6 判 C 档出局时用的
+ * **同一条判据**(「冒用官方 client_id」是主动欺骗,不是灰区)。我们自己名下的 OAuth app 尚未
+ * 申请 ⇒ 这一格的诚实值是**空**,而不是先填一个能跑的别人的号。
+ *
+ * 空表不是把这条腿废了:轮询器、退避、上限、终态词表全部在位并被门覆盖(门用一份合成 descriptor
+ * 跑真 HTTP)。**注册一家 = 往这张表加一行**,零代码改动。在那之前 `supportsDeviceCodeAuth`
+ * 对每一家如实返回 false,UI 不显示该选项 —— 这正是「能力真值 = 两者与」自带的正确降级。
+ *
+ * ## key 到手之后
+ *
+ * 🔴 **落盘不在包内做**。`poll()` 把 key 原样返给宿主,宿主走**与手填完全相同的那条路径**
+ * (壳 = `applyOnboard.ts` 写 settings `env.MODEL_API_KEY`)。两树都没有 auth.json 实体,
+ * 本文件也不新建任何持久面(design/166 §5 复核 M4:零新持久面,禁造)。
+ */
+import type { ProviderPreset, ProviderDeviceAuthHint } from './providerPresets.js';
+/**
+ * 一个 provider 可用的凭证轨。
+ * `api_key` 是现状唯一轨(手填,env 名来自 preset.authEnv);`device_code` 是 B 档新轨。
+ */
+export type ProviderAuthMethod = {
+    kind: 'api_key';
+    env: string;
+} | {
+    kind: 'device_code';
+    providerId: string;
+};
+/**
+ * 设备码端点三件套 —— **编译进包**(design/165 §2 红线:client_id / token 端点 / authorize 端点
+ * 一律不进目录)。
+ */
+export interface DeviceCodeEndpoints {
+    clientId: string;
+    /** RFC 8628 device authorization endpoint。 */
+    deviceCodeUrl: string;
+    /** token endpoint(轮询这一个)。 */
+    tokenUrl: string;
+    /** 申请的 scope(留空 = 不发这个参数)。 */
+    scope?: string;
+}
+/** 包内登记的一家设备码 provider。 */
+export interface DeviceAuthProvider {
+    /** 与目录/preset 的 `id` 同一个命名空间(用户 settings 里的持久引用)。 */
+    providerId: string;
+    label: string;
+    endpoints: DeviceCodeEndpoints;
+}
+/**
+ * 包内实现的设备码 provider 表。
+ * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
+ * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
+ */
+export declare const DEVICE_AUTH_PROVIDERS: readonly DeviceAuthProvider[];
+/** 包内是否实现了这一家(能力真值的一半)。 */
+export declare function deviceAuthProviderFor(providerId: string): DeviceAuthProvider | undefined;
+/**
+ * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
+ * 任一缺席 ⇒ false(见文件头「能力真值」段)。
+ */
+export declare function supportsDeviceCodeAuth(providerId: string, catalogHint: ProviderDeviceAuthHint | undefined): boolean;
+/**
+ * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
+ */
+export declare function providerAuthMethods(preset: ProviderPreset): ProviderAuthMethod[];
+/**
+ * 一次 `poll()` 的结局。
+ *
+ * 🔴 比设计档草案多两个终态,理由是诚实:草案只有 `pending|ok|expired`,于是
+ * 「用户点了拒绝」与「会话被本地取消」都只能冒充 `expired`(= 骗用户「过期了,再来一次」,
+ * 而事实是再来一次还会被拒 / 是他自己取消的)。两者各占一位:
+ *   · `denied`    —— 授权服务器说 access_denied;
+ *   · `cancelled` —— 本地调过 `cancel()`。
+ */
+export type DeviceCodeStatus = 'pending' | 'ok' | 'expired' | 'denied' | 'cancelled';
+export interface DeviceCodePollResult {
+    status: DeviceCodeStatus;
+    /** 只在 `ok` 时在场。🔴 宿主拿去走与手填同一条落盘路径;包内零持久面。 */
+    key?: string;
+    /** 人话细节(分诊用;绝不带 key、绝不带完整响应体)。 */
+    detail?: string;
+}
+/**
+ * 一次设备码会话。**宿主驱动**:UI 渲大字码 + URL,自己按 `intervalMs` 起节拍调 `poll()`
+ * (等待型判据,不固定拍)。包内不起定时器 —— 定时器是宿主资产(与 `TimersPort` 同一条纪律)。
+ */
+export interface DeviceCodeSession {
+    /** 用户要在浏览器里输入的大字码。 */
+    userCode: string;
+    /** 用户要打开的验证页。 */
+    verificationUrl: string;
+    /** 建议轮询间隔(毫秒)。429 / slow_down 之后会**变大**,宿主每拍都该重读这个值。 */
+    intervalMs: number;
+    /** 本会话的墙钟终点(min(服务端 expires_in, 15min 上限))。 */
+    expiresAtMs: number;
+    poll(): Promise<DeviceCodePollResult>;
+    cancel(): void;
+}
+/**
+ * 设备码流的宿主注入面。
+ * 🔴 `nowMs` **必填**:5s 间隔与 15min 上限都是墙钟判据,而本包绝不偷读时钟
+ * (与 `catalog.ts` / `AdapterContext.now` 同一口径)。宿主传 `() => Date.now()`。
+ */
+export interface DeviceCodeAuthOptions {
+    nowMs: () => number;
+    /** 传输注入口(缺省全局 `fetch`)。 */
+    fetchImpl?: typeof fetch;
+    /** 单次 HTTP 预算(缺省 `DEVICE_CODE_HTTP_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+}
+/** 轮询间隔下限(RFC 8628 建议 5s;服务端给更大的值时听服务端的)。 */
+export declare const DEVICE_CODE_MIN_INTERVAL_MS = 5000;
+/** 会话墙钟上限(design/166 §5:15min)。服务端 `expires_in` 更短时听服务端的。 */
+export declare const DEVICE_CODE_MAX_LIFETIME_MS: number;
+/** 429 / slow_down 的退避增量(RFC 8628 §3.5 就是「加 5 秒」)。 */
+export declare const DEVICE_CODE_BACKOFF_STEP_MS = 5000;
+/** 单次 HTTP 预算。 */
+export declare const DEVICE_CODE_HTTP_TIMEOUT_MS = 10000;
+/**
+ * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
+ * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
+ * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
+ *
+ * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
+ * 绝不返回一个永远 pending 的假会话。
+ */
+export declare function openDeviceCodeSession(endpoints: DeviceCodeEndpoints, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;
+/**
+ * 按 providerId 开设备码会话(UI 入口)。
+ * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
+ */
+export declare function beginDeviceCodeAuth(providerId: string, opts: DeviceCodeAuthOptions): Promise<DeviceCodeSession>;

package/dist/model/providerAuth.js

@@ -0,0 +1,190 @@
+/**
+ * 包内实现的设备码 provider 表。
+ * 🔴 **今天是空的,理由见文件头**(宁空勿假:没有我们自己名下的 client_id 之前,填一行 = 冒用)。
+ * 加一家 = 加一行;端点必须 https(门 ④a 逐行校)。
+ */
+export const DEVICE_AUTH_PROVIDERS = [];
+/** 包内是否实现了这一家(能力真值的一半)。 */
+export function deviceAuthProviderFor(providerId) {
+    return DEVICE_AUTH_PROVIDERS.find((p) => p.providerId === providerId);
+}
+/**
+ * UI 是否显示「设备码登录」= **目录说有** ∧ **包里有实现**。
+ * 任一缺席 ⇒ false(见文件头「能力真值」段)。
+ */
+export function supportsDeviceCodeAuth(providerId, catalogHint) {
+    if (catalogHint?.kind !== 'device_code')
+        return false;
+    return deviceAuthProviderFor(providerId) !== undefined;
+}
+/**
+ * 一家 provider 摆给用户的轨(顺序 = UI 呈现序)。`api_key` 恒在;`device_code` 只在能力真值成立时出。
+ */
+export function providerAuthMethods(preset) {
+    const out = [{ kind: 'api_key', env: preset.authEnv }];
+    if (supportsDeviceCodeAuth(preset.id, preset.deviceAuth)) {
+        out.push({ kind: 'device_code', providerId: preset.id });
+    }
+    return out;
+}
+/** 轮询间隔下限(RFC 8628 建议 5s;服务端给更大的值时听服务端的)。 */
+export const DEVICE_CODE_MIN_INTERVAL_MS = 5000;
+/** 会话墙钟上限(design/166 §5:15min)。服务端 `expires_in` 更短时听服务端的。 */
+export const DEVICE_CODE_MAX_LIFETIME_MS = 15 * 60 * 1000;
+/** 429 / slow_down 的退避增量(RFC 8628 §3.5 就是「加 5 秒」)。 */
+export const DEVICE_CODE_BACKOFF_STEP_MS = 5000;
+/** 单次 HTTP 预算。 */
+export const DEVICE_CODE_HTTP_TIMEOUT_MS = 10_000;
+/** 异常 → 短 detail(绝不带栈、绝不带响应体)。 */
+function shortError(e) {
+    return (e instanceof Error ? e.message : String(e)).slice(0, 160);
+}
+/** POST application/x-www-form-urlencoded,收 JSON。返回 {status, body}(body 解析不动 ⇒ null)。 */
+async function postForm(url, form, fetchImpl, timeoutMs, signal) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    if (signal.aborted)
+        controller.abort();
+    else
+        signal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { accept: 'application/json', 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(form).toString(),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = null; // 非 JSON 响应 ⇒ 当作「说不出所以然」,由调用方按 status 判(绝不回显正文)
+        }
+        return { status: res.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * 开一次设备码会话 —— **端点由调用方给**(包内表里那一行,或门的合成 descriptor)。
+ * 🔴 端点是**编译进包的常量**,不是远端数据,所以本函数不对它再做白名单;真正的门是
+ * 「client_id/端点绝不目录化下发」(design/165 §2 红线)+ 表内每行必须 https(门 ④a)。
+ *
+ * 失败(网络 / 非 2xx / 缺 user_code)⇒ **throw**(§C1 三选一里的 throw):开不出会话就是开不出,
+ * 绝不返回一个永远 pending 的假会话。
+ */
+export async function openDeviceCodeSession(endpoints, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? DEVICE_CODE_HTTP_TIMEOUT_MS;
+    const abort = new AbortController();
+    const started = opts.nowMs();
+    const { status, body } = await postForm(endpoints.deviceCodeUrl, { client_id: endpoints.clientId, ...(endpoints.scope !== undefined ? { scope: endpoints.scope } : {}) }, fetchImpl, timeoutMs, abort.signal);
+    if (status < 200 || status >= 300) {
+        throw new Error(`device code request failed: HTTP ${status}`);
+    }
+    const grant = (body ?? {});
+    const deviceCode = typeof grant.device_code === 'string' ? grant.device_code : '';
+    const userCode = typeof grant.user_code === 'string' ? grant.user_code : '';
+    const verificationUrl = typeof grant.verification_uri_complete === 'string'
+        ? grant.verification_uri_complete
+        : typeof grant.verification_uri === 'string'
+            ? grant.verification_uri
+            : '';
+    if (deviceCode === '' || userCode === '' || verificationUrl === '') {
+        throw new Error('device code response missing device_code / user_code / verification_uri');
+    }
+    const serverLifetimeMs = typeof grant.expires_in === 'number' && grant.expires_in > 0 ? grant.expires_in * 1000 : undefined;
+    const lifetimeMs = Math.min(serverLifetimeMs ?? DEVICE_CODE_MAX_LIFETIME_MS, DEVICE_CODE_MAX_LIFETIME_MS);
+    const serverInterval = typeof grant.interval === 'number' && grant.interval > 0 ? grant.interval * 1000 : undefined;
+    const session = {
+        userCode,
+        verificationUrl,
+        intervalMs: Math.max(serverInterval ?? DEVICE_CODE_MIN_INTERVAL_MS, DEVICE_CODE_MIN_INTERVAL_MS),
+        expiresAtMs: started + lifetimeMs,
+        poll: async () => poll(),
+        cancel: () => {
+            if (terminal === null)
+                terminal = { status: 'cancelled', detail: 'cancelled by the host' };
+            abort.abort();
+        },
+    };
+    /** 终态一旦落定就恒定(拿到 key 之后再 poll 不重复拨号)。 */
+    let terminal = null;
+    /** 下一次允许真正拨号的墙钟时刻(间隔是硬的,不靠调用方自律)。 */
+    let nextDialAtMs = started;
+    async function poll() {
+        if (terminal !== null)
+            return terminal;
+        const now = opts.nowMs();
+        if (now >= session.expiresAtMs) {
+            // 本地上限先于服务端判:上限是我们对用户的承诺,不该靠服务端良心。
+            terminal = { status: 'expired', detail: 'device code session exceeded its lifetime — start a new one' };
+            return terminal;
+        }
+        if (now < nextDialAtMs) {
+            return { status: 'pending', detail: 'polled before the interval elapsed — no request was sent' };
+        }
+        let res;
+        try {
+            res = await postForm(endpoints.tokenUrl, {
+                client_id: endpoints.clientId,
+                device_code: deviceCode,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            }, fetchImpl, timeoutMs, abort.signal);
+        }
+        catch (e) {
+            if (terminal !== null)
+                return terminal; // cancel() 把在飞请求打断了 —— 终态已落定
+            // 单次网络失败不是终态:设备码流本就是长轮询,下一拍再试(退避一格避免打点)。
+            nextDialAtMs = opts.nowMs() + session.intervalMs;
+            return { status: 'pending', detail: `poll failed, will retry: ${shortError(e)}` };
+        }
+        if (terminal !== null)
+            return terminal;
+        nextDialAtMs = opts.nowMs() + session.intervalMs;
+        const token = (res.body ?? {});
+        const err = typeof token.error === 'string' ? token.error : '';
+        if (res.status === 429 || err === 'slow_down') {
+            session.intervalMs += DEVICE_CODE_BACKOFF_STEP_MS;
+            nextDialAtMs = opts.nowMs() + session.intervalMs;
+            return { status: 'pending', detail: 'rate limited — backing off' };
+        }
+        if (typeof token.access_token === 'string' && token.access_token.length > 0) {
+            terminal = { status: 'ok', key: token.access_token };
+            return terminal;
+        }
+        if (err === 'authorization_pending')
+            return { status: 'pending' };
+        if (err === 'expired_token') {
+            terminal = { status: 'expired', detail: 'the device code expired — start a new one' };
+            return terminal;
+        }
+        if (err === 'access_denied') {
+            terminal = { status: 'denied', detail: 'the user declined the authorization request' };
+            return terminal;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            return { status: 'pending', detail: `poll got HTTP ${res.status}, will retry` };
+        }
+        // 认不出的 error 码:不冒充终态(别把一个我们没见过的码说成「过期了」),下一拍再试。
+        return { status: 'pending', detail: err === '' ? 'unrecognised token response' : `unrecognised error: ${err}` };
+    }
+    return session;
+}
+/**
+ * 按 providerId 开设备码会话(UI 入口)。
+ * 包内没有这一家 ⇒ **throw**(UI 本就不该显示这个选项;走到这里说明能力判据被绕过了)。
+ */
+export async function beginDeviceCodeAuth(providerId, opts) {
+    const provider = deviceAuthProviderFor(providerId);
+    if (provider === undefined) {
+        throw new Error(`device code auth is not supported for provider "${providerId}" in this build ` +
+            '(DEVICE_AUTH_PROVIDERS has no entry — the UI must gate on supportsDeviceCodeAuth())');
+    }
+    return openDeviceCodeSession(provider.endpoints, opts);
+}

package/dist/model/providerPresets.d.ts

@@ -25,7 +25,23 @@ export type ProviderPreset = {
     consoleUrl?: string;
     /** 没账号时的注册入口。与 `consoleUrl` 同页的家不重复填(缺席 = 用 consoleUrl 那条)。 */
     signupUrl?: string;
+    /**
+     * 🆕 design/165 §2 + design/166 §5(2026-08-04):**设备码能力开关**(B 档)。
+     *
+     * 🔴 它只是**开关**,不携带 client_id / token 端点 / authorize 端点 —— 那些编译进
+     * `model/providerAuth.ts` 的 `DEVICE_AUTH_PROVIDERS`。理由:目录是远端可改的数据,
+     * 让它决定鉴权端点 = 把钓鱼面下发给客户端(design/165 §2 红线④,CI 的 validate.mjs
+     * 里有对应的机械不变式)。
+     * 🔴 能力真值 = **本键在场 ∧ 包内有实现**(`supportsDeviceCodeAuth`)——目录先行不造 affordance。
+     */
+    deviceAuth?: ProviderDeviceAuthHint;
 };
+/** 目录里的设备码能力开关(只有 kind 与文档链接;凭证参数一律不进目录)。 */
+export interface ProviderDeviceAuthHint {
+    kind: 'device_code';
+    /** 该家自己的设备码说明页(纯链接;拿不准就不填,绝不编 URL)。 */
+    docsUrl?: string;
+}
 export type ModelFamily = {
     id: string;
     name: string;

package/package.json

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