@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/subagent/engineSubagentResume.js

@@ -6,29 +6,10 @@ import { engineWireTargetFor } from '../engineWireTarget.js';
 import { activeEngineRunId, engineSessionParamFor } from '../engineSessionParam.js';
 import { DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { getBgParentRunOwner, parentToolCallIdOf, } from '../subagentContentStore.js';
-/** 能力位键(server `routes/capabilities.ts` 的 `subagentResume`;SDK `Capabilities.subagentResume`)。 */
 export const SUBAGENT_RESUME_CAP = 'subagentResume';
-/**
- * 复活口在不在。未判/缺键 = false = 详情面不渲「继续」腿。
- *
- * 🔴 design/285 批 3(D7b):`baseUrl` 缺席时的派生从零参 `engineWireTarget()`(写死默认槽)换成
- *    `engineWireTargetFor(sessionKey)`。**本腿没有行上下文**(它答的是「这台引擎有没有这个口」,
- *    不是「这一行该打到哪」)⇒ 槽键只能由调用方给,缺省 `DEFAULT_SESSION_KEY` = 与 0.44.0 逐字同。
- *    显式 `baseUrl` 恒赢(既有注入缝不动;空串仍原样保留 —— `??` 只对 `undefined` 让位,与默认参形同)。
- */
 export function subagentResumeAvailable(baseUrl, sessionKey = DEFAULT_SESSION_KEY) {
     return engineCapTrue(baseUrl ?? engineWireTargetFor(sessionKey)?.baseUrl, SUBAGENT_RESUME_CAP);
 }
-/**
- * 「继续」腿的 resume 取址(1.0.74 终扫 P2-11)。
- *
- * 🔴 resume API 的 `target` 契约只认两种取址:委派工具调用的 **parentToolCallId**(一等精确取址,
- * 同型并发子代唯一能分开的键)与**子代显示名**(同名多员 ⇒ server 409 `steering.ambiguous_target`)。
- * 行 taskId 不是契约取址形 —— 传它只会得到一条不带替代路径的歧义/未知错。
- * alias 台账(`registerSubagentAlias`,task_progress 双携建;taskToParent 无删除无淘汰,子代 settle
- * 后仍可取)⇒ 精确取址优先;显示名仅回落(它可能是 'Task' 字面占位,同名多员的 409 由每格出路
- * 文案接);两支皆缺 ⇒ undefined,调用方按诚实缺席**不渲入口**。
- */
 export function resolveSubagentContinueTarget(rowId, displayName) {
     const precise = parentToolCallIdOf(rowId);
     if (precise !== undefined && precise !== '')
@@ -36,7 +17,6 @@ export function resolveSubagentContinueTarget(rowId, displayName) {
     const name = typeof displayName === 'string' ? displayName.trim() : '';
     return name !== '' ? name : undefined;
 }
-/** 留存失效族(三码同处置:留存曾经在、现在没了;文案一致,留痕分得开)。 */
 const RETENTION_LAPSED_CODES = new Set([
     'resume.evicted',
     'resume.cap',
@@ -50,22 +30,10 @@ function shapeOf(e) {
         message: typeof o.message === 'string' && o.message !== '' ? o.message : String(e),
     };
 }
-/**
- * resume 失败 → 处置分类。机器轴 = `errorCode`(开集);`status` 只用于**码缺席**时的两格粗分
- * (404 无存在性谕示 / 400 入参),绝不用数字去猜某个具体 409 成因(那些 409 只有 `errorCode`
- * 分得开,按数字分支等于把好几种处置压成一种)。
- */
 export function classifySubagentResumeFailure(e) {
     const { status, errorCode, message } = shapeOf(e);
-    // L-102(0.57.0):时间性拒绝二码 —— **先判具名闭集**(与 SDK `classifyApiError` 同序:具名码排在
-    // `resume.` 前缀兜底之前)。此前这两码双双落进末尾的开集兜底 `error`,于是 server 明明给了
-    // 「等多久」,到端只剩一句泛泛失败(与 #318 件④ 收 `row_recycling`/`row_gone` 那次同形)。
-    // 读口在 `wireErrorTriage`,不在这里就地重判:同一把窄读器还要服务不走本腿的宿主(decide/park
-    // 腿也吃这两码),两处各写一遍就是两个会各自漂的判官。
     const retryLater = resumeRetryLaterFromError(e);
     if (retryLater !== null) {
-        // 🔴 **按证据分两格,不按码分**:`waitable` 是读口那一位(全包单一判断点)——`terminal` 臂的
-        //    预检拒没有可等证据,归 `refused-preflight`(不可判),绝不渲成「稍后重试」。
         return {
             reason: retryLater.waitable ? 'retry-later' : 'refused-preflight',
             detail: message,
@@ -84,9 +52,6 @@ export function classifySubagentResumeFailure(e) {
         return { reason: 'not-resumable', detail: message };
     if (errorCode === 'steering.ambiguous_target')
         return { reason: 'ambiguous-target', detail: message };
-    // #318 件④([4743] SendMessage 复活语义)—— 复活裁决腿的两码。此前它们双双落进末尾的开集兜底
-    // `error`,于是 core 明明给了**两个不同的下一步**(等一会儿再发 / 重开一个新 agent),到客户端
-    // 只剩一句泛泛失败。判定归包、文案归端:这里只分格,不写出路文案。
     if (errorCode === 'resume.row_recycling')
         return { reason: 'row-contended', detail: message };
     if (errorCode === 'resume.row_gone')
@@ -99,77 +64,19 @@ export function classifySubagentResumeFailure(e) {
         return { reason: 'not-found', detail: message };
     return { reason: 'error', detail: message };
 }
-/**
- * 「这一行子代该打到哪条 run」——**纯函数,单点判据**(对抗复审 H1 的修 + 它的可证伪点)。
- *
- * 🔴 **按行取,不取「此刻在飞的那条」**:`activeEngineRunId()` 是 turn-scoped(壳 `seamQuery` 在
- *    turn 收尾 `setActiveEngineTaskId(null)`),而「继续」这个动作按定义只在子代**已 settle** 之后
- *    才出现 —— 那时它恒空;更坏的一支是另一条 turn 正飞时它有值但**是别的 run**,请求会打到不
- *    相干的 run 上(404,或叫醒那条 run 里的同名子代)。判据必须锚在决定量(这一行的宿主 run)
- *    上,不是锚在「有没有 run 在飞」这个前置条件上([anchor-on-the-deciding-quantity])。
- *
- * 三态:
- *   · 台账有这一行 ⇒ 用台账值(**哪怕此刻另有 run 在飞**);
- *   · 台账没有、且调用方**指名了某一行** ⇒ `undefined`(诚实不知道 ⇒ no-run 出路),绝不回落成在飞的那条;
- *   · 调用方**没指名行**(无行上下文的通用调用)⇒ 才回落到在飞的那条。
- *
- * @param activeRunId 注入缝(缺省 = `activeEngineRunId()`)—— 判据要能在没有 SessionPort 的纯层里验。
- */
 export function resolveOwnerRunId(childTaskId, activeRunId) {
     const owner = getBgParentRunOwner(childTaskId);
     if (owner !== undefined)
         return owner.runId;
     if (childTaskId !== undefined && childTaskId !== '')
         return undefined;
-    // 🔴 **惰性求值**(design/285 批 3,异源对抗复审 [medium] 采纳):此前 `activeRunId` 是**默认参**,
-    //    于是**每一次**调用都先读一遍**默认槽**的 `SessionPort` —— 哪怕台账里明明有这一行、第三态根本
-    //    走不到。批 3 之后 keyed 宿主是成文支持的路径,那次白读会给 keyed-only 宿主(默认槽本就没装)
-    //    刷 `hostPortMisses()`,而接入档要求宿主的自检**恒空**:一个恒响的假警报会把真漏装淹掉。
-    //    注入语义一字未变(传值即用;传 `undefined` 与不传都落到这条真读)。
     return activeRunId ?? activeEngineRunId();
 }
-/**
- * 「这一行子代属于哪个会话槽」—— design/285 批 3(D6+D7b)读侧的**一次读**。
- *
- * 五个读点(tail / output / taskHandle 两口 / delegatedPrompt)此前各自读一次台账,而 wire target
- * 一律走零参 `engineWireTarget()`(= 默认槽)。keyed 多会话宿主上那意味着「会话对了、打的服务器与
- * 凭证可能还是别人的」(D7b)。本函数把「取哪一行的记录 + 它属于哪个槽」收成一处;
- * `key` 缺席回落默认槽 ⇒ `engineWireTargetFor(DEFAULT_SESSION_KEY)` ≡ `engineWireTarget()`,
- * 单会话宿主逐字同。
- *
- * 🔴 **会话策略刻意留在各腿**(不在这里合并):steer/tail/output 是二态(行的会话优先,缺则退现势),
- *    resume 是三态(指名了行却没有会话 ⇒ 干脆不带,AT-MOST-ONCE 不许猜)。收成一份就必然要加一个
- *    「模式」参数,那等于把两条**有意不同**的口径伪装成同一个函数的两种配置。
- */
 export function resolveOwnerContext(childTaskId) {
     const record = getBgParentRunOwner(childTaskId);
     return { record, runId: record?.runId, key: record?.sessionKey ?? DEFAULT_SESSION_KEY };
 }
-/**
- * 产品 facade + 运行定位。**逐字复用 `steerEngineSubagent` 的三步**(engineWireTarget → 无则 no-wire;
- * 取运行 → 无则 no-run;makeEngineWireClient)—— 两条腿共用同一套装配,免得 steer 能到达而 resume
- * 到不了(或反过来),那种不对称在用户面上表现为「同一个 agent 有时能说话有时不能」。
- *
- * 🔴 `session` 的三态(#242 批 2 定口径,对抗复审 medium 收紧):
- *    · 台账有这一行**且**捕到了它的会话 ⇒ 用**行登记的**会话(resume 是 per-id 读面,配错的
- *      `{runId, session}` 组合在 session-bound run 上 fail-closed 404);
- *    · 台账**有这一行但没捕到会话**(fleet 行帧腿/通知腿今天不传 session)⇒ **不带 `?session=`**,
- *      🔴 **绝不拿「此刻的会话」去猜** —— resume 是有副作用的动作(AT-MOST-ONCE,叫醒 = 真跑一轮),
- *      猜错会话可能落到**另一个会话的同名子代**上,那是不可回收的伤害;不带参数的失败只是 server
- *      fail-closed 的干净 404,已有 `not-found` 出路文案接。与本模块「错值比缺席更坏」同一条口径。
- *    · 调用方**完全没指名行**(无行上下文的通用调用)⇒ 才退当前会话(既有口径不变)。
- *    ⚠️ 供给面欠账(**已由 design/285 批 2 补上**):fleet/通知两腿此前手里没有流会话;ingress 落地后
- *    它们按 `{runId, sessionId, sessionKey}` 三值原子写,第二态自然变成第一态,判据一字未改 ——
- *    这正是本注 0.30.x 时预告过的那一步。
- *
- * 🔴 design/285 批 3(D7b):wire target 从零参 `engineWireTarget()`(默认槽)换成
- *    `engineWireTargetFor(owner.sessionKey ?? DEFAULT_SESSION_KEY)`。会话对了而 baseUrl/token/
- *    principal 还是别人的,等于把 resume 这条 AT-MOST-ONCE 的动作发到另一台引擎上。
- *    第三态(没指名行)的现势会话回落**同样按 key**(`engineSessionParamFor(key)`)—— 没指名行时
- *    key 恒是默认槽,与 0.44.0 逐字同。
- */
 export function resolveSubagentResumeContext(childTaskId) {
-    // 记录先取(纯台账读):`key` 决定 wire target 取哪个槽,所以它必须排在 cfg 之前。
     const { record: owner, key } = resolveOwnerContext(childTaskId);
     const cfg = engineWireTargetFor(key);
     if (!cfg)
@@ -183,30 +90,17 @@ export function resolveSubagentResumeContext(childTaskId) {
         return { facade: null, runId: undefined, session: {} };
     const named = childTaskId !== undefined && childTaskId !== '';
     const sessionFromRow = owner?.sessionId;
-    // 第三态(没指名行)的现势会话回落**也按 key** —— 没指名行时 key 恒是默认槽,与 0.44.0 逐字同。
     const fallback = named ? undefined : engineSessionParamFor(key);
     const session = sessionFromRow !== undefined
         ? { session: sessionFromRow }
         : fallback !== undefined
-            ? { session: fallback } // 没指名行 ⇒ 退当前会话(既有第三态口径不变)
-            : {}; // 指名了行却没有它的会话 ⇒ 诚实缺席,绝不用当前会话冒充
-    // 取址三态的唯一判据(含「没指名行才回落在飞 run」那一态);刻意排在 wire 两道闸**之后**,
-    // 与 0.44.0 求值序逐字同 —— 无 wire 时一次 SessionPort 都不读。
+            ? { session: fallback }
+            : {};
     return { facade: client.runs, runId: resolveOwnerRunId(childTaskId), session };
 }
-/** UNTRUSTED 串的呈前消毒。 */
 function clean(v, max = 200) {
-    // eslint-disable-next-line no-control-regex
     return String(v ?? '').replace(/[\x00-\x1f\x7f]/g, '.').slice(0, max);
 }
-/**
- * 叫醒一个已 settle 的保留子代。
- *
- * @param target parentToolCallId 或 agentName(与 `steerEngineSubagent` 同一取址口径;
- *               同名多个活体 ⇒ server 409 `steering.ambiguous_target`)。
- * 🔴 AT-MOST-ONCE:server 明写不重试。本层因此**不重试任何一格** —— 「叫醒」是有副作用的动作,
- *   重投一次可能真的多跑一轮。
- */
 export async function resumeSettledSubagent(facade, runId, target, content, opts) {
     if (facade === null)
         return { ok: false, reason: 'no-wire', detail: 'no engine wire' };
@@ -231,27 +125,7 @@ export async function resumeSettledSubagent(facade, runId, target, content, opts
         return { ok: false, ...f };
     }
 }
-// ── caps × verb 组合告警([4000] Q5 裁定的另一半)────────────────────────────────────────────
-// Q5 裁定:`ClientSliceLike.wakeSubagent` 在 `CLIENT_VERBS` 表里**维持 `required:false`**
-// (fail-soft —— 不实现只是少一个入口,不丢已发生的行为);但「引擎这边留存在付费、客户端这边
-// 一个兑现口都没有」这个**组合**必须响亮说出来,否则它就是一笔谁也看不见的常驻成本。
-//
-// 🔴 键名订正(勘设计稿措辞):caps 上**没有** `retainSubagentSessions` 这个位 ——
-//    `retainSubagentSessions` 是**run 请求位**(`request/taskRequest.ts:118/320`,壳默认 true),
-//    引擎宣示兑现口的 caps 位是 **`subagentResume`**(SDK `Capabilities.subagentResume`,
-//    `types.d.ts:1879` 逐字「还需 run 侧 retainSubagentSessions」)。所以本告警的判据是
-//    **两半都在场**:caps 宣示 `subagentResume` ∧ 本端的 run 请求真在打 retain ⇒ 成本真在付。
 const warnedRetainWithoutWake = new Set();
-/**
- * 「引擎有复活口 + 本端在付留存成本 + 本端没有 wake 实现」⇒ 响亮一条(每 baseUrl 至多一次)。
- *
- * 返回 {@link RetainWithoutWakeVerdict}:`undefined` = 组合不成立(没这笔账);有记录 = 组合成立,
- * 其中 `emitted` 说明**本次**响没响。**返回值即判据** —— 只落日志的告警在测试里等于不存在,
- * 而只回一个字符串又分不出「本次响了」与「早响过了」(按返回值呈现的调用方会重复提示)。
- *
- * @param slice 本端的 `ClientSliceLike` 实现(或它的任意子集);`wakeSubagent` 不是函数即算未实现。
- * @param retainRequested 本端 run 请求里的 `retainSubagentSessions`(缺省 true = 包内 taskRequest 的缺省)。
- */
 export function auditRetainWithoutWake(input) {
     const baseUrl = input.baseUrl ?? engineWireTargetFor(input.sessionKey ?? DEFAULT_SESSION_KEY)?.baseUrl;
     if (!engineCapTrue(baseUrl, SUBAGENT_RESUME_CAP))
@@ -271,7 +145,6 @@ export function auditRetainWithoutWake(input) {
     hostLog('warn', message);
     return { message, emitted: true };
 }
-/** 测试钩:清 once 去重台账。 */
 export function __resetRetainWithoutWakeWarningForTests() {
     warnedRetainWithoutWake.clear();
 }

package/dist/subagent/engineSubagentSteer.d.ts

@@ -6,30 +6,4 @@ export type SubagentSteerOutcome = {
     reason: 'no-wire' | 'no-run' | 'not-running' | 'error';
     detail?: string;
 };
-/**
- * Steer a running engine subagent (target = its parentToolCallId, or agentName).
- *
- * 🔴 #280 件A(取址第四腿并入 [4000] Q3=B 口径):`childTaskId` 在场时**台账优先、缺席即诚实缺席**,
- * 与 tail / taskOutput·taskStop / subagentOutput 三腿同姿势,也与孪生的 resume 腿共用**同一个**
- * 取址判据(`resolveOwnerRunId`,不是第二份手抄)。此前本腿直取 `activeEngineRunId()` —— 正是
- * `engineSubagentResume` 头注点名的那处不对称(「同一个 agent 有时能说话有时不能」):
- *   · 进程级活跃 run 被并发 main/fork 流互相覆写、又在每个 query 的 finally 清空 ⇒ 后台子代在
- *     宿主 turn 收尾之后仍在跑时,这里恒空(no-run,消息发不出去);另一条 turn 正飞时它有值
- *     但**是别的 run**(打到不相干的 run 上 —— 错值比缺席更坏,与 Q3 同一条理由)。
- * 三态(`resolveOwnerRunId` 的单一判据):台账有这一行 ⇒ 用行值(哪怕此刻另有 run 在飞);
- * 指名了行而台账缺席 ⇒ `no-run` + `noteBgOwnerAbsence` 留痕(绝不回落在飞 run);
- * **没指名行**(既有两参调用)⇒ 才回落在飞 run —— 老调用方逐字零行为变化,本参数是 additive。
- *
- * 🔴 会话参数**二态**(对抗复审 medium 采纳:「取了台账的 run 却配现势 session」是确定性 404):
- *   · 行登记时**捕到了会话** ⇒ 用**行的会话**(与行的 runId 同源同拍,是唯一自洽的组合);
- *   · 行**没有**随行会话(`recordBgParentRun` 只写 run —— 今天 bg 行多数是这一格)⇒ 退**现势会话**。
- * 刻意**不**跟 resume 腿的「没捕到就干脆不带」:本腿与 tail/subagentOutput 同族,遵 [1498]③
- * 无条件带 session 的双版本兼容纪律;runId 既已由台账钉死,配错的 `{runId, session}` 组合在
- * session-bound run 上是 server 干净的 fail-closed 404(落既有 `not-running` 出路),**不会**把消息
- * 投到别的会话 —— 而「没捕到就不带」会让今天最常见的那一格整批 404。resume 那边更严是因为它是
- * AT-MOST-ONCE 的叫醒(真跑一轮,不可回收),两者的代价不对称。
- * 诚实边界:行无会话且端已切到别的会话时,对旧行 steer 会得到 `not-running`(而非静默投错人)。
- *
- * @param childTaskId 这一行子代的 taskId(fleet 行 id 尾段;端有行上下文时**应当**传)。
- */
 export declare function steerEngineSubagent(target: string, text: string, childTaskId?: string): Promise<SubagentSteerOutcome>;

package/dist/subagent/engineSubagentSteer.js

@@ -1,76 +1,17 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentSteer.ts` 整搬。
- *
- * 🔴 搬迁三处差分(端资产上移到 port,行为一字节不变):`wireConfig()`(六份手抄之一,而且
- *    **这一份的 token 读法与另外五份不同步** —— 收编前它是 `token: process.env.SEMA_LIVE_TOKEN`
- *    直挂而非 `...(cfg.token ? … )` spread,漂移已实际发生)→ `engineWireTarget()`;
- *    `getActiveEngineTaskId()` → `activeEngineRunId()`;`logForDebugging` → `hostLog`。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * engineSubagentSteer — C2 (service 1.89): direct steer to a RUNNING engine subagent.
- *
- * Wire: `POST /v1/runs/:runId/subagents/:target/steer` (SubagentSteerRegistry, three-legged onSubagentSpawn;
- * target = parentToolCallId or agentName — the client always has the parentToolCallId from the diverted C1
- * content events / progress binding). SDK 宪法迁移批:SDK 0.0.52 有 runs.steerSubagent verb(同 wire 同
- * encodeURIComponent 同 body {content}),raw fetch 退役 —— 改走 engineWireSdk 工厂 client;auth
- * (Bearer SEMA_LIVE_TOKEN)+ x-agent-principal(owner-gated route — must match the run's stamped
- * principal)姿势 = Transport buildHeaders,与原手抄同三头。
- *
- * Semantics (CC AGe parity): the message drains at the subagent's next tool round; the service echoes CC's
- * verbatim receipt "Message queued for delivery…". 409 = subagent not running (settled/unknown) — surfaced
- * honestly so the caller can fall back (steer the lead) or tell the user the agent already ended.
- * 迁移差分记账:原 raw POST 无超时 → SDK 缺省 60s 上界(steer 是入队即回的 verb,纯上界改善);
- * 'not-running' 的 detail 从「响应体原文」→「APIError.message(server body.error 原文)」——该 detail
- * 只进 debug 日志(REPL 对 not-running 显示固定文案),error 形语义不劣化。
- */
 import { hostLog } from '../host.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTargetFor } from '../engineWireTarget.js';
 import { engineSessionParamFor } from '../engineSessionParam.js';
 import { resolveOwnerContext, resolveOwnerRunId } from './engineSubagentResume.js';
 import { noteBgOwnerAbsence } from './subagentOwnerAbsence.js';
-/**
- * Steer a running engine subagent (target = its parentToolCallId, or agentName).
- *
- * 🔴 #280 件A(取址第四腿并入 [4000] Q3=B 口径):`childTaskId` 在场时**台账优先、缺席即诚实缺席**,
- * 与 tail / taskOutput·taskStop / subagentOutput 三腿同姿势,也与孪生的 resume 腿共用**同一个**
- * 取址判据(`resolveOwnerRunId`,不是第二份手抄)。此前本腿直取 `activeEngineRunId()` —— 正是
- * `engineSubagentResume` 头注点名的那处不对称(「同一个 agent 有时能说话有时不能」):
- *   · 进程级活跃 run 被并发 main/fork 流互相覆写、又在每个 query 的 finally 清空 ⇒ 后台子代在
- *     宿主 turn 收尾之后仍在跑时,这里恒空(no-run,消息发不出去);另一条 turn 正飞时它有值
- *     但**是别的 run**(打到不相干的 run 上 —— 错值比缺席更坏,与 Q3 同一条理由)。
- * 三态(`resolveOwnerRunId` 的单一判据):台账有这一行 ⇒ 用行值(哪怕此刻另有 run 在飞);
- * 指名了行而台账缺席 ⇒ `no-run` + `noteBgOwnerAbsence` 留痕(绝不回落在飞 run);
- * **没指名行**(既有两参调用)⇒ 才回落在飞 run —— 老调用方逐字零行为变化,本参数是 additive。
- *
- * 🔴 会话参数**二态**(对抗复审 medium 采纳:「取了台账的 run 却配现势 session」是确定性 404):
- *   · 行登记时**捕到了会话** ⇒ 用**行的会话**(与行的 runId 同源同拍,是唯一自洽的组合);
- *   · 行**没有**随行会话(`recordBgParentRun` 只写 run —— 今天 bg 行多数是这一格)⇒ 退**现势会话**。
- * 刻意**不**跟 resume 腿的「没捕到就干脆不带」:本腿与 tail/subagentOutput 同族,遵 [1498]③
- * 无条件带 session 的双版本兼容纪律;runId 既已由台账钉死,配错的 `{runId, session}` 组合在
- * session-bound run 上是 server 干净的 fail-closed 404(落既有 `not-running` 出路),**不会**把消息
- * 投到别的会话 —— 而「没捕到就不带」会让今天最常见的那一格整批 404。resume 那边更严是因为它是
- * AT-MOST-ONCE 的叫醒(真跑一轮,不可回收),两者的代价不对称。
- * 诚实边界:行无会话且端已切到别的会话时,对旧行 steer 会得到 `not-running`(而非静默投错人)。
- *
- * @param childTaskId 这一行子代的 taskId(fleet 行 id 尾段;端有行上下文时**应当**传)。
- */
 export async function steerEngineSubagent(target, text, childTaskId) {
-    // 空串/非串按「没指名行」处理(与 resolveOwnerRunId 的 named 判据同口径);窄成 string|undefined
-    // 而不是 boolean —— 布尔位不给 TS 窄化,留痕那一行会被迫 cast。
     const named = typeof childTaskId === 'string' && childTaskId !== '' ? childTaskId : undefined;
-    // 🔴 design/285 批 3(D7b):台账记录**先取**(纯读)—— wire target 按**这一行的会话槽**取,
-    //    零参 `engineWireTarget()` 写死默认槽(会话对了而 baseUrl/token/principal 是别人的)。
-    //    这也顺带把本腿原有的「同一张表读两次」收成一次读(取址判据仍在 resolveOwnerRunId 一处)。
     const { record: owner, key } = resolveOwnerContext(named);
     const cfg = engineWireTargetFor(key);
     if (!cfg)
         return { ok: false, reason: 'no-wire' };
     const runId = resolveOwnerRunId(named);
     if (!runId) {
-        // 指名了行才算「台账缺席」——不指名的通用调用只是没有在飞 run,不是宿主映射缺席(两者出路
-        // 同为 no-run,但只有前者是 Q3 要响亮的那一类)。
         if (named !== undefined)
             noteBgOwnerAbsence('subagent-steer', named);
         return { ok: false, reason: 'no-run' };
@@ -82,9 +23,6 @@ export async function steerEngineSubagent(target, text, childTaskId) {
     });
     if (!client)
         return { ok: false, reason: 'no-wire' };
-    // 会话二态(见头注):行登记的会话优先,缺则退现势会话。记录来自上面那一次读(`resolveOwnerContext`),
-    // 不再第二次查表;取址判据本身仍只有 `resolveOwnerRunId` 那一处,不另铸。
-    // 🔴 design/285 批 3:现势会话回落也按 `key` 取(没指名行时 key 恒是默认槽 ⇒ 与 0.44.0 逐字同)。
     const rowSession = owner?.sessionId;
     const fallbackSession = rowSession === undefined ? engineSessionParamFor(key) : undefined;
     const session = rowSession !== undefined
@@ -93,7 +31,6 @@ export async function steerEngineSubagent(target, text, childTaskId) {
             ? { session: fallbackSession }
             : {};
     try {
-        // service 1.89 receipt shape: { note: "Message queued for delivery to <name> …", delivery, … }
         const body = await client.runs.steerSubagent(runId, target, { content: text }, session);
         let receipt = 'Message queued for delivery at the next tool round.';
         const copy = body?.note ?? body?.message;

package/dist/subagent/engineSubagentTail.d.ts

@@ -1,58 +1,20 @@
-/** 测试钩:清 caps 缓存。 */
 export declare function __resetSubagentStreamCapCacheForTests(): void;
-/**
- * 一次子代工具活动(详情页 `Progress` 段的数据面,CC 2.1.220 `Zja` 的 recentActivities)。
- *
- * 🔴 `toolName` 必须是**真工具名**、`args` 必须是**真参数** —— 端的 `renderToolActivity` 拿
- * `toolName` 去工具注册表查、再用工具自己的 `userFacingName(input)` 渲染。把 `currentAction`
- * 那类自由文本塞进 `toolName` 只会走 `!tool` 回落分支把原文吐出来,是「看起来能显示」的假绑定。
- * 自由文本只能进 `activityDescription` 展示位。
- */
 export interface SubagentActivity {
     taskId: string;
     toolName: string;
-    /** `tool_start.args` 原样(非对象由端归一;端会拿它过工具 schema 的 safeParse)。 */
     args: unknown;
-    /** UNTRUSTED 展示文本(server 已 redact+bound);绝不冒充结构化 args。 */
     activityDescription?: string;
 }
-/** 端装的活动落点(执行半场)。不装 ⇒ Progress 段无数据(不是错误态,只是该面不启用)。 */
 export type SubagentActivitySink = (a: SubagentActivity) => void;
-/** 装/卸 Progress 段落点。传 null 卸。返回还原函数。 */
 export declare function installSubagentActivitySink(sink: SubagentActivitySink | null): () => void;
-/**
- * 一帧 tail `event: meta` 的发布载荷(#280 件2,0.30.4)。`meta` 是连接语义帧(server 建连即发:
- * `{version, runId, target, status, seq?, contentFrames?, …}`),**不进内容面** —— 但其中的
- * **供给形判别位 `contentFrames`**(server e439a6c,闭集 {on | progress_only | unknown})是端
- * 区分「内容帧**永远不会来**(forward 缺席宿主,结构性无内容)vs **还没来**」的唯一诚实依据;
- * 0.30.3 及之前它被消费循环的 forward-only 过滤整类 skip,端结构性到不了。
- * 🔴 `meta` 为**开集原文**(SDK subagentStream 产物 `Record<string, unknown>` 原样):判别位的
- * 窄读(闭集判词/缺席处置)归消费端,包只搬运 —— additive 上游往 meta 里加键零施工。
- * ⚠️ 供给形登记随句柄终态在 server 侧撤销(SubagentTailBus.forgetHandleContentMode)⇒ 判别位
- * 要在子代存活窗内消费,终态后重开的 tail 读到 `unknown` 不是回归。
- */
 export interface SubagentTailMeta {
     taskId: string;
-    /** meta 帧原文(开集;`contentFrames` 等判别位的窄读归消费端)。 */
     meta: Record<string, unknown>;
 }
-/** 端装的 meta 帧落点(#280 件2)。不装 ⇒ 判别位不达端(不是错误态,该面不启用;0.30.3 现状字节不变)。 */
 export type SubagentTailMetaSink = (m: SubagentTailMeta) => void;
-/** 装/卸 tail meta 帧落点。传 null 卸。返回还原函数。 */
 export declare function installSubagentTailMetaSink(sink: SubagentTailMetaSink | null): () => void;
-/**
- * tail 是否正对该行开着 —— **两源互斥判别口**(行帧 `currentTool` 臂在 tail 活跃时让位:
- * tail 的 tool_start 带真 args,渲染更细;两源同录 = 每步双行)。
- */
 export declare function isEngineSubagentTailActive(taskId: string): boolean;
-/**
- * 打开一个后台子代的 live tail(幂等:已开着的同 id 直接返回)。内容帧进 subagentContentStore,
- * 渲染由既有 C1 notify 链接管。绝不 throw;开不了(无 wire/caps 缺/寻址失败)= 静默维持现状。
- */
 export declare function tailEngineSubagent(taskId: string): void;
-/** 关闭一个子代的 tail(幂等;查看态退出/终态/行消失时调)。 */
 export declare function stopEngineSubagentTail(taskId: string): void;
-/** 在飞判别([1543]① 重开路用):true = 该子代已有 tail 挂着。 */
 export declare function hasActiveSubagentTail(taskId: string): boolean;
-/** 测试钩:在飞 tail 数。 */
 export declare function __activeTailCountForTests(): number;

package/dist/subagent/engineSubagentTail.js

@@ -1,52 +1,3 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentTail.ts` 的**流消费半场**。
- *
- * ── 拆缝(T35/T36/T44 同一条原则:判定半场进包、执行半场留宿主)────────────────────────────────
- * **进包**:caps 探测 · tail 台账(每 taskId 至多一条)· SSE 消费循环 · 帧 → subagentContentStore
- *   的四条投影 · settle 收口 · 诊断锚 · 两源互斥判别口 `isEngineSubagentTailActive`
- *   (`coerceOutput` 原也在这里,2026-08-12 搬去 `subagentContentStore.ts` 与 C1 腿共用一份)。
- * **留宿主**:`recordSubagentActivity` / `recordFleetCurrentTool` 里对
- *   `AppState.tasks[taskId].progress.recentActivities` 的读改写 —— 那是**端的任务状态形状**
- *   (`LocalAgentTaskState` / `ToolActivity`),web/桌面各有各的形。
- *   本包改为在 `tool_start` 上调 `SubagentActivitySink`(下面的可装口),壳侧 shim 装一个
- *   把原 `recordSubagentActivity` 逐字搬过去的 sink ⇒ 行为一字节不变。
- *
- * 🔴 单实例纪律:`activeTails` 是 module 级 Map。写者 = 本文件;读者 = **两源互斥判别**
- *   (行帧 `currentTool` 臂在 tail 活跃时必须让位)与查看态 watcher 的「重开」判别。
- *   两份实例 ⇒ 让位判别恒读 false ⇒ tail 与行帧两源同时录 Progress 段 = 每步双行
- *   ([new-data-source-systemic-checks]「两臂共写台账要整臂让位」)。
- *
- * 🔴 搬迁差分:`wireConfig()`(六份手抄的第六份,至此**全部收编**)→ `engineWireTarget()`;
- *   `getActiveEngineTaskId()` → `activeEngineRunId()`;`logForDebugging` → `hostLog`。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * engineSubagentTail — 后台子代 live tail(A2,server 1.251 subagentStream 提货;1.253 起
- * probe→subscribe 竞态已修([1524] HIGH-2 → [1526] 即修),接线以 1.253+ 为期望域)。
- *
- * Wire: `GET /v1/runs/:runId/subagents/:handle/stream`(SSE)——SDK runs.subagentStream 消费:
- *   · `event: meta`  {version:1, runId, target, status, seq?, …}:status 非 running/pending 时
- *     server 立即收流(终态无 tail,回放面=subagentOutput);
- *   · `event: forward` = projectTailFrame 投影帧:text_delta/reasoning_delta {delta,…}、
- *     tool_start {toolCallId,toolName,args,label?}、tool_end {toolCallId,toolName,isError,output?}、
- *     task_progress {…}(rollup,面板已有 task_progress 腿,这里不重复消费)、
- *     task_settled {taskId,status,seq?,summary?} = 收口帧(server 随即 end);
- *   · `event: heartbeat` {} 每 15s(连接活性由 server 保障,端侧无需 idle timer)。
- *
- * 消费面:帧 → subagentContentStore.publishSubagentContentEvent(C1 同一 store)——既有
- * notify→重组链零改动接管渲染;running 查看态的「live transcript pending engine wire」占位行在
- * 首个内容项落地时自然消失。
- *
- * 防双注入:task_settled → settleSubagentContent(flush 流式尾巴)后关流;终报正文不从
- * tail 合成——终态渲染仍走既有 subagentOutput 读面 / bg 事实臂,臂序(content prefix → report)
- * 保证两面不重复。
- *
- * 生命周期:查看态进入开,退出/终态/行消失关;每 taskId 至多一条(幂等);caps 探测
- * capabilities.subagentStream(true 固化/false TTL/失败不缓存,engineSubagentOutput 同纪律);
- * 寻址 runId=getBgParentRun **唯一源**(#242 批 3 起台账缺席即诚实缺席不回落,warn 留痕)、
- * 无条件带 `?session=`(同 [1498]③ 纪律)。
- * 一切失败 fail-soft:tail 断=回到占位行现状,绝不 throw。
- */
 import { hostLog } from '../host.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTargetFor } from '../engineWireTarget.js';
@@ -54,7 +5,6 @@ import { engineSessionParamFor } from '../engineSessionParam.js';
 import { resolveOwnerContext } from './engineSubagentResume.js';
 import { coerceOutput, parentToolCallIdOf, publishSubagentContentEvent, settleSubagentContent, } from '../subagentContentStore.js';
 import { noteBgOwnerAbsence } from './subagentOwnerAbsence.js';
-// ── caps 探测(true 固化 / false TTL / 失败不缓存)────────────────────────────────────────────
 const capByBase = new Map();
 const CAP_FALSE_RETRY_TTL_MS = 5 * 60_000;
 async function subagentStreamCapable(client, baseUrl, signal) {
@@ -62,24 +12,20 @@ async function subagentStreamCapable(client, baseUrl, signal) {
     if (hit && (hit.ok || Date.now() - hit.at < CAP_FALSE_RETRY_TTL_MS))
         return hit.ok;
     try {
-        // SDK 0.0.77 起 capabilities() 有真型(Capabilities 开集)——宽形 cast 已撤;键仍防御读。
         const caps = await client.capabilities({ ...(signal ? { signal } : {}) });
         const ok = caps.subagentStream === true;
         capByBase.set(baseUrl, { ok, at: Date.now() });
         return ok;
     }
     catch {
-        return false; // 探测失败不缓存(引擎瞬断):本次不开,下次再判
+        return false;
     }
 }
-/** 测试钩:清 caps 缓存。 */
 export function __resetSubagentStreamCapCacheForTests() {
     capByBase.clear();
 }
-// ── tail 台账(每 taskId 至多一条)──────────────────────────────────────────────────────────────
 const activeTails = new Map();
 let activitySink = null;
-/** 装/卸 Progress 段落点。传 null 卸。返回还原函数。 */
 export function installSubagentActivitySink(sink) {
     const prev = activitySink;
     activitySink = sink;
@@ -88,7 +34,6 @@ export function installSubagentActivitySink(sink) {
     };
 }
 let tailMetaSink = null;
-/** 装/卸 tail meta 帧落点。传 null 卸。返回还原函数。 */
 export function installSubagentTailMetaSink(sink) {
     const prev = tailMetaSink;
     tailMetaSink = sink;
@@ -96,38 +41,16 @@ export function installSubagentTailMetaSink(sink) {
         tailMetaSink = prev;
     };
 }
-/* `coerceOutput`(tool_end.output 的字符串化口)**已搬到 `subagentContentStore.ts`**
- * (#158 移交① / [3674](d) 姊妹病,2026-08-12):喂那个 store 的是两条腿(本 tail 腿 + seam
- * 适配器的 C1 分流臂),字符串化口必须只有一份,故跟着它服务的那个位走。公面导出名不变
- * (index.ts 对两个模块都是 `export *`,所以这里**不再 re-export** —— 同名双星导出会撞)。 */
-/**
- * tail 是否正对该行开着 —— **两源互斥判别口**(行帧 `currentTool` 臂在 tail 活跃时让位:
- * tail 的 tool_start 带真 args,渲染更细;两源同录 = 每步双行)。
- */
 export function isEngineSubagentTailActive(taskId) {
     return activeTails.has(taskId);
 }
-/**
- * 打开一个后台子代的 live tail(幂等:已开着的同 id 直接返回)。内容帧进 subagentContentStore,
- * 渲染由既有 C1 notify 链接管。绝不 throw;开不了(无 wire/caps 缺/寻址失败)= 静默维持现状。
- */
 export function tailEngineSubagent(taskId) {
     if (activeTails.has(taskId))
         return;
-    // 🔴 design/285 批 3(D7b):台账记录**先取**(纯读),因为 wire target 要按**这一行的会话槽**取 ——
-    //    零参 `engineWireTarget()` 写死默认槽,keyed 宿主上会拿 A 槽的 baseUrl/token/principal 去
-    //    读 B 槽的子代。`sessionKey` 缺席 ⇒ 回落默认槽 ⇒ 与 0.44.0 逐字同。
-    //    ⚠️ 两道闸的**次序一字未动**(无 wire 仍先于「台账缺席」返回,缺席留痕不会在离线宿主上刷屏)。
     const { record: owner, runId, key } = resolveOwnerContext(taskId);
     const cfg = engineWireTargetFor(key);
     if (!cfg)
         return;
-    // 🔴 #242 批 3([4000] Q3=B 裁定执行,行为翻面):台账缺席即**诚实缺席,绝不回落**
-    //    `activeEngineRunId()` —— 与 resume 腿 `resolveOwnerRunId` 同口径(错值比缺席更坏:回落值
-    //    被并发 main/fork 流覆写,可能连到不相干的 run)。缺席不静默:留痕见 noteBgOwnerAbsence。
-    //    供给面:本表由 fleet 行帧 parentId / bg 通知 parentTaskId / task_progress tick 三腿喂
-    //    (fleetLedger.ts:394/:496 + recordSubagentOwnerFromProgress),正常 bg 子代出生帧即有值;
-    //    缺席 = 真不知道宿主(壳重启且行帧未重播等),此时连「当前活跃 run」纯属赌。
     if (!runId) {
         noteBgOwnerAbsence('subagent-tail', taskId);
         return;
@@ -141,8 +64,6 @@ export function tailEngineSubagent(taskId) {
         return;
     const ac = new AbortController();
     activeTails.set(taskId, ac);
-    // [1568] 诊断锚(SEMA_DEBUG 才落盘,量有界:每条 tail 一行首帧 + 一行收尾统计)——查看态
-    // 「慢/稀疏」类报障必须能把【数据面到端】与【端渲染】分层归因,首帧时延是那条分界线。
     const openedAt = Date.now();
     let frames = 0;
     let connectLogged = false;
@@ -151,15 +72,7 @@ export function tailEngineSubagent(taskId) {
         try {
             if (!(await subagentStreamCapable(client, cfg.baseUrl, ac.signal)))
                 return;
-            // 🔴 design/285 批 3(D6,会话二态;与 steer 腿 `:88-91` 同一口径):
-            //   · 行登记时**捕到了会话** ⇒ 用**行的**会话(与行的 runId 同源同拍,唯一自洽的组合);
-            //   · 行没有随行会话 ⇒ 退**本槽的现势会话**(遵 [1498]③ 无条件带 session 的双版本兼容纪律;
-            //     runId 已由台账钉死,配错的组合在 session-bound run 上是 server 干净的 404,落既有静默出路)。
-            //   🔴 **BEHAVIOR CHANGE(默认槽也变)**:tick 腿今天就在默认槽写 `sessionId`,所以「会话轮换后
-            //   对旧行开 tail」此前用**现势**会话打一条 session-bound 的旧 run = 确定性 404;现在用行登记的
-            //   那一个,与 steer/resume 已成立的口径统一。现势会话回落也按 `key` 取,不再写死默认槽。
             const session = owner?.sessionId ?? engineSessionParamFor(key);
-            // SDK 0.0.77 起 runs.subagentStream 有真型([1547]① 候发版即消费兑现)——宽形 cast 已撤。
             const stream = client.runs.subagentStream(runId, taskId, {
                 signal: ac.signal,
                 ...(session ? { session } : {}),
@@ -171,20 +84,10 @@ export function tailEngineSubagent(taskId) {
                     break;
                 if (!connectLogged) {
                     connectLogged = true;
-                    // 连接分界线:meta 帧即到 = SSE 建连成功(与「子代此刻恰好在跑长工具、没内容可发」区分开)
                     hostLog('debug', `[subagent-tail] ${taskId} stream connected +${Date.now() - openedAt}ms`);
                 }
-                // #280 件2(0.30.4):帧分类闸 —— `meta` 经发布口出去(`contentFrames` 判别位在其中,
-                // 见 SubagentTailMeta 顶注),`forward` 进内容面,其余(heartbeat / 未来新连接语义帧)
-                // 维持 skip。🔴 开闸范围**只放 meta**(最小化):放宽 default 臂 = 把未知帧灌进发布口,
-                // 消费端会把连接杂音当判别位读。
                 switch (ev.event) {
                     case 'meta':
-                        // 连接语义帧,不进内容面;不装 sink = 现状。🔴 消费端 sink 失败**绝不撕裂 tail**
-                        //(本文件头注铁律「一切失败 fail-soft…绝不 throw」;runStream onDroppedFrame
-                        // 「sink 抛错绝不打断流且痕迹落回」同族)——两臂都要:同步 throw 由 try/catch 兜,
-                        // **异步拒绝**(类型虽 void,宿主传 async 函数合法)也要有界观察 —— 不观察 =
-                        // unhandledRejection = Node 缺省整进程崩,TUI 宿主最坏形。痕迹留 hostLog,内容帧照常消费。
                         try {
                             const out = tailMetaSink?.({ taskId, meta: ev.data });
                             if (out !== null && typeof out === 'object' && typeof out.then === 'function') {
@@ -201,7 +104,7 @@ export function tailEngineSubagent(taskId) {
                     case 'forward':
                         break;
                     default:
-                        continue; // heartbeat 等连接语义帧,不进内容面
+                        continue;
                 }
                 const d = ev.data;
                 const t = d.type;
@@ -230,8 +133,6 @@ export function tailEngineSubagent(taskId) {
                         ...(typeof d.toolName === 'string' ? { toolName: d.toolName } : {}),
                         args: d.args,
                     });
-                    // 详情页 `Progress` 段的数据面(执行半场在端,见 SubagentActivitySink)。
-                    // 只有真拿到工具名才记 —— 无名帧不编。
                     if (typeof d.toolName === 'string' && d.toolName.length > 0) {
                         activitySink?.({ taskId, toolName: d.toolName, args: d.args });
                     }
@@ -249,16 +150,10 @@ export function tailEngineSubagent(taskId) {
                     });
                 }
                 else if (t === 'task_settled') {
-                    // 收口:flush 流式尾巴;终报/结局事实由既有 hydrate/bg 事实臂渲染,不从 tail 合成。
-                    // [1543]①:seq 骑帧(core 1.373 UnifiedTaskOutput.seq;1.377 起 live 臂同键全域投影,
-                    // [1548]——settle 世代口径 spawn=1/复活承袭 claim 周期号)——≥2 = 复活周期(S3c revive)
-                    // 的 settle。tail 台账按周期关流;重开由查看态 watcher 兜(viewing 行回 running 且无
-                    // 在飞 tail 即重开,revive/断线同一恢复路)。
                     settleSubagentContent(taskId);
                     hostLog('debug', `[subagent-tail] ${taskId} settled (${String(d.status)}${typeof d.seq === 'number' ? ` seq=${d.seq}` : ''}${typeof d.summary === 'string' ? ` summary=${d.summary.slice(0, 80)}` : ''}) — close`);
                     break;
                 }
-                // task_progress:面板 rollup 已有独立腿,这里不重复消费
             }
         }
         catch (e) {
@@ -273,7 +168,6 @@ export function tailEngineSubagent(taskId) {
         }
     })();
 }
-/** 关闭一个子代的 tail(幂等;查看态退出/终态/行消失时调)。 */
 export function stopEngineSubagentTail(taskId) {
     const ac = activeTails.get(taskId);
     if (!ac)
@@ -281,11 +175,9 @@ export function stopEngineSubagentTail(taskId) {
     activeTails.delete(taskId);
     ac.abort();
 }
-/** 在飞判别([1543]① 重开路用):true = 该子代已有 tail 挂着。 */
 export function hasActiveSubagentTail(taskId) {
     return activeTails.has(taskId);
 }
-/** 测试钩:在飞 tail 数。 */
 export function __activeTailCountForTests() {
     return activeTails.size;
 }