@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/liveInitToolFace.js

@@ -1,72 +1,8 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B2 判给后批的**宿主耦合六件**之一):cli
- *    `src/sema/liveInitToolFace.ts` 整搬。B2 当时不搬的理由 = 它 `await import('./engineTarget.js')`
- *    取凭证,而 engineTarget 是 fs 重图;B4 的 §8-2 收编把凭证解析定到了 `resolveWireAuth`
- *    (engineWireSdk,零依赖),那条理由随之消失。
- *
- * 🔴 搬迁三处差分(行为一字节不变):
- *   ① 凭证:`engineTarget.resolveLiveAuthToken(baseUrl)`(其 token 缺省 = `process.env.SEMA_LIVE_TOKEN`)
- *      → `resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN)`。两者是同一套 #118 三态,`resolveWireAuth`
- *      的头注自述就是它的收编口。取值面完全一致:三态里只有**真 token 串**与 `'anon'` 是 string,
- *      `{mode:'loopback-unauthed'}` 是对象 ⇒ 原文那句 `typeof t === 'string' ? t : undefined` 语义照搬。
- *   ② 三个 `await import('./xxxWire.js')` fail-soft 动态 import → **静态 import**(scenarioWire /
- *      interactiveToolsWire / webSearchWireCaps 三件 B5 都已在本包内)。原文那三层 try/catch 的
- *      目的是「模块缺席也别挡首帧」,包内它们不可能缺席;**try/catch 仍逐条保留**——它护的另一半是
- *      「函数自己抛」,那半在包内照样成立。
- *   ③ `process.env` → 入参 `EnvLike`(签名本来就显式收 env;缺省值不存在,调用方必传)。
- *
- * 🔴 模块级状态:`cached`(baseUrl+scenario+旋钮 键控的一次性探测缓存)。写读口都在本文件;
- *    两份实例只是多探一次(不是静默失效),但仍登记进单实例清单。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * liveInitToolFace — 件1(core [931] 壳半场):headless `-p` live 车道 `system/init` 首帧的
- * `tools` 自报面,从「壳静态工具表」改为「引擎实挂 wire 词表」生成。
- *
- * 根因(core [931]/CC209 裁决):壳自报静态表(TodoWrite 在、TaskCreate 族不在)而引擎 wire 实挂
- * TaskCreate 族(core 1.296+ 默认)且不挂 TodoWrite ⇒ SDK/自动化消费者照自报面配
- * `--disallowedTools TodoWrite` 之类静默无效(fail-open)。core 1.300 已在引擎侧加名单池审计
- * advisory(config.toolpolicy.unmatched_names)兜观测面;这里是壳半场 = 自报按实挂生成。
- *
- * 真源层级(gap-check 2026-07-16 实测读数,server 1.214.0 / core 1.300.0):
- *   1. server 无全量挂载探测面:GET /v1/capabilities 只有能力布尔;
- *      GET /v1/capabilities/scenarios/:name 只含【场景附加】工具(default/code →
- *      Now/WebFetch/Agent/TaskCreate 族七具),首方 band(Bash/Read/…)由 core prepare-task
- *      另挂、不进该面 ⇒ 整表无法远端取。
- *   2. 故缺省场景用壳已知 wire 词表(下表):观测 tap 记录壳 `-p` live 车道 LLM 请求体
- *      tools[].name(REMOTE_EXEC=host 生产姿势)实测定稿,再按壳自己 stamp 的请求旋钮修正
- *      (interactiveTools≠false → AskUserQuestion;settings.webSearch 在 → WebSearch)。
- *   3. per-scenario 差异如实标注:非缺省 scenario(--scenario/SEMA_HEADLESS_SCENARIO)的工具面
- *      由部署定义(scan/oa = repo-readonly 面,首方 band 是否在位壳无法确证)⇒ 尽力探场景详情面
- *      GET /v1/capabilities/scenarios/:name 报【场景附加】工具 + runner 恒挂段,并经
- *      SEMA_DEBUG 如实标注是探测面而非整表;探测失败回退缺省词表(fail-soft,绝不阻塞首帧)。
- *   4. mock/离线车道(无 SEMA_LIVE_BASEURL)返回 null,调用方保持现状静态表 —— 宪法三问的
- *      补偿轴:离线态回退静态表,行为字节不变。
- *
- * 已知局限(如实):词表按 pin 的 server/core 版本定稿,外接旧引擎或无执行底座的 worker
- * (REMOTE_EXEC 缺省的裸 worker 不挂 hands band)会有偏差 —— 但相比旧静态表(TodoWrite 幻影 +
- * TaskCreate 族缺席)已是严格更准的自报;整表探测面等引擎侧补(见 [931] 报告)。
- */
 import { makeEngineWireClient, resolveWireAuth } from './engineWireSdk.js';
 import { hostLog } from './host.js';
 import { scenarioForPrint } from './scenarioWire.js';
 import { resolveHeadlessInteractiveTools } from './interactiveToolsWire.js';
 import { webSearchFromEnv } from './webSearchWireCaps.js';
-// ── 🔴 退役条款(0.63.0 / L-161 登记;engine ≥7.66.0 有名册,≥7.9.0 才真推)──────────────────
-// 下面三张表(`ENGINE_HANDS_BAND` / `ENGINE_SCENARIO_EXTRAS_DEFAULT` / `ENGINE_RUNNER_FACE`)是
-// **估计值**:2026-07-16 一次 tap 实测按当时 pin 的引擎版本定稿,外接别的引擎、别的场景、别的
-// env 门就会偏(文件头「已知局限」段自己写着这一条)。它们的继任者是引擎**自己说的**那份东西 ——
-// `wiring_manifest.tools` 上的工具名册(本包 `toolRoster.ts`:`projectToolRoster` /
-// `toolRosterNames` / `toolShimFromRoster`),那里有每只工具的身份、轴与面,不用按名字猜。
-//
-// **本批刻意不删表**,因为回落还得留着:名册只在 **effective 半场**(live 帧)铸,而本函数跑在
-// 首帧之前走的是 HTTP 探测面;且只有 ≥7.9.0 的引擎才真推那条帧。⇒ 现役姿势 =
-// **名册在场用名册,缺席才回落这三张表**,装配在宿主(它才拿得到帧流)。
-// 退役条件(满足即删这三张表 + 删掉本段):**名册恒在场**的引擎版本成为支持底线。
-// ⚠️ 删表时连 `runnerFaceForEnv` 的 env 门一起删 —— 那道门也是在补估计值的偏,名册在场时它是
-//    第二份台账(引擎已经按 env 门算过一遍才铸的名册)。
-// ── 壳已知 wire 词表(tap 实测 2026-07-16,server 1.214.0/core 1.300.0,壳 -p 缺省旋钮)──────────
-/** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
 export const ENGINE_HANDS_BAND = [
     'Bash',
     'Read',
@@ -81,10 +17,6 @@ export const ENGINE_HANDS_BAND = [
     'ExitWorktree',
     'Monitor',
 ];
-/** 缺省(code/default)场景附加段 —— 与 GET /v1/capabilities/scenarios/{code,default} 详情面
- *  实测逐字一致(场景工厂 nowTool + assembleFullBodyTools)。
- *  ⚠️ TodoWrite 故意不在(core 1.296+ 默认 taskList:true ⇒ TodoWrite 不挂,[931] 本案根因);
- *  TaskCreate 族在 —— 这两条就是本修要对齐的实况。 */
 export const ENGINE_SCENARIO_EXTRAS_DEFAULT = [
     'Now',
     'WebFetch',
@@ -94,10 +26,6 @@ export const ENGINE_SCENARIO_EXTRAS_DEFAULT = [
     'TaskUpdate',
     'TaskList',
 ];
-/** runner 恒挂段(prepare-task 按请求旋钮挂载、场景无关):壳 `-p` 恒 stamp
- *  selfOrchestration→Workflow、attachments.backgroundTasks→TaskOutput/TaskStop/Monitor/
- *  SendMessage/AgentTranscript;ReadToolResult/ReportBlocked/ReportFindings/Skill/Cron 族/
- *  ScheduleWakeup 为 runner 缺省注入。 */
 export const ENGINE_RUNNER_FACE = [
     'AgentTranscript',
     'CronCreate',
@@ -111,14 +39,9 @@ export const ENGINE_RUNNER_FACE = [
     'Skill',
     'TaskOutput',
     'TaskStop',
-    // [1870] L2 半条(0.11.1):deferred-tools 取回工具,runner 恒挂——引擎对模型的真实请求
-    // 恒声明它(sema-test repro A2 双向断言实证),此前自报面漏它=显示轨迹失真误导归因。
     'ToolSearch',
     'Workflow',
 ];
-/** [1036]/clay 裁:runner 恒挂段按壳已知 env 门过滤——print 宿主前置 SCHEDULER_ENABLED=false
- *  (scheduler 族 headless 不挂)/SELF_ORCHESTRATION_ENABLED=false(Workflow 卸)时,自报面
- *  必须跟实挂(此前静态词表在 env 门形态失真=自报 32 实挂 28,消融实测逮到)。 */
 export function runnerFaceForEnv(env) {
     let face = [...ENGINE_RUNNER_FACE];
     if (env.SCHEDULER_ENABLED === 'false') {
@@ -129,18 +52,10 @@ export function runnerFaceForEnv(env) {
     }
     return face;
 }
-// 按 baseUrl+scenario 缓存(多 turn headless 会话只付一次探测;词表车道零 IO 本就便宜,统一缓存简单)。
 let cached = null;
-/** 测试钩子:清缓存。 */
 export function _resetLiveInitToolFaceForTest() {
     cached = null;
 }
-/** 非缺省场景的详情面探测:SDK 0.0.52 scenarioCapabilities(name)(GET /v1/capabilities/scenarios/:name,
- *  同 wire 同 encodeURIComponent)→ { tools(场景附加段), toolset }。fail-soft:任何失败(网络/404/
- *  形状不符/超时)返回 null,调用层回退缺省词表。等价性记账:超时经 client timeoutMs(缺省 2s 同预算,
- *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
- *  principal 头:SDK 6.11 起值检查删头(缺席不发;F-011 停发后单机形恒缺席)——原手抄在无 principal
- *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
 export async function probeScenarioTools(baseUrl, scenario, opts) {
     const client = makeEngineWireClient({
         baseUrl,
@@ -167,21 +82,11 @@ export async function probeScenarioTools(baseUrl, scenario, opts) {
         return null;
     }
 }
-/**
- * resolveLiveInitToolFace — live 车道 init 首帧 `tools` 的实挂投影。
- *   · 无 SEMA_LIVE_BASEURL ⇒ null(mock/离线车道,调用方维持静态表现状);
- *   · 缺省场景 ⇒ hands band + runner 恒挂段 + 旋钮修正(词表车道,零 IO);
- *   · 非缺省场景 ⇒ 详情面探测成功用【场景附加 + runner 恒挂】(如实标注:hands band 是否在位
- *     由部署定,不妄报),失败回退缺省词表;
- *   · 任何内部错误 fail-soft 返回 null(调用方回退静态表,首帧永不因此缺席)。
- */
 export async function resolveLiveInitToolFace(argv, env, opts) {
     const baseUrl = env.SEMA_LIVE_BASEURL;
     if (!baseUrl)
         return null;
     try {
-        // 场景解析(scenarioWire 同源:flag > SEMA_HEADLESS_SCENARIO;非法 flag 在 seamQueryEngine
-        // 已 fail-loud 退出,这里只可能看到合法值或解析失败 → 按缺省处理)。
         let scenario;
         try {
             const sc = scenarioForPrint([...argv], env);
@@ -189,47 +94,36 @@ export async function resolveLiveInitToolFace(argv, env, opts) {
                 scenario = sc.scenario;
         }
         catch {
-            /* fail-soft → 缺省场景 */
         }
-        // 旋钮修正① interactiveTools:壳 `-p` 缺省 stamp false ⇒ AskUserQuestion 不挂;
-        // 显式交互意图(--permission-mode plan)/部署旋钮开 ⇒ 引擎缺省挂。
         let askUserQuestion = false;
         try {
             const r = resolveHeadlessInteractiveTools([...argv], env);
             askUserQuestion = r.fields.interactiveTools !== false;
         }
         catch {
-            /* fail-soft → 按缺省 stamp false,不报 AskUserQuestion */
         }
-        // 旋钮修正② webSearch:壳发 settings.webSearch 时 server 才组 WebSearch 后端
-        // (seamQueryEngine `-p` 车道同源 = env 面 webSearchFromEnv)。
         let webSearch = false;
         try {
             webSearch = webSearchFromEnv(env) !== undefined;
         }
         catch {
-            /* fail-soft → 不报 WebSearch */
         }
         const knobTools = [
             ...(askUserQuestion ? ['AskUserQuestion'] : []),
             ...(webSearch ? ['WebSearch'] : []),
         ];
-        // 缓存键含旋钮(argv/env 同进程内稳定,但键面完备防同进程内旋钮变化的陈旧命中)。
         const key = `${baseUrl}::${scenario ?? ''}::${askUserQuestion ? 'q' : ''}${webSearch ? 'w' : ''}::${env.SCHEDULER_ENABLED === 'false' ? 'ns' : ''}${env.SELF_ORCHESTRATION_ENABLED === 'false' ? 'nw' : ''}`;
         if (cached && cached.key === key)
             return cached.face;
         let names;
         let source = 'wire-vocabulary';
         if (scenario) {
-            // 非缺省场景:详情面探测(场景附加段真源)。auth 同 live 车道纪律(#118 三态;
-            // loopback-unauthed ⇒ 不出示 bearer —— 对象形不是 string,下面那句照原文过滤掉)。
             let authToken;
             try {
                 const t = resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN);
                 authToken = typeof t === 'string' ? t : undefined;
             }
             catch {
-                /* fail-soft → 无 token 探测 */
             }
             const probed = await probeScenarioTools(baseUrl, scenario, {
                 ...(opts?.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
@@ -238,8 +132,6 @@ export async function resolveLiveInitToolFace(argv, env, opts) {
                 ...(env.SEMA_LIVE_PRINCIPAL ? { principal: env.SEMA_LIVE_PRINCIPAL } : {}),
             });
             if (probed) {
-                // 如实标注:场景附加(探测面)+ runner 恒挂段;hands band 只在详情面自证 full-body 时
-                // 才报(repo-readonly 等场景不挂首方 band,不妄报)。
                 const handsBand = probed.toolset === 'full-body' ? ENGINE_HANDS_BAND : [];
                 names = [...new Set([...probed.tools, ...handsBand, ...runnerFaceForEnv(env), ...knobTools])];
                 source = 'scenario-probe';
@@ -262,6 +154,6 @@ export async function resolveLiveInitToolFace(argv, env, opts) {
         return face;
     }
     catch {
-        return null; // 调用方回退静态表(首帧契约:永不因自报面缺席)
+        return null;
     }
 }

package/dist/liveModelCatalog.d.ts

@@ -1,76 +1,24 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/liveModelCatalog.ts 逐字搬入(零依赖;🔴 catalog/refresher 是单实例态 —— 写口 setLiveModelCatalog/installer 与读口 getLiveModelCatalog 必须同实例)。
- */
-/**
- * src/sema/liveModelCatalog.ts — the LIVE model-catalog singleton (TEAM-C / clay decision #1 = A).
- *
- * WHY THIS FILE EXISTS
- * --------------------
- * The `/model` picker, the header model line, the /status "Model" row, and the picker's ✔ are all stuck on
- * a STATIC opus[1m] / a STATIC fictional catalog (mock/control/modelOptionsSeam.ts). The live engine actually
- * serves a different fleet — `client.models.list()` returns `{ models, default }` (the REAL catalog), and
- * `done.result.model` echoes the REAL served model (MF-25). This module is the one-shot, process-wide bridge
- * between the LIVE wire read (done once at boot in replEntry's live block) and the SYNCHRONOUS render-time
- * readers (getModelOptions, called inside the picker's React render — it cannot await).
- *
- * SINGLE INSTANCE (build discipline): replEntry.tsx (build-src/src/sema/replEntry.tsx) SETS the catalog and
- * mock/control/modelOptionsSeam.ts (build-src/mock/control/…, the aliased getModelOptions target) READS it.
- * Both resolve this module to ONE staged path (build-src/src/sema/liveModelCatalog.ts), so the singleton is
- * shared — the same single-instance invariant the seam-module fix in scripts/build.sema.mjs guarantees.
- *
- * MOCK PATH UNCHANGED: with SEMA_LIVE_BASEURL unset, no one calls setLiveModelCatalog → the catalog stays
- * null → getModelOptions falls back to the static fleetModels mock and the boot keeps opus[1m]. So the
- * cell-exact mock parity (the /model picker mock rows, the opus[1m] header/status, the /context 20-glyph
- * grid driven by has1mContext('opus[1m]')) is preserved byte-for-byte.
- */
-/** The neutral wire shape of one model-catalog row (a structural subset of @sema-ai/sdk ModelInfo +
- *  mock/control/modelSelect.ts ModelInfo — name/id/provider/reasoning/vision drive the picker badges). */
 export interface LiveModelInfo {
     name: string;
     id?: string;
     provider?: string;
     reasoning?: boolean;
     vision?: boolean;
-    /** sdk `ModelInfo.routePairing`(#345,server ≥7.45 恒在场;真开集):这一行的 key↔URL 配对姿态;读法用 {@link routePairingVerdict}。 */
     routePairing?: string;
     [k: string]: unknown;
 }
-/** The `GET /v1/models` envelope: the catalog rows + the deployment default model id (display-only). */
 export interface LiveModelCatalog {
     models: LiveModelInfo[];
-    /** The served-by-default model id (models.list().default) — the boot mainLoopModel + the picker default desc. */
     default: string;
 }
-/** Install the live catalog (called once at boot from replEntry's live block). null clears it. */
 export declare function setLiveModelCatalog(next: LiveModelCatalog | null): void;
-/** boot 注册的重取器(与 boot fetch 同参)。k3 案(clay 2026-07-20):/config 改 Model ID 后
- *  同会话 /model 仍显旧目录名——目录只在 boot 拉一次。Hub 保存/面板打开时经此重取。 */
 export declare function setLiveModelCatalogRefresher(fn: (() => Promise<LiveModelCatalog | null>) | null): void;
-/** Re-fetch the live catalog (boot 参数);成功即替换 singleton 并返回 true。mock 路径(无
- *  refresher)/拉取失败 → false,现值不动(fail-soft,绝不用 null 清掉可用旧目录)。 */
 export declare function refreshLiveModelCatalog(): Promise<boolean>;
-/** Read the live catalog (null = mock path / live read failed → callers fall back to the static mock). */
 export declare function getLiveModelCatalog(): LiveModelCatalog | null;
-/**
- * 件4/MOD-6(F1 模型面批):id/name 双键归一。目录行有两个可寻址键 —— `name`(池 entry id,
- * /model 面板行的 value、@mention 的 handle)和 `id`(上游 modelId);/v1/models 的 `default`
- * 与 boot 回读可能给 id,面板/appState 用 name ⇒ 单键比对时 id≠name 的行匹配不上,面板追加
- * 合成 "Current model" 重复行、✔ 落错行。归一规则:ref 已是某行 name ⇒ 原样;否则命中某行
- * id ⇒ 归一到该行 name;目录缺失(mock 路径)/未命中 ⇒ 原样返回(mock parity 零影响)。
- */
 export declare function normalizeLiveModelRef(ref: string): string;
-/** 件4(S2 回显):目录 default 的用户名 —— name(池 entry id)优先,id 兜底;null=无目录
- *  (mock 路径,调用方回落 CC 字面护 parity)。 */
 export declare function liveDefaultModelName(): string | null;
-/** {@link routePairingVerdict} 的读数:`ok` / `broken` / `unknown` 三态 + 原样姿态词(缺席 / 非串时无 posture)。 */
 export interface RoutePairingVerdict {
     verdict: 'ok' | 'broken' | 'unknown';
     posture?: string;
 }
-/**
- * CC-06 / B-081(0.71.3):`ModelInfo.routePairing` 的读口 —— 只对 sdk 头注列出的**七词**给 verdict:四个 `ok:*` ⇒ ok
- * (凭据路说得通)/ 两个 `broken:*` ⇒ broken(真请求会被引擎拒:标红,给这只模型配 per-model 凭据或挪到部署根上)/
- * 其余一律 unknown(`unknown` 本身、未知词、缺席、非串、空串)—— 真开集下按前缀猜好坏 = 给一个契约没支持的词发正常 /
- * 故障提示(异源复审实抓);`posture` 原样带给端渲「未知(<词>)」。
- */
 export declare function routePairingVerdict(v: unknown): RoutePairingVerdict;

package/dist/liveModelCatalog.js

@@ -1,41 +1,11 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/liveModelCatalog.ts 逐字搬入(零依赖;🔴 catalog/refresher 是单实例态 —— 写口 setLiveModelCatalog/installer 与读口 getLiveModelCatalog 必须同实例)。
- */
-/**
- * src/sema/liveModelCatalog.ts — the LIVE model-catalog singleton (TEAM-C / clay decision #1 = A).
- *
- * WHY THIS FILE EXISTS
- * --------------------
- * The `/model` picker, the header model line, the /status "Model" row, and the picker's ✔ are all stuck on
- * a STATIC opus[1m] / a STATIC fictional catalog (mock/control/modelOptionsSeam.ts). The live engine actually
- * serves a different fleet — `client.models.list()` returns `{ models, default }` (the REAL catalog), and
- * `done.result.model` echoes the REAL served model (MF-25). This module is the one-shot, process-wide bridge
- * between the LIVE wire read (done once at boot in replEntry's live block) and the SYNCHRONOUS render-time
- * readers (getModelOptions, called inside the picker's React render — it cannot await).
- *
- * SINGLE INSTANCE (build discipline): replEntry.tsx (build-src/src/sema/replEntry.tsx) SETS the catalog and
- * mock/control/modelOptionsSeam.ts (build-src/mock/control/…, the aliased getModelOptions target) READS it.
- * Both resolve this module to ONE staged path (build-src/src/sema/liveModelCatalog.ts), so the singleton is
- * shared — the same single-instance invariant the seam-module fix in scripts/build.sema.mjs guarantees.
- *
- * MOCK PATH UNCHANGED: with SEMA_LIVE_BASEURL unset, no one calls setLiveModelCatalog → the catalog stays
- * null → getModelOptions falls back to the static fleetModels mock and the boot keeps opus[1m]. So the
- * cell-exact mock parity (the /model picker mock rows, the opus[1m] header/status, the /context 20-glyph
- * grid driven by has1mContext('opus[1m]')) is preserved byte-for-byte.
- */
 let catalog = null;
 let refresher = null;
-/** Install the live catalog (called once at boot from replEntry's live block). null clears it. */
 export function setLiveModelCatalog(next) {
     catalog = next;
 }
-/** boot 注册的重取器(与 boot fetch 同参)。k3 案(clay 2026-07-20):/config 改 Model ID 后
- *  同会话 /model 仍显旧目录名——目录只在 boot 拉一次。Hub 保存/面板打开时经此重取。 */
 export function setLiveModelCatalogRefresher(fn) {
     refresher = fn;
 }
-/** Re-fetch the live catalog (boot 参数);成功即替换 singleton 并返回 true。mock 路径(无
- *  refresher)/拉取失败 → false,现值不动(fail-soft,绝不用 null 清掉可用旧目录)。 */
 export async function refreshLiveModelCatalog() {
     if (!refresher)
         return false;
@@ -47,21 +17,12 @@ export async function refreshLiveModelCatalog() {
         }
     }
     catch {
-        /* fail-soft */
     }
     return false;
 }
-/** Read the live catalog (null = mock path / live read failed → callers fall back to the static mock). */
 export function getLiveModelCatalog() {
     return catalog;
 }
-/**
- * 件4/MOD-6(F1 模型面批):id/name 双键归一。目录行有两个可寻址键 —— `name`(池 entry id,
- * /model 面板行的 value、@mention 的 handle)和 `id`(上游 modelId);/v1/models 的 `default`
- * 与 boot 回读可能给 id,面板/appState 用 name ⇒ 单键比对时 id≠name 的行匹配不上,面板追加
- * 合成 "Current model" 重复行、✔ 落错行。归一规则:ref 已是某行 name ⇒ 原样;否则命中某行
- * id ⇒ 归一到该行 name;目录缺失(mock 路径)/未命中 ⇒ 原样返回(mock parity 零影响)。
- */
 export function normalizeLiveModelRef(ref) {
     if (!catalog || !ref)
         return ref;
@@ -70,22 +31,13 @@ export function normalizeLiveModelRef(ref) {
     const row = catalog.models.find(m => typeof m.id === 'string' && m.id === ref);
     return row?.name || ref;
 }
-/** 件4(S2 回显):目录 default 的用户名 —— name(池 entry id)优先,id 兜底;null=无目录
- *  (mock 路径,调用方回落 CC 字面护 parity)。 */
 export function liveDefaultModelName() {
     if (!catalog?.default)
         return null;
     return normalizeLiveModelRef(catalog.default);
 }
-/** sdk `RoutePairingStatus` 已知七词(9.6.0 `types.d.ts`);头注逐字「switch 认上面七词,再留一条 default 臂当未知」。 */
 const ROUTE_PAIRING_OK = new Set(['ok:per-model', 'ok:paired', 'ok:unpinned', 'ok:keyless']);
 const ROUTE_PAIRING_BROKEN = new Set(['broken:credential_mismatch', 'broken:credential_missing']);
-/**
- * CC-06 / B-081(0.71.3):`ModelInfo.routePairing` 的读口 —— 只对 sdk 头注列出的**七词**给 verdict:四个 `ok:*` ⇒ ok
- * (凭据路说得通)/ 两个 `broken:*` ⇒ broken(真请求会被引擎拒:标红,给这只模型配 per-model 凭据或挪到部署根上)/
- * 其余一律 unknown(`unknown` 本身、未知词、缺席、非串、空串)—— 真开集下按前缀猜好坏 = 给一个契约没支持的词发正常 /
- * 故障提示(异源复审实抓);`posture` 原样带给端渲「未知(<词>)」。
- */
 export function routePairingVerdict(v) {
     if (typeof v !== 'string' || v.length === 0)
         return { verdict: 'unknown' };

package/dist/liveQuestionStore.d.ts

@@ -1,63 +1,20 @@
 import type { AskAnswer } from './hitl/hitlBridge.js';
-/**
- * src/sema/liveQuestionStore.ts — the SIDE-CHANNEL for §4④ live-stream AskUserQuestion (the conversation-seam
- * twin of liveSessionStore.ts).
- *
- * WHY THIS EXISTS
- * ---------------
- * In TOC (two-process) the MODEL runs in the engine; its `AskUserQuestion` tool fires on core's
- * `RunnerDeps.onQuestion` seam and the service (question.ts, 1.61.0) emits a NAMED SSE frame
- * (`event: question` / `event: question_complete`) that INTERLEAVES on the same live token stream as the
- * AgentEvents. That frame is NOT an AgentEvent arm (it is a DISTINCT vocabulary, exactly like elicitation) —
- * so it must be DEMUXED out of the transcript-render pipeline and routed to an interactive DIALOG overlay
- * instead. This tiny, dependency-FREE module is that route: liveClient WRITES the demuxed frame here (on each
- * `question`/`question_complete`) and publishes its `client.questions.respond` binding; the UI overlay
- * (main.tsx / REPL) READS the frames and answers via `respondToQuestion`. Same shape as liveSessionStore /
- * rewindAnchorStore — the overlay stays testable (no @sema-ai/sdk graph) and seamQuery/normalizeToolNames are
- * untouched.
- *
- * 🔴 LIVE-ONLY + SAME-REPLICA (the `steer()`-class of HITL): the service parks the answer promise in-memory,
- * so a respond that lands after the TTL (5 min) / after answer / on another replica → 404. No durable resume
- * anchor — a mid-question disconnect just lets the run proceed with the headless default (the model never
- * hangs). The overlay must therefore treat `respondToQuestion` as best-effort (a 404 = "already released",
- * dismiss the dialog, never retry).
- *
- * 🔴 UNTRUSTED: the `questions` payload is model-authored (service secret-redacted, but still UNTRUSTED for
- * display). The overlay RENDERS it; it must NEVER be re-fed to a model. The answer the overlay sends back is
- * fenced by CORE (`selected ⊆ options`, `note` untrusted-fenced) — the overlay must echo the EXACT option
- * labels the user saw, never fabricate one.
- */
-/** One option of an AskUserQuestion question (CC AskUserQuestionTool option shape). */
 export interface AskQuestionOption {
-    /** EXACT display label — the answer echoes labels verbatim (core fences `selected ⊆ options`). */
     label: string;
     description?: string;
 }
-/** One model-authored question (UNTRUSTED: render-only, never re-fed to a model). */
 export interface AskQuestion {
-    /** The question text (the CC dialog keys its answers Record by this). */
     question: string;
-    /** Short header — the WIRE answer is keyed by this (see {@link QuestionAnswer}). */
     header: string;
     options: AskQuestionOption[];
     multiSelect: boolean;
 }
-/** A demuxed/synthetic live question frame (legacy 1.61 wire payload `{type,questionId,questions?,outcome?}`;
- *  today also synthesized locally by liveHitlAskWire (`hitl-ask:*`) and planReviewWire (`plan-review:*`)).
- *  `question` opens the dialog overlay; `question_complete` dismisses a still-open one. */
 export interface QuestionFrame {
     type: 'question' | 'question_complete';
     questionId: string;
-    /** Present on `question` frames; may be absent when the service dropped an over-cap payload. */
     questions?: AskQuestion[];
-    /** `question_complete` only (legacy wire): why the ask was released (answered/expired/aborted). */
     outcome?: string;
 }
-/** The answer the overlay sends back — keyed by HEADER; `selected` echoes exact option labels
- *  (`selected ⊆ options`, core's fence); off-list / free-text input rides `note` (untrusted-fenced).
- *  REF-CC-038(2026-08-02):entry 直接是 hitlBridge 的 `AskAnswer`(唯一源),不再各写一份 ——
- *  之前这里是一份内联匿名形的独立声明,只靠注释断言与 hitlBridge 那份「形状相同」,
- *  下游(`askGateWire.ts`)因此要 `as AskAnswer[]` 兜齐两个名不同的等价形状。 */
 export interface QuestionAnswer {
     answers: AskAnswer[];
 }
@@ -65,62 +22,18 @@ type QuestionFrameHandler = (frame: QuestionFrame) => void;
 type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
     signal?: AbortSignal;
 }) => Promise<unknown>;
-/** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
- *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
 export declare function registerLocalQuestionResponder(id: string, fn: RespondFn): () => void;
-/**
- * Unregister a local responder **by id**(A-028.4 复审二轮收紧,2026-08-12)。
- *
- * 为什么需要按 id 注销:`registerLocalQuestionResponder` 的注销钩只回到注册方手里,而重开腿
- * (`planReviewWire.reopenPlanReviewCard`)要退役的是**别的注册方**(arm 臂)登记的 canonical
- * responder —— 只发 `question_complete` 撤帧撤不掉表里的 responder,一个在途的迟到作答仍能经
- * 它投递决断,与新卡的投递构成同一 gate 的双决断面。返回是否真删了一条(调用方留痕用)。
- * 🔴 只删表项,不通知原注册方 —— 原注册方的自愈臂(如 arm 的陈旧武装态分支)按
- * `hasLocalQuestionResponder` 探询真相,不依赖回调。
- */
 export declare function unregisterLocalQuestionResponder(id: string): boolean;
-/**
- * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
- *
- * 🔴 为什么这是**只读探询**而不是「谁注册谁自己记着就行」:上面那条契约把「对话框被 dismiss 却没
- * 作答」的清理责任交给了 caller,而 caller(planReviewWire)自己那份武装态与这张表是**两个**容器 ——
- * 两个容器各自都可能被单方面改动(`respondToQuestion` 的一次性 delete、别的注册把同 id 顶掉后再
- * 注销),于是「我以为还武装着」和「表里还真有人收答」会漂开。漂开的后果不是多弹一张卡,是
- * **一张都不弹**:去重短路认为卡还在,而实际上没有任何 responder 能收答([paired-mechanisms-must-
- * share-premise])。给出这条探询口,让去重臂能问真相而不是问自己的记忆。
- *
- * 🔴 只回答布尔:responder 函数本身绝不出境(它闭包着 caller 的一次性状态,交出去就有第二个调用者)。
- */
 export declare function hasLocalQuestionResponder(id: string): boolean;
-/**
- * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
- * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER
- * break the live stream drain (the run must keep flowing; a lost frame just headless-defaults the ask).
- */
 export declare function publishQuestionFrame(frame: QuestionFrame): void;
-/** W1 keyed variant: publish to ONE session's overlay (multi-session hosts demux by their own key). */
 export declare function publishQuestionFrameFor(sessionKey: string, frame: QuestionFrame): void;
-/** Whether a UI overlay is currently subscribed (liveHitlAskWire gates on this: print/non-REPL mode has no
- *  dialog to park on, so the suspended terminal must fall through honestly instead of hanging the stream). */
 export declare function hasQuestionOverlay(): boolean;
-/** W1 keyed variant. */
 export declare function hasQuestionOverlayFor(sessionKey: string): boolean;
-/** Subscribe the UI overlay to live question frames. Returns an unsubscribe. Last writer wins (one overlay). */
 export declare function onQuestionFrame(handler: QuestionFrameHandler): () => void;
-/** W1 keyed variant: one overlay PER sessionKey (last writer wins within a key; keys never clobber
- *  each other — the r1 E2 dual-session hazard this registry exists to close). */
 export declare function onQuestionFrameFor(sessionKey: string, handler: QuestionFrameHandler): () => void;
-/** Publish the live client's `questions.respond` binding (called from createLiveConversationClient). `null`
- *  clears it (offline/mock → respondToQuestion rejects cleanly). */
 export declare function setQuestionRespond(fn: RespondFn | null): void;
-/**
- * Answer a parked live question (POST /v1/questions/:id/respond via the live client). Rejects when no live
- * client is wired (offline/mock) so the overlay can fall back / dismiss. The 404 (answered/expired/wrong
- * replica) surfaces as a thrown ApiError — the overlay treats it as "already released", never a retry.
- */
 export declare function respondToQuestion(id: string, answer: QuestionAnswer, opts?: {
     signal?: AbortSignal;
 }): Promise<unknown>;
-/** Test-only reset. */
 export declare function _resetLiveQuestionStore(): void;
 export {};

package/dist/liveQuestionStore.js

@@ -1,62 +1,22 @@
-/**
- * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/liveQuestionStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
- * 本模块自持 AskUserQuestion 的 wire 词汇(SDK 0.0.44 删掉了 questions 资源导出),搬入后这套
- * 类型随包发布 —— web/桌面端的 HITL 覆盖层与 TUI 共用同一份 QuestionFrame/QuestionAnswer 形。
- */
 import { createSessionSlot, DEFAULT_SESSION_KEY } from './sessionSlot.js';
-// W1(design/161):frameHandler 槽位改 sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY
-// 兼容层(cli 装配不动)。respondFn / localResponders 不在 W1 五槽位切口内,维持原样。
 const frameHandlerByKey = createSessionSlot();
 let respondFn = null;
-/** SHELL-LOCAL question responders (plan-review approval cards etc. — synthetic frames whose id does
- *  NOT exist engine-side, so POST /v1/questions/:id/respond would 404). Registered per-questionId by
- *  the frame's publisher; consumed once (respond removes the entry). Checked BEFORE the live respond. */
 const localResponders = new Map();
-/** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
- *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
 export function registerLocalQuestionResponder(id, fn) {
     localResponders.set(id, fn);
     return () => {
         localResponders.delete(id);
     };
 }
-/**
- * Unregister a local responder **by id**(A-028.4 复审二轮收紧,2026-08-12)。
- *
- * 为什么需要按 id 注销:`registerLocalQuestionResponder` 的注销钩只回到注册方手里,而重开腿
- * (`planReviewWire.reopenPlanReviewCard`)要退役的是**别的注册方**(arm 臂)登记的 canonical
- * responder —— 只发 `question_complete` 撤帧撤不掉表里的 responder,一个在途的迟到作答仍能经
- * 它投递决断,与新卡的投递构成同一 gate 的双决断面。返回是否真删了一条(调用方留痕用)。
- * 🔴 只删表项,不通知原注册方 —— 原注册方的自愈臂(如 arm 的陈旧武装态分支)按
- * `hasLocalQuestionResponder` 探询真相,不依赖回调。
- */
 export function unregisterLocalQuestionResponder(id) {
     return localResponders.delete(id);
 }
-/**
- * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
- *
- * 🔴 为什么这是**只读探询**而不是「谁注册谁自己记着就行」:上面那条契约把「对话框被 dismiss 却没
- * 作答」的清理责任交给了 caller,而 caller(planReviewWire)自己那份武装态与这张表是**两个**容器 ——
- * 两个容器各自都可能被单方面改动(`respondToQuestion` 的一次性 delete、别的注册把同 id 顶掉后再
- * 注销),于是「我以为还武装着」和「表里还真有人收答」会漂开。漂开的后果不是多弹一张卡,是
- * **一张都不弹**:去重短路认为卡还在,而实际上没有任何 responder 能收答([paired-mechanisms-must-
- * share-premise])。给出这条探询口,让去重臂能问真相而不是问自己的记忆。
- *
- * 🔴 只回答布尔:responder 函数本身绝不出境(它闭包着 caller 的一次性状态,交出去就有第二个调用者)。
- */
 export function hasLocalQuestionResponder(id) {
     return localResponders.has(id);
 }
-/**
- * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
- * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER
- * break the live stream drain (the run must keep flowing; a lost frame just headless-defaults the ask).
- */
 export function publishQuestionFrame(frame) {
     publishQuestionFrameFor(DEFAULT_SESSION_KEY, frame);
 }
-/** W1 keyed variant: publish to ONE session's overlay (multi-session hosts demux by their own key). */
 export function publishQuestionFrameFor(sessionKey, frame) {
     const frameHandler = frameHandlerByKey.get(sessionKey);
     if (!frameHandler)
@@ -65,24 +25,17 @@ export function publishQuestionFrameFor(sessionKey, frame) {
         frameHandler(frame);
     }
     catch {
-        /* a UI handler throw must never propagate into the AgentEvent drain */
     }
 }
-/** Whether a UI overlay is currently subscribed (liveHitlAskWire gates on this: print/non-REPL mode has no
- *  dialog to park on, so the suspended terminal must fall through honestly instead of hanging the stream). */
 export function hasQuestionOverlay() {
     return hasQuestionOverlayFor(DEFAULT_SESSION_KEY);
 }
-/** W1 keyed variant. */
 export function hasQuestionOverlayFor(sessionKey) {
     return frameHandlerByKey.get(sessionKey) !== undefined;
 }
-/** Subscribe the UI overlay to live question frames. Returns an unsubscribe. Last writer wins (one overlay). */
 export function onQuestionFrame(handler) {
     return onQuestionFrameFor(DEFAULT_SESSION_KEY, handler);
 }
-/** W1 keyed variant: one overlay PER sessionKey (last writer wins within a key; keys never clobber
- *  each other — the r1 E2 dual-session hazard this registry exists to close). */
 export function onQuestionFrameFor(sessionKey, handler) {
     frameHandlerByKey.set(sessionKey, handler);
     return () => {
@@ -90,20 +43,13 @@ export function onQuestionFrameFor(sessionKey, handler) {
             frameHandlerByKey.set(sessionKey, undefined);
     };
 }
-/** Publish the live client's `questions.respond` binding (called from createLiveConversationClient). `null`
- *  clears it (offline/mock → respondToQuestion rejects cleanly). */
 export function setQuestionRespond(fn) {
     respondFn = fn;
 }
-/**
- * Answer a parked live question (POST /v1/questions/:id/respond via the live client). Rejects when no live
- * client is wired (offline/mock) so the overlay can fall back / dismiss. The 404 (answered/expired/wrong
- * replica) surfaces as a thrown ApiError — the overlay treats it as "already released", never a retry.
- */
 export function respondToQuestion(id, answer, opts) {
     const local = localResponders.get(id);
     if (local) {
-        localResponders.delete(id); // one-shot — a second respond on the same card must not double-fire
+        localResponders.delete(id);
         return local(id, answer, opts);
     }
     if (!respondFn) {
@@ -111,7 +57,6 @@ export function respondToQuestion(id, answer, opts) {
     }
     return respondFn(id, answer, opts);
 }
-/** Test-only reset. */
 export function _resetLiveQuestionStore() {
     frameHandlerByKey.clear();
     respondFn = null;