@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/liveInitToolFace.d.ts

@@ -1,3 +1,53 @@
+/**
+ * ⇄ 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 { type EngineProbeOpts } from './engineWireSdk.js';
 import type { EnvLike } from './hostEnv.js';
 /** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
 export declare const ENGINE_HANDS_BAND: readonly string[];
@@ -30,12 +80,7 @@ export declare function _resetLiveInitToolFaceForTest(): void;
  *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
  *  差分:SDK Transport 恒 stamp x-agent-principal(缺省 'anon:shell-live')——原手抄在无 principal
  *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
-export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: {
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-    authToken?: string;
-    principal?: string;
-}): Promise<{
+export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: EngineProbeOpts): Promise<{
     tools: string[];
     toolset?: string;
 } | null>;

package/dist/liveQuestionStore.d.ts

@@ -1,3 +1,4 @@
+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).
@@ -54,13 +55,11 @@ export interface QuestionFrame {
 }
 /** 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).
- *  Entry shape === hitlBridge's AskAnswer (the T23 ApprovalDecision.answer leg consumes it as-is). */
+ *  REF-CC-038(2026-08-02):entry 直接是 hitlBridge 的 `AskAnswer`(唯一源),不再各写一份 ——
+ *  之前这里是一份内联匿名形的独立声明,只靠注释断言与 hitlBridge 那份「形状相同」,
+ *  下游(`askGateWire.ts`)因此要 `as AskAnswer[]` 兜齐两个名不同的等价形状。 */
 export interface QuestionAnswer {
-    answers: Array<{
-        header: string;
-        selected: string[];
-        note?: string;
-    }>;
+    answers: AskAnswer[];
 }
 type QuestionFrameHandler = (frame: QuestionFrame) => void;
 type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
@@ -69,6 +68,19 @@ type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
 /** 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;
+/**
+ * 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

package/dist/liveQuestionStore.js

@@ -20,6 +20,21 @@ export function registerLocalQuestionResponder(id, fn) {
         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

package/dist/model/providerPresets.js

@@ -85,7 +85,17 @@ export function inferFamily(modelId) {
         const ctx = capSuffix[2] === 'm' ? n * 1000000 : n * 1024;
         const base = inferFamily(raw.replace(/\[[0-9]+[km]\]$/, ''));
         // perModelCap 透传:后缀只声明 ctx,不改该模型的确证输出 cap(deepseek-chat[1m] 仍 cap 8192)
-        return { id: base?.id ?? 'cap-suffix', name: base?.name ?? 'capacity suffix', match: '', contextWindow: ctx, maxTokens: base?.maxTokens ?? 64000, vision: base?.vision, perModelCap: base?.perModelCap };
+        // eopt:vision/perModelCap 是「缺省=未知不 stamp」的条件展开位(与 taskId/status 那种「键恒在」
+        // 公面契约不同义——那两位没有「已确认为未知」这个第三态,这两位有),诚实透传 base 的键在场与否。
+        return {
+            id: base?.id ?? 'cap-suffix',
+            name: base?.name ?? 'capacity suffix',
+            match: '',
+            contextWindow: ctx,
+            maxTokens: base?.maxTokens ?? 64000,
+            ...(base?.vision !== undefined ? { vision: base.vision } : {}),
+            ...(base?.perModelCap !== undefined ? { perModelCap: base.perModelCap } : {}),
+        };
     }
     const id = normalizeId(raw);
     // ① preset 大表精确(含剥变体尾巴后再试)——精确命中才带 perModelCap(F2 裁决封顶① 证据位;

package/dist/notifications.d.ts

@@ -176,6 +176,37 @@ export declare function outstandingWorkflowCount(): number;
  *  必然送达或 TTL 放弃(2h 上界=run 蒸发极端形,与 CC 等本地 bg 任务的无界形同族)。 */
 export declare function outstandingDeliverableWorkflowCount(): number;
 export declare function subscribeOutstandingWorkflows(listener: () => void): () => void;
+/**
+ * 🔴 已**停止等待**的 outstanding 条目数(workflow + bg 合计,process-lifetime 只增)。
+ * 消费方(footer / headless 退出前的收尾行)据此把「N 个后台任务已停止等待」与「都送达了」
+ * 分开渲——H1:排队与放弃对消费方必须可分辨。additive:既有计数口的语义一字节不变。
+ */
+export declare function outstandingAbandonedCount(): number;
+/**
+ * 观测口:被**静默 return 掉**的投递次数(notif-02)。去重与丢失在行为上都是「不入队」,
+ * 不记账就在观测上等价 —— 分成两个键是因为它们的正当性完全不同:
+ *   · `bgDedupDropped` = 同 (taskId,seq,status) 键重复,**正当**(at-least-once 双投自免),恒可 >0;
+ *   · `bgCrossChannelDropped` = 首周期已由别的通道送达而被压制,**正当但需可查**(seq 透传一旦
+ *     回归,复活周期会伪装成首周期落进这一格 —— 这个数异常增长就是 seq 又丢了的信号);
+ *   · `stuckTickResets` = 在飞 tick 超过 STUCK_TICK_RESET_MS 被强制复位的次数,**恒应为 0**;
+ *     >0 = 有 probe 连 PROBE_TIMEOUT_MS 都没能截断它。
+ *
+ * 🔴 [2393] F-1 补两格 —— 上面三格全是 **enqueue 内部**的记账,而 watcher 收摊臂在到达 enqueue
+ * **之前**就把台账条目删掉了:「复活周期被秒删」这条路径对上面三格 100% 不可见(立案时被点名当
+ * 信号的 `bgCrossChannelDropped` 正是这样对它零判别力的)。删除动作要挣得,也要看得见:
+ *   · `bgWatchRevivalPromoted` = 收摊臂靠 probe 实证「任务又在跑」把条目升到新周期的次数
+ *     —— 正是修前被静默秒删的那一类;>0 说明 wire 的 seq 没到货,壳在自己补周期号;
+ *   · `bgWatchCollectedUnprobed` = probe 未装(mock/离线)时按裸 id 黑名单**盲摘**的次数,
+ *     这是唯一保留的无证据删除;>0 = 有完成周期在这类宿主上恒不可观察。
+ */
+export interface NotificationDropCounters {
+    bgDedupDropped: number;
+    bgCrossChannelDropped: number;
+    stuckTickResets: number;
+    bgWatchRevivalPromoted: number;
+    bgWatchCollectedUnprobed: number;
+}
+export declare function notificationDropCounters(): NotificationDropCounters;
 /** liveClient 在构造会话 client 时注册(带正确 baseUrl/token/principal 的 workflows.get)。 */
 export declare function installWorkflowStatusProbe(probe: WorkflowStatusProbe): void;
 type BgTaskStatusProbe = (taskId: string) => Promise<{
@@ -185,8 +216,22 @@ type BgTaskStatusProbe = (taskId: string) => Promise<{
 /** 委派 prompt 取件口(行消费端建行/详情页兜底用)。未登记 ⇒ undefined(诚实缺席)。 */
 export declare function outstandingBgTaskPrompt(taskId: string): string | undefined;
 export declare function installBgTaskStatusProbe(probe: BgTaskStatusProbe): void;
-/** bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。幂等;已通知不再登记。 */
-export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string): void;
+/**
+ * bridge 在 Agent async_launched 回执(structured type:'agent')经过时登记。按 (taskId,seq) 幂等。
+ *
+ * 🔴 notif-02(两账分离):登记闸**不再查 `notifiedRunIds`**。那个集合是「模型通知去重」账
+ * (哪次完成已经喂给模型了),不是「是否还要观察」账;两账混用的后果是 seq≥2 的复活周期
+ * 永远登记不进来(`notifiedRunIds` 全文无 delete 站点,首周期一通知就是终身黑名单)。
+ * 首周期若确已送达,由 watcher 的收摊臂在下一拍摘除(见 `tickWatchInner` bg 半场),
+ * 代价是一次 no-op 遍历,而不是一整个完成周期的结构性缺席。
+ *
+ * 🔴 [2393] F-1:`seq` 缺席时这里仍然**按首周期解释,不在登记口猜周期号** —— 猜出来的周期号会
+ * 把「已终局任务的回执重放」也升成新周期,方向相反地造出重复通知。周期号只在 watcher 那侧、
+ * 拿到 probe 的「它又在跑」这个证据之后才前进(见 `tickWatchInner` 的收摊臂三档)。
+ *
+ * @param seq bg 子代生命周期号;wire 未带 ⇒ 按首周期(BG_FIRST_SEQ)解释,复活周期由 watcher 补。
+ */
+export declare function registerOutstandingBgTask(taskId: string, description: string, prompt?: string, seq?: number): void;
 export declare function isOwnWorkflowRun(runId: string): boolean;
 /** 本壳亲手启动过的 workflow run 列表(Set 插入序 = 启动序;/workflows 命令的目标 run 选择用,
  *  cmd-workflows.tsx——fleet source 无行可选时的兜底 id 源)。 */
@@ -211,6 +256,21 @@ export declare function enqueueEngineWorkflowNotification(c: EngineWorkflowCompl
 /** 测试钩(B2 新增,壳侧原文件没有):清空全部通知台账 + probe 槽 + watcher。
  *  🔴 生产绝不调用 —— 台账是 process-lifetime 去重的唯一凭据,清了就会双投。 */
 export declare function _resetEngineTaskNotificationForTest(): void;
+/**
+ * 测试钩:**驱动一拍** watcher(生产由 setInterval 驱动,外部无入口 ⇒ 护栏/TTL/deadline
+ * 三条链在门里全不可达,notif-01/-02/-03 才会一路活到今天)。
+ * @param nowMs TTL 判据的时钟注入(WATCH_TTL_MS 是 2h,不注入时钟就只能真等两小时)。
+ * 🔴 生产绝不调用。
+ */
+export declare function _tickWatchOnceForTest(nowMs?: number): Promise<void>;
+/**
+ * 测试钩:覆写 watcher 时序常量(默认是 10s/60s 量级,门里等不起)。传 null 恢复生产值。
+ * 🔴 生产绝不调用;覆写只影响 deadline 与强制复位门,不动 WATCH_INTERVAL_MS/WATCH_TTL_MS。
+ */
+export declare function _setWatcherTimingForTest(o: {
+    probeTimeoutMs?: number;
+    stuckTickResetMs?: number;
+} | null): void;
 /** 该 objective 是否为 task-notification 自动提交 turn 的注入 XML(整体即通知,非提及)。 */
 export declare function isTaskNotificationObjective(objective: unknown): boolean;
 /**