@sema-agent/client-core 0.30.5 → 0.30.7

package/CHANGELOG.md

@@ -16,6 +16,75 @@
 > 🔴 **互链**(web [C166]⑦):各版「已知局限」段只记**该版新增**;接入面已知局限的完整台账在
 > `docs/INTEGRATION-CLIENTS.md` §6e/§7 —— **只读其一会漏**,两处都过。
 
+## 0.30.7(2026-08-15)
+
+**#242 批 2 subagent 归属单表 + resume 腿归位(A-028.6/.7 收编)——公开面 additive,一处行为面加强:**
+
+- **「这一行子代属于哪条 run」从此只有一张表**:`subagentContentStore` 的 `bgParentRun` 收编了
+  sema-cli 的壳侧 `subagentOwnerLedger`。收编前同一个问题两仓两份台账、**答案规则相反**(壳表按
+  `task_progress` tick 喂、缺席即诚实缺席;包表按 fleet 行帧/bg 通知喂、消费方一律回落在飞 run),
+  且两表覆盖面互补(壳表只覆盖发 tick 的子代、包表覆盖零 tick 的 fleet-row lane)。
+  - 新写入口 `recordSubagentOwnerFromProgress(ev, ownerRunId, ownerSessionId)` —— 收编前本表
+    **零 `task_progress` 腿**。🔴 宿主 run **必须由持有 stream-local 值的调用方显式传入**,包内
+    绝不从 `activeEngineRunId()` 推断(进程级值被并发 main/fork 流互相覆写 + 每个 query 的 finally
+    清空 ⇒ 推断出的宿主可能是别的 run,而**错值比缺席更坏**)。
+  - `recordBgParentRun(taskId, runId)` 补 **additive** 第三参 `sessionId`;新读口
+    `getBgParentRunOwner(taskId)` 回整条 `{runId, sessionId?}`(旧读口 `getBgParentRun` 签名不变)。
+  - 表上限 64 → **320**(收编前两表之和;收货订正:本行中期文案曾写 256「较大者」,与终版实现、
+    断言 R1l/R1m 及本段下方「表容量」条相矛盾——之和才不缩窄既有保障,详见下方)。
+- **resume 腿与它的孪生 steer 同居**:新 `subagent/engineSubagentResume.ts`(判定半场:能力位 gate
+  `subagentResume` / 取址三态 / 409 **六族**分类禁合并 / AT-MOST-ONCE 调用腿 / UNTRUSTED 收据消毒)。
+  此前 steer 在包、resume 整条在 sema-cli,且两腿**取址的决定量不同**(steer 取在飞 run、resume 取
+  行锚)—— 那正是「同一个 agent 有时能说话有时不能」的成因。出路文案(CC 措辞面)留端。
+  新公开面:`resumeSettledSubagent` / `resolveSubagentResumeContext` / `resolveOwnerRunId` /
+  `classifySubagentResumeFailure` / `resolveSubagentContinueTarget` / `subagentResumeAvailable` /
+  `SUBAGENT_RESUME_CAP` + `SubagentResumeContext` / `SubagentResumeFacade` /
+  `SubagentResumeFailureKind` / `SubagentResumeOutcome` 类型。
+- **caps × verb 组合告警**(`auditRetainWithoutWake`):引擎 caps 宣示 `subagentResume` ∧ 本端在请求
+  `retainSubagentSessions` ∧ 本端**未实现** `wakeSubagent` ⇒ 响亮一条 warn(每 baseUrl 至多一次)。
+  返回 `RetainWithoutWakeVerdict {message, emitted}`(`undefined` = 组合不成立):`message` 答「组合
+  成不成立」、`emitted` 答「**本次**响没响」——两问分开,按返回值呈现的端才不会重复提示。`CLIENT_VERBS.wakeSubagent` 按裁定**维持 `required:false`**(fail-soft)——
+  留存成本天天在付而一个兑现口都没有,这笔账不该只有沉默。
+  ⚠️ 键名订正:caps 上没有 `retainSubagentSessions` 位,它是 **run 请求位**;引擎宣示兑现口的
+  caps 位是 `subagentResume`。
+- **🔴 刻意未做(候三端表态)**:包内三处 `getBgParentRun(x) ?? activeEngineRunId()` 回落
+  (`engineSubagentTail` / `engineTaskHandleWire` / `engineSubagentOutput`)**口径一字未改**,只各加
+  一条候裁注释。统一到 resume 腿的「指名了行就诚实缺席」口径会让台账缺席时这三腿从「能连上(可能
+  连错 run)」变成「不连」= 真行为翻面,需 cli/web/desktop 表态后单批改。
+  ⚠️ **本批的一个附带效果**:tick 腿补进单表后,这三处在过去恒缺席、必走回落的那些子代行,现在能
+  查到**真**宿主 run 了 —— 回落分支的触发面因此缩小(方向是从「可能连错」变成「连对」)。
+- **🔴 resume 的 `?session=` 口径(端请注意)**:`resolveSubagentResumeContext` 对「台账认得这一行
+  但没捕到它的会话」**不带 `?session=`**,绝不用「此刻的会话」冒充 —— resume 是 AT-MOST-ONCE 的
+  副作用动作,猜错会话可能落到另一个会话的同名子代上(不可回收),而不带参数只是 server 干净 404。
+  今天 fleet 行帧腿/通知腿不传 session,所以 fleet-only 行稳定落这一格;**供给面欠账**:两腿补上
+  流会话后这一格自然变成「有真值」,判据无需再改。「完全没指名行」的通用调用仍退当前会话(口径不变)。
+- **表容量**:合表上限取收编前**两表之和 320**(不是较大者 256)—— 按 256 钉会出现「tick 池已满、
+  再来一条 fleet 行就淘汰一条 tick」,那条子代的 resume 入口凭空消失而收编前还在。
+  另:同 `runId` 上**无 session 的刷新不覆盖已捕获的 session**(`runId` 真变了才丢)——
+  fleet/通知两腿的无 session 写此前会抹掉 tick 一次性捕获的会话。
+
+## 0.30.6(2026-08-15)
+
+**#242 批 1 workflow 单流化(A-028.8 收编)——wire 行为变更,消费端请对表:**
+
+- **同一 workflowId 恰一条 SSE**:运行期 activity 台账上收包内(模块级常驻,workflow 起跑即积累;
+  `createLiveWorkflowSource` 不再自开流,改搭台账 change-tick 做节流 re-GET,逐拍语义等价)。
+  此前包流帧体整丢只当 ticker、消费端(sema-cli)自建第二条同 id 流 —— 连接数从 2 降到 1。
+  **若你的端也自建了第二条 workflow detail 流,请改读包台账。**
+- **新公开面**:`ensureWorkflowActivityLedger(cfg)`(预热口,幂等)/`stopWorkflowActivityLedger(id)`
+  (收口)/`readWorkflowActivityLedger(id)`(读口,null=没开过账)+ `WorkflowActivityLedgerView`/
+  `WorkflowActivityAgentView` 类型。
+- **投影新增 `WorkflowAgent.callKey`**(additive):SSE activity 帧的主键此前被投影丢弃,label 因此
+  成了消费端唯一钥匙;现在重名 agent 也能精确归属。label 归属只在「该 label 恰一个 acc」时成立,
+  归属不可判整组跳过(诚实缺席)。
+- 台账语义:`agent_end.toolCalls` 权威、活动期 start 计数为下界;收口分因(terminal/stopped/error,
+  仅 error 可被 ensure 重开且事实保留);连线身份(baseUrl/principal/凭证)变更整条换新,被顶掉的
+  消费者停手降级 GET 轮询(不 ping-pong 抢回)。
+
+已知局限(本版新增;完整台账见 docs/INTEGRATION-CLIENTS.md §6e/§7):台账注册表按 workflowId 单键
+(两个不同连线身份同 id 并存时后者赢、前者退 GET 轮询);台账自预热口首调起积累(attach 老 run 时
+运行期计数是下界);常驻上限 16 条,满且全部在飞时新 id 不建账(详情退 GET 轮询,响亮留痕)。
+
 ## 0.30.5
 
 - **#244 F4 族D:配置/模型表单源化(A-028.17/.18/.20 三件单源上收 + A-028.19 对账钉,additive,

package/README.md

@@ -35,7 +35,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.30.5
+**Version:** 0.30.6
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver

package/dist/index.d.ts

@@ -203,6 +203,7 @@ export * from './subagent/engineDelegatedPrompt.js';
 export * from './subagent/engineRowStopGate.js';
 export * from './subagent/engineSubagentOutput.js';
 export * from './subagent/engineSubagentSteer.js';
+export * from './subagent/engineSubagentResume.js';
 export * from './subagent/engineTaskHandleWire.js';
 export * from './subagent/engineCompactWire.js';
 export * from './subagent/engineSubagentTail.js';

package/dist/index.js

@@ -264,6 +264,8 @@ export * from './subagent/engineDelegatedPrompt.js';
 export * from './subagent/engineRowStopGate.js';
 export * from './subagent/engineSubagentOutput.js';
 export * from './subagent/engineSubagentSteer.js';
+// #242 批 2(A-028.7):resume 判定半场与 steer 同居 —— 两条孪生腿的取址口径才有单一真源。
+export * from './subagent/engineSubagentResume.js';
 export * from './subagent/engineTaskHandleWire.js';
 export * from './subagent/engineCompactWire.js';
 export * from './subagent/engineSubagentTail.js';

package/dist/subagent/engineSubagentOutput.js

@@ -64,6 +64,9 @@ export async function fetchEngineSubagentReport(taskId, opts) {
     const cfg = engineWireTarget();
     if (!cfg)
         return null;
+    // 🔴 候裁([4000] Q3 / design-242 §5 Q3,#242 批 2 **刻意不动**):这条回落与 resume 腿的
+    //    `resolveOwnerRunId`(指名了行就诚实缺席)口径相反;统一口径是真行为翻面,候三端表态。
+    //    同族另两处:`engineSubagentTail.ts:tailEngineSubagent` / `engineTaskHandleWire.ts:resolveHostRun`。
     const runId = getBgParentRun(taskId) ?? activeEngineRunId();
     if (!runId)
         return null;

package/dist/subagent/engineSubagentResume.d.ts

@@ -0,0 +1,198 @@
+/**
+ * ⇄ #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 数字分支**;未知码原样透传落诚实兜底臂。
+ *
+ * ── UNTRUSTED ───────────────────────────────────────────────────────────────────────────────
+ * 收据 `note` 是 server 铸的文案(引擎会把子代名字拼进去,名字是 spawning model 的自由文本)——
+ * 呈前消毒 + 截长,只渲染。
+ */
+import type { SubagentSteerReceipt } from '@sema-agent/sdk';
+/** 能力位键(server `routes/capabilities.ts` 的 `subagentResume`;SDK `Capabilities.subagentResume`)。 */
+export declare const SUBAGENT_RESUME_CAP = "subagentResume";
+/** 复活口在不在。未判/缺键 = false = 详情面不渲「继续」腿。 */
+export declare function subagentResumeAvailable(baseUrl?: string | undefined): 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;
+    }, opts?: {
+        session?: string;
+        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'
+/** 404 —— 未知 run / 非属主(**无存在性谕示**,两者同形)。 */
+ | 'not-found'
+/** 400 —— 空 content 等入参问题。 */
+ | 'bad-request'
+/** 开集兜底。 */
+ | 'error';
+export type SubagentResumeOutcome = {
+    ok: true;
+    receipt: string;
+} | {
+    ok: false;
+    reason: SubagentResumeFailureKind;
+    detail: string;
+};
+/**
+ * resume 失败 → 处置分类。机器轴 = `errorCode`(开集);`status` 只用于**码缺席**时的两格粗分
+ * (404 无存在性谕示 / 400 入参),绝不用数字去猜某个具体 409 成因(六个 409 只有 `errorCode`
+ * 分得开,按数字分支等于把六种处置压成一种)。
+ */
+export declare function classifySubagentResumeFailure(e: unknown): {
+    reason: SubagentResumeFailureKind;
+    detail: string;
+};
+/**
+ * 「这一行子代该打到哪条 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;
+/** 一次 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 定口径,codex 复审 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` 出路文案接。与本模块「错值比缺席更坏」同一条口径。
+ *    · 调用方**完全没指名行**(无行上下文的通用调用)⇒ 才退当前会话(既有口径不变)。
+ *    ⚠️ 供给面欠账:fleet/通知两腿手里没有流会话,补上之后第二态自然变成第一态,判据无需再改。
+ */
+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} 的判决(codex 复审 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;
+            message: string;
+        }) => Promise<void>) | undefined;
+    } | null | undefined;
+    retainRequested?: boolean | 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;

package/dist/subagent/engineSubagentResume.js

@@ -0,0 +1,210 @@
+import { hostLog } from '../host.js';
+import { engineCapTrue } from '../engineCapsCache.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+import { getBgParentRunOwner, parentToolCallIdOf, } from '../subagentContentStore.js';
+/** 能力位键(server `routes/capabilities.ts` 的 `subagentResume`;SDK `Capabilities.subagentResume`)。 */
+export const SUBAGENT_RESUME_CAP = 'subagentResume';
+/** 复活口在不在。未判/缺键 = false = 详情面不渲「继续」腿。 */
+export function subagentResumeAvailable(baseUrl = engineWireTarget()?.baseUrl) {
+    return engineCapTrue(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 !== '')
+        return precise;
+    const name = typeof displayName === 'string' ? displayName.trim() : '';
+    return name !== '' ? name : undefined;
+}
+/** 留存失效族(三码同处置:留存曾经在、现在没了;文案一致,留痕分得开)。 */
+const RETENTION_LAPSED_CODES = new Set([
+    'resume.evicted',
+    'resume.cap',
+    'resume.session_not_found',
+]);
+function shapeOf(e) {
+    const o = (e ?? {});
+    return {
+        ...(typeof o.status === 'number' ? { status: o.status } : {}),
+        ...(typeof o.errorCode === 'string' ? { errorCode: o.errorCode } : {}),
+        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);
+    if (errorCode === 'resume.retain_off')
+        return { reason: 'retain-off', detail: message };
+    if (errorCode !== undefined && RETENTION_LAPSED_CODES.has(errorCode)) {
+        return { reason: 'retention-lapsed', detail: message };
+    }
+    if (errorCode === 'steering.still_running')
+        return { reason: 'still-running', detail: message };
+    if (errorCode === 'steering.not_running')
+        return { reason: 'not-resumable', detail: message };
+    if (errorCode === 'steering.ambiguous_target')
+        return { reason: 'ambiguous-target', detail: message };
+    if (errorCode === undefined && status === 404)
+        return { reason: 'not-found', detail: message };
+    if (errorCode === undefined && status === 400)
+        return { reason: 'bad-request', detail: message };
+    if (errorCode?.startsWith('not_found.') === true)
+        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 = activeEngineRunId() ?? undefined) {
+    const owner = getBgParentRunOwner(childTaskId);
+    if (owner !== undefined)
+        return owner.runId;
+    if (childTaskId !== undefined && childTaskId !== '')
+        return undefined;
+    return activeRunId;
+}
+/**
+ * 产品 facade + 运行定位。**逐字复用 `steerEngineSubagent` 的三步**(engineWireTarget → 无则 no-wire;
+ * 取运行 → 无则 no-run;makeEngineWireClient)—— 两条腿共用同一套装配,免得 steer 能到达而 resume
+ * 到不了(或反过来),那种不对称在用户面上表现为「同一个 agent 有时能说话有时不能」。
+ *
+ * 🔴 `session` 的三态(#242 批 2 定口径,codex 复审 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` 出路文案接。与本模块「错值比缺席更坏」同一条口径。
+ *    · 调用方**完全没指名行**(无行上下文的通用调用)⇒ 才退当前会话(既有口径不变)。
+ *    ⚠️ 供给面欠账:fleet/通知两腿手里没有流会话,补上之后第二态自然变成第一态,判据无需再改。
+ */
+export function resolveSubagentResumeContext(childTaskId) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return { facade: null, runId: undefined, session: {} };
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        ...(cfg.principal !== undefined ? { principal: cfg.principal } : {}),
+    });
+    if (!client)
+        return { facade: null, runId: undefined, session: {} };
+    const named = childTaskId !== undefined && childTaskId !== '';
+    const owner = getBgParentRunOwner(childTaskId);
+    const sessionFromRow = owner?.sessionId;
+    const session = sessionFromRow !== undefined
+        ? { session: sessionFromRow }
+        : named
+            ? {} // 指名了行却没有它的会话 ⇒ 诚实缺席,绝不用当前会话冒充
+            : engineSessionParamSpread();
+    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' };
+    if (runId === undefined || runId === '')
+        return { ok: false, reason: 'no-run', detail: 'no active engine run' };
+    const text = content.trim();
+    if (text === '')
+        return { ok: false, reason: 'bad-request', detail: 'empty message' };
+    try {
+        const receipt = await facade.resumeSubagent(runId, target, { content: text }, opts);
+        const note = receipt?.note;
+        return {
+            ok: true,
+            receipt: typeof note === 'string' && note !== ''
+                ? clean(note, 240)
+                : 'Message queued for delivery; the agent will continue in the background.',
+        };
+    }
+    catch (e) {
+        const f = classifySubagentResumeFailure(e);
+        hostLog('debug', `engineSubagentResume: resume(${clean(target, 64)}) → ${f.reason} (${clean(f.detail, 160)})`);
+        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 ?? engineWireTarget()?.baseUrl;
+    if (!engineCapTrue(baseUrl, SUBAGENT_RESUME_CAP))
+        return undefined;
+    if (input.retainRequested === false)
+        return undefined;
+    if (typeof input.slice?.wakeSubagent === 'function')
+        return undefined;
+    const message = 'client-core: engine advertises capabilities.subagentResume and this client requests ' +
+        'retainSubagentSessions, but the client slice implements no wakeSubagent verb — retained ' +
+        'subagent sessions are being paid for with no way to redeem them (CLIENT_VERBS.wakeSubagent ' +
+        'stays fail-soft by design; wire an entry point or stop requesting retention).';
+    const key = baseUrl ?? '<no-base>';
+    if (warnedRetainWithoutWake.has(key))
+        return { message, emitted: false };
+    warnedRetainWithoutWake.add(key);
+    hostLog('warn', message);
+    return { message, emitted: true };
+}
+/** 测试钩:清 once 去重台账。 */
+export function __resetRetainWithoutWakeWarningForTests() {
+    warnedRetainWithoutWake.clear();
+}

package/dist/subagent/engineSubagentTail.js

@@ -114,6 +114,11 @@ export function tailEngineSubagent(taskId) {
     const cfg = engineWireTarget();
     if (!cfg)
         return;
+    // 🔴 候裁([4000] Q3 / design-242 §5 Q3,#242 批 2 **刻意不动**):这条 `?? activeEngineRunId()`
+    //    与 resume 腿的 `resolveOwnerRunId`(指名了行就诚实缺席,绝不回落)口径**相反**。壳侧对抗
+    //    复审的结论是「错值比缺席更坏」;统一到那个口径 ⇒ 台账缺席时本腿从「能连上(可能连错 run)」
+    //    变成「不连」= 真行为翻面,需三端(cli/web/desktop)表态后单批改。同族另两处:
+    //    `engineTaskHandleWire.ts:resolveHostRun` / `engineSubagentOutput.ts:fetchEngineSubagentReport`。
     const runId = getBgParentRun(taskId) ?? activeEngineRunId();
     if (!runId)
         return;

package/dist/subagent/engineTaskHandleWire.js

@@ -57,6 +57,9 @@ import { STOP_CONFLICT_CODES, STOP_NOT_LANDED, STOP_NOT_LOCAL, STOP_PARKED, STOP
 /** 宿主 run 解析:fleet 行/通知帧喂的 parent 映射优先(行 id=`${runId} ${handle}` 的 parentId
  *  投影),缺席退当前交互 run(register 时刻的活跃 run 即宿主——engineSide bash 行的出生形)。 */
 function resolveHostRun(handle) {
+    // 🔴 候裁([4000] Q3 / design-242 §5 Q3,#242 批 2 **刻意不动**):这条回落与 resume 腿的
+    //    `resolveOwnerRunId`(指名了行就诚实缺席)口径相反;统一口径是真行为翻面,候三端表态。
+    //    同族另两处:`engineSubagentTail.ts:tailEngineSubagent` / `engineSubagentOutput.ts`。
     return getBgParentRun(handle) ?? activeEngineRunId() ?? null;
 }
 // 游标累积(按 handle;进程内存态,与查看态生命周期同级——端重启即空,重读从引擎再取)

package/dist/subagentContentStore.d.ts

@@ -192,8 +192,56 @@ export interface BgTerminalFacts {
 }
 export declare function recordBgTerminalFacts(taskId: string, facts: BgTerminalFacts): void;
 export declare function getBgTerminalFacts(taskId: string): BgTerminalFacts | undefined;
-export declare function recordBgParentRun(taskId: string, runId: string): void;
+/** 一行子代的宿主记录。`sessionId` = 登记时刻那条流的会话(per-id 读面要拼 `?session=`)。 */
+export interface SubagentOwnerRecord {
+    /** 宿主引擎 run id(resume / subagentOutput / tail 三条读面寻址的第一段)。 */
+    runId: string;
+    /** 登记时的会话 id;缺席即不带 `?session=`(空串按「带了且不匹配」处理 = 404,恒不铸空串)。 */
+    sessionId?: string;
+}
+/**
+ * fleet 行帧 / bg 通知腿的登记口(既有两写点)。
+ * `sessionId` 是 #242 批 2 additive 补位:缺席则不落键(读面据此判「不带 `?session=`」)。
+ */
+export declare function recordBgParentRun(taskId: string, runId: string, sessionId?: string): void;
+/**
+ * 「这一行子代的宿主 run」统一登记口(**显式传值**,零推断,见本段头注)。
+ * `runId` 缺席/空串 ⇒ 什么都不记(宁可「不知道」也不记一个错的宿主);`taskId === runId`
+ * 的退化自指映射同样拒收(顶层 run 行不是任何人的子代)。
+ *
+ * 🔴 **`sessionId` 的缺席不覆盖在场**(合表的承重口径,#242 批 2 自查抓出):喂本表的三条腿里
+ *    **只有 tick 腿带 session**(它在开流时一次性捕获),fleet 行帧腿与 bg 通知腿都不带。合表前
+ *    两表各记各的,合表后若让「后到的无 session 写」直接盖掉整条记录,tick 捕获的会话就会被抹掉,
+ *    resume 退回「此刻的会话」—— 那正是对抗复审轮5 M1 要防的错组合(旧 runId + 新 sessionId ⇒
+ *    session-bound run 上 fail-closed 404)。
+ *    口径:**同一 `runId` 上缺席不覆盖在场**(带值的写照常赢);`runId` 真变了 ⇒ 旧 session 必须丢
+ *    (那是另一条宿主 run 的会话,留着就是错组合)。
+ */
+export declare function recordSubagentOwner(taskId: string, runId?: string, sessionId?: string): void;
+/**
+ * `task_progress` 腿的登记口(#242 批 2 ①:收编前本表**零 task_progress 腿**,已直证)。
+ *
+ * 一条帧进,认得就记,认不得就什么都不做(**绝不改帧**)。只认 `task_progress` —— 引擎侧子代的
+ * 累计 tick,带子代自己的 `taskId`。
+ *
+ * 🔴 **`ownerRunId` / `ownerSessionId` 必须由调用方显式喂**,本函数**不许**从
+ *    `activeEngineRunId()` 推断(壳 `subagentOwnerLedger.ts:20-22` 对抗复审轮3 H2 实撞的教训:
+ *    进程级值被并发 main/fork 流互相覆写 + 每个 query 的 finally 清空 ⇒ run A 的 tick 可能被
+ *    登记到 run B 名下,而错值比缺席更坏)。登记点必须在**持有 stream-local run id 的那个闭包**
+ *    里(壳 = `liveClient.ts` 的 `stampSubagentOwners`),把不可变的值传进来。
+ * 🔴 `ownerSessionId` 同理**开流时一次性捕获**,不逐帧现读:逐帧现读会让 `/clear`、resume、
+ *    会话切换之后晚到的旧流 tick 被登记成 `{旧 runId, 新 sessionId}`,这对组合去 resume 会带着
+ *    错 session 打旧 run,fail-closed 404。
+ */
+export declare function recordSubagentOwnerFromProgress(ev: unknown, ownerRunId?: string, ownerSessionId?: string): void;
 export declare function getBgParentRun(taskId: string): string | undefined;
+/**
+ * 整条宿主记录(runId + 登记时会话)。undefined = **诚实不知道**,调用方渲 no-run 出路 /
+ * 不渲入口 —— 绝不在这里回落成「此刻在飞的那条 run」([anchor-on-the-deciding-quantity])。
+ */
+export declare function getBgParentRunOwner(taskId: string | undefined): SubagentOwnerRecord | undefined;
+/** 测试钩:清宿主台账(module 级单例,同进程多组断言必须能清)。 */
+export declare function __resetSubagentOwnerLedgerForTests(): void;
 export declare function recordOwnEngineRun(runId: string): void;
 export declare function isOwnEngineRun(runId: string): boolean;
 /** Single consumer (the panel hook). Returns an unsubscribe. */