@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/subagent/engineSubagentSteer.js

@@ -0,0 +1,68 @@
+/**
+ * ⇄ 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 { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+/** Steer a running engine subagent (target = its parentToolCallId, or agentName). */
+export async function steerEngineSubagent(target, text) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return { ok: false, reason: 'no-wire' };
+    const runId = activeEngineRunId();
+    if (!runId)
+        return { ok: false, reason: 'no-run' };
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return { ok: false, reason: 'no-wire' };
+    try {
+        // service 1.89 receipt shape: { note: "Message queued for delivery to <name> …", delivery, … }
+        const body = await client.runs.steerSubagent(runId, target, { content: text }, engineSessionParamSpread());
+        let receipt = 'Message queued for delivery at the next tool round.';
+        const copy = body?.note ?? body?.message;
+        if (typeof copy === 'string' && copy.length > 0)
+            receipt = copy;
+        return { ok: true, receipt };
+    }
+    catch (e) {
+        const status = e?.status;
+        if (typeof status === 'number') {
+            const detail = e instanceof Error ? e.message : String(e);
+            hostLog('debug', `engineSubagentSteer: ${status} ${detail.slice(0, 200)}`);
+            if (status === 409 || status === 404) {
+                return { ok: false, reason: 'not-running', detail };
+            }
+            return { ok: false, reason: 'error', detail: `${status}` };
+        }
+        hostLog('debug', `engineSubagentSteer: fetch failed ${String(e)}`);
+        return { ok: false, reason: 'error', detail: String(e) };
+    }
+}

package/dist/subagent/engineSubagentTail.d.ts

@@ -0,0 +1,40 @@
+/** 测试钩:清 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;
+/** tool_end.output 经 server redactDeep,原型不保 string——渲染面统一字符串化(对象走 JSON)。 */
+export declare function coerceOutput(v: unknown): string | undefined;
+/**
+ * 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

@@ -0,0 +1,241 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineSubagentTail.ts` 的**流消费半场**。
+ *
+ * ── 拆缝(T35/T36/T44 同一条原则:判定半场进包、执行半场留宿主)────────────────────────────────
+ * **进包**:caps 探测 · tail 台账(每 taskId 至多一条)· SSE 消费循环 · 帧 → subagentContentStore
+ *   的四条投影 · `coerceOutput` · settle 收口 · 诊断锚 · 两源互斥判别口 `isEngineSubagentTailActive`。
+ * **留宿主**:`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 ?? 活跃 run、无条件带 `?session=`(同 [1498]③ 纪律)。
+ * 一切失败 fail-soft:tail 断=回到占位行现状,绝不 throw。
+ */
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParam } from '../engineSessionParam.js';
+import { getBgParentRun, parentToolCallIdOf, publishSubagentContentEvent, settleSubagentContent, } from '../subagentContentStore.js';
+// ── caps 探测(true 固化 / false TTL / 失败不缓存)────────────────────────────────────────────
+const capByBase = new Map();
+const CAP_FALSE_RETRY_TTL_MS = 5 * 60_000;
+async function subagentStreamCapable(client, baseUrl, signal) {
+    const hit = capByBase.get(baseUrl);
+    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; // 探测失败不缓存(引擎瞬断):本次不开,下次再判
+    }
+}
+/** 测试钩:清 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;
+    return () => {
+        activitySink = prev;
+    };
+}
+/** tool_end.output 经 server redactDeep,原型不保 string——渲染面统一字符串化(对象走 JSON)。 */
+export function coerceOutput(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/**
+ * 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;
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return;
+    const runId = getBgParentRun(taskId) ?? activeEngineRunId();
+    if (!runId)
+        return;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return;
+    const ac = new AbortController();
+    activeTails.set(taskId, ac);
+    // [1568] 诊断锚(SEMA_DEBUG 才落盘,量有界:每条 tail 一行首帧 + 一行收尾统计)——查看态
+    // 「慢/稀疏」类报障必须能把【数据面到端】与【端渲染】分层归因,首帧时延是那条分界线。
+    const openedAt = Date.now();
+    let frames = 0;
+    let connectLogged = false;
+    let firstContentLogged = false;
+    void (async () => {
+        try {
+            if (!(await subagentStreamCapable(client, cfg.baseUrl, ac.signal)))
+                return;
+            const session = engineSessionParam();
+            // SDK 0.0.77 起 runs.subagentStream 有真型([1547]① 候发版即消费兑现)——宽形 cast 已撤。
+            const stream = client.runs.subagentStream(runId, taskId, {
+                signal: ac.signal,
+                ...(session ? { session } : {}),
+            });
+            hostLog('debug', `[subagent-tail] open ${taskId} via run ${runId}`);
+            const parentKey = () => parentToolCallIdOf(taskId) ?? taskId;
+            for await (const ev of stream) {
+                if (ac.signal.aborted)
+                    break;
+                if (!connectLogged) {
+                    connectLogged = true;
+                    // 连接分界线:meta 帧即到 = SSE 建连成功(与「子代此刻恰好在跑长工具、没内容可发」区分开)
+                    hostLog('debug', `[subagent-tail] ${taskId} stream connected +${Date.now() - openedAt}ms`);
+                }
+                if (ev.event !== 'forward')
+                    continue; // meta/heartbeat:连接语义帧,不进内容面
+                const d = ev.data;
+                const t = d.type;
+                frames += 1;
+                if (!firstContentLogged &&
+                    (t === 'text_delta' || t === 'reasoning_delta' || t === 'tool_start')) {
+                    firstContentLogged = true;
+                    hostLog('debug', `[subagent-tail] ${taskId} first content frame +${Date.now() - openedAt}ms (${String(t)})`);
+                }
+                if (t === 'text_delta' || t === 'reasoning_delta') {
+                    if (typeof d.delta === 'string' && d.delta.length > 0) {
+                        publishSubagentContentEvent({
+                            type: t,
+                            taskId,
+                            parentToolCallId: parentKey(),
+                            delta: d.delta,
+                        });
+                    }
+                }
+                else if (t === 'tool_start') {
+                    publishSubagentContentEvent({
+                        type: 'tool_start',
+                        taskId,
+                        parentToolCallId: parentKey(),
+                        ...(typeof d.toolCallId === 'string' ? { toolCallId: d.toolCallId } : {}),
+                        ...(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 });
+                    }
+                }
+                else if (t === 'tool_end') {
+                    const out = coerceOutput(d.output);
+                    publishSubagentContentEvent({
+                        type: 'tool_end',
+                        taskId,
+                        parentToolCallId: parentKey(),
+                        ...(typeof d.toolCallId === 'string' ? { toolCallId: d.toolCallId } : {}),
+                        ...(typeof d.toolName === 'string' ? { toolName: d.toolName } : {}),
+                        ...(out !== undefined ? { output: out } : {}),
+                        ...(d.isError === true ? { isError: true } : {}),
+                    });
+                }
+                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) {
+            if (!ac.signal.aborted) {
+                hostLog('debug', `[subagent-tail] ${taskId} torn: ${String(e).slice(0, 160)}`);
+            }
+        }
+        finally {
+            hostLog('debug', `[subagent-tail] ${taskId} closed after ${frames} content frame(s)`);
+            if (activeTails.get(taskId) === ac)
+                activeTails.delete(taskId);
+        }
+    })();
+}
+/** 关闭一个子代的 tail(幂等;查看态退出/终态/行消失时调)。 */
+export function stopEngineSubagentTail(taskId) {
+    const ac = activeTails.get(taskId);
+    if (!ac)
+        return;
+    activeTails.delete(taskId);
+    ac.abort();
+}
+/** 在飞判别([1543]① 重开路用):true = 该子代已有 tail 挂着。 */
+export function hasActiveSubagentTail(taskId) {
+    return activeTails.has(taskId);
+}
+/** 测试钩:在飞 tail 数。 */
+export function __activeTailCountForTests() {
+    return activeTails.size;
+}

package/dist/subagent/engineTaskHandleWire.d.ts

@@ -0,0 +1,90 @@
+export { engineTaskHandlesCapable } from './engineRowStopGate.js';
+export interface EngineTaskOutputResult {
+    /** 累积后的输出正文(游标两形兼容,见头注)。 */
+    content: string;
+    /** wire output 投影原样的常用位(UI 一律以这些 flags 为准,别解析 content 猜状态)。 */
+    status?: string;
+    stoppedBy?: string;
+    partialResult?: boolean;
+}
+/** 测试钩:清累积缓存。 */
+export declare function __resetTaskHandleWireForTests(): void;
+/**
+ * 读一个引擎侧任务句柄的输出(新面 A)。null = 读不到(无 wire / caps 缺 / 无宿主 run / 404
+ * 域外或已 reap / 网错)——调用方回落既有渲染(receipt/outputFile tail)。绝不 throw。
+ */
+export declare function fetchEngineTaskOutput(handle: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EngineTaskOutputResult | null>;
+/**
+ * [1505] 契约标记判别(头注):spool 全量 → 替换;cursor 增量 → append;无标记 → 保守
+ * append-if-changed(与上次逐字节相同视为幂等重读,不重复)。空 content 不动累积。
+ * 🔴 B6 提出成具名纯函数 —— 它是这条读面唯一会「把输出显示成两遍」的地方,值得被直接断言。
+ */
+export declare function mergeTaskOutput(prev: string, fresh: string): string;
+export type EngineTaskStopOutcome = 
+/** 200:停止动作完成(status = wire 终态照实;重复 stop 幂等)。 */
+{
+    ok: true;
+    status?: string;
+    stoppedBy?: string;
+}
+/** 409 stop.not_landed:kill 没落地,进程可能还在跑——UI 绝不能渲染成「已停止」。 */
+ | {
+    ok: false;
+    reason: 'not_landed';
+    detail?: string;
+}
+/** 409 stop.not_local(server 1.250+ durable 臂):任务在**别的实例**上还在跑,此处没有 kill
+ *  被尝试——「别处在跑,此处停不了」,非失败重试件([1518]§一)。UI 同样不翻行。 */
+ | {
+    ok: false;
+    reason: 'not_local';
+    detail?: string;
+}
+/** 409 stop.parked(server 1.263 parked 状态机):子代停在待审批检查点——不是在跑,也不该被
+ *  stop 杀(人先 /decide);409 stop.park_resume_won:复活赛跑输给了别处的 resume。两者 UI
+ *  都不翻行(fleet 行渲染词汇已由 coerceTaskStatus 映射 'awaiting approval')。 */
+ | {
+    ok: false;
+    reason: 'parked' | 'park_resume_won';
+    detail?: string;
+}
+/** 409 stop.park_arbiter_unreachable(core 1.397 三分,G13 补齐的第五形):仲裁店不可达 ⇒
+ *  **真相未知**(既不是「停了」也不是「没落地」)。UI 同样不翻行,但文案必须说「状态未知」——
+ *  塌进 not_landed 就是把「不知道」渲染成一个具体的失败原因。 */
+ | {
+    ok: false;
+    reason: 'park_arbiter_unreachable';
+    detail?: string;
+}
+/** 未知/未来 `stop.*` 码(开集 default)。不翻行;`detail` 带原文供诊断。 */
+ | {
+    ok: false;
+    reason: 'unknown_conflict';
+    detail?: string;
+} | {
+    ok: false;
+    reason: 'unavailable' | 'error';
+    detail?: string;
+};
+/**
+ * 🔴 **G13 删债(先红后绿)**:taskStop 的 409 冲突分类 —— 手抄 code 判 → typed
+ * `TaskStopConflictError`(SDK 把**任何** `stop.*` 前缀码映到该类,errors.js:277-278;
+ * SDK 自己的注释还点名了壳的手抄位置 `engineTaskHandleWire.ts:186-197`)。
+ *
+ * 手抄版的实际缺陷(pure 门先红实证):SDK 明列**五**形,手抄只认前四形 ⇒ 第五形
+ * `stop.park_arbiter_unreachable`(core 1.397 三分:仲裁店不可达 ⇒ **真相未知**)静默塌进
+ * `not_landed`。
+ * 🔴 后果方向先定正负号([anchor-on-the-deciding-quantity]):门控的量 = 「UI 翻不翻这一行」,
+ *    五形与 default **全都是不翻** ⇒ 这不是安全缺陷,是**诚实缺陷** —— 把「真相未知」渲染成
+ *    「kill 没落地」,用户与诊断双双被误导。所以修法是给第五形一个自己的名字,而不是调整门。
+ *
+ * 开集纪律:`switch` 留 `default`(未来新 `stop.*` 码落 `unknown_conflict`,照样不翻行、
+ * 照样带原始 `code`),绝不塌进任何一个已知形 —— 塌进去就等于替 server 编了一个它没说的原因。
+ */
+export declare function classifyTaskStopConflict(e: unknown): EngineTaskStopOutcome;
+/** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
+export declare function stopEngineTask(handle: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EngineTaskStopOutcome>;

package/dist/subagent/engineTaskHandleWire.js

@@ -0,0 +1,212 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineTaskHandleWire.ts` 整搬。
+ *
+ * 🔴 搬迁差分:`wireConfig()` → `engineWireTarget()`;`getActiveEngineTaskId()` →
+ *    `activeEngineRunId()`;`logForDebugging` → `hostLog`;`process.env.SEMA_DEBUG` 前置判
+ *    → `engineWireDebugEnabled()`。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineTaskHandleWire — CC TaskOutput/TaskStop 人侧对位的 wire 消费([1501] server 1.246.0 /
+ * SDK 0.0.67 提货)。
+ *
+ * Wire(两面都是出生即强制带 `?session=`,与 subagentOutput 同姿势;非阻塞、副本本地):
+ *   · 读:`GET  /v1/runs/:id/tasks/:handle/output?session=` → SDK `runs.taskOutput`
+ *   · 停:`POST /v1/runs/:id/tasks/:handle/stop?session=`   → SDK `runs.taskStop`
+ *   · :id = 宿主 run;:handle = canonical 句柄 ONLY(b… bash / m… monitor / a… agent)——
+ *     不收名字、不收 legacy shellId,传了就是 404;workflow(w…/wa…)恒 404(journal 是那边的
+ *     读面,永不打这里)。
+ *   · 能力门 = capabilities.taskHandles(engineCapsCache 通用缓存,[1501] 明令:用能力位判断,
+ *     别 trial-by-501/404)。老引擎(≤1.245)缺该键 → 两动词都回落 null/不可用,version-safe。
+ *
+ * 读面游标语义([1501]§一 + [1505] must-fix 修正,UI 必须按此做):是否「读即消费」取决于句柄
+ * 形态——spooled 腿全量可重读、GET 幂等;cursor-only 腿每次 GET 只出新字节、读走就没了。
+ * 两形判别用 **wire 契约自带标记**(server [1505] 钉版承诺稳定,变更走 CHANGELOG+黑板;core
+ * CC-verbatim 固定形):content 含 `--- stdout (full, re-readable) ---` = spool 全量形 → 整体
+ * 替换;含 `--- new stdout ---` = cursor 增量形 → append。初版的「前缀延展」启发式被 [1505]
+ * 否决——spool content 首行 `status: <displayStatus>` 在任务完成时刻从 running 翻 exited,
+ * 前缀检测恰在最常见时刻失败 → 全量被 append = 输出重复。无标记(极端/未知形)按保守形
+ * append-if-changed 处理;空 content 不动累积。绝不假设重拉能拿到同样字节。
+ *
+ * ⚠️ cursor-only 腿双消费者 caveat([1505]):同一 b* 句柄若同时被模型侧 TaskOutput 工具读,
+ * 两个消费者互抢增量(工具读走的字节本读面拿不到,反之亦然),端侧累积在该形下不保证完整;
+ * spool 腿(server 正常接线下的常态)无此问题。UI 在 cursor 形下不承诺完整性。
+ *
+ * 停面语义([1501]§二):**只有 200 算停了**;409 `stop.not_landed` = kill 没落地、进程可能
+ * 还在跑(UI 绝不能渲染成「已停止」);终态句柄重复 stop 幂等诚实(200,状态照实)。
+ *
+ * `?filter=` 禁用(带了=400):CC 的 filter 语义由调用方拿回 content 后本地做,本模块不透传。
+ */
+import { TaskStopConflictError } from '@sema-agent/sdk';
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireDebugEnabled, engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+import { getBgParentRun } from '../subagentContentStore.js';
+import { engineTaskHandlesCapable } from './engineRowStopGate.js';
+// 能力门同步读口:#98 起真源在零依赖叶 `engineRowStopGate`(批量停要同步分类,不能拉本模块的
+// SDK 图),这里原样 re-export,消费方不动。
+export { engineTaskHandlesCapable } from './engineRowStopGate.js';
+/** 宿主 run 解析:fleet 行/通知帧喂的 parent 映射优先(行 id=`${runId} ${handle}` 的 parentId
+ *  投影),缺席退当前交互 run(register 时刻的活跃 run 即宿主——engineSide bash 行的出生形)。 */
+function resolveHostRun(handle) {
+    return getBgParentRun(handle) ?? activeEngineRunId() ?? null;
+}
+// 游标累积(按 handle;进程内存态,与查看态生命周期同级——端重启即空,重读从引擎再取)
+const accumulated = new Map();
+/** 测试钩:清累积缓存。 */
+export function __resetTaskHandleWireForTests() {
+    accumulated.clear();
+}
+/**
+ * 读一个引擎侧任务句柄的输出(新面 A)。null = 读不到(无 wire / caps 缺 / 无宿主 run / 404
+ * 域外或已 reap / 网错)——调用方回落既有渲染(receipt/outputFile tail)。绝不 throw。
+ */
+export async function fetchEngineTaskOutput(handle, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg || !engineTaskHandlesCapable())
+        return null;
+    const runId = resolveHostRun(handle);
+    if (!runId)
+        return null;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return null;
+    try {
+        const r = await client.runs.taskOutput(runId, handle, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...engineSessionParamSpread(),
+        });
+        const fresh = typeof r?.content === 'string' ? r.content : '';
+        const prev = accumulated.get(handle) ?? '';
+        const merged = mergeTaskOutput(prev, fresh);
+        accumulated.set(handle, merged);
+        const out = r?.output ?? {};
+        if (engineWireDebugEnabled()) {
+            hostLog('debug', `[task-handle] output ${handle} via run ${runId}: ok fresh=${fresh.length}b merged=${merged.length}b status=${typeof out.status === 'string' ? out.status : '-'}`);
+        }
+        return {
+            content: merged,
+            ...(typeof out.status === 'string' ? { status: out.status } : {}),
+            ...(typeof out.stoppedBy === 'string' ? { stoppedBy: out.stoppedBy } : {}),
+            ...(out.partial_result === true ? { partialResult: true } : {}),
+        };
+    }
+    catch (e) {
+        const status = e?.status;
+        hostLog('debug', `[task-handle] output ${handle} via run ${runId}: ${typeof status === 'number' ? status : String(e).slice(0, 160)}`);
+        return null;
+    }
+}
+/**
+ * [1505] 契约标记判别(头注):spool 全量 → 替换;cursor 增量 → append;无标记 → 保守
+ * append-if-changed(与上次逐字节相同视为幂等重读,不重复)。空 content 不动累积。
+ * 🔴 B6 提出成具名纯函数 —— 它是这条读面唯一会「把输出显示成两遍」的地方,值得被直接断言。
+ */
+export function mergeTaskOutput(prev, fresh) {
+    if (fresh.length === 0)
+        return prev;
+    if (fresh.includes('--- stdout (full, re-readable) ---'))
+        return fresh;
+    if (fresh.includes('--- new stdout ---'))
+        return prev + fresh;
+    return fresh === prev ? prev : prev + fresh;
+}
+/**
+ * 🔴 **G13 删债(先红后绿)**:taskStop 的 409 冲突分类 —— 手抄 code 判 → typed
+ * `TaskStopConflictError`(SDK 把**任何** `stop.*` 前缀码映到该类,errors.js:277-278;
+ * SDK 自己的注释还点名了壳的手抄位置 `engineTaskHandleWire.ts:186-197`)。
+ *
+ * 手抄版的实际缺陷(pure 门先红实证):SDK 明列**五**形,手抄只认前四形 ⇒ 第五形
+ * `stop.park_arbiter_unreachable`(core 1.397 三分:仲裁店不可达 ⇒ **真相未知**)静默塌进
+ * `not_landed`。
+ * 🔴 后果方向先定正负号([anchor-on-the-deciding-quantity]):门控的量 = 「UI 翻不翻这一行」,
+ *    五形与 default **全都是不翻** ⇒ 这不是安全缺陷,是**诚实缺陷** —— 把「真相未知」渲染成
+ *    「kill 没落地」,用户与诊断双双被误导。所以修法是给第五形一个自己的名字,而不是调整门。
+ *
+ * 开集纪律:`switch` 留 `default`(未来新 `stop.*` 码落 `unknown_conflict`,照样不翻行、
+ * 照样带原始 `code`),绝不塌进任何一个已知形 —— 塌进去就等于替 server 编了一个它没说的原因。
+ */
+export function classifyTaskStopConflict(e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    const raw = e?.code;
+    // typed 优先:SDK ≥0.0.11x 恒给 TaskStopConflictError 且 `code` 是 errorCode 原文。
+    // 兜底(老 SDK / 非 typed 抛点):code 非串时从 message 里认字面 —— 与手抄版同姿势,只是
+    // 现在是**回落**而不是主判据。
+    const code = typeof raw === 'string'
+        ? raw
+        : (STOP_CONFLICT_CODES.find(c => detail.includes(c)) ?? '');
+    switch (code) {
+        case 'stop.not_local':
+            return { ok: false, reason: 'not_local', detail };
+        case 'stop.parked':
+            return { ok: false, reason: 'parked', detail };
+        case 'stop.park_resume_won':
+            return { ok: false, reason: 'park_resume_won', detail };
+        case 'stop.park_arbiter_unreachable':
+            return { ok: false, reason: 'park_arbiter_unreachable', detail };
+        case 'stop.not_landed':
+            return { ok: false, reason: 'not_landed', detail };
+        default:
+            // 开集:未知/未来 `stop.*`(以及 code 完全缺席的残破形)。诚实说「有冲突但我不认识它」,
+            // 不冒充 not_landed。UI 处置与其余五形相同(不翻行)。
+            return { ok: false, reason: 'unknown_conflict', detail };
+    }
+}
+/** 兜底字面认码用的已知集(顺序 = 长码优先,避免 `stop.parked` 抢走 `stop.park_resume_won`)。 */
+const STOP_CONFLICT_CODES = [
+    'stop.park_arbiter_unreachable',
+    'stop.park_resume_won',
+    'stop.not_landed',
+    'stop.not_local',
+    'stop.parked',
+];
+/** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
+export async function stopEngineTask(handle, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg || !engineTaskHandlesCapable())
+        return { ok: false, reason: 'unavailable' };
+    const runId = resolveHostRun(handle);
+    if (!runId)
+        return { ok: false, reason: 'unavailable', detail: 'no host run mapping' };
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return { ok: false, reason: 'unavailable' };
+    try {
+        const r = await client.runs.taskStop(runId, handle, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...engineSessionParamSpread(),
+        });
+        const out = r?.output ?? {};
+        if (engineWireDebugEnabled()) {
+            hostLog('debug', `[task-handle] stop ${handle} via run ${runId}: ok status=${typeof out.status === 'string' ? out.status : '-'} stoppedBy=${typeof out.stoppedBy === 'string' ? out.stoppedBy : '-'}`);
+        }
+        return {
+            ok: true,
+            ...(typeof out.status === 'string' ? { status: out.status } : {}),
+            ...(typeof out.stoppedBy === 'string' ? { stoppedBy: out.stoppedBy } : {}),
+        };
+    }
+    catch (e) {
+        const status = e?.status;
+        const detail = e instanceof Error ? e.message : String(e);
+        hostLog('debug', `[task-handle] stop ${handle} via run ${runId}: ${typeof status === 'number' ? status : detail.slice(0, 160)}`);
+        // [1521]F2 订正:server 文案句里不含 errorCode 字面(message 判恒 miss=死分形),而 SDK
+        // APIError.code 一直透 errorCode——锚 code(对文案措辞变化免疫),message 兜底保留。
+        // 🔴 G13:判别锚从 `status===409` 换成 **typed 类**(`TaskStopConflictError`)—— SDK 把任何
+        //   `stop.*` 码都映到它,以后 server 换 HTTP 码(或同码复用别的语义)时这条腿不会失灵;
+        //   status 判保留为兜底(老 SDK 不抛 typed 类时仍要认)。
+        if (e instanceof TaskStopConflictError || status === 409) {
+            return classifyTaskStopConflict(e);
+        }
+        return { ok: false, reason: 'error', detail };
+    }
+}