@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/subagent/engineSubagentOutput.js

@@ -1,41 +1,9 @@
-/**
- * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentOutput.ts` 整搬。
- *
- * 🔴 搬迁三处差分(全部是「端资产上移到 port」,行为一字节不变):
- *   · `wireConfig()`(六份手抄之一)→ `engineWireTarget()`;
- *   · `getActiveEngineTaskId()`(engineToolDetach,pty 绑定的活跃 run)→ `activeEngineRunId()`
- *     (SessionPort.activeRunId);
- *   · `logForDebugging` → `hostLog('debug', …)`。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * engineSubagentOutput — 后台子代终报读面消费(server 1.244 / SDK 0.0.65 提货,提货单 [1488]③(b))。
- *
- * Wire: `GET /v1/runs/:runId/subagents/:handle/output` → {taskId, target, content, output:{status,…}}
- *   · content = 子代最终 assistant 正文(终态)或诚实 running 状态文本;
- *   · runId = spawn 该子代的 run(registry access 从 run 行推导——寻址映射由 fleet 行 parentId /
- *     bg_notification.parentTaskId 喂 subagentContentStore.recordBgParentRun);
- *   · a… 域(background_agent)专用——wa… 观测行恒 404(workflow journal 是那边的读面),调用方
- *     按 null 回落 bg 事实渲染,fail-soft;
- *   · caps 探测 capabilities.subagentOutput(selfKnowledge caps 同款纪律:true 固化/false TTL/
- *     探测失败不缓存)。老引擎(<1.244)= caps 无该键 → 恒走回落,version-safe。
- *
- * 副本域注意([1491]④):TaskRegistry 是进程内存态——引擎重启后 handle 消失(404),按 null 回落,
- * 绝不把 404 当异常上抛。
- *
- * session 作用域([1498]③,server 1.245.0 / SDK 0.0.66):session-bound run 的 subagentOutput
- * 必须带匹配的 `?session=`,否则 404 fail-closed(这个读面正是 [1493]② 双开串扰的读侧入口,
- * server 侧已把它闩死)。端无条件带 session 即双版本兼容——1.244 忽略该参数,1.245 起必需。
- * 🔴 端漏装 SessionPort ⇒ `engineSessionParam()` 恒 undefined ⇒ 本读面对 session-bound run
- * 一律 404 ⇒ 整条子代终报静默哑掉(所以 `hostSession()` 计 miss,见 host.ts)。
- */
 import { hostLog } from '../host.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTargetFor } from '../engineWireTarget.js';
 import { engineSessionParamFor } from '../engineSessionParam.js';
 import { resolveOwnerContext } from './engineSubagentResume.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 subagentOutputCapable(client, baseUrl, signal) {
@@ -43,36 +11,23 @@ async function subagentOutputCapable(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.subagentOutput === true;
         capByBase.set(baseUrl, { ok, at: Date.now() });
         return ok;
     }
     catch {
-        return false; // 探测失败不缓存(引擎瞬断):本次回落,下次再判
+        return false;
     }
 }
-/** 测试钩:清 caps 缓存。 */
 export function __resetSubagentOutputCapCacheForTests() {
     capByBase.clear();
 }
-/**
- * 拉取一个后台子代的终报正文。null = 读不到(无 wire / caps 缺 / 404 域外或副本重启 / 网错)——
- * 调用方回落 bg 事实渲染。绝不 throw。
- */
 export async function fetchEngineSubagentReport(taskId, opts) {
-    // 🔴 design/285 批 3(D7b):台账记录**先取**(纯读)—— wire target 按**这一行的会话槽**取,
-    //    零参 `engineWireTarget()` 写死默认槽。`sessionKey` 缺席 ⇒ 回落默认槽 ⇒ 与 0.44.0 逐字同。
-    //    ⚠️ 两道闸的**次序一字未动**(无 wire 仍先于「台账缺席」返回)。
     const { record: owner, runId, key } = resolveOwnerContext(taskId);
     const cfg = engineWireTargetFor(key);
     if (!cfg)
         return null;
-    // 🔴 #242 批 3([4000] Q3=B 裁定执行,行为翻面):台账缺席即**诚实缺席,绝不回落**
-    //    `activeEngineRunId()` —— 与 resume 腿 `resolveOwnerRunId` 同口径(错值比缺席更坏:回落
-    //    到「此刻在飞的 run」对 session-bound 旧 run 是 404 撞墙,对同名子代是读错人)。缺席不
-    //    静默(noteBgOwnerAbsence warn 留痕);调用方按既有 null 回落 bg 事实渲染,fail-soft。
     if (!runId) {
         noteBgOwnerAbsence('subagent-output', taskId);
         return null;
@@ -87,11 +42,6 @@ export async function fetchEngineSubagentReport(taskId, opts) {
     if (!(await subagentOutputCapable(client, cfg.baseUrl, opts?.signal)))
         return null;
     try {
-        // [1498]③:无条件带 session(1.244 忽略/1.245 必需,双版本兼容);缺席时(端未装 SessionPort /
-        // 端自己还没有值)不带——1.245 对 session-bound run 会 404,按既有 null 回落,下次重试自然带上。
-        // 🔴 design/285 批 3(D6,会话二态;与 steer/tail 同一口径):行登记的会话优先,缺则退**本槽**现势会话。
-        //    🔴 BEHAVIOR CHANGE(默认槽也变):tick 腿今天就在默认槽写 `sessionId` ⇒ 会话轮换后读旧行的终报,
-        //    此前拿**现势**会话打一条 session-bound 的旧 run = 确定性 404;现在用行登记的那一个。
         const session = owner?.sessionId ?? engineSessionParamFor(key);
         const r = await client.runs.subagentOutput(runId, taskId, {
             ...(opts?.signal ? { signal: opts.signal } : {}),

package/dist/subagent/engineSubagentResume.d.ts

@@ -1,88 +1,8 @@
-/**
- * ⇄ #242 批 2 搬迁(2026-08-15,design/242 §3 批 2 / A-028.7):cli `src/sema/subagentResumeWire.ts`
- *    的**判定半场**整搬(取址三态 + 409 六族分类 + at-most-once 调用腿),**逐条搬迁不重新发明**。
- *
- * ── 为什么搬(A-028.7 的真缺口)────────────────────────────────────────────────────────────────
- * 孪生两腿此前**分居两仓**:steer 在包(`engineSubagentSteer.ts`),resume 整条在壳(270 行)。
- * 而两腿的**决定量口径不同** —— steer 取址 `activeEngineRunId()`(在飞的那条),resume 取址
- * `resolveOwnerRunId()`(按行锚)—— 正是壳侧头注自己警告的那种不对称:「同一个 agent 有时能说话
- * 有时不能」。同居之后两腿的取址口径才有单一真源可对(口径统一本身是行为面,候 [4000] Q3)。
- *
- * ── 拆缝(判定进包 / 呈现留壳,与 T35/T36/T44 同一条原则)────────────────────────────────────
- * **进包**:能力位 gate · 取址(`resolveOwnerRunId` 三态 + `resolveSubagentContinueTarget`)·
- *   409 六族分类 · at-most-once 调用腿 · 收据消毒 · caps×verb 组合告警。
- * **留壳**:出路文案(`subagentResumeCopy`,CC 措辞面)与 Ink 卡面动作。
- *
- * ── 搬迁差分(行为一字节不变,端资产上移到 port)────────────────────────────────────────────
- *   · `capsBaseUrl()` 直读 `process.env.SEMA_LIVE_BASEURL` → `engineWireTarget()?.baseUrl`
- *     (本包零 `process.env`,portability 门盯着;壳侧 env 臂由 `engineWireTarget` 同源派生,
- *     且这一形对**显式装配** wire target 的宿主 —— web/桌面 —— 才答得对。同 `engineRowStopGate:44`)。
- *   · `logForDebugging` → `hostLog('debug', …)`(同 steer 腿搬迁差分)。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * subagentResumeWire — 保留子代的**复活口**消费面(A-022.1 + A-022.12 的人机面 / 缺口 G2+G9)。
- *
- * 取址/收据/错误族逐字对位既有的 `steerEngineSubagent` —— 同一个 `target`(parentToolCallId 或
- * agentName)、同一个 `{content}` 体、同一个 200 `SubagentSteerReceipt`。**两条腿刻意同形**:
- * steer 是「它还在跑,插句话」,resume 是「它已经结束了,叫醒它」——同一个人机动作的两个时相,
- * 分不清哪个时相就会拿错 verb 吃 409。
- *
- * ── 🔴 能力位 gate:`subagentResume` ────────────────────────────────────────────────────────
- * SDK `runs.d.ts` 头注逐字「Gate on `capabilities.subagentResume`」。未判/缺键 = false = **不渲入口**
- * (渲了就是一个恒 404/409 的假 affordance)。
- *
- * ── 🔴 409 族是**六个不同的处置**,禁合并 ───────────────────────────────────────────────────
- * `resume.retain_off`(这条 run 压根没开留存 —— 与「留存过期了」是两回事)/ `resume.evicted` /
- * `resume.cap` / `resume.session_not_found`(留存失效)/ `steering.still_running`(**它还在跑,
- * 该 steer 不该 resume**)/ `steering.not_running`(本副本无匹配 / run 已 settle)。
- * 判据是 `errorCode` 串(机器轴,开集),**不按 HTTP 数字分支**;未知码原样透传落诚实兜底臂。
- * ⚠️ **0.38.0(#318 件④)补第七、八格**:`resume.row_recycling`(行正在被裁决 —— **窗口自清,
- * 过一会儿再发就成**)/ `resume.row_gone`(行已被终态 GC 收走 —— **等也没用,重开新 agent**)。
- * 这两码在 core 侧早已在铸,是 [4743] #323「completed bg 子代跨重启 SendMessage 复活」把复活裁决
- * 腿变成常走路径之后才真正会被用户撞见;此前它们双双落进开集兜底,两个不同的下一步被压成一句
- * 泛泛失败。
- * ⚠️ **0.57.0(L-102)补第九、十格**:`resume.usage_window_exhausted` / `resume.preflight_rejected`
- * 是这一族里**唯一带得出「等多久」**的两码(`retryAfterSec`,server ≥7.47.0 / ≥7.51.0 起在 409 体上
- * additive 携;SDK 8.1.0 起铸 `ResumeRetryLaterError`)。⚠️ **「唯一带得出等待量」≠「唯一可等」**:
- * 同族的 `resume.row_recycling` 也可等(core 铸文逐字「this clears on its own; send again in a
- * moment」= 本文件的 `row-contended` 格),只是 server 给不出秒数 —— 闭集之外不等于「等也没用」。同上一次的机理:两码此前双双落进开集兜底,
- * server 明明给了等待窗,到端只剩一句泛泛失败。判型读口在
- * `wireErrorTriage.resumeRetryLaterFromError`(三端共用,不走本腿的宿主也吃这两码)。
- * 🔴 **两码不是一格而是两格**(异源对抗复审 [medium] 真病修):`resume.preflight_rejected` 有一条
- * `terminal` 臂(token 不可再赎)而判别位只在 message 散文里 ⇒ 仅凭码就归 `retry-later` 会把终局
- * 说成暂时等待。按**正向证据**分:有证据 ⇒ `retry-later`;没有 ⇒ `refused-preflight`(**不可判**,
- * 不是「不可重试」)。证据判据收在读口的 `waitable` 一位上,本层不复判。
- *
- * ── UNTRUSTED ───────────────────────────────────────────────────────────────────────────────
- * 收据 `note` 是 server 铸的文案(引擎会把子代名字拼进去,名字是 spawning model 的自由文本)——
- * 呈前消毒 + 截长,只渲染。
- */
 import type { SubagentSteerReceipt } from '@sema-agent/sdk';
 import { type SubagentOwnerRecord } from '../subagentContentStore.js';
-/** 能力位键(server `routes/capabilities.ts` 的 `subagentResume`;SDK `Capabilities.subagentResume`)。 */
 export declare const SUBAGENT_RESUME_CAP = "subagentResume";
-/**
- * 复活口在不在。未判/缺键 = false = 详情面不渲「继续」腿。
- *
- * 🔴 design/285 批 3(D7b):`baseUrl` 缺席时的派生从零参 `engineWireTarget()`(写死默认槽)换成
- *    `engineWireTargetFor(sessionKey)`。**本腿没有行上下文**(它答的是「这台引擎有没有这个口」,
- *    不是「这一行该打到哪」)⇒ 槽键只能由调用方给,缺省 `DEFAULT_SESSION_KEY` = 与 0.44.0 逐字同。
- *    显式 `baseUrl` 恒赢(既有注入缝不动;空串仍原样保留 —— `??` 只对 `undefined` 让位,与默认参形同)。
- */
 export declare function subagentResumeAvailable(baseUrl?: string, sessionKey?: string): boolean;
-/**
- * 「继续」腿的 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 declare function resolveSubagentContinueTarget(rowId: string, displayName: string | undefined): string | undefined;
-/** 本层消费的 `client.runs` 切片(注入缝)。 */
 export interface SubagentResumeFacade {
     resumeSubagent(taskId: string, target: string, message: {
         content: string;
@@ -91,228 +11,47 @@ export interface SubagentResumeFacade {
         signal?: AbortSignal;
     }): Promise<SubagentSteerReceipt>;
 }
-export type SubagentResumeFailureKind = 
-/** 没有 live 引擎 / 没有在飞 run —— 连地址都拼不出来(与「引擎拒了」是两回事)。 */
-'no-wire' | 'no-run'
-/** `resume.retain_off` —— 这条 run 没开 retainSubagentSessions(改配置才有救,重试无用)。 */
- | 'retain-off'
-/** `resume.evicted` / `resume.cap` / `resume.session_not_found` —— 留存**曾经在**,现在没了。 */
- | 'retention-lapsed'
-/** `steering.still_running` —— 它还在跑:该 steer,不该 resume(唯一「换个动作就成」的一格)。 */
- | 'still-running'
-/** `steering.not_running` —— 本副本无匹配 / run 已 settle。 */
- | 'not-resumable'
-/** `steering.ambiguous_target` —— 按名取址撞上同名多员(取址口径本身可分,是唯一「换个地址就成」的一格)。 */
- | 'ambiguous-target'
-/**
- * `resume.row_recycling`(#318 件④ / [4743] SendMessage 复活语义半场)—— registry 行**正在被裁决**
- * (另一个复活 claim 或一次 reap sweep 正持着它)。
- * 🔴 与 `not-resumable` **禁合并**:core 铸文逐字「this clears on its own; send again in a moment」——
- * 窗口自清,**同一条命令过一会儿就成**。渲成「不可复活」会把一个自愈的瞬时窗说成终局。
- */
- | 'row-contended'
-/**
- * `resume.row_gone`(同上)—— registry 行**已经不存在**(终态 GC 收走了)。
- * 🔴 与 `row-contended` **禁合并**:这一格**等也没用**,core 给的下一步是「relaunch a new agent」。
- * 两码合并 = 一半用户白等、另一半白重开。
- */
- | 'row-gone'
-/**
- * `resume.usage_window_exhausted` / `resume.preflight_rejected`(L-102,0.57.0;server ≥7.47.0 /
- * ≥7.51.0,SDK 8.1.0 `ResumeRetryLaterError`)—— **有证据表明现在不行、过一会儿行**,也是这一族里
- * **唯一带得出「等多久」**的一格({@link SubagentResumeFailureVerdict.retryAfterSec})。
- * ⚠️ 「唯一带得出等待量」**不是**「唯一可等」——`row-contended` 那一格同样可等(窗口自清),
- *    只是 server 给不出秒数。两件事别混。
- *
- * 🔴 与 `row-contended` **不合并**(两者都是「等」,但不是同一件事,也不是同一个量):
- *    `row-contended` 是**行级**的瞬时争用(另一个复活 claim / 一次 reap sweep 正持着它),窗口
- *    自清、server 给不出秒数;本格是**部署级**的时间性拒绝(治理窗满 / 预检拒),server 明确给了
- *    建议等待窗。合并会把一个有确定等待量的格说成「过一会儿再试试」,或者反过来给一个没有窗的
- *    格编一个倒计时。
- * 🔴 与 `retention-lapsed` / `row-gone` / `retain-off` **方向相反**:那三格**等也没用**。
- * 🔴 处置 = **等,不是重发**:resume 是 AT-MOST-ONCE 的有副作用动作,本层照旧一格都不重试 ——
- *    「可以再试」是说给**人**听的,不是给自动重试腿的授权。
- * 🔴 **本格只收有正向证据的那些**(异源对抗复审 [medium] 真病修):`resume.usage_window_exhausted`
- *    恒进本格(core 铸文的不变量就是证据);`resume.preflight_rejected` 只在 server 真给了等待窗
- *    时进本格,否则落 {@link SubagentResumeFailureKind} 的 `'refused-preflight'`。
- */
- | 'retry-later'
-/**
- * `resume.preflight_rejected` **且 server 没给等待窗**(L-102,0.57.0)—— 部署自己的 resume 预检拒了
- * 这次,它是提交前的最后一档,所以**什么都没被消费**;但**还能不能再赎不可判**。
- *
- * 🔴 与 `retry-later` **禁合并**(异源对抗复审 [medium] 立的格):core 在这一码上有两条臂 ——
- *    `retry_later`(行留 pending,同一 token 可再赎)与 `terminal`(行已被单发 expire CAS 结清,
- *    token 不可再赎)——而**判别位在 message 散文里**,wire 上没有机读位。把没有证据的那些一律
- *    渲成「稍后重试」,就是把一个终局说成暂时等待;而本包**不按文案分臂**(按文案分支 = 上游改
- *    一个词就静默空转)。⇒ 诚实的第三条路:**说两条臂都成立的那句**,把「还能不能再赎」交给
- *    引擎那行原文({@link SubagentResumeFailureVerdict.detail})。
- * 🔴 **它不是「不可重试」**:`false` 只是「不可判」。端**不许**渲成终局,也**不许**渲成「稍后重试」。
- */
- | 'refused-preflight'
-/** 404 —— 未知 run / 非属主(**无存在性谕示**,两者同形)。 */
- | 'not-found'
-/** 400 —— 空 content 等入参问题。 */
- | 'bad-request'
-/** 开集兜底。 */
- | 'error';
+export type SubagentResumeFailureKind = 'no-wire' | 'no-run' | 'retain-off' | 'retention-lapsed' | 'still-running' | 'not-resumable' | 'ambiguous-target' | 'row-contended' | 'row-gone' | 'retry-later' | 'refused-preflight' | 'not-found' | 'bad-request' | 'error';
 export type SubagentResumeOutcome = {
     ok: true;
     receipt: string;
-}
-/** 失败臂 = `ok:false` + {@link SubagentResumeFailureVerdict} 的四位(0.57.0 起含 `retryAfterSec`
- *  与 `code`;两位都只在 L-102 那两格上可能在场。additive,既有按 `reason`/`detail` 读的宿主
- *  一字不用改)。 */
- | {
+} | {
     ok: false;
     reason: SubagentResumeFailureKind;
     detail: string;
     retryAfterSec?: number;
     code?: string;
 };
-/**
- * {@link classifySubagentResumeFailure} 的判决(命名形;0.57.0 因 `retryAfterSec` 位达 3 成员抽名 ——
- * 导出签名里不留 ≥3 成员的内联匿名形,typeshape B4 口径。结构与 0.56.0 的内联形逐字兼容)。
- */
 export interface SubagentResumeFailureVerdict {
     reason: SubagentResumeFailureKind;
-    /** server 的原话(UNTRUSTED;呈前由调用方消毒截长)。 */
     detail: string;
-    /**
-     * **只在** `reason === 'retry-later'` 上可能在场 —— server 给的建议等待秒数(整数 ≥1)。
-     * 🔴 **缺席 ≠ 0**:缺席 = 服务端没给窗(老引擎 / 老 SDK 映射 / 该腿不发头),绝不渲一个编出来的
-     *    倒计时;别的 `reason` 上本位恒缺席。窄读域见 `resumeRetryLaterFromError`(同包
-     *    `wireErrorTriage.ts`)。
-     * 🔴 **缺席时该说什么由 `reason` 决定,不由本位决定**:`retry-later` 且窗缺席(= 治理窗满而 server
-     *    没给数字)⇒ 说「稍后重试」但不给数字;`refused-preflight` ⇒ **不许**说「稍后重试」。
-     * 🔴 `reason === 'refused-preflight'` 上本位**恒缺席**——它正是「没有窗」那一格的定义。
-     */
     retryAfterSec?: number;
-    /**
-     * **只在** `reason` 是 `'retry-later'` / `'refused-preflight'` 两格上在场 —— 命中的那一个 wire 码
-     * (`resume.usage_window_exhausted` / `resume.preflight_rejected`)。
-     *
-     * 🔴 **为什么处置分了格还要把码带出来**:`retry-later` 这一格今天有两个来源(治理窗满 / 带窗的
-     *    预检拒),而端的诚实措辞不同 —— 前者说「本部署的用量窗满了」,后者说「部署的预检暂时拒了」。
-     *    `detail` 是 server 的散文,**不是**机读位,别从它反解码。
-     * 别的 `reason` 上本位恒缺席(闭集之外本包不认得码,也就不替 server 声明成因)。
-     */
     code?: string;
 }
-/**
- * resume 失败 → 处置分类。机器轴 = `errorCode`(开集);`status` 只用于**码缺席**时的两格粗分
- * (404 无存在性谕示 / 400 入参),绝不用数字去猜某个具体 409 成因(那些 409 只有 `errorCode`
- * 分得开,按数字分支等于把好几种处置压成一种)。
- */
 export declare function classifySubagentResumeFailure(e: unknown): SubagentResumeFailureVerdict;
-/**
- * 「这一行子代该打到哪条 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 declare function resolveOwnerRunId(childTaskId?: string, activeRunId?: string | undefined): string | undefined;
-/** {@link resolveOwnerContext} 的返回三件。 */
 export interface SubagentOwnerContext {
-    /** 整条台账记录;`undefined` = **诚实不知道**,调用方走各自既有的缺席出路(绝不在这里回落)。 */
     record: SubagentOwnerRecord | undefined;
-    /**
-     * `= record?.runId`,与既有 `getBgParentRun()` 逐字同。
-     * 🔴 **不含**「没指名行就回落到在飞 run」那一态 —— 那一态的判据住在 {@link resolveOwnerRunId},
-     *    本函数既不复制它,也**不读 SessionPort**(读了就会给 tail/output/taskHandle 三条
-     *    「台账缺席即诚实缺席」的腿凭空添一次 `activeEngineRunId()` 端口读)。
-     */
     runId: string | undefined;
-    /** 读侧要用的会话槽键 = `record.sessionKey ?? DEFAULT_SESSION_KEY`。 */
     key: string;
 }
-/**
- * 「这一行子代属于哪个会话槽」—— 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 declare function resolveOwnerContext(childTaskId?: string): SubagentOwnerContext;
-/** 一次 resume 调用需要的三件:facade(null = 无 wire)、宿主 run(undefined = 诚实缺席)、会话参数。 */
 export interface SubagentResumeContext {
     facade: SubagentResumeFacade | null;
     runId: string | undefined;
     session: Record<string, string>;
 }
-/**
- * 产品 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 declare function resolveSubagentResumeContext(childTaskId?: string): SubagentResumeContext;
-/**
- * 叫醒一个已 settle 的保留子代。
- *
- * @param target parentToolCallId 或 agentName(与 `steerEngineSubagent` 同一取址口径;
- *               同名多个活体 ⇒ server 409 `steering.ambiguous_target`)。
- * 🔴 AT-MOST-ONCE:server 明写不重试。本层因此**不重试任何一格** —— 「叫醒」是有副作用的动作,
- *   重投一次可能真的多跑一轮。
- */
 export declare function resumeSettledSubagent(facade: SubagentResumeFacade | null, runId: string | undefined, target: string, content: string, opts?: {
     session?: string;
     signal?: AbortSignal;
 }): Promise<SubagentResumeOutcome>;
-/**
- * {@link auditRetainWithoutWake} 的判决(对抗复审 low 收紧的**返回契约**)。
- *
- * 两位分别回答两个不同的问题,**不许合成一个**:
- *   · `message` = 组合成不成立(成立才有这条记录;`undefined` 返回 = 不成立);
- *   · `emitted` = **本次**响没响(per-baseUrl once 去重命中时为 `false`)。
- * 旧形(去重命中仍回正文)有双义:按返回值呈现的调用方会**重复提示**,而「至多一次」的承诺
- * 只兑现在日志上。调用方要「只提示一次」就看 `emitted`,要「组合还成不成立」就看有没有记录。
- */
 export interface RetainWithoutWakeVerdict {
     message: string;
     emitted: boolean;
 }
-/** {@link auditRetainWithoutWake} 的入参(命名形:导出签名里不留 ≥3 成员的内联匿名形)。 */
 export interface RetainWithoutWakeInput {
     baseUrl?: string | undefined;
-    /**
-     * 本端的 `ClientSliceLike` 实现(或它的任意子集)。类型刻意窄到 `wakeSubagent` 这一位的**函数
-     * 形**而不是 `unknown` —— 判据是「这个 verb 实现了没有」,而 `unknown` 会把「端传了个字符串」
-     * 也算成合法入参(边界层的 unknown 必须在本模块内窄化,typeshape 门守的正是这条)。
-     */
     slice?: {
         wakeSubagent?: ((input: {
             taskId: string;
@@ -320,23 +59,7 @@ export interface RetainWithoutWakeInput {
         }) => Promise<void>) | undefined;
     } | null | undefined;
     retainRequested?: boolean | undefined;
-    /**
-     * 🔴 design/285 批 3(D7b):`baseUrl` 缺席时按哪个会话槽派生。缺省 `DEFAULT_SESSION_KEY`
-     * ⇒ 与 0.44.0 逐字同(零参 `engineWireTarget()` 就是默认槽)。本告警是**per-baseUrl once**
-     * 的,keyed 宿主不点名槽就会让两个槽共用一条 once 记录(先响的那个把另一个吞掉)。
-     */
     sessionKey?: string | undefined;
 }
-/**
- * 「引擎有复活口 + 本端在付留存成本 + 本端没有 wake 实现」⇒ 响亮一条(每 baseUrl 至多一次)。
- *
- * 返回 {@link RetainWithoutWakeVerdict}:`undefined` = 组合不成立(没这笔账);有记录 = 组合成立,
- * 其中 `emitted` 说明**本次**响没响。**返回值即判据** —— 只落日志的告警在测试里等于不存在,
- * 而只回一个字符串又分不出「本次响了」与「早响过了」(按返回值呈现的调用方会重复提示)。
- *
- * @param slice 本端的 `ClientSliceLike` 实现(或它的任意子集);`wakeSubagent` 不是函数即算未实现。
- * @param retainRequested 本端 run 请求里的 `retainSubagentSessions`(缺省 true = 包内 taskRequest 的缺省)。
- */
 export declare function auditRetainWithoutWake(input: RetainWithoutWakeInput): RetainWithoutWakeVerdict | undefined;
-/** 测试钩:清 once 去重台账。 */
 export declare function __resetRetainWithoutWakeWarningForTests(): void;