@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/engineWireSdk.js

@@ -1,29 +1,5 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/engineWireSdk.ts 逐字搬入(纯半场 client 工厂;agentsWireCaps 的静态依赖,故同批过来)。
- */
-/**
- * engineWireSdk — SDK 宪法迁移批(0.0.52)的纯半场 client 工厂:壳内各 wire 子模块(compact/steer/
- * plan-review/auto-title/recap/caps 探测)从手抄 raw fetch 改接 @sema-agent/sdk AgentClient 的共用
- * 构造点。ZERO 产品依赖(只 import 外部零依赖 SDK)——agentsWireCaps/liveInitToolFace 等「纯半场/
- * 零产品图」模块可安全 import,不拖 engineTarget 的 fs 图,亦无循环依赖。
- *
- * 凭证解析 = engineTarget.resolveLiveAuthToken 的逐字镜像(#118 三态;那边是产品半场真源,这里为
- * 纯半场复刻,两处语义必须一致):
- *   · token 有            → 原样 Bearer;
- *   · 无 token ∧ loopback → { mode: 'loopback-unauthed' }(出站零 Authorization 头,绝不伪造);
- *   · 无 token ∧ 非 loopback → 'anon'(fail-closed worker 换来诚实 401;与主车道 replEntry 同姿势)。
- * ⚠️ 迁移差分记账:旧 raw fetch 在「无 token ∧ 非 loopback」时不带任何 Authorization 头;SDK 恒需
- * 合法 authToken 形,这里按主车道姿势出 'anon'——该态本就是残破配置(connect 未登录),两种姿势对
- * fail-closed worker 都是 401,对 owner-gated 路由都是 owner 不匹配,行为面等价。
- *
- * 缺省 maxRetries=0:raw fetch 原语义是单发不重试(探针有自己的预算窗;fire-and-forget 不该静默
- * 翻倍打点)。要 SDK 缺省重试的调用方显式传。principal 缺席=不发头(F-011 停发,replEntry live 车道
- * 同款)——SDK Transport 恒 stamp x-agent-principal(principal-first 宪法);旧 raw fetch 在缺
- * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
- */
 import { AgentClient } from '@sema-agent/sdk';
 import { normalizeWirePrincipal } from './principalWire.js';
-/** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
 export function isLoopbackWireUrl(url) {
     try {
         const h = new URL(url).hostname;
@@ -33,24 +9,6 @@ export function isLoopbackWireUrl(url) {
         return false;
     }
 }
-/**
- * §8-2 定谳的**唯一**凭证解析口(B4 收编)—— 11 处构造点的公共分母。
- *
- * 背景(设计稿 §8-2 + B4 实测):壳里今天是 **2 份三态解析**(`engineTarget.resolveLiveAuthToken`
- * 产品半场 + 本包 `wireAuthTokenFor` 纯半场,后者头注自述是前者的「逐字镜像」⇒ 两份必然漂移)
- * 外加 **11 处 `new AgentClient` 直造**,其中 7 处根本不走任何解析口,直接手写
- * `token ?? { mode:'loopback-unauthed' }` —— 那一形**丢了 'anon' 那一态**:非 loopback 且无 token
- * 时它给的是 loopback-unauthed(出站零 Authorization 头),而三态解析给 'anon'。对 fail-closed
- * worker 两者都是 401,但对 **owner-gated 路由**不是同一回事,所以这是真分歧不是等价写法。
- *
- * 🔴 **env 缺省留在端上**:`resolveLiveAuthToken` 的第二参缺省是 `process.env.SEMA_LIVE_TOKEN`,
- * 那一半**绝不进包**(本包零 `process.env` —— portability 门盯着)。壳侧 shim 保留缺省参即可:
- * `resolveLiveAuthToken(u, t = process.env.SEMA_LIVE_TOKEN) => resolveWireAuth(u, t)`。
- *
- * 三态(#118):token 有 ⇒ 原样 Bearer;无 token ∧ loopback ⇒ `{mode:'loopback-unauthed'}`
- * (出站零 Authorization 头,绝不伪造);无 token ∧ 非 loopback ⇒ `'anon'`(fail-closed 换诚实 401)。
- * `baseUrl` 允许 undefined(= `resolveLiveAuthToken` 的签名超集,本地自 spawn 态)⇒ 'anon'。
- */
 export function resolveWireAuth(baseUrl, token) {
     if (token)
         return token;
@@ -58,16 +16,9 @@ export function resolveWireAuth(baseUrl, token) {
         return { mode: 'loopback-unauthed' };
     return 'anon';
 }
-/**
- * #118 三态凭证解析(旧名,B2 引入)。
- * B4 起是 `resolveWireAuth` 的**别名**(baseUrl 必填的窄签名);两者行为逐字相同,保留是为了
- * 壳侧既有 import 零改动 —— 不设代际让位([clean-cut-no-legacy-compat] 只约束**行为面**硬切,
- * 同一函数的两个名字不是两套行为)。新代码一律用 `resolveWireAuth`。
- */
 export function wireAuthTokenFor(baseUrl, token) {
     return resolveWireAuth(baseUrl, token);
 }
-/** 出站头的**归一读写**(SDK 的传输层给的是普通对象,但入参形状是 `HeadersInit` 三形之一)。 */
 function headersToRecord(init) {
     const out = {};
     if (init === undefined)
@@ -89,16 +40,6 @@ function headersToRecord(init) {
         out[String(k).toLowerCase()] = String(v);
     return out;
 }
-/**
- * 把一个 `fetch` 包一层:**每一发出站请求**重读凭证并就地改写 Authorization 头。
- *
- * 🔴 为什么是包 `fetch` 而不是「构造时解析一次」:底层客户端把凭证捕获进构造期闭包,构造时解析
- *    等于把快照换了个位置放 —— 换代之后照样发旧凭证。请求那一刻才是**决定结果的时刻**。
- * 🔴 三态在这一层逐格重演(与 {@link resolveWireAuth} 同一只):串 ⇒ `Bearer <串>`;
- *    `{mode:'loopback-unauthed'}` ⇒ **删**掉 Authorization 头(绝不伪造一个)。
- * 🔴 取值函数抛错 ⇒ 当「这一刻没有凭证」处置(fail-soft):一个坏掉的取值口不该让整条 wire 不可用,
- *    而且异常里可能夹带凭证材料,原样上抛就是又一条外溢面。
- */
 function withPerRequestAuth(baseUrl, read, inner) {
     return async (input, init) => {
         let token;
@@ -106,7 +47,6 @@ function withPerRequestAuth(baseUrl, read, inner) {
             token = read();
         }
         catch {
-            // fail-soft:取不到就按无 token 走三态(理由见本函数头注第三条)。
             token = undefined;
         }
         const resolved = resolveWireAuth(baseUrl, token);
@@ -118,20 +58,13 @@ function withPerRequestAuth(baseUrl, read, inner) {
         return inner(input, { ...init, headers });
     };
 }
-/**
- * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
- * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
- */
 export function makeEngineWireClient(cfg) {
     try {
         const principal = normalizeWirePrincipal(cfg.principal);
-        // 取值函数形:出站腿包一层「每发一次读一次」;构造期**一次都不读**(读一次就是一次快照)。
         const source = typeof cfg.token === 'function' ? cfg.token : null;
         const innerFetch = cfg.fetchImpl ?? fetch;
         const base = {
             baseUrl: cfg.baseUrl,
-            // F-011 停发:缺席/空串=不给键(SDK 6.11 缺席=不发 x-agent-principal 头,owner-null)。
-            // A-028.10(0.30.3):空串判升级为 trim 判(principalWire 同尺)——全空白值同罪,归缺席。
             ...(principal !== undefined ? { principal } : {}),
             ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
             maxRetries: cfg.maxRetries ?? 0,
@@ -141,18 +74,11 @@ export function makeEngineWireClient(cfg) {
                     ? { fetch: cfg.fetchImpl }
                     : {}),
         };
-        // relay 形直传(显式声明,不过三态解析);串/缺席走 resolveWireAuth 三态,语义与 0.28.x 字节
-        // 不变。分支构造而非三元合流:SDK AgentClientConfig 按 authToken 判别联合,联合值不可直赋。
         if (typeof cfg.token === 'object')
             return new AgentClient({ ...base, authToken: cfg.token });
         if (source !== null) {
-            // 🔴 构造期给的是**不读取值函数**的三态形(回环 ⇒ loopback-unauthed;非回环 ⇒ 匿名身份)。
-            //    它只用来过 SDK 的构造期形校验与浏览器守卫 —— 真正上 wire 的那一份由上面那层每发重写,
-            //    所以这里绝不能顺手调一次取值函数:调了就多一次「与任何请求都不对应」的读取,
-            //    而「读取次数 = 请求次数」正是本形的可验证承诺(见 run-wire-auth-source-test.mjs G2)。
             return new AgentClient({ ...base, authToken: resolveWireAuth(cfg.baseUrl, undefined) });
         }
-        // 到这里 `cfg.token` 只可能是串或缺席(对象形与函数形都已在上面分流),类型面收窄靠一次显式判。
         const literal = typeof cfg.token === 'string' ? cfg.token : undefined;
         return new AgentClient({ ...base, authToken: resolveWireAuth(cfg.baseUrl, literal) });
     }

package/dist/engineWireTarget.d.ts

@@ -1,24 +1,10 @@
 export interface EngineWireTarget {
     baseUrl: string;
     token?: string;
-    /** 缺席=不发 x-agent-principal 头(owner-null,F-011 停发);显式装配/env 值恒赢。
-     *  A-028.10(0.30.3):在场性按 trim 判(principalWire 原语)——全空白值在**读出口**归缺席,
-     *  绝不发全空白头(裁定=壳 livePrincipal trim 语义为正)。 */
     principal?: string;
 }
-/** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */
 export declare function installEngineWireTarget(t: EngineWireTarget | null): () => void;
-/** W1 带 key 变体:装/卸某会话的引擎 wire 目标(多会话宿主每会话一键,互不顶盖)。 */
 export declare function installEngineWireTargetFor(sessionKey: string, t: EngineWireTarget | null): () => void;
-/**
- * 当前引擎 wire 目标。null = 无 wire(离线/mock/浏览器未装)—— 调用方走各自的回落路径,
- * **不是**错误态。
- */
 export declare function engineWireTarget(): EngineWireTarget | null;
-/**
- * W1 带 key 变体。env 派生回落是**进程级**(键无关):该键未显式装过 ⇒ 与零参同一条 env
- * 回落路径(Node 壳单会话语义不变;浏览器宿主 env 恒空 ⇒ null)。
- */
 export declare function engineWireTargetFor(sessionKey: string): EngineWireTarget | null;
-/** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */
 export declare function engineWireDebugEnabled(): boolean;

package/dist/engineWireTarget.js

@@ -1,33 +1,10 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):子代 wire 族里**逐字重复**的 `wireConfig()`
- *    (SEMA_LIVE_BASEURL / SEMA_LIVE_TOKEN / SEMA_LIVE_PRINCIPAL 三读;principal 缺席=不发头,F-011 停发)
- *    收成一份。
- *
- * 🔴 收编前的事实(壳 HEAD 2aa1d3e 实测,`grep -rln 'function wireConfig' src/sema/`):
- *    **七**份而不是六份 —— `engineSubagentOutput.ts:30` · `engineSubagentSteer.ts:26` ·
- *    `engineTaskHandleWire.ts:40` · `engineCompactWire.ts:77` · `engineSubagentTail.ts:40` ·
- *    `engineDelegatedPrompt.ts:80` · **`planReviewWire.ts:36`**。
- *    ⚠️ 本批搬入的是前六份(子代/fleet 族);**第七份 `planReviewWire` 不在 B6 范围**,仍留壳内
- *    —— 它是下一批的收编候选,别以为已经收干净了(这条更正即为「按名字数数会数漏」的实例)。
- *    七份漂移不是假想:`engineCompactWire` 那份已经多了一行 principal 注释,`engineSubagentSteer`
- *    那份 token 读法与其它几份的 `...(cfg.token ? …)` spread 姿势不同步。
- *
- * 🔴 env 读取走 `hostEnv()`(本包零 `process` —— portability 门盯着)。Node 下 `hostEnv()` 返回的
- *    就是 `process.env` 那个同一对象 ⇒ 壳侧行为一字节不变;浏览器宿主返回 `{}` ⇒ `baseUrl`
- *    缺席 ⇒ 每个 verb 走自己既有的「无 wire」回落路径(不是报错)。
- *    ⚠️ web/桌面宿主要用这条 wire,**不能靠 env** —— 用 `installEngineWireTarget()` 显式装。
- */
 import { hostEnv } from './hostEnv.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from './sessionSlot.js';
 import { normalizeWirePrincipal } from './principalWire.js';
-/** 显式装配(非 Node 宿主唯一的入口;装了就**优先于** env,便于桌面/web 一页多引擎)。
- *  W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层。 */
 const installedByKey = createSessionSlot();
-/** 装/卸引擎 wire 目标。传 null 卸回 env 派生。返回还原函数。 */
 export function installEngineWireTarget(t) {
     return installEngineWireTargetFor(DEFAULT_SESSION_KEY, t);
 }
-/** W1 带 key 变体:装/卸某会话的引擎 wire 目标(多会话宿主每会话一键,互不顶盖)。 */
 export function installEngineWireTargetFor(sessionKey, t) {
     const prev = installedByKey.get(sessionKey);
     installedByKey.set(sessionKey, t);
@@ -35,21 +12,11 @@ export function installEngineWireTargetFor(sessionKey, t) {
         installedByKey.set(sessionKey, prev);
     };
 }
-/**
- * 当前引擎 wire 目标。null = 无 wire(离线/mock/浏览器未装)—— 调用方走各自的回落路径,
- * **不是**错误态。
- */
 export function engineWireTarget() {
     return engineWireTargetFor(DEFAULT_SESSION_KEY);
 }
-/**
- * W1 带 key 变体。env 派生回落是**进程级**(键无关):该键未显式装过 ⇒ 与零参同一条 env
- * 回落路径(Node 壳单会话语义不变;浏览器宿主 env 恒空 ⇒ null)。
- */
 export function engineWireTargetFor(sessionKey) {
     const installed = installedByKey.get(sessionKey) ?? null;
-    // A-028.10 显式装配臂(0.30.3 BEHAVIOR CHANGE):装配值里全空白 principal 在读出口归缺席
-    // (键不出现)——与 env 臂同一把 trim 尺;其余键原样。非空白值(含带空白包围的实值)一字不动。
     if (installed !== null) {
         const p = normalizeWirePrincipal(installed.principal);
         if (p === installed.principal)
@@ -61,11 +28,6 @@ export function engineWireTargetFor(sessionKey) {
     const baseUrl = env.SEMA_LIVE_BASEURL;
     if (!baseUrl)
         return null;
-    // principal must match the run's owner (stamped by the live stream) — the owner-gated routes answer
-    // 404 for non-owners (no existence oracle). F-011 停发([3279]):缺席=不发头,owner-null 两侧
-    // 对齐(server 7.8.1 读写面窄互认盖存量);显式 SEMA_LIVE_PRINCIPAL 恒赢,绝不铸哨兵值。
-    // A-028.10(0.30.3 BEHAVIOR CHANGE):裸 truthy → trim 判定 —— 全空白 env 值此前会发出
-    // 全空白 x-agent-principal 头(垃圾值伪装在场),现归缺席(键不出现),与壳 livePrincipal 同尺。
     const envPrincipal = normalizeWirePrincipal(env.SEMA_LIVE_PRINCIPAL);
     return {
         baseUrl,
@@ -73,7 +35,6 @@ export function engineWireTargetFor(sessionKey) {
         ...(envPrincipal !== undefined ? { principal: envPrincipal } : {}),
     };
 }
-/** 诊断开关(壳侧 `process.env.SEMA_DEBUG` 的等价读;本包零 process)。 */
 export function engineWireDebugEnabled() {
     return Boolean(hostEnv().SEMA_DEBUG);
 }

package/dist/env/localeGeo.d.ts

@@ -1,23 +1,11 @@
-/** 三档。🔴 `unknown` ≠ `intl`:前者是没有判据,后者是有判据且指向境外。 */
 export type RegionHint = 'cn' | 'intl' | 'unknown';
-/** 全部输入由调用方注入(Node 侧传 `env.LANG`/`env.LC_ALL` 与 `Intl.DateTimeFormat().resolvedOptions().timeZone`)。 */
 export interface RegionHintInput {
-    /** `LANG`,如 `zh_CN.UTF-8`。 */
     lang?: string;
-    /** `LC_ALL`。POSIX 下它压过 `LANG`(见 localeTag)。 */
     lcAll?: string;
-    /** IANA 时区名,如 `Asia/Shanghai`。 */
     timeZone?: string;
 }
 export interface RegionHintResult {
     region: RegionHint;
-    /** 给端直接显示的诚实说明(英文,与本包其它面向宿主的文案同口径)。 */
     reason: string;
 }
-/**
- * 地域预选提示(纯函数,零网络、零环境读取)。
- *
- * 结果**永远只是默认值**:端必须让用户能当场改掉,并把 `reason` 显示出来(「已按你的系统区域
- * 预选,可随时改」)。见文件头零耦合约束 —— 它不得被用于对模型 provider 目录做任何排序/过滤。
- */
 export declare function resolveRegionHint(input?: RegionHintInput): RegionHintResult;

package/dist/env/localeGeo.js

@@ -1,55 +1,4 @@
-/**
- * localeGeo.ts — **地域预选 v1(零网络)**:只看系统 locale 与 IANA 时区,给出一个「默认选哪个
- * 地址更可达」的提示。三端复用(CLI / web / 桌面)。
- *
- * ## 🔴 零耦合约束:模型 provider 目录不吃地域信号(clay 令 2026-07-31)
- *
- * 模型 provider **不分国内国外,完全用户选择,走全表** —— 模型 provider 表恒**全表呈现、顺序
- * 不随地域变**,选哪家 100% 是用户的事。因此本模块与模型目录之间是**设计上的零耦合**,不是巧合:
- *   · 本模块**不导出**任何 `sortProvidersByRegion` / `filterProvidersFor(region)` 形状的函数;
- *   · `src/model/**` **不许** import 本模块(pure 门 GEO 段有机械断言把这条钉住,不靠自觉);
- *   · 唯一合法用途:**搜索 provider / 镜像源 / SearXNG 镜像地址**这类「取哪个地址更可达」的
- *     **默认预选**,而且**永远只是默认值,用户可改**。
- *
- * ## 为什么 v1 零网络
- *
- * 拨号探测(测 RTT / 查出口 IP)会在**用户还没同意任何事**之前就产生一次出站请求,而它换来的
- * 只是一个初始默认值。locale 与时区是宿主已经知道的事实,不需要问任何人。⇒ 本模块是纯函数,
- * 输入由调用方注入(不读宿主的环境变量,与本包 hostEnv 纪律一致:环境是宿主资产)。
- * 门里那条「零环境读取」断言查的是**整份源文件**(注释也算),所以本文里刻意不出现那个成员
- * 表达式的字面写法 —— 判据不必先长出一个词法器,代价只是这一行说明。
- *
- * ## 三档,`unknown` 不是 `intl`
- *
- * 两个信号都没有 ⇒ `unknown`,**绝不猜 `intl`**。「不知道」和「知道它在境外」是两件事:端拿到
- * `unknown` 应当**不预选**(让用户自己挑),拿到 `intl` 才是预选国际地址。把不知道渲染成一个
- * 具体答案,就是[honest-absence-not-fabricated-zero]里那条「编造零值」的同族错误。
- *
- * ## 冲突时**时区赢**(locale 说 zh 但时区是 America/New_York)
- *
- * 理由锚在本模块的用途上 —— 判的是「**哪个地址更可达**」,那是**机器在哪张网上**决定的:
- *   · **时区** = 系统对自己**所在位置**的记录(装机/NTP 时按位置设),与网络出口高度相关;
- *   · **locale** = 用户偏好**哪种语言**,与机器在哪张网上无关(在纽约用中文界面的人很多)。
- * ⇒ 时区是位置的更强证据,冲突时它赢。两个信号一致时 `reason` 同时点名两者(证据更足)。
- *
- * ## `reason` 是「我看到了什么」,不是「你在哪」
- *
- * 端会把它渲成「已按你的系统区域预选,可随时改」。所以 reason 只陈述观测到的事实
- * (`system time zone Asia/Shanghai`),不做身份断言(不写 "you are in China")—— 用户看到的
- * 是判据本身,于是「这判据不对」是他能当场看出来并改掉的。
- *
- * ## tag 手术委托 `./localeTag.js`(F4 族D A-028.20,双出口成文)
- *
- * 剥 codeset/modifier、中性 locale 认定、子标签切分这台**手术**与 `env/uiLanguage.ts` 共用
- * 同一份实现;但两件各答各的题(本件答「哪个地址更可达」,那件答「界面用哪种文字」),
- * 输出域语义不同,刻意不收敛 —— 理由成文在 localeTag.ts 文件头。
- */
 import { parseLocaleTag } from './localeTag.js';
-/**
- * 判为「内地」的 IANA 时区(含 backward 链接别名与老 `PRC` 形)。
- * 🔴 `Asia/Hong_Kong` / `Asia/Macau` / `Asia/Taipei` **不在**表内:本模块判的是「哪个镜像地址
- * 更可达」,这三处的网络出口与内地不同,按内地预选反而会给出更慢的默认值。
- */
 const CN_TIME_ZONES = new Set([
     'asia/shanghai',
     'asia/chongqing',
@@ -59,37 +8,21 @@ const CN_TIME_ZONES = new Set([
     'asia/kashgar',
     'prc',
 ]);
-/** IANA 时区名的形(`Area/Location`,允许多级如 `America/Argentina/Salta`)。 */
 const IANA_SHAPE = /^[a-z]+(?:\/[a-z0-9_+-]+)+$/i;
-/** 不含地理信息的时区(UTC 家族):有值,但不构成判据。 */
 const GEOLESS_ZONES = new Set(['utc', 'gmt', 'z', 'universal', 'zulu']);
-/** reason 里回显观测值的长度上限 —— 输入来自宿主环境变量,不该由它决定一行 UI 有多长。 */
 const ECHO_MAX = 64;
 const echo = (v) => (v.length > ECHO_MAX ? `${v.slice(0, ECHO_MAX)}…` : v);
-/**
- * 取生效的 locale 标签(已剥 codeset 与 modifier:`zh_CN.UTF-8@pinyin` → `zh_CN`)。
- *
- * 🔴 `LC_ALL` 非空时**独赢,不回落 `LANG`** —— POSIX 就是这个覆盖语义,而 reason 必须说的是
- * **真正生效**的那个 locale。`LC_ALL=C` 时回落去报 `LANG` 的值,等于在 reason 里陈述一件
- * 当前并不成立的事。
- */
 function localeTag(input) {
     const pick = (v) => (typeof v === 'string' ? v.trim() : '');
     const raw = pick(input.lcAll) || pick(input.lang);
-    // tag 手术(剥 codeset/modifier、中性 locale、认形)单源在 localeTag.ts —— 本件只保留
-    // 「LC_ALL 独赢」这半句 POSIX 语义,手术本身不再自持第二份。
     return parseLocaleTag(raw).tag;
 }
-/**
- * locale → 信号。`zh` 系按**地区码优先、脚本次之**读(地区码比脚本更接近地理事实:
- * `zh-Hans-TW` 用的是简体,但机器在台北那张网上)。
- */
 function localeSignal(tag) {
     if (!tag)
         return 'unknown';
     const parts = parseLocaleTag(tag).subtags;
     if (parts[0] !== 'zh')
-        return 'intl'; // 非中文 locale = 有信号且不指向内地
+        return 'intl';
     const rest = parts.slice(1);
     if (rest.includes('cn'))
         return 'cn';
@@ -99,9 +32,8 @@ function localeSignal(tag) {
         return 'cn';
     if (rest.includes('hant'))
         return 'intl';
-    return 'cn'; // 裸 `zh`:实践中是内地系统的默认写法
+    return 'cn';
 }
-/** 时区 → 信号。形不对/UTC 家族 ⇒ 没信号(不是 `intl`)。 */
 function timeZoneSignal(zone) {
     const z = zone.toLowerCase();
     if (!z)
@@ -112,12 +44,6 @@ function timeZoneSignal(zone) {
         return 'unknown';
     return IANA_SHAPE.test(z) ? 'intl' : 'unknown';
 }
-/**
- * 地域预选提示(纯函数,零网络、零环境读取)。
- *
- * 结果**永远只是默认值**:端必须让用户能当场改掉,并把 `reason` 显示出来(「已按你的系统区域
- * 预选,可随时改」)。见文件头零耦合约束 —— 它不得被用于对模型 provider 目录做任何排序/过滤。
- */
 export function resolveRegionHint(input = {}) {
     const zone = typeof input.timeZone === 'string' ? input.timeZone.trim() : '';
     const tag = localeTag(input);
@@ -130,7 +56,6 @@ export function resolveRegionHint(input = {}) {
         if (localeHint === zoneHint) {
             return { region: zoneHint, reason: `system time zone ${echo(zone)} and locale ${echo(tag)}` };
         }
-        // 冲突:两个观测都说出来,并说明用了哪一个(见文件头「冲突时时区赢」)。
         return {
             region: zoneHint,
             reason: `system time zone ${echo(zone)} (locale ${echo(tag)} differs; time zone wins)`,

package/dist/env/localeTag.d.ts

@@ -1,40 +1,6 @@
-/**
- * localeTag.ts — F4 族D(A-028.20,2026-08-15):locale 标签的**纯 tag 手术**单源。
- *
- * ## 为什么要有这一件
- *
- * 「把一个 locale 标签剥成语言子标签」这台手术此前被做了三次:cli `i18n/core/uiLanguage.ts`
- * (剥 codeset/modifier → 取语言子标签 → 判 UI 语言)、本包 `env/localeGeo.ts`(同一台手术 →
- * 判地域预选)、web 侧第二份(答案还不一致)。手术步骤漂了(比如谁剥 `@modifier` 谁不剥),
- * 同一个 `zh_CN.UTF-8@pinyin` 会在不同端得出不同判定。手术进包单源后,两个**输出域不同**的
- * 判定(见下)共用这一台手术,步骤从结构上不可能再漂。
- *
- * ## 🔴 双出口成文:tag 手术单源 ≠ 答案单源
- *
- * 本件只做**手术**(剥、切、认形),不做**判定**。判定有两个,输出域**语义不同**,刻意不收敛:
- *   · `env/uiLanguage.ts` `pickUiLanguage` → `'en' | 'zh'`:**用户读哪种界面文字**(语言偏好域;
- *     未知回落 en = 回落到可读的 fallback 目录);
- *   · `env/localeGeo.ts` `resolveRegionHint` → `'cn' | 'intl' | 'unknown'`:**机器在哪张网上**
- *     (地址可达域;未知就是 unknown,绝不猜 —— 端应当不预选)。
- * 两域对同一输入给不同答案是**设计**,不是漂移:`zh-Hant` 的界面语言是中文(zh),而它的网络
- * 预选是境外(intl)。谁要「收敛成一个函数」谁就把这两件事重新搅在一起。
- *
- * ## 手术步骤(POSIX `zh_CN.UTF-8@pinyin` → `zh_CN`)
- *
- *   ① trim;② 剥 codeset(`.` 后);③ 剥 modifier(`@` 后)再 trim;
- *   ④ 中性 locale(`C`/`POSIX`)与不合语言标签形的串(头段非 2–3 位字母)⇒ **无信号**
- *      (`tag: ''`)——「没有 locale」和「locale 指向某语言」必须分得开;
- *   ⑤ 子标签统一小写、`_`→`-` 后切开(`tag` 保留原大小写 —— 端要拿它回显观测值)。
- */
-/** 手术产物。`tag === ''` = 无信号(空/中性/形不对),此时 language/subtags 也为空。 */
 export interface ParsedLocaleTag {
-    /** 剥 codeset/modifier 后的标签**原样**(保留大小写,供端回显观测值);'' = 无信号。 */
     tag: string;
-    /** 语言子标签(小写);无信号时 ''。 */
     language: string;
-    /** 全部子标签(小写,[-_] 切);无信号时 []。 */
     subtags: string[];
 }
-/** 纯 tag 手术(见文件头步骤表)。任何宿主形态的标签都吃:POSIX `LANG`、BCP 47、
- *  `navigator.language`、Electron `app.getLocale()`。 */
 export declare function parseLocaleTag(raw: string | undefined): ParsedLocaleTag;

package/dist/env/localeTag.js

@@ -1,37 +1,5 @@
-/**
- * localeTag.ts — F4 族D(A-028.20,2026-08-15):locale 标签的**纯 tag 手术**单源。
- *
- * ## 为什么要有这一件
- *
- * 「把一个 locale 标签剥成语言子标签」这台手术此前被做了三次:cli `i18n/core/uiLanguage.ts`
- * (剥 codeset/modifier → 取语言子标签 → 判 UI 语言)、本包 `env/localeGeo.ts`(同一台手术 →
- * 判地域预选)、web 侧第二份(答案还不一致)。手术步骤漂了(比如谁剥 `@modifier` 谁不剥),
- * 同一个 `zh_CN.UTF-8@pinyin` 会在不同端得出不同判定。手术进包单源后,两个**输出域不同**的
- * 判定(见下)共用这一台手术,步骤从结构上不可能再漂。
- *
- * ## 🔴 双出口成文:tag 手术单源 ≠ 答案单源
- *
- * 本件只做**手术**(剥、切、认形),不做**判定**。判定有两个,输出域**语义不同**,刻意不收敛:
- *   · `env/uiLanguage.ts` `pickUiLanguage` → `'en' | 'zh'`:**用户读哪种界面文字**(语言偏好域;
- *     未知回落 en = 回落到可读的 fallback 目录);
- *   · `env/localeGeo.ts` `resolveRegionHint` → `'cn' | 'intl' | 'unknown'`:**机器在哪张网上**
- *     (地址可达域;未知就是 unknown,绝不猜 —— 端应当不预选)。
- * 两域对同一输入给不同答案是**设计**,不是漂移:`zh-Hant` 的界面语言是中文(zh),而它的网络
- * 预选是境外(intl)。谁要「收敛成一个函数」谁就把这两件事重新搅在一起。
- *
- * ## 手术步骤(POSIX `zh_CN.UTF-8@pinyin` → `zh_CN`)
- *
- *   ① trim;② 剥 codeset(`.` 后);③ 剥 modifier(`@` 后)再 trim;
- *   ④ 中性 locale(`C`/`POSIX`)与不合语言标签形的串(头段非 2–3 位字母)⇒ **无信号**
- *      (`tag: ''`)——「没有 locale」和「locale 指向某语言」必须分得开;
- *   ⑤ 子标签统一小写、`_`→`-` 后切开(`tag` 保留原大小写 —— 端要拿它回显观测值)。
- */
-/** 显式「无 locale」的 POSIX 值 —— 它们不携带任何语言/地域信息。 */
 const NEUTRAL_LOCALES = new Set(['c', 'posix']);
-/** 语言标签的形:头一段是 2–3 位字母的语言码。不合形的串(`1234` / 空串)当没信号。 */
 const LANGUAGE_TAG_SHAPE = /^[a-z]{2,3}(?:[-_]|$)/i;
-/** 纯 tag 手术(见文件头步骤表)。任何宿主形态的标签都吃:POSIX `LANG`、BCP 47、
- *  `navigator.language`、Electron `app.getLocale()`。 */
 export function parseLocaleTag(raw) {
     const trimmed = typeof raw === 'string' ? raw.trim() : '';
     const noCodeset = trimmed.split('.')[0] ?? '';

package/dist/env/uiLanguage.d.ts

@@ -1,18 +1,5 @@
-/** The languages sema's own screens are available in. */
 export type UiLanguage = 'en' | 'zh';
-/** Menu order: the detected language is pre-focused, so this order is presentation only. */
 export declare const UI_LANGUAGES: readonly UiLanguage[];
-/**
- * Language names in the language itself (endonyms). NEVER translated and never routed through the
- * message catalog: a language picker has to be readable by someone who cannot read the current UI
- * language — that is the whole point of the screen.
- */
 export declare const UI_LANGUAGE_ENDONYMS: Record<UiLanguage, string>;
 export declare function isUiLanguage(v: unknown): v is UiLanguage;
-/**
- * Decide the UI language from ONE locale tag, whatever the host got it from — a POSIX `LANG`
- * (`zh_CN.UTF-8`), a BCP 47 tag (`zh-Hant`), `navigator.language`, an Electron `app.getLocale()`.
- * Anything whose language subtag is `zh` ⇒ 中文; everything else — including empty, `C` and
- * `POSIX` — ⇒ English (which is also the fallback catalog, so "unknown" degrades to "readable").
- */
 export declare function pickUiLanguage(localeTag: string | undefined): UiLanguage;

package/dist/env/uiLanguage.js

@@ -1,24 +1,5 @@
-/**
- * uiLanguage.ts — F4 族D(A-028.20,2026-08-15;整体自 cli `src/sema/i18n/core/uiLanguage.ts`
- * 搬迁):UI 语言的**词表 + 判定**——类型、两种受支持语言、各自的 endonym、以及
- * 「一个 locale 标签 → UI 语言」的纯判定。三端(CLI / web / 桌面)共用这一份。
- *
- * tag 手术(剥 codeset/modifier、切子标签)委托 `./localeTag.js` —— 与 `./localeGeo.js` 共用
- * **同一台手术**但**各答各的题**(双出口成文,理由见 localeTag.ts 文件头:语言偏好域 ≠ 地址
- * 可达域,`zh-Hant` 在前者是 zh、在后者是 intl)。
- *
- * 标签从哪来是宿主的事,本件不读环境:CLI 读 POSIX env(LC_ALL > LC_MESSAGES > LANG),
- * 浏览器读 `navigator.language`,Electron 读 `app.getLocale()` —— 各宿主的三行 adapter 都
- * 调同一个 `pickUiLanguage`。
- */
 import { parseLocaleTag } from './localeTag.js';
-/** Menu order: the detected language is pre-focused, so this order is presentation only. */
 export const UI_LANGUAGES = ['en', 'zh'];
-/**
- * Language names in the language itself (endonyms). NEVER translated and never routed through the
- * message catalog: a language picker has to be readable by someone who cannot read the current UI
- * language — that is the whole point of the screen.
- */
 export const UI_LANGUAGE_ENDONYMS = {
     en: 'English',
     zh: '中文',
@@ -26,12 +7,6 @@ export const UI_LANGUAGE_ENDONYMS = {
 export function isUiLanguage(v) {
     return v === 'en' || v === 'zh';
 }
-/**
- * Decide the UI language from ONE locale tag, whatever the host got it from — a POSIX `LANG`
- * (`zh_CN.UTF-8`), a BCP 47 tag (`zh-Hant`), `navigator.language`, an Electron `app.getLocale()`.
- * Anything whose language subtag is `zh` ⇒ 中文; everything else — including empty, `C` and
- * `POSIX` — ⇒ English (which is also the fallback catalog, so "unknown" degrades to "readable").
- */
 export function pickUiLanguage(localeTag) {
     return parseLocaleTag(localeTag).language === 'zh' ? 'zh' : 'en';
 }

package/dist/envFlag.d.ts

@@ -1,39 +1,2 @@
-/**
- * envFlag.ts — single spelling-set source for boolean-shaped `SEMA_*` env knobs (REF-CC-141, P2
- * 台账 dup-02,wave1 卡B,2026-08-01).
- *
- * WHY: ten call sites across nine `*Wire*`/`*WireCaps*` modules each hand-rolled their own
- * off/on-spelling check for a `SEMA_*` boolean env knob, and the four variants DISAGREED:
- *   ① 4-word off-set `'0'|'false'|'no'|'off'` (6 copies: forkWireCaps.ts isFalsy,
- *      selfOrchestrationWireCaps.ts isFalsy, retainBackgroundWireCaps.ts isFalsy,
- *      ultracodeWireCaps.ts deferOptedOut + lowFreqOptedOut, hooksWireCaps.ts isGoalStopHookWireArmed);
- *   ② 2-word off-set `'false'|'0'` (2 copies: detachWire.ts headlessDetachDisabledByEnv,
- *      finalVerifyWire.ts headlessFinalVerifyDisabledByEnv) — `=off` / `=no` silently did nothing;
- *   ③ 4-word off-set but a DIFFERENT fourth word `'off'|'0'|'false'|'none'`
- *      (attachmentsWireCaps.ts attachmentsForRequest — accepted "none", not "no");
- *   ④ 2-word set WITHOUT lowercasing `raw==='true'||raw==='1'` / `raw==='false'||raw==='0'`
- *      (interactiveToolsWire.ts resolveHeadlessInteractiveTools — `SEMA_HEADLESS_INTERACTIVE_TOOLS=False`
- *      fell through to the "not a boolean" warn-and-default path instead of being recognized).
- *
- * User-visible consequence (dup-02 evidence): the SAME settings.json could have
- * `SEMA_HEADLESS_DETACH=off` silently ignored (falls back to default-ON) sitting right next to
- * `SEMA_RETAIN_BACKGROUND=off` which worked — no way for a user to know which spelling their knob
- * actually honors.
- *
- * FIX: one leaf module, one spelling set PER POLARITY, each the UNION across all four prior
- * variants (only-tightens-never-loosens direction inverted here on purpose — widen everywhere,
- * never narrow a caller's existing accepted set). Zero dependencies (no `hostEnv`/`EnvLike` import —
- * operates on the already-extracted string, so it stays trivially portable and unit-testable).
- */
-/**
- * True iff `v` is an explicit OFF spelling ({@link OFF_SPELLINGS}: `0`/`false`/`no`/`off`/`none`,
- * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
- * explicitly off" defaults to (many of these knobs are default-ON escape hatches).
- */
 export declare function envFlagOff(v: string | undefined): boolean;
-/**
- * True iff `v` is an explicit ON spelling ({@link ON_SPELLINGS}: `1`/`true`/`yes`/`on`,
- * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
- * explicitly on" defaults to.
- */
 export declare function envFlagOn(v: string | undefined): boolean;

package/dist/envFlag.js

@@ -1,51 +1,11 @@
-/**
- * envFlag.ts — single spelling-set source for boolean-shaped `SEMA_*` env knobs (REF-CC-141, P2
- * 台账 dup-02,wave1 卡B,2026-08-01).
- *
- * WHY: ten call sites across nine `*Wire*`/`*WireCaps*` modules each hand-rolled their own
- * off/on-spelling check for a `SEMA_*` boolean env knob, and the four variants DISAGREED:
- *   ① 4-word off-set `'0'|'false'|'no'|'off'` (6 copies: forkWireCaps.ts isFalsy,
- *      selfOrchestrationWireCaps.ts isFalsy, retainBackgroundWireCaps.ts isFalsy,
- *      ultracodeWireCaps.ts deferOptedOut + lowFreqOptedOut, hooksWireCaps.ts isGoalStopHookWireArmed);
- *   ② 2-word off-set `'false'|'0'` (2 copies: detachWire.ts headlessDetachDisabledByEnv,
- *      finalVerifyWire.ts headlessFinalVerifyDisabledByEnv) — `=off` / `=no` silently did nothing;
- *   ③ 4-word off-set but a DIFFERENT fourth word `'off'|'0'|'false'|'none'`
- *      (attachmentsWireCaps.ts attachmentsForRequest — accepted "none", not "no");
- *   ④ 2-word set WITHOUT lowercasing `raw==='true'||raw==='1'` / `raw==='false'||raw==='0'`
- *      (interactiveToolsWire.ts resolveHeadlessInteractiveTools — `SEMA_HEADLESS_INTERACTIVE_TOOLS=False`
- *      fell through to the "not a boolean" warn-and-default path instead of being recognized).
- *
- * User-visible consequence (dup-02 evidence): the SAME settings.json could have
- * `SEMA_HEADLESS_DETACH=off` silently ignored (falls back to default-ON) sitting right next to
- * `SEMA_RETAIN_BACKGROUND=off` which worked — no way for a user to know which spelling their knob
- * actually honors.
- *
- * FIX: one leaf module, one spelling set PER POLARITY, each the UNION across all four prior
- * variants (only-tightens-never-loosens direction inverted here on purpose — widen everywhere,
- * never narrow a caller's existing accepted set). Zero dependencies (no `hostEnv`/`EnvLike` import —
- * operates on the already-extracted string, so it stays trivially portable and unit-testable).
- */
-/** OFF spellings — union of all four prior variants (see file header). Case-insensitive, trimmed. */
 const OFF_SPELLINGS = new Set(['0', 'false', 'no', 'off', 'none']);
-/** ON spellings — union of all prior variants that had an explicit truthy branch (forkWireCaps
- *  isTruthy `1/true/yes/on`; interactiveToolsWire's narrower `true/1`). Case-insensitive, trimmed. */
 const ON_SPELLINGS = new Set(['1', 'true', 'yes', 'on']);
 function normalize(v) {
     return typeof v === 'string' ? v.trim().toLowerCase() : '';
 }
-/**
- * True iff `v` is an explicit OFF spelling ({@link OFF_SPELLINGS}: `0`/`false`/`no`/`off`/`none`,
- * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
- * explicitly off" defaults to (many of these knobs are default-ON escape hatches).
- */
 export function envFlagOff(v) {
     return OFF_SPELLINGS.has(normalize(v));
 }
-/**
- * True iff `v` is an explicit ON spelling ({@link ON_SPELLINGS}: `1`/`true`/`yes`/`on`,
- * case-insensitive, trimmed). Unset/empty/unrecognized ⇒ `false` — the caller decides what "not
- * explicitly on" defaults to.
- */
 export function envFlagOn(v) {
     return ON_SPELLINGS.has(normalize(v));
 }