@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hooksWireCaps.d.ts

@@ -2,46 +2,8 @@ import { type HookFailureNotice } from './notifications.js';
 import type { WireHooksConfig } from './finalVerifyWire.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 export type { WireHooksConfig };
-/**
- * The merged, GOVERNANCE-GATED settings-file hooks for the wire, or undefined when none apply.
- * Per-event arrays concatenate across sources (policy → user → project → local).
- */
 export declare function hooksForWire(): WireHooksConfig | undefined;
-/** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
 export declare function __resetHooksWireCapsForTests(): void;
-/**
- * 这台引擎会不会发 `hook_non_blocking_failure` 观测帧(hook 自己坏了的那一族)。
- *
- * 🔴 **能力位嵌在 `fleet` 对象里**,不是顶层键 —— server `dist/http/routes/capabilities.js:52`:
- * `fleet: { stream, sessionScope, observe, resume, bgNotifyFailClosed, steerPriority,
- *  hookFailureNotice: true }`。拿平铺口 `engineCapTrue(base,'hookFailureNotice')` 去读**恒 false**
- * (白读),而白读的后果不是报错、是安静地把新车道判成没有。
- * 🔴 未判/父键缺席/父键为 `false`(整族不供)/子键缺席 ⇒ **false** = fail-closed。
- *
- * 🔴 **它是 affordance 判据,不是上屏闸**:一帧真到货的故障通知**不该**被本位闸掉 —— 帧在手里
- * 就是最强证据,而能力位在探测落地前恒 false,拿它闸会把早到的真实故障静默掉(方向与 #281 相反)。
- * 本位的正当用途 = 「要不要在设置/状态面声称有这项监测」。判定口见 `notifications.ts`
- * 的 `classifyHookFailureFrame`(那里刻意不读本位)。
- */
 export declare function fleetHookFailureNoticeCapable(baseUrl: string | undefined): boolean;
-/** footer 横幅文案前缀(测试锁字面;与 `HOOK_NOTICE_WARN_PREFIX` 同族风格)。 */
 export declare const HOOK_FAILURE_WARN_PREFIX = "Hook error";
-/**
- * 「这个 hook 自己坏了」的**单行**横幅文案(hook 名 + 故障形/退出码 + stderr 摘要)。
- *
- * 🔴 **为什么在本文件而不是 `notifications.ts`**:文案口要过展示消毒单源 `collapseLabel`
- * (在 `fleetTaskDesc.ts`),而 `notifications.ts` 在 **A 层闭包**内(portability 门只降棘轮)——
- * 从那里 import 会让闭包涨一格,手抄第二份字符集又是 `fleetTaskDesc` 顶注点名禁止的形。
- * ⇒ 判定留 `notifications.ts`(它只交出**原文**),展示归本层。
- *
- * 🔴 **绝不编造退出码**:`timeout` / `spawn_failed` 上没有 `exitCode`,那两形只报故障词
- * (写 `exit 0` 会让人去查一个根本不存在的退出码)。
- * 🔴 **两位都是 UNTRUSTED-for-display**(异源对抗复审二轮 [medium] 采纳):`hookName` 的一手源是
- * **用户 settings 里自己写的** `statusMessage` / command / url / prompt;`stderr` 是**坏 hook 自己吐的
- * 流**。server 只做脱敏 + 截断、**不做控制符消毒**(与 `workerBadge.name` / fleet 行标签同一条分工)。
- * 不消毒的后果不是难看:一个带 `\n` / ESC / RLO 的 hook 名能把「**哪个**安全 hook 失效了」这条
- * **唯一**告警重排、截断或整段藏掉,而这条横幅存在的全部理由就是让那件事看得见。
- * 🔴 **单行**:渲染面是 `wrap="truncate"` 的一行;`collapseLabel` 同时做 `\s+` 折平与控制符/双向符/
- * 孤代理项可见化转义,两件事一把做完(不在这里手抄第二份字符集)。
- */
 export declare function hookFailureNoticeText(n: HookFailureNotice): string;

package/dist/hooksWireCaps.js

@@ -1,122 +1,10 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B2 判给后批的**宿主耦合六件**之一,也是最后一件大的):
- *    cli `src/sema/hooksWireCaps.ts` 整搬。B2 当时不搬的唯一理由 = 它读三层 settings 文件 +
- *    工作区信任门,而那时还没有 `SettingsPort`;B4 把口定出来了(host.ts `SettingsPort`),本批接线。
- *
- * 🔴 搬迁四处差分(端资产上移到 port,行为一字节不变):
- *   ① `getSettingsForSource`(cli `utils/settings/settings.ts`)→ `hostSettings()?.getSettingsForSource`;
- *   ② `shouldSkipHookDueToTrust`(cli `utils/hooks.ts`,原文用 **lazy `require()`** 避免把大图拖进
- *      静态依赖)→ `hostSettings()?.shouldSkipHookDueToTrust` —— port 化之后 lazy require 的理由
- *      连同 `require` 本身一起消失(本包零 CJS,portability 门的产物断言盯着 `require(`);
- *   ③ `logForDebugging` → `hostLog('debug', …)`;
- *   ④ `process.env` 缺省参 → `hostEnv()`。
- *
- * 🔴 **SettingsPort 缺席的后果不是「少读一层配置」,是把治理门整个拆了**:
- *    `shouldSkipHookDueToTrust` 是**安全门**(未受信工作区的 hook 绝不上 wire)。端不实现它 =
- *    信任门在引擎腿上不存在。所以本文件在 port 缺席时**整体 fail-closed 返回 undefined**
- *    (= 一条 hook 都不投),而不是「读不到 settings 就当没有治理策略、把 goal 钩子照投」。
- *    ⚠️ 这与壳侧原文那条「早启动就 fall through」的 catch **不同**,是本批唯一的语义差:
- *    壳里那条 catch 的前提是「本地执行器仍会 per-fire 把门」(单进程);库里没有那个兜底,
- *    端要么装 port 要么这条腿不启用。`hostPortMisses().settings` 会把漏装喊出来。
- *
- * 🔴 模块级状态:`wireSessionStopHookPrompt` / `wireSessionStopHookCcSemantics`(`/goal` 的会话级
- *    Stop 钩子锁存)——写口 `setWireSessionStopHook`(命令层)、读口 `hooksForWire`(每 turn 请求
- *    构造期)与 `getWireSessionStopHook`(`/goal clear` 回显)。两份实例 = 设了目标却投不出去
- *    (而两边代码看着都对)。单实例清单登记项。
- *    ⇄ REF-CC-156(midband-04,split,2026-08-02):这份状态 + 版本判档 + prompt 组装已拆到
- *    `./goalStopHook.ts`(原文件那一半占体量 57%、是独立关注点——`/goal` 命令专属,与本文件剩下
- *    的「通用 settings-file hooks 投影 + 治理门」不是同一件事)。本文件只在 `hooksForWire()` 尾部
- *    调 `goalStopHookMatcher()` 合流一次;所有对外名字原样从这里 re-export,调用方 import 路径
- *    零改动。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * hooksWireCaps — project the user's settings-file hooks onto the wire (`TaskRequest.settings.hooks`).
- *
- * service 1.131.0 hook-runner 阶段一([495]①,契约 = @sema-ai/registry-core/hooks 0.1.51, CC 2.1.198
- * 逐字形状):引擎消费 `body.settings.hooks`,当前点亮 PreToolUse + PostToolUse × command 条目(真
- * /bin/sh -c,exit-2 阻断 stderr 喂模型,matcher 精确/`a|b`/锚定正则);其余事件配置合法不点亮
- * (`hook_events_not_fired` 记账,后续阶段自动亮)。这正是 live 模式的空缺半场:工具在引擎执行,
- * 壳本地永远 fire 不了工具链 hooks — 30 事件枚举里的 ENGINE_OWNED 常量(rc.36 壳半场)壳侧只做
- * schema 合法,不触发,所以整份投影零双跑。
- *
- * GOVERNANCE GATES (对抗复审 rc.41 review HIGH — the wire must honor the SAME gates the local executor
- * honors, or a fleet-managed policy is silently bypassed by the engine leg):
- *  - workspace trust: interactive sessions with the trust dialog unaccepted ship NO hooks
- *    (shouldSkipHookDueToTrust — the rc.36 "hooks 全被 trust 门禁" invariant, engine leg included);
- *  - `disableAllHooks` (managed/policy settings): ships NO hooks;
- *  - `allowManagedHooksOnly`: ONLY the policy-settings hooks ship; user/project/local are blocked;
- *  - `strictPluginOnlyCustomization` covering the "hooks" surface (L-67④, 0.52.0): same disposition as
- *    `allowManagedHooksOnly` — ONLY the policy-settings hooks ship. Verbatim parity with the local
- *    executor's `isRestrictedToPluginOnly('hooks')` is argued clause-by-clause on
- *    {@link hooksLockedToPluginOnly}.
- *
- * 🔴 **在册缺口(同形族扫所得,本批刻意未修 —— 别把它读成「已经守住了」)**:cli 本地执行器
- *    (`src/utils/hooks/hooksConfigSnapshot.ts:getHooksFromAllowedSources`)还有**第四条**腿 ——
- *    `disableAllHooks` 出现在**非** managed 的来源(user/project/local)时,按 CC 语义降级成
- *    「只跑 managed hooks」(非 managed 设置不能禁掉 managed hooks,但能禁掉自己)。本文件今天
- *    **只读 `policySettings.disableAllHooks`** ⇒ 这一形在引擎腿上不成立(用户把自己的 hooks 关了,
- *    引擎照投照跑)。**为什么本批不修**:cli 那条腿读的是**合并后**的标量
- *    (`getSettings_DEPRECATED().disableAllHooks`,四源按 policy→user→project→local 后写覆盖前写),
- *    而本包的 `SettingsPort` 只有 per-source 读口 —— 拿「任一来源为 true」去近似合并结果会在
- *    「user 写 true、local 写 false」这一形上判反(cli 那边是**不**限制)。忠实复刻需要给
- *    `SettingsPort` 加一个合并读口 = **公面改动**,属另一批(端要跟车实现)。
- *    ⇒ 登记在此,不做单边近似([honest-absence-not-fabricated-zero]:守不住就说守不住,
- *    别用一个会判反的近似冒充守住了)。
- *
- * Projection semantics (CC settings merge, verbatim shapes):
- *  - Sources: policy → user → project → local settings files, per-event arrays CONCATENATED in that
- *    order (CC's own multi-source hook semantics — later scopes append, they don't shadow).
- *  - Values pass through AS-IS including malformed entries (对抗复审 MED: dropping them client-side is a
- *    silent-fallback; the service 400s fail-loud with a field path, which the turn error card shows).
- *  - Presence is the opt-in: no hooks configured ⇒ undefined ⇒ no stamp ⇒ request shape unchanged.
- *  - Session-scoped runtime hooks and plugin/skill hooks are NOT projected in phase one (they carry
- *    pluginRoot/skillRoot expansion contexts the wire contract doesn't model yet).
- *  - Multi-tenant deployments advertise `taskSettings.hooks:false` and warn+ignore server-side, so
- *    the shell does not pre-gate on capabilities (single-user TOC is always true — [495]① note ①).
- *
- * Secrets: hook processes run under the SERVICE's env allowlist (PATH/HOME/locale + CLAUDE_PROJECT_DIR)
- * and never inherit engine secrets; user-defined variables must ride `settings.env` — nothing for the
- * shell to scrub here (commands are the user's own text).
- */
 import { engineCapNestedTrue } from './engineCapsCache.js';
 import { collapseLabel } from './fleetTaskDesc.js';
 import { hostLog, hostSettings } from './host.js';
 import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
-// REF-CC-156(split):`/goal` 版本判档 + prompt 组装 + 模块状态搬到 goalStopHook.ts。
-// `goalStopHookMatcher`/`__resetGoalStopHookForTests` 是两文件间的私有接口(不 re-export);
-// 其余七个名字原样 re-export,外部 import 路径(index 的 `export *`)零改动。
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 const EDITABLE_HOOK_SOURCES = ['userSettings', 'projectSettings', 'localSettings'];
-/**
- * managed `strictPluginOnlyCustomization` 对 **hooks 面**的锁判定(L-67④,0.52.0)。
- *
- * 🔴 病(修前):`hooksForWire()` 过了 `disableAllHooks` / `allowManagedHooksOnly` 两道 managed 治理门,
- *    **没过**这一道 —— 而本文件头注自己写着「the wire must honor the SAME gates the local executor
- *    honors, or a fleet-managed policy is silently bypassed by the engine leg」。后果:管理侧把 hooks
- *    面锁成 plugin-only 之后,壳的**本地执行器**不再跑 user/project/local 的 hooks,而**引擎腿**照投
- *    照跑 —— 禁令只在一半的执行面上成立,而这一半恰好是工具真正执行的那一半。
- *
- * 🔴 与 cli 本地执行器 `src/utils/settings/pluginOnlyPolicy.ts:isRestrictedToPluginOnly('hooks')`
- *    **逐条对照,差异为零**:
- *      · `=== true`(布尔真)⇒ 锁(cli 原文 `if (policy === true) return true`:`true` 锁**全部四个面**,
- *        hooks 在内)。⚠️ 本条是必须实现的一形 —— 只认数组形会把「一个字就锁全部」的管理写法整个放过,
- *        而那正是本件要堵的洞;
- *      · 数组且含 `'hooks'` ⇒ 锁;数组不含 ⇒ **不锁**(锁的是别的面:skills/agents/mcp,与 hooks 无关);
- *      · 其余一切值形(缺席 / `false` / 串 / 对象 / 数字)⇒ **不锁**(当未设),**不** fail-closed 整条腿。
- *
- * 🔴 「非数组非 true ⇒ 当未设」为什么与 cli 差异为零(而不是本包自己另立一条宽口):cli 侧读到这个字段
- *    之前先过 `SettingsSchema`,该字段的 `.preprocess(...).catch(undefined)`(cli `settings/types.ts`
- *    逐字注释:「Non-array invalid values ("skills" string, {object}) … .catch drops the field to
- *    undefined instead. Degrades to unlocked-for-this-field, never to everything-broken.」)已经把脏值形
- *    丢成 `undefined` ⇒ 到达 `isRestrictedToPluginOnly` 的值形只有 boolean / 字符串数组两种,本函数对这
- *    两种与 cli **逐条同判**;而对**没过 schema** 的脏值形(别的宿主可能把盘上原文直接交上来),本函数
- *    的处置方向与 cli 那条 schema 腿**同向**(degrade to unlocked-for-this-field)。
- * 🔴 与相邻两道门的 fail-closed 纪律**不矛盾**:那两条 fail-closed 守的是「读取**抛出**」(治理策略
- *    读不出来 = 当作有限制);本条守的是「读到了、但值是个坏形」—— 值在手里,方向由字段属主(schema)
- *    定,不是未知态。两件事别混。
- */
 function hooksLockedToPluginOnly(policyValue) {
     if (policyValue === true)
         return true;
@@ -124,13 +12,6 @@ function hooksLockedToPluginOnly(policyValue) {
         return policyValue.includes('hooks');
     return false;
 }
-/**
- * REF-CC-155(midband-03,fix-outright):此前这里是静默 `catch { return null }` —— 零 hostLog、零
- * 注释说明「为什么这次失败可以死」。settings 读取失败(格式损坏 / 端内部错误)会被悄悄当成
- * 「该来源没配 hooks」处理,与真实的「没配」在结果上不可分辨,排查只能靠猜。补一行 debug 记录被吞的
- * 异常(与本文件其余分支的记账习惯一致);这一处仍按「无 hooks」降级 —— 单来源读失败不是安全门
- * (信任门/policy 门另有专门处置,见 hooksForWire),不必 fail-closed 整条腿。
- */
 function hooksOfSource(source) {
     try {
         const s = hostSettings()?.getSettingsForSource(source);
@@ -141,25 +22,10 @@ function hooksOfSource(source) {
         return null;
     }
 }
-/**
- * The merged, GOVERNANCE-GATED settings-file hooks for the wire, or undefined when none apply.
- * Per-event arrays concatenate across sources (policy → user → project → local).
- */
 export function hooksForWire() {
-    // 🔴 port 缺席 = **整条腿 fail-closed**(见文件头第三段):端没装 SettingsPort 就没有信任门,
-    //    而信任门是安全门。`hostSettings()` 自己会计 miss 并喊一次,宿主自检读得到。
     const settings = hostSettings();
     if (settings === undefined)
         return undefined;
-    // trust gate first (cheapest + broadest): untrusted interactive workspace ⇒ no hooks anywhere,
-    // the engine leg included — same invariant the local executor enforces per-fire.
-    // [2393] F-2(fix-outright):此前这条 catch 是 **fail-OPEN**(fall through),理由句写「端侧本地
-    // 执行器仍 per-fire 把门」—— 那句在本包语境下是**假话**,本文件头第三段自己写明:壳里那条
-    // catch 的前提是单进程本地执行器,**库里没有那个兜底**。后果是「未受信工作区的 hooks 绝不上
-    // wire」这条被文件头称作安全门的不变量,在 SettingsPort 抛错时整个失效(用户/项目 settings 里的
-    // `command` 型 hook 照投给引擎真执行)。而同一函数下方对**同类失败**(port 抛)的 policy 读已选
-    // fail-closed 并写明「治理策略读不出来时更安全的默认应是当作有限制」—— 两道门相邻、同类输入,
-    // 结论必须一致,更敏感的那道不许留在宽的一侧。改成 fail-closed:信任查不出来 = 当作未受信。
     try {
         if (settings.shouldSkipHookDueToTrust()) {
             hostLog('debug', 'hooksWireCaps: workspace not trusted — no hooks projected to the engine');
@@ -171,12 +37,6 @@ export function hooksForWire() {
         return undefined;
     }
     let policy = null;
-    // REF-CC-155(midband-03,fix-outright,行为面已裁 GO — 安全敏感面 [2374] 背书):policy 是
-    // `disableAllHooks`/`allowManagedHooksOnly` 两道治理门的唯一读口。此前读取失败(格式损坏 / 端内部
-    // 错误)与「本来就没配 policy」在这里被静默折成同一个 `policy = null` ⇒ 等价于「无限制」——而这条
-    // 恰恰是安全敏感面:治理策略读不出来时,更安全的默认应是「当作有限制」而不是「当作无限制」。改成
-    // fail-closed:读取真的**抛出**(不是「值合法地缺席」)⇒ 整条腿按 disableAllHooks 同款处置,不再
-    // 往下算 managedOnly / 拼装钩子。
     try {
         policy = settings.getSettingsForSource('policySettings');
     }
@@ -188,18 +48,10 @@ export function hooksForWire() {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (managed) — no hooks projected to the engine');
         return undefined;
     }
-    // L-67④(0.52.0):第三道 managed 治理门 —— `strictPluginOnlyCustomization` 含 hooks 面。
-    // 🔴 **顺序与 `allowManagedHooksOnly` 无关**(两者同时在场时无论谁先判,结论都是同一个
-    //    `['policySettings']`,处置逐字相同 —— 它们是**同一个动作**的两个理由,不是两级策略);
-    //    真正有顺序的只有 `disableAllHooks`:它在上面**先**判且**恒赢**(连 policy 自己的都不投),
-    //    本门只在它没命中时才有机会求值。
     const pluginOnlyHooks = hooksLockedToPluginOnly(policy?.strictPluginOnlyCustomization);
     if (pluginOnlyHooks) {
         hostLog('debug', 'hooksWireCaps: strictPluginOnlyCustomization locks the hooks surface (managed) — only policySettings hooks projected to the engine');
     }
-    // 🔴 `managedOnly` 这个名字下面还被 `/goal` overlay 的分道复用(用户态 goal 钩子必须与
-    //    EDITABLE_HOOK_SOURCES 同进退)——所以本门**合流进同一个量**,而不是只改 `sources`:
-    //    只改 sources 会让 plugin-only 锁下 user 态的 goal 钩子照投,那是同一个洞换了个入口。
     const managedOnly = policy?.allowManagedHooksOnly === true || pluginOnlyHooks;
     const sources = managedOnly
         ? ['policySettings']
@@ -212,68 +64,26 @@ export function hooksForWire() {
         for (const [event, groups] of Object.entries(hooks)) {
             if (!Array.isArray(groups) || groups.length === 0)
                 continue;
-            // Verbatim passthrough INCLUDING malformed entries — the service is the single validator
-            // (400 fail-loud with a field path); a client-side drop would be a silent fallback.
             merged[event] = [...(merged[event] ?? []), ...groups];
         }
     }
-    // `/goal` 的会话级 Stop×prompt 钩子(CC 220 Xdr)——在治理门之后合并,所以 trust /
-    // disableAllHooks / allowManagedHooksOnly 任一命中时它同样不投影(managedOnly 下用户态的
-    // goal 钩子也一并禁掉,与 EDITABLE_HOOK_SOURCES 被排除同理)。默认开,见上方 overlay 注释。
-    // REF-CC-156(split):判档/锁存态/包装全归 goalStopHook.ts,本文件只调尾部合流点。
     const goalMatcher = goalStopHookMatcher(managedOnly);
     if (goalMatcher !== null) {
         merged['Stop'] = [...(merged['Stop'] ?? []), goalMatcher];
     }
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
-/** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
 export function __resetHooksWireCapsForTests() {
     __resetGoalStopHookForTests();
 }
-// ── hook 观测面的能力位(#281 / server ≥7.48.0)──────────────────────────────────────────────
-/**
- * 这台引擎会不会发 `hook_non_blocking_failure` 观测帧(hook 自己坏了的那一族)。
- *
- * 🔴 **能力位嵌在 `fleet` 对象里**,不是顶层键 —— server `dist/http/routes/capabilities.js:52`:
- * `fleet: { stream, sessionScope, observe, resume, bgNotifyFailClosed, steerPriority,
- *  hookFailureNotice: true }`。拿平铺口 `engineCapTrue(base,'hookFailureNotice')` 去读**恒 false**
- * (白读),而白读的后果不是报错、是安静地把新车道判成没有。
- * 🔴 未判/父键缺席/父键为 `false`(整族不供)/子键缺席 ⇒ **false** = fail-closed。
- *
- * 🔴 **它是 affordance 判据,不是上屏闸**:一帧真到货的故障通知**不该**被本位闸掉 —— 帧在手里
- * 就是最强证据,而能力位在探测落地前恒 false,拿它闸会把早到的真实故障静默掉(方向与 #281 相反)。
- * 本位的正当用途 = 「要不要在设置/状态面声称有这项监测」。判定口见 `notifications.ts`
- * 的 `classifyHookFailureFrame`(那里刻意不读本位)。
- */
 export function fleetHookFailureNoticeCapable(baseUrl) {
     return engineCapNestedTrue(baseUrl, 'fleet', 'hookFailureNotice');
 }
-/** footer 横幅文案前缀(测试锁字面;与 `HOOK_NOTICE_WARN_PREFIX` 同族风格)。 */
 export const HOOK_FAILURE_WARN_PREFIX = 'Hook error';
-/**
- * 「这个 hook 自己坏了」的**单行**横幅文案(hook 名 + 故障形/退出码 + stderr 摘要)。
- *
- * 🔴 **为什么在本文件而不是 `notifications.ts`**:文案口要过展示消毒单源 `collapseLabel`
- * (在 `fleetTaskDesc.ts`),而 `notifications.ts` 在 **A 层闭包**内(portability 门只降棘轮)——
- * 从那里 import 会让闭包涨一格,手抄第二份字符集又是 `fleetTaskDesc` 顶注点名禁止的形。
- * ⇒ 判定留 `notifications.ts`(它只交出**原文**),展示归本层。
- *
- * 🔴 **绝不编造退出码**:`timeout` / `spawn_failed` 上没有 `exitCode`,那两形只报故障词
- * (写 `exit 0` 会让人去查一个根本不存在的退出码)。
- * 🔴 **两位都是 UNTRUSTED-for-display**(异源对抗复审二轮 [medium] 采纳):`hookName` 的一手源是
- * **用户 settings 里自己写的** `statusMessage` / command / url / prompt;`stderr` 是**坏 hook 自己吐的
- * 流**。server 只做脱敏 + 截断、**不做控制符消毒**(与 `workerBadge.name` / fleet 行标签同一条分工)。
- * 不消毒的后果不是难看:一个带 `\n` / ESC / RLO 的 hook 名能把「**哪个**安全 hook 失效了」这条
- * **唯一**告警重排、截断或整段藏掉,而这条横幅存在的全部理由就是让那件事看得见。
- * 🔴 **单行**:渲染面是 `wrap="truncate"` 的一行;`collapseLabel` 同时做 `\s+` 折平与控制符/双向符/
- * 孤代理项可见化转义,两件事一把做完(不在这里手抄第二份字符集)。
- */
 export function hookFailureNoticeText(n) {
     const code = n.exitCode !== undefined ? `exit ${n.exitCode}` : n.reason;
     const name = collapseLabel(n.hookName);
     const tail = n.stderr !== undefined ? `: ${collapseLabel(n.stderr)}` : '';
     const line = `${HOOK_FAILURE_WARN_PREFIX}: ${name} (${code})${tail}`;
-    // 有界兜底(与铸点同上限;消毒在前、截断在后 —— 反过来会把一个转义序列切成半截)。
     return line.length <= MAX_HOOK_NOTICE_TEXT_CHARS ? line : line.slice(0, MAX_HOOK_NOTICE_TEXT_CHARS);
 }

package/dist/host.d.ts

@@ -1,149 +1,44 @@
-/**
- * host.ts — **包级宿主装配**(B4;B3 交接报告的建议件 + 设计稿 §5.4 「web 宿主的最小接入面」)。
- *
- * ## 两种口,别混
- *
- * · `AdapterContext`(seam.ts)= **per-turn 切片** —— 时钟、铸号、signal、定时器、攒批节拍。
- *   它随每个 `adapt()` 调用传进来,因为这些东西**每个 turn 可以不一样**(比如这一 turn 可中断)。
- * · `installHost()`(本文件)= **进程/端级装配** —— settings 读取、fs、通知队列。
- *   它们在会话开始之前就该在位,而且被**请求构造期**的代码调用(`hooksForWire()` /
- *   `scratchpadDirField()`),那时候根本没有 `ctx` 可传。
- *
- * ⇒ 判据:**这个能力是不是每 turn 会变?** 会 ⇒ ctx;不会 ⇒ installHost。
- *
- * ## 缺席语义(与 AdapterContext 同一条纪律)
- *
- * 🔴 缺席 = **该能力不启用**,不是报错、更不是「换个方式偷偷做」。库绝不 `require('fs')`、
- * 绝不 `console.log`、绝不读 `process.env` 兜底 —— 那正是搬迁要切掉的东西。
- * 但「静默不启用」有个已知的失败形:**宿主漏装了,而症状是某个面悄悄空掉**。所以每个口都带
- * miss 计数(`hostPortMisses()`),宿主自检断言它恒为 0 —— 与 `notificationQueuePortMisses()`
- * 同一套姿势([probe-must-prove-it-speaks]:不能让「什么都没有」看起来像「一切正常」)。
- */
 import type { AdapterLogLevel, TimerHandle } from './seam.js';
 import { type NotificationQueuePort } from './notifications.js';
-/**
- * settings 文件的顶层文档形状(TYPESHAPE-11)。开集是**有理由的**:settings 文件本身是用户
- * 自由格式(壳三层合并后的 JSON、web center 下发、桌面主进程各自的形状都不同),库不认识
- * 具体键——窄化点在各消费者(如 hooksWireCaps)按各自需要的子形状 cast。缺席该来源的
- * settings ⇒ `null`(与本包既有 mock/消费点已经在用的口径一致,不是新增语义)。
- */
 export type SettingsDocument = Record<string, unknown>;
-/**
- * settings 口 —— 用户 settings 文件的读取面(壳=三层合并后的文件读;web=center 下发;桌面=主进程)。
- *
- * 🔴 `shouldSkipHookDueToTrust` 是**安全门**不是取值:未受信目录的 hook 绝不上 wire。
- * 端必须真实现它;不实现(端返回恒 false)= 把信任门拆了。所以它在 required 清单里。
- */
 export interface SettingsPort {
-    /** 按来源取 settings(cli `utils/settings/settings.ts` 的 `getSettingsForSource`)。 */
     getSettingsForSource(source: string): SettingsDocument | null;
-    /**
-     * 信任门:hook 是否因工作区未受信而跳过。**返回 true = 跳过**。
-     * 🔴 B6 更正:壳侧真身 `utils/hooks.shouldSkipHookDueToTrust()` 是**零参**的(门是工作区级、
-     * 不是逐条 hook 级)。B4 定口时按「逐条判」写了一个必填参,与真身不符 —— 改成可选参:
-     * 既容得下零参真身,也不妨碍将来某个端要做逐条判。库内唯一调用点(hooksWireCaps)不传参。
-     */
     shouldSkipHookDueToTrust(hook?: unknown): boolean;
 }
-/**
- * fs 口 —— scratchpad 目录族(cli `utils/permissions/filesystem.ts`)。
- * `ensureScratchpadDir` 是**真 IO**(mkdir);浏览器宿主整个口省略即可(⇒ 不 stamp scratchpadDir,
- * additive 字段缺席对引擎无害)。
- */
 export interface FsPort {
     getScratchpadDir(): string | undefined;
     isScratchpadEnabled(): boolean;
-    /** 🔴 壳侧真身是 **async**(mkdir 0o700);端可返 void 或 Promise,库两种都吞(fire-and-forget)。 */
     ensureScratchpadDir(): void | Promise<void>;
 }
-/**
- * 定时器口(进程级默认;`ctx.setTimer` 仍可按 turn 覆盖)。
- * 🔴 TYPESHAPE-10:句柄用 seam.ts 已有的命名不透明别名 `TimerHandle`(不透明本身不变 —— Node 是
- * Timeout 对象、浏览器是 number,库侧只负责回传;只是把裸 `unknown` 收进一个有名字的口)。
- */
 export interface TimersPort {
     setTimer(ms: number, fn: () => void): TimerHandle;
     clearTimer(handle: TimerHandle): void;
 }
-/**
- * session 口(**B6 引入**)—— 「现在是哪个会话 / 哪个 run 在飞」。
- *
- * 为什么必须是端给:这两个量在壳里分别住在 `liveSessionStore`(引擎首轮 done 回填的权威值)+
- * `bootstrap/state`(壳 boot 时生成的 uuidv7)与 `engineToolDetach`(pty 绑定的活跃 run),
- * **三个都是宿主生命周期资产**;web 宿主是路由参数 + BFF 会话,桌面是主进程 session-host。
- *
- * 🔴 缺席后果**不是**「少个装饰」:`engineSessionParam()` 恒 undefined ⇒ durable 面
- * (taskOutput/taskStop/subagentOutput)对 session-bound run 一律 **404 fail-closed**
- * ([1501]§三 / [1498]③),整条子代读面静默哑掉。所以本口**计 miss**。
- *
- * 🔴 `currentSessionId()` 绝不返回空串 —— `?session=`(空值)按「带了且不匹配」判 404
- * ([1501] 空串陷阱);端返空串时库当缺席处理(下面 `engineSessionParam` 有归一)。
- */
 export interface SessionPort {
-    /** 当前会话 id(壳:引擎捕获值优先、退 boot-time id);两源都缺 ⇒ undefined。 */
     currentSessionId(): string | undefined;
-    /**
-     * 当前**活跃引擎 run** 的 id(壳 = `engineToolDetach.getActiveEngineTaskId()`,由
-     * X-Task-Id 响应头早捕获)。没有在飞的 turn ⇒ undefined/null 都收。
-     */
     activeRunId(): string | undefined | null;
 }
-/** `installHost` 的入参 —— 全部可选,缺席即该能力不启用。 */
 export interface HostPorts {
     log?(level: AdapterLogLevel, msg: string, data?: unknown): void;
     probe?(channel: string, line: string): void;
-    /** 通知队列(B2 引入)。经本口装 == 直接调 `installNotificationQueuePort`,单一真源不分裂。 */
     queue?: NotificationQueuePort | null;
     timers?: TimersPort;
     settings?: SettingsPort;
     fs?: FsPort;
-    /** B6:会话/活跃 run 口(缺席 ⇒ durable 子代面对 session-bound run 恒 404,见 SessionPort)。 */
     session?: SessionPort;
 }
-/**
- * 装配宿主口。**可多次调用做增量装配**(只覆盖本次给出的键),便于分模块装。
- * 传 `queue` 会直通 `installNotificationQueuePort` —— 队列的真源仍在 notifications.ts,
- * 本文件不另存一份([paired-mechanisms-must-share-premise]:两处各存一份 = 装了 A 读了 B)。
- * 返回一个还原函数(测试/热重载用)。
- */
 export declare function installHost(ports: HostPorts): () => void;
-/**
- * W1 带 key 变体:装配某会话的宿主口(多会话宿主每会话一键,互不顶盖;合并语义与零参同)。
- * ⚠️ 入参不含 `queue` —— 通知队列在 W1 仍是包级单例(notifications.ts 不在五槽位切口内),
- * per-session 队列归后续工单;要装队列走零参 `installHost({ queue })`。
- */
 export declare function installHostFor(sessionKey: string, ports: Omit<HostPorts, 'queue'>): () => void;
-/** 日志(缺席 = 静默,**不计 miss**:诊断面本就是可选的)。 */
 export declare function hostLog(level: AdapterLogLevel, msg: string, data?: unknown): void;
-/** 行式探针(缺席 = 静默,不计 miss:同上)。 */
 export declare function hostProbe(channel: string, line: string): void;
-/** settings 口(缺席 = undefined + 计 miss:漏装会让 hooks 整条 wire 静默空掉)。 */
 export declare function hostSettings(): SettingsPort | undefined;
-/** W1 带 key 变体(缺席语义与零参同:undefined + 计该键 miss)。 */
 export declare function hostSettingsFor(sessionKey: string): SettingsPort | undefined;
-/** fs 口(缺席 = undefined + 计 miss)。 */
 export declare function hostFs(): FsPort | undefined;
-/** W1 带 key 变体。 */
 export declare function hostFsFor(sessionKey: string): FsPort | undefined;
-/** 定时器口(缺席 = undefined,不计 miss:T40 竞速本就允许不启用)。 */
 export declare function hostTimers(): TimersPort | undefined;
-/** W1 带 key 变体(同零参:不计 miss)。 */
 export declare function hostTimersFor(sessionKey: string): TimersPort | undefined;
-/** session 口(缺席 = undefined + 计 miss:漏装会让整条 durable 子代读面 404 静默哑掉)。 */
 export declare function hostSession(): SessionPort | undefined;
-/** W1 带 key 变体。 */
 export declare function hostSessionFor(sessionKey: string): SessionPort | undefined;
-/**
- * 🔴 宿主自检出口 —— 恒应为空对象。非空 = 有口漏装,**对应的面已经在静默失效**。
- * 含通知队列的 miss(从 notifications.ts 汇过来,宿主只需看这一个数)。
- */
 export declare function hostPortMisses(): Record<string, number>;
-/** W1 带 key 变体。⚠️ 通知队列是包级单例,其 miss 只折进 DEFAULT_SESSION_KEY 键的视图。 */
 export declare function hostPortMissesFor(sessionKey: string): Record<string, number>;
-/**
- * 测试钩:清空装配与计数。
- * 🔴 队列那一路必须走 `_resetNotificationQueuePortForTest()` 而不是 `installNotificationQueuePort(null)`
- * —— 后者只卸口、**不清 miss 计数**,于是 `hostPortMisses()` 会带着上一段测试的历史 miss,
- * 让「未装配时 misses 为空」这类断言恒假(B4 首写时就撞上了)。
- */
 export declare function _resetHostForTest(): void;

package/dist/host.js

@@ -14,7 +14,6 @@ function miss(sessionKey, name) {
     slot.misses[name] = (slot.misses[name] ?? 0) + 1;
     if (!slot.warned.has(name)) {
         slot.warned.add(name);
-        // eslint-disable-next-line no-console
         console.error(`[client-core] host port "${name}" NOT installed — the surface it drives is silently inert. ` +
             'Host must call installHost({ ' +
             name +
@@ -22,23 +21,12 @@ function miss(sessionKey, name) {
     }
     return undefined;
 }
-/**
- * 装配宿主口。**可多次调用做增量装配**(只覆盖本次给出的键),便于分模块装。
- * 传 `queue` 会直通 `installNotificationQueuePort` —— 队列的真源仍在 notifications.ts,
- * 本文件不另存一份([paired-mechanisms-must-share-premise]:两处各存一份 = 装了 A 读了 B)。
- * 返回一个还原函数(测试/热重载用)。
- */
 export function installHost(ports) {
     const restore = installHostFor(DEFAULT_SESSION_KEY, ports);
     if ('queue' in ports)
         installNotificationQueuePort(ports.queue ?? null);
     return restore;
 }
-/**
- * W1 带 key 变体:装配某会话的宿主口(多会话宿主每会话一键,互不顶盖;合并语义与零参同)。
- * ⚠️ 入参不含 `queue` —— 通知队列在 W1 仍是包级单例(notifications.ts 不在五槽位切口内),
- * per-session 队列归后续工单;要装队列走零参 `installHost({ queue })`。
- */
 export function installHostFor(sessionKey, ports) {
     const slot = hostSlot(sessionKey);
     const prev = { ...slot.state };
@@ -58,54 +46,39 @@ export function installHostFor(sessionKey, ports) {
         slot.state = prev;
     };
 }
-/** 日志(缺席 = 静默,**不计 miss**:诊断面本就是可选的)。 */
 export function hostLog(level, msg, data) {
     hostSlot(DEFAULT_SESSION_KEY).state.log?.(level, msg, data);
 }
-/** 行式探针(缺席 = 静默,不计 miss:同上)。 */
 export function hostProbe(channel, line) {
     hostSlot(DEFAULT_SESSION_KEY).state.probe?.(channel, line);
 }
-/** settings 口(缺席 = undefined + 计 miss:漏装会让 hooks 整条 wire 静默空掉)。 */
 export function hostSettings() {
     return hostSettingsFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体(缺席语义与零参同:undefined + 计该键 miss)。 */
 export function hostSettingsFor(sessionKey) {
     return hostSlot(sessionKey).state.settings ?? miss(sessionKey, 'settings');
 }
-/** fs 口(缺席 = undefined + 计 miss)。 */
 export function hostFs() {
     return hostFsFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体。 */
 export function hostFsFor(sessionKey) {
     return hostSlot(sessionKey).state.fs ?? miss(sessionKey, 'fs');
 }
-/** 定时器口(缺席 = undefined,不计 miss:T40 竞速本就允许不启用)。 */
 export function hostTimers() {
     return hostTimersFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体(同零参:不计 miss)。 */
 export function hostTimersFor(sessionKey) {
     return hostSlot(sessionKey).state.timers;
 }
-/** session 口(缺席 = undefined + 计 miss:漏装会让整条 durable 子代读面 404 静默哑掉)。 */
 export function hostSession() {
     return hostSessionFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体。 */
 export function hostSessionFor(sessionKey) {
     return hostSlot(sessionKey).state.session ?? miss(sessionKey, 'session');
 }
-/**
- * 🔴 宿主自检出口 —— 恒应为空对象。非空 = 有口漏装,**对应的面已经在静默失效**。
- * 含通知队列的 miss(从 notifications.ts 汇过来,宿主只需看这一个数)。
- */
 export function hostPortMisses() {
     return hostPortMissesFor(DEFAULT_SESSION_KEY);
 }
-/** W1 带 key 变体。⚠️ 通知队列是包级单例,其 miss 只折进 DEFAULT_SESSION_KEY 键的视图。 */
 export function hostPortMissesFor(sessionKey) {
     const out = { ...hostSlot(sessionKey).misses };
     if (sessionKey === DEFAULT_SESSION_KEY) {
@@ -115,12 +88,6 @@ export function hostPortMissesFor(sessionKey) {
     }
     return out;
 }
-/**
- * 测试钩:清空装配与计数。
- * 🔴 队列那一路必须走 `_resetNotificationQueuePortForTest()` 而不是 `installNotificationQueuePort(null)`
- * —— 后者只卸口、**不清 miss 计数**,于是 `hostPortMisses()` 会带着上一段测试的历史 miss,
- * 让「未装配时 misses 为空」这类断言恒假(B4 首写时就撞上了)。
- */
 export function _resetHostForTest() {
     hostByKey.clear();
     _resetNotificationQueuePortForTest();

package/dist/hostEnv.d.ts

@@ -1,16 +1,2 @@
-/**
- * hostEnv.ts — B2 批引入的**唯一**宿主环境读口(多端改造设计稿 §5.2 浏览器可移植性)。
- *
- * 为什么需要:搬入的 `*WireCaps` 族有 11 个函数签名是 `(env: NodeJS.ProcessEnv = process.env)`
- * —— 两个问题:① `NodeJS` 命名空间在本包(tsconfig `types: []`、无 @types/node)不存在;
- * ② 浏览器里 `process` 未定义,**不传参调用会 ReferenceError**(不是类型问题,是运行时崩)。
- *
- * 🔴 等价性记账(逐字):Node 下 `hostEnv()` 返回的就是 `process.env` 那个**同一对象**
- * (`globalThis.process === process`),所以壳侧既有「不传 env 参数」的调用点行为一字节不变;
- * 浏览器/worker 下返回 `{}` —— 相当于「所有 env 旋钮未设置」,即各函数自己的缺省档。
- * `EnvLike` 与 `NodeJS.ProcessEnv`(= `Dict<string>`)结构等价,壳侧传 `process.env` 照样过型。
- */
-/** `process.env` 的结构等价形(`NodeJS.ProcessEnv` 的包内替身)。 */
 export type EnvLike = Record<string, string | undefined>;
-/** 宿主 env(Node = 真 `process.env` 同一对象;无 process 的宿主 = 空表)。 */
 export declare function hostEnv(): EnvLike;

package/dist/hostEnv.js

@@ -1,16 +1,3 @@
-/**
- * hostEnv.ts — B2 批引入的**唯一**宿主环境读口(多端改造设计稿 §5.2 浏览器可移植性)。
- *
- * 为什么需要:搬入的 `*WireCaps` 族有 11 个函数签名是 `(env: NodeJS.ProcessEnv = process.env)`
- * —— 两个问题:① `NodeJS` 命名空间在本包(tsconfig `types: []`、无 @types/node)不存在;
- * ② 浏览器里 `process` 未定义,**不传参调用会 ReferenceError**(不是类型问题,是运行时崩)。
- *
- * 🔴 等价性记账(逐字):Node 下 `hostEnv()` 返回的就是 `process.env` 那个**同一对象**
- * (`globalThis.process === process`),所以壳侧既有「不传 env 参数」的调用点行为一字节不变;
- * 浏览器/worker 下返回 `{}` —— 相当于「所有 env 旋钮未设置」,即各函数自己的缺省档。
- * `EnvLike` 与 `NodeJS.ProcessEnv`(= `Dict<string>`)结构等价,壳侧传 `process.env` 照样过型。
- */
-/** 宿主 env(Node = 真 `process.env` 同一对象;无 process 的宿主 = 空表)。 */
 export function hostEnv() {
     const p = globalThis.process;
     return p?.env ?? {};

package/dist/imagesWireCaps.d.ts

@@ -1,28 +1,7 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/imagesWireCaps.ts 逐字搬入(零依赖)。
- */
-/**
- * src/sema/imagesWireCaps.ts — PURE projection of a CC user message's IMAGE content blocks → engine ImageInput[]
- * (CC paste-image / drag-image parity). seamQuery imports it.
- *
- * The signature "壳渲染后端空" hole: REPL.tsx:3444 builds Anthropic image blocks
- *   { type:'image', source:{ type:'base64', media_type, data } }  (or { type:'url', url })
- * into the user message's `content` block array, but seamQuery.objectiveFromMessage kept ONLY `type==='text'`
- * blocks — so pasted images RENDERED but never reached the live engine. core/service already consume
- * `body.images` (main.ts:1296 → core `TaskSpec.images?: ImageInput[]`, types.ts:416 + brain toUserBlocks); this
- * is purely the missing shell-side projection. config-class (model-content the caller chose for their OWN turn).
- *
- * core ImageInput = `{ data: base64, mimeType } | { url }`. We map the Anthropic base64 source
- * (`source.media_type`/`source.data`) → `{ data, mimeType }`, and a url source → `{ url }`.
- */
 export type ImageInput = {
     data: string;
     mimeType: string;
 } | {
     url: string;
 };
-/**
- * Extract the IMAGE blocks of a CC user message → ImageInput[]. Reads `message.content` (string | block[]) the
- * same way objectiveFromMessage reads its text; a bare-string content has no images ⇒ []. Malformed blocks drop.
- */
 export declare function imagesFromMessage(msg: unknown): ImageInput[];