@sema-agent/client-core 0.2.0 → 0.4.0

package/dist/sseIdleTriage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sseIdleTriage.ts 逐字搬入(只 import SDK)。
+ */
+/**
+ * src/sema/sseIdleTriage.ts — turn-stream SSE idle-silence triage(TB2.0 反馈批 D · P0-2 壳半场,2026-07-15)。
+ *
+ * WHY: TB2.0 bench 真实案例 —— agent 长跑前台编译 ~9.5min,工具完成前壳侧 45s 空闲监测器
+ * (`@sema-agent/sdk` readSseFrames HEARTBEAT_GRACE_MS)命中 `SSE: no data for 45000ms (heartbeat
+ * silence)` → 整轮 rc=1 丢弃,引擎不知情继续跑完(access log 499)。分诊报告判决①修正段拍定:
+ * 壳侧独立可发 = S1(SDK grace 透传+typed SseIdleError,0.0.47 已发)+ S4(grace 旋钮)+
+ * S3 缩水版(engine-alive-idle 分诊,只改报错文案,不重连)。本模块 = S4 + S3 的共享件。
+ *
+ * S4 · SEMA_SSE_HEARTBEAT_GRACE_MS(settings.json `env` 块 → 1a-envseed → process.env,其它 wire
+ * 旋钮同一车道):整数毫秒,合法域 [5000, 600000];非法/缺省 = 不透传(SDK 默认 45s)——静默
+ * fail-soft,一个 settings typo 绝不 brick 任何 run(scenarioWire settings-lane 纪律)。
+ * ⚠️ 作用面 = 会话 turn 流(tasks.stream / liveClient)一条车道。SDK 控制通道(SSETransport.ts:21
+ * LIVENESS_TIMEOUT_MS=45s)自带重连+give-up 自愈,本旋钮【不】达那条车道——这不是全局 grace。
+ *
+ * S3 缩水版 · engine-alive-idle 分诊:liveClient 的 tasks.stream 包装 catch 到 SseIdleError 时,
+ * 先判 signal.aborted(用户中止契约先行,seamQuery.ts:1073——Esc 撕流绝不被分诊吞),再 GET
+ * `/health`(非 /healthz;server dist server.js:290)短超时探引擎活性:引擎死 → 原样抛(现行
+ * engine-down/not-restart 路径不变);引擎活 → 给同一错误对象打 engine-alive-idle 标记,
+ * seamQuery 的 tearVerdict 恢复腿据此渲染诚实分诊文案(engineAliveIdleContent)。
+ *
+ * 【本模块绝不重连】(判决①修正段圣旨,范围随 M2 精化):非 detach 车道上 tasks/stream 客户端
+ * 断连 = server onDisconnect ac.abort() 终止 run(anti token-burn by design),且该车道帧无 id
+ * 不可位置续传——空闲监测器抛出的那一刻 finally 已 cancel res.body,run 已被这次断连自身中止,
+ * 同 key in-flight 重放拿到的只是 aborted 结局。前台另有既有裁决:mid-turn 工具副作用非幂等,
+ * 绝不自动重发。引擎 E2(server ≥1.196 x-detach-on-disconnect,[854]①)已到货:headless `-p`
+ * detach 车道的 R1 换道重连 = 重连腿 M2,住在 headlessReconnectWire.ts(liveClient 管线最内层,
+ * 只在 detach 头已发出的流上武装);本模块保持「探活+打标,不重连」——交互 REPL 与一切非
+ * detach 车道的取消契约一根毛不动,M2 耗尽预算后判死文案也仍由这里的打标驱动。
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。整数毫秒。 */
+export declare const SSE_HEARTBEAT_GRACE_ENV = "SEMA_SSE_HEARTBEAT_GRACE_MS";
+/** 合法域下界:低于 5s 会把正常 token 间隙误判成静默。 */
+export declare const SSE_GRACE_MIN_MS = 5000;
+/** 合法域上界:10min——超过引擎自身各级 idle 顶,再长没有意义。 */
+export declare const SSE_GRACE_MAX_MS = 600000;
+/** SDK 默认(readSseFrames HEARTBEAT_GRACE_MS)——文案引用用,不在本模块生效。 */
+export declare const SDK_DEFAULT_GRACE_MS = 45000;
+/**
+ * S4 — resolve the turn-stream heartbeat grace override. Unset/empty → undefined(SDK 默认 45s,
+ * 不透传);非纯十进制整数 / 超出 [5000,600000] → undefined(静默落默认,fail-soft)。
+ */
+export declare function resolveSseHeartbeatGraceMs(env?: EnvLike): number | undefined;
+/** 给 SseIdleError 打 engine-alive-idle 标(引擎 /health 已确认活着)。返回同一对象。 */
+export declare function markEngineAliveIdle<E extends Error>(err: E): E;
+/**
+ * engine-alive-idle 判型:命中返回静默时长 elapsedMs(SseIdleError 0.0.47 自带;缺失兜 0),
+ * 未命中返回 undefined。seamQuery tearVerdict 腿与 headless `-p` 的 stderr 面共用。
+ */
+export declare function engineAliveIdleElapsedMs(err: unknown): number | undefined;
+/**
+ * SseIdleError 判型:instanceof 为主;双包风险(bundle 内外两份 SDK class identity 分叉)下
+ * name 兜底——name 由 SDK 构造器冻结为 'SseIdleError',非我方铸造。
+ */
+export declare function isSseIdleError(err: unknown): boolean;
+/**
+ * 引擎活性探针 — SDK probeHealth(GET `${baseUrl}/health`;端点是 /health 非 /healthz),默认 2s
+ * 预算,永不抛:alive = 200 且 status==='ok';非 2xx / 不可达 / 超时 = not alive(引擎死 → 现行
+ * 失败路径,分诊绝不让真死引擎空等)。与 engineUpgradeCoordinator 的 classifyStreamTear 同款姿势。
+ * SDK 宪法迁移批差分记账:原实现只看 res.ok(200 非 JSON / status!=='ok' 也判活);SDK 额外要
+ * status==='ok'——service /health 200 恒报 status:'ok',契约面等价,对「200 但引擎自述非 ok」的
+ * 病态更严格诚实。
+ */
+export declare function probeEngineAlive(baseUrl: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * S3 缩水版 — the tasks.stream diagnose wrapper(liveClient 出口整流罩)。
+ * 透传 inner 的每个事件;仅当 inner 以 SseIdleError 收场时介入:
+ *   1. signal.aborted 先行 — 用户中止(Esc)撕流原样抛,绝不探活/绝不改判(seamQuery.ts:1073 契约);
+ *   2. GET /health 探引擎活性(2s 预算);
+ *   3. 引擎活 → 同一错误对象打 engine-alive-idle 标后重抛(下游 tearVerdict 腿改文案;detach `-p`
+ *      车道的 R1 重连发生在更内层的 headlessReconnectWire——错误能到这里 = 重连已耗尽/不可换道);
+ *      引擎死/探测失败 → 原样重抛(现行 classifyStreamTear 会诚实判 engine-down)。
+ * 非 SseIdleError 一律原样穿透。
+ */
+export declare function diagnoseSseIdleTear<T>(inner: AsyncGenerator<T>, baseUrl: string, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * engine-alive-idle 的用户可见分诊文案(升级自裸 "API Error: SSE: no data for …" 行)。
+ * 措辞如实(判决②契约),按 detach 态分叉:
+ *  · 非 detach(默认/旋钮关/版本门拒/交互车道):tasks/stream 断连 = server 端 abort 这次 run——
+ *    不许说"任务仍在继续"的安慰话;能给的出路只有 grace 旋钮 + 手动重发。字节与批 D 发运稿一致
+ *    (存量脚本可能 grep)。
+ *  · detach 态(重连腿 M1,`x-detach-on-disconnect: true` 已随首次 POST 发出,server ≥1.196):
+ *    断连【不再】abort run——run 已 detach,引擎会把它后台跑完并落 durable 账本;文案如实改述并
+ *    指 `GET /v1/runs/<id>`(taskId 已知时带上)/ `sema resume` 查终局。M1 不重连(M2/M3),
+ *    本轮前台 rc 仍非零——这是净改善:结果不再整轮丢弃。
+ */
+export declare function engineAliveIdleContent(elapsedMs: number, detach?: {
+    detached: true;
+    taskId?: string;
+}): string;

package/dist/sseIdleTriage.js

@@ -0,0 +1,142 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sseIdleTriage.ts 逐字搬入(只 import SDK)。
+ */
+/**
+ * src/sema/sseIdleTriage.ts — turn-stream SSE idle-silence triage(TB2.0 反馈批 D · P0-2 壳半场,2026-07-15)。
+ *
+ * WHY: TB2.0 bench 真实案例 —— agent 长跑前台编译 ~9.5min,工具完成前壳侧 45s 空闲监测器
+ * (`@sema-agent/sdk` readSseFrames HEARTBEAT_GRACE_MS)命中 `SSE: no data for 45000ms (heartbeat
+ * silence)` → 整轮 rc=1 丢弃,引擎不知情继续跑完(access log 499)。分诊报告判决①修正段拍定:
+ * 壳侧独立可发 = S1(SDK grace 透传+typed SseIdleError,0.0.47 已发)+ S4(grace 旋钮)+
+ * S3 缩水版(engine-alive-idle 分诊,只改报错文案,不重连)。本模块 = S4 + S3 的共享件。
+ *
+ * S4 · SEMA_SSE_HEARTBEAT_GRACE_MS(settings.json `env` 块 → 1a-envseed → process.env,其它 wire
+ * 旋钮同一车道):整数毫秒,合法域 [5000, 600000];非法/缺省 = 不透传(SDK 默认 45s)——静默
+ * fail-soft,一个 settings typo 绝不 brick 任何 run(scenarioWire settings-lane 纪律)。
+ * ⚠️ 作用面 = 会话 turn 流(tasks.stream / liveClient)一条车道。SDK 控制通道(SSETransport.ts:21
+ * LIVENESS_TIMEOUT_MS=45s)自带重连+give-up 自愈,本旋钮【不】达那条车道——这不是全局 grace。
+ *
+ * S3 缩水版 · engine-alive-idle 分诊:liveClient 的 tasks.stream 包装 catch 到 SseIdleError 时,
+ * 先判 signal.aborted(用户中止契约先行,seamQuery.ts:1073——Esc 撕流绝不被分诊吞),再 GET
+ * `/health`(非 /healthz;server dist server.js:290)短超时探引擎活性:引擎死 → 原样抛(现行
+ * engine-down/not-restart 路径不变);引擎活 → 给同一错误对象打 engine-alive-idle 标记,
+ * seamQuery 的 tearVerdict 恢复腿据此渲染诚实分诊文案(engineAliveIdleContent)。
+ *
+ * 【本模块绝不重连】(判决①修正段圣旨,范围随 M2 精化):非 detach 车道上 tasks/stream 客户端
+ * 断连 = server onDisconnect ac.abort() 终止 run(anti token-burn by design),且该车道帧无 id
+ * 不可位置续传——空闲监测器抛出的那一刻 finally 已 cancel res.body,run 已被这次断连自身中止,
+ * 同 key in-flight 重放拿到的只是 aborted 结局。前台另有既有裁决:mid-turn 工具副作用非幂等,
+ * 绝不自动重发。引擎 E2(server ≥1.196 x-detach-on-disconnect,[854]①)已到货:headless `-p`
+ * detach 车道的 R1 换道重连 = 重连腿 M2,住在 headlessReconnectWire.ts(liveClient 管线最内层,
+ * 只在 detach 头已发出的流上武装);本模块保持「探活+打标,不重连」——交互 REPL 与一切非
+ * detach 车道的取消契约一根毛不动,M2 耗尽预算后判死文案也仍由这里的打标驱动。
+ */
+import { hostEnv } from './hostEnv.js';
+import { SseIdleError, probeHealth as sdkProbeHealth } from '@sema-agent/sdk';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。整数毫秒。 */
+export const SSE_HEARTBEAT_GRACE_ENV = 'SEMA_SSE_HEARTBEAT_GRACE_MS';
+/** 合法域下界:低于 5s 会把正常 token 间隙误判成静默。 */
+export const SSE_GRACE_MIN_MS = 5_000;
+/** 合法域上界:10min——超过引擎自身各级 idle 顶,再长没有意义。 */
+export const SSE_GRACE_MAX_MS = 600_000;
+/** SDK 默认(readSseFrames HEARTBEAT_GRACE_MS)——文案引用用,不在本模块生效。 */
+export const SDK_DEFAULT_GRACE_MS = 45_000;
+/**
+ * S4 — resolve the turn-stream heartbeat grace override. Unset/empty → undefined(SDK 默认 45s,
+ * 不透传);非纯十进制整数 / 超出 [5000,600000] → undefined(静默落默认,fail-soft)。
+ */
+export function resolveSseHeartbeatGraceMs(env = hostEnv()) {
+    const raw = env[SSE_HEARTBEAT_GRACE_ENV]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        return undefined; // 纯十进制整数——'45e3'/'45000.5'/'-1' 全部落默认
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n) || n < SSE_GRACE_MIN_MS || n > SSE_GRACE_MAX_MS)
+        return undefined;
+    return n;
+}
+/** 给 SseIdleError 打 engine-alive-idle 标(引擎 /health 已确认活着)。返回同一对象。 */
+export function markEngineAliveIdle(err) {
+    ;
+    err.semaTearVerdict = 'engine-alive-idle';
+    return err;
+}
+/**
+ * engine-alive-idle 判型:命中返回静默时长 elapsedMs(SseIdleError 0.0.47 自带;缺失兜 0),
+ * 未命中返回 undefined。seamQuery tearVerdict 腿与 headless `-p` 的 stderr 面共用。
+ */
+export function engineAliveIdleElapsedMs(err) {
+    const e = err;
+    if (!e || e.semaTearVerdict !== 'engine-alive-idle')
+        return undefined;
+    return typeof e.elapsedMs === 'number' && Number.isFinite(e.elapsedMs) ? e.elapsedMs : 0;
+}
+/**
+ * SseIdleError 判型:instanceof 为主;双包风险(bundle 内外两份 SDK class identity 分叉)下
+ * name 兜底——name 由 SDK 构造器冻结为 'SseIdleError',非我方铸造。
+ */
+export function isSseIdleError(err) {
+    if (err instanceof SseIdleError)
+        return true;
+    return err?.name === 'SseIdleError';
+}
+/**
+ * 引擎活性探针 — SDK probeHealth(GET `${baseUrl}/health`;端点是 /health 非 /healthz),默认 2s
+ * 预算,永不抛:alive = 200 且 status==='ok';非 2xx / 不可达 / 超时 = not alive(引擎死 → 现行
+ * 失败路径,分诊绝不让真死引擎空等)。与 engineUpgradeCoordinator 的 classifyStreamTear 同款姿势。
+ * SDK 宪法迁移批差分记账:原实现只看 res.ok(200 非 JSON / status!=='ok' 也判活);SDK 额外要
+ * status==='ok'——service /health 200 恒报 status:'ok',契约面等价,对「200 但引擎自述非 ok」的
+ * 病态更严格诚实。
+ */
+export async function probeEngineAlive(baseUrl, timeoutMs = 2_000) {
+    return (await sdkProbeHealth(baseUrl, timeoutMs)).alive;
+}
+/**
+ * S3 缩水版 — the tasks.stream diagnose wrapper(liveClient 出口整流罩)。
+ * 透传 inner 的每个事件;仅当 inner 以 SseIdleError 收场时介入:
+ *   1. signal.aborted 先行 — 用户中止(Esc)撕流原样抛,绝不探活/绝不改判(seamQuery.ts:1073 契约);
+ *   2. GET /health 探引擎活性(2s 预算);
+ *   3. 引擎活 → 同一错误对象打 engine-alive-idle 标后重抛(下游 tearVerdict 腿改文案;detach `-p`
+ *      车道的 R1 重连发生在更内层的 headlessReconnectWire——错误能到这里 = 重连已耗尽/不可换道);
+ *      引擎死/探测失败 → 原样重抛(现行 classifyStreamTear 会诚实判 engine-down)。
+ * 非 SseIdleError 一律原样穿透。
+ */
+export async function* diagnoseSseIdleTear(inner, baseUrl, signal) {
+    try {
+        yield* inner;
+    }
+    catch (err) {
+        if (!signal?.aborted && isSseIdleError(err) && (await probeEngineAlive(baseUrl))) {
+            throw markEngineAliveIdle(err);
+        }
+        throw err;
+    }
+}
+/**
+ * engine-alive-idle 的用户可见分诊文案(升级自裸 "API Error: SSE: no data for …" 行)。
+ * 措辞如实(判决②契约),按 detach 态分叉:
+ *  · 非 detach(默认/旋钮关/版本门拒/交互车道):tasks/stream 断连 = server 端 abort 这次 run——
+ *    不许说"任务仍在继续"的安慰话;能给的出路只有 grace 旋钮 + 手动重发。字节与批 D 发运稿一致
+ *    (存量脚本可能 grep)。
+ *  · detach 态(重连腿 M1,`x-detach-on-disconnect: true` 已随首次 POST 发出,server ≥1.196):
+ *    断连【不再】abort run——run 已 detach,引擎会把它后台跑完并落 durable 账本;文案如实改述并
+ *    指 `GET /v1/runs/<id>`(taskId 已知时带上)/ `sema resume` 查终局。M1 不重连(M2/M3),
+ *    本轮前台 rc 仍非零——这是净改善:结果不再整轮丢弃。
+ */
+export function engineAliveIdleContent(elapsedMs, detach) {
+    const secs = Math.max(1, Math.round((elapsedMs > 0 ? elapsedMs : SDK_DEFAULT_GRACE_MS) / 1000));
+    const graceTail = `If your tasks legitimately go quiet this long (e.g. a long build), raise the idle grace: set ${SSE_HEARTBEAT_GRACE_ENV} ` +
+        `(settings env, integer ms, ${SSE_GRACE_MIN_MS}-${SSE_GRACE_MAX_MS}; default ${SDK_DEFAULT_GRACE_MS}).`;
+    if (detach?.detached) {
+        const runRef = detach.taskId ? `GET /v1/runs/${detach.taskId}` : 'GET /v1/runs/<task-id>';
+        return (`The engine is still running, but this turn's event stream went silent for ${secs}s, so the connection was closed as idle. ` +
+            `This run was DETACHED (x-detach-on-disconnect): the disconnect did NOT abort it — the engine keeps running it to completion in the background ` +
+            `and records the outcome durably. Check the final result with \`${runRef}\` on the engine, or \`sema resume\` to pick the session back up. ` +
+            graceTail);
+    }
+    return (`The engine is still running, but this turn's event stream went silent for ${secs}s, so the connection was closed as idle — ` +
+        `and closing the stream aborts the run on the engine side (this turn did NOT finish; a long-running tool may have been killed mid-flight). ` +
+        graceTail +
+        ` The session is intact — resend the prompt to retry.`);
+}

package/dist/steering.d.ts

@@ -2,6 +2,10 @@
  * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
  * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
  *
+ * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
+ * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
+ * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
+ *
  * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
  * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
  * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:

package/dist/steering.js

@@ -2,6 +2,10 @@
  * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
  * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
  *
+ * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
+ * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
+ * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
+ *
  * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
  * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
  * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:

package/dist/subagentContentStore.d.ts

@@ -0,0 +1,131 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/subagentContentStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 module 级台账(tasks/parentToTask/ownEngineRuns/bgFacts)= 单实例语义:写方(seam adapter
+ * runStream 的子代内容分流 + liveClient 的 run_started own 台账)与读方(查看态/帧级 own 判别)
+ * 必须走**同一个模块实例**,否则 own 判别恒 false(帧级校验静默失效)。
+ */
+/**
+ * subagentContentStore — dep-free side-channel store for ENGINE subagent CONTENT events (C1 consumption,
+ * service 1.89 `forwardSubagentEvents` + core 1.219; blackboard [381]⑤/[383]③).
+ *
+ * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
+ * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * {taskId, parentToolCallId} (§E1 redact upstream; §E2 identity). The seam adapter (runStream.ts)
+ * DIVERTS those events here — they must never reach the main-transcript pipeline (a subagent's tokens
+ * rendering as the leader's text is the pollution failure mode).
+ *
+ * WHAT IT KEEPS (bounded, per task):
+ *   - a NEUTRAL item log: {kind:'text'|'thinking',text} | {kind:'tool',name,input,output,isError,id}
+ *     (ring-capped) — the 查看态 transcript backlog, so entering a running agent mid-flight still shows
+ *     history. Message SHAPES are built by the consumers (engineAgentView/chrome-agentprogress own the
+ *     CC message creators; this store stays dep-free like engineAgentPanelStore).
+ *   - live accumulation buffers (streaming text/thinking not yet segment-closed).
+ *   - taskId → parentToolCallId (the C2 steer target — service routes subagent steer by parentToolCallId).
+ *
+ * NOTIFY: coalesced (~250ms) per-task notify so a per-token delta storm never turns into per-token
+ * AppState writes; consumers pull a snapshot on notify.
+ */
+export type SubagentContentItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'thinking';
+    text: string;
+} | {
+    kind: 'tool';
+    id: string;
+    name: string;
+    input: unknown;
+    output?: string;
+    isError?: boolean;
+}
+/** local user echo (查看态 composer 插话) — rides in the item log so a full rebuild keeps it in order */
+ | {
+    kind: 'echo';
+    text: string;
+};
+export interface SubagentContentEvent {
+    type: 'text_delta' | 'reasoning_delta' | 'tool_start' | 'tool_end';
+    taskId: string;
+    parentToolCallId: string;
+    delta?: string;
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    output?: string;
+    isError?: boolean;
+}
+/** Register the parentToolCallId ↔ engine-taskId pair (from task_progress, which carries both).
+ *  Content parked under the parent key migrates to the canonical task key. */
+export declare function registerSubagentAlias(parentToolCallId: string, taskId: string): void;
+export declare function publishSubagentContentEvent(ev: SubagentContentEvent): void;
+/** 查看态 composer echo (C2 steer optimistic display) — segment-closes the buffers first so the echo
+ *  lands AFTER the text streamed before it. taskId may be unseen (row entered before any content):
+ *  parentToolCallId may then be unknown — pass '' and the steer path resolves the target separately. */
+export declare function pushSubagentLocalEcho(taskId: string, text: string): void;
+export interface SubagentContentSnapshot {
+    items: SubagentContentItem[];
+    /** streaming tails not yet segment-closed (render as the live trailing message) */
+    textBuf: string;
+    thinkBuf: string;
+}
+export declare function getSubagentContentSnapshot(taskId: string): SubagentContentSnapshot | null;
+/**
+ * 一个查看态转录槽位。`slot` = 稳定 key(消费端拿去当 message uuid —— 250ms 一次的重组不换 key);
+ * `live: true` = 尚未段闭合的流式尾巴(下一次段闭合后由同内容的真 item 接位)。
+ */
+export type SubagentViewSlot = {
+    kind: 'text';
+    slot: string;
+    text: string;
+    live?: true;
+} | {
+    kind: 'thinking';
+    slot: string;
+    text: string;
+    live?: true;
+} | {
+    kind: 'echo';
+    slot: string;
+    text: string;
+} | {
+    kind: 'tool';
+    slot: string;
+    id: string;
+    name: string;
+    input: unknown;
+    /** undefined = tool_start 已到、tool_end 未到(在飞工具:卡先上屏,结果就地补) */
+    output?: string;
+    isError?: boolean;
+};
+/**
+ * 把一个子代的内容账本投影成查看态渲染计划。
+ *
+ * [1568] 之前的形(壳侧 engineAgentView 里)有两处「等段闭合」:①遇到第一个未闭合工具就 break;
+ * ②textBuf/thinkBuf 完全不投影。实测(engine 1.275.0 真跑):数据面 ~23 帧/s 的 delta 连续到壳,
+ * 查看态却只在 tool 边界更新(进查看态后 6.0s 全空,之后每 5–15s 才动一次)。现形:在飞工具照投,
+ * 流式尾巴作为 live 槽投 —— 屏面粒度 = wire 粒度(store notify 已按 250ms 合并)。
+ */
+export declare function planSubagentViewSlots(taskId: string): SubagentViewSlot[];
+/** C2 steer target: the service routes subagent steer by the delegating tool call's id. */
+export declare function parentToolCallIdOf(taskId: string): string | undefined;
+/** Settle a task's streaming buffers (turn ended / run settled) so the snapshot is complete. */
+export declare function settleSubagentContent(taskId: string): void;
+export declare function clearSubagentContent(taskId: string): void;
+export interface BgTerminalFacts {
+    status: string;
+    summary?: string;
+    recentSteps?: Array<{
+        tool?: string;
+        target?: string;
+        outcome?: string;
+    }>;
+}
+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;
+export declare function getBgParentRun(taskId: string): string | undefined;
+export declare function recordOwnEngineRun(runId: string): void;
+export declare function isOwnEngineRun(runId: string): boolean;
+/** Single consumer (the panel hook). Returns an unsubscribe. */
+export declare function subscribeSubagentContent(fn: (taskId: string) => void): () => void;