@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/subagent/engineCompactWire.js

@@ -0,0 +1,176 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineCompactWire.ts` 整搬。
+ *
+ * 🔴 搬迁差分:
+ *   · `wireConfig()`(六份手抄的**最后一份**,而且这一份已经多长了一行 principal 注释 ——
+ *     漂移的活样本)→ `engineWireTarget()`;
+ *   · `getActiveEngineTaskId()` → `activeEngineRunId()`(SessionPort);
+ *   · `logForDebugging` → `hostLog('debug', …)`;
+ *   · `setTimeout(...)+t.unref?.()` → `hostTimers()`(**本文件是 TimersPort 的第一个消费者**)。
+ *     🔴 端没装 TimersPort 的后果**说清楚**:两处延迟发射(404 单次重试 / bind 后 1.5s 发射)
+ *     会**整个不发生** —— `/compact` 在 idle armed 之后就再也不会真正打到引擎,而命令行显示的
+ *     还是 'armed'。这不是「少个定时器」,是一条静默失效的功能腿。所以缺 port 时留 debug 日志,
+ *     并且 `hostPortMisses()` 里能看见(端自检恒应为空)。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineCompactWire — manual /compact reaches the ENGINE (K-1c), not just the client projection.
+ *
+ * Problem (clay dogfood 07-03): in live mode `/compact` ran only the CLIENT-side compaction (the local
+ * message projection) — the engine session's context was never compacted, so the next turn still paid
+ * the full window.
+ *
+ * Engine contract (service server.ts:1874, core 1.156 `TaskStream.compact()`):
+ *   POST /v1/runs/:id/compact → 202; compaction runs at the next SAFE turn boundary and a
+ *   `compacted{trigger:"manual"}` event rides the run's OWN stream. The verb only applies to a run LIVE
+ *   on the replica — and `/compact` is typed while IDLE, when there is no live run. So the wire is
+ *   arm-then-fire:
+ *     - `/compact` mid-turn (active engine run bound)  → fire immediately against that run.
+ *     - `/compact` idle → arm a pending flag; the host's run_started bind (onEngineTaskBound) fires it
+ *       against the NEXT turn's run — the engine compacts at that turn's first safe boundary, exactly
+ *       the semantics CC users expect ("everything before this point is summarized").
+ *
+ * SDK 0.0.52 长出 runs.compact verb(SDK 宪法迁移批)—— raw fetch 退役,改走 AgentClient
+ * (engineWireSdk 工厂;baseUrl/token/principal 纪律与 live wire 同源)。Fire-and-forget + fail-soft
+ * 语义不变:409/501/网络错都只留 debug 日志,端侧投影压缩仍是可见结果。
+ * 迁移差分记账:①原 raw POST 无超时 → SDK 缺省 60s 预算(compact 是 202 即回的 arm verb,本地
+ * 口毫秒级,纯上界改善);②404 单次 2s 延迟重试(早 header bind 跑赢 run-row 持久化)逐字保留。
+ */
+import { hostLog, hostTimers } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+let pendingEngineCompact = false;
+/** Test/introspection hook. */
+export function isEngineCompactPending() {
+    return pendingEngineCompact;
+}
+/**
+ * [488] 定谳(2026-07-07 指纹探针,server 1.130.0):TOC 本地引擎(无 TiDB runStore)的
+ * manual-compact verb 是 BY-DESIGN 501(handler 第一道闸 `!deps.runStore → 501`,capabilities
+ * 也如实报 `manualCompact:false`)——之前端没消费这个 gate,verb 打过去 501 被 fire-and-forget
+ * 吞掉,引擎 session 从未压缩=「静默 no-op」的真机理。这里 lazy 探一次 /v1/capabilities 并缓存;
+ * false ⇒ requestEngineCompact 返回 'unsupported'(不再装作 armed/fired)。探测失败 fail-open
+ * (null=未知 ⇒ 保持旧行为发 verb,错误面不变)。
+ */
+let manualCompactCapable = null;
+let capabilitiesProbe = null;
+function probeManualCompactCapability() {
+    if (capabilitiesProbe)
+        return;
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return;
+    capabilitiesProbe = (async () => {
+        try {
+            // SDK 0.0.52 client.capabilities()(typed Capabilities.manualCompact)。5s 预算经 client
+            // timeoutMs(对抗复审 MED 原语义:hung engine 不 pin probe promise);非 2xx/网络错/超时 SDK
+            // 统一抛错 → 与原「non-200 也重试」同归 catch 置 null 允许后续重试。
+            const client = makeEngineWireClient({
+                baseUrl: cfg.baseUrl,
+                ...(cfg.token ? { token: cfg.token } : {}),
+                principal: cfg.principal,
+                timeoutMs: 5000,
+            });
+            if (!client) {
+                capabilitiesProbe = null;
+                return;
+            }
+            const caps = await client.capabilities();
+            if (typeof caps.manualCompact === 'boolean')
+                manualCompactCapable = caps.manualCompact;
+            else
+                capabilitiesProbe = null; // shape we don't understand — retry later
+        }
+        catch {
+            capabilitiesProbe = null; // non-2xx/network error/timeout: unknown stays fail-open, next call re-probes
+        }
+    })();
+}
+/** Test hook: reset the cached capability (fresh engine / respawn). */
+export function resetManualCompactCapability() {
+    manualCompactCapable = null;
+    capabilitiesProbe = null;
+}
+/**
+ * 延迟发射(`setTimeout` + `unref` 的 port 形)。缺 TimersPort ⇒ **不发射**并留日志 ——
+ * 静默 drop 会让 `/compact` 看起来 armed 了却永不落地(见文件头)。
+ */
+function deferFire(ms, fn, why) {
+    const timers = hostTimers();
+    if (!timers) {
+        hostLog('debug', `engineCompactWire: no TimersPort — ${why} 不会发射(端漏装 port,/compact 这条腿静默失效)`);
+        return;
+    }
+    timers.setTimer(ms, fn);
+}
+async function postCompact(taskId, retriesLeft = 1) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return;
+    // SDK runs.compact(0.0.52)——POST /v1/runs/:id/compact body {}(无 instructions 时与原 '{}' 逐字
+    // 同 wire);header 姿势 = Transport buildHeaders(Bearer 仅有 token 时 + x-agent-principal +
+    // content-type),与原手抄同三头。
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return;
+    try {
+        const ack = await client.runs.compact(taskId, engineSessionParamSpread());
+        hostLog('debug', `engineCompactWire: POST compact ${taskId} → ok${ack?.status ? ` (${ack.status})` : ''}`);
+    }
+    catch (e) {
+        const status = e?.status;
+        if (typeof status === 'number') {
+            hostLog('debug', `engineCompactWire: POST compact ${taskId} → ${status}`);
+            // 404 = the early header bind outran the run-row persist — one deferred retry covers it.
+            if (status === 404 && retriesLeft > 0) {
+                deferFire(2000, () => void postCompact(taskId, retriesLeft - 1), '404 单次重试');
+            }
+            return;
+        }
+        hostLog('debug', `engineCompactWire: compact fire failed (best-effort): ${String(e)}`);
+    }
+}
+/**
+ * The /compact command's live half. Mid-turn: fire now. Idle: arm for the next run bind.
+ * Returns what it did (for the command's display line / tests). No-op ('offline') without a live
+ * wire; 'unsupported' when the engine's capabilities said manualCompact:false ([488] TOC-local) —
+ * the client-side projection compaction still runs, but the ENGINE session context does not shrink.
+ */
+export function requestEngineCompact() {
+    if (!engineWireTarget())
+        return 'offline';
+    probeManualCompactCapability(); // lazy, cached; first call may still ride the old path (fail-open)
+    if (manualCompactCapable === false) {
+        hostLog('debug', 'engineCompactWire: engine capabilities report manualCompact:false — verb suppressed (TOC-local runStore-less engine, [488])');
+        return 'unsupported';
+    }
+    const taskId = activeEngineRunId();
+    if (taskId) {
+        void postCompact(taskId);
+        return 'fired';
+    }
+    pendingEngineCompact = true;
+    return 'armed';
+}
+/**
+ * host run_started hook: a new engine run just bound. If a manual compact is pending, fire it —
+ * the engine compacts at this turn's first safe boundary.
+ *
+ * Timing: the bind fires off the X-Task-Id RESPONSE HEADER — the earliest possible signal, which can
+ * precede the server's run-row persist (a straight POST here raced it to a 404 in the live harness).
+ * Compaction runs at the next safe TURN BOUNDARY anyway, so a short defer loses nothing; retry once
+ * more for slow persists. Both shots are best-effort (postCompact never throws).
+ */
+const BOUND_FIRE_DELAY_MS = 1500;
+export function onEngineTaskBound(taskId) {
+    probeManualCompactCapability(); // warm the capability cache off the first turn bind, before any /compact
+    if (!pendingEngineCompact)
+        return;
+    pendingEngineCompact = false;
+    deferFire(BOUND_FIRE_DELAY_MS, () => void postCompact(taskId), 'bind 后发射');
+}

package/dist/subagent/engineDelegatedPrompt.d.ts

@@ -0,0 +1,44 @@
+/** 记一个子代行的转录锚(幂等;server <1.278 永不调用 = 台账恒空,取件腿整条静默不动)。 */
+export declare function recordEngineTranscriptId(taskId: string, transcriptId: string): void;
+/** 读面(取件腿 + 测试)。 */
+export declare function getEngineTranscriptId(taskId: string): string | undefined;
+/** 测试钩:清台账 + 在飞记号。 */
+export declare function __resetEngineDelegatedPromptForTests(): void;
+/**
+ * content → 纯文本。tool_result 型正文返回 undefined —— 那是子代自己跑工具的回填,**不是**委派
+ * prompt(这条判别就是「别把子代自己的消息当委派 prompt」的落点)。
+ */
+export declare function delegatedPromptText(content: unknown): string | undefined;
+/**
+ * 从转录里挑出委派 prompt = **最后一条非 tool_result 的 user 消息**(倒扫)。
+ * 🔴 倒扫不是随手选的:fork 型子代的转录以**父会话历史**开头,正扫会拿到宿主自己的首轮提示
+ * (live pty 实测的错答案);全新子会话型只有一条 user 文本消息,倒扫结果与正扫相同。
+ */
+export declare function pickDelegatedPrompt(messages: readonly unknown[]): string | undefined;
+/** 读面注入点(离线测试用):替身返回转录窗口条目数组。 */
+type TranscriptWindowReader = (transcriptId: string) => Promise<readonly unknown[] | null>;
+export declare function __setTranscriptWindowReaderForTests(r: TranscriptWindowReader | null): void;
+/** `fetchDelegatedPrompt` 的结果 —— 三态,**端必须分得开**(见下面 outcome 的键注)。 */
+export interface DelegatedPromptFetch {
+    /** 挑到的委派 prompt;`undefined` = 没拿到(看 `outcome` 分清是哪种没拿到)。 */
+    prompt?: string;
+    /**
+     * · `'hit'`        —— 拿到了,端可以落状态。
+     * · `'skipped'`    —— 无转录锚 / 已有在飞 ⇒ 端什么都别做(不是失败)。
+     * · `'unreadable'` —— 压根没读到(无 wire / 构造失败 / throw)⇒ **记号已撤**,下次可重试。
+     * · `'absent'`     —— 读成功但转录里挑不出委派 user 消息 ⇒ **定论**,记号保留,不再重复打读面。
+     *
+     * 🔴 `unreadable` 与 `absent` 分开是复审穷举第 5 条:混成一个会把「一次性取件」变成
+     *    「每次进查看态都打一发 `GET /v1/sessions/:id`」。
+     */
+    outcome: 'hit' | 'skipped' | 'unreadable' | 'absent';
+}
+/**
+ * 取一个后台子代行的**委派 prompt**(判定半场:防抖 + 取锚 + 读转录 + 挑正文)。
+ * 幂等、fail-soft、绝不 throw。**不碰任何端状态** —— 落状态是端的事(见文件头拆缝说明)。
+ *
+ * 端侧用法(壳 `hydrateEngineAgentPrompt` shim):先自己判「这行是不是 local_agent、prompt 是不是
+ * 已经有了」,是才调本函数;拿到 `outcome==='hit'` 再 `setState`。
+ */
+export declare function fetchDelegatedPrompt(taskId: string): Promise<DelegatedPromptFetch>;
+export {};

package/dist/subagent/engineDelegatedPrompt.js

@@ -0,0 +1,205 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 + §2.5 拆缝表):cli `src/sema/engineDelegatedPrompt.ts` 的
+ *    **判定半场** —— 转录锚台账(module 级)+ 委派 prompt 挑选规则 + 转录窗口读面 + 在飞防抖。
+ *
+ * 留在 TUI(**执行半场**):`hydrateEngineAgentPrompt` 里对 `AppState.tasks[taskId]` 的
+ * `isLocalAgentTask` 判别 / `store.setState` 落 `prompt` / 查看态转录补插首条 user 消息 ——
+ * 那三件读写的是**端的任务状态形状**(`LocalAgentTaskState`),web/桌面各有各的形。
+ * 壳侧 shim 保留原函数名与签名,内部改成「调本包 `fetchDelegatedPrompt()` → 拿到串再 setState」。
+ *
+ * 🔴 **单实例纪律(这条是本文件搬迁的真正理由,不是顺手)**:`transcriptIdByTask` 是 module 级
+ *    Map,**写者 = `fleetLedger` 的行帧/通知帧消费臂**(`recordEngineTranscriptId`),
+ *    **读者 = 取件腿**。fleetLedger 已在本包内 ⇒ 台账若留在壳里就是「包写壳读」两份实例,
+ *    取件腿恒读空、Prompt 段恒留白,而两边代码看着都对
+ *    ([paired-mechanisms-must-share-premise] 同族失败形)。所以台账必须与写者同包。
+ *
+ * ── 以下为原文件的领域说明(逐字保留,它记着两条踩过的坑)────────────────────────────────────
+ *
+ * engineDelegatedPrompt — 后台子代**委派 prompt** 的取件腿(server 1.278.0 `transcriptId` 提货)。
+ *
+ * ── 缺陷形
+ *   后台子代行是行帧 lane(fleet stream)投影出来的,行帧上**没有** prompt —— 于是
+ *   `AsyncAgentDetailDialog` 的 `Prompt` 段恒空(row.prompt = '')。前台子代的 prompt 由
+ *   `task_progress` tick 的绑定臂晚绑,后台子代整跑零 tick(tick lane 根本没通道),所以那条腿
+ *   对它无效。
+ *
+ * ── 修法(不发明:server 1.278.0 在 fleet 行上加了 `transcriptId`)
+ *   `transcriptId` = core 铸的**子代 childSessionId**(core subagent.js:`transcriptId: child.sessionId`)。
+ *   它是**取件锚不是内容** —— 端凭它去 session 读面(`GET /v1/sessions/:id`,SDK
+ *   `sessions.get`)取转录,从里面挑出委派 prompt。
+ *
+ * 🔴 取哪一条 —— **最后一条非 tool_result 的 user 消息**,不是第一条(live 一手取证订正):
+ *   `fork` 型子代的 `child.sessionId` 是**父会话的 fork**(core subagent.js:1749
+ *   `forkTranscriptId = child.sessionId ?? forkedId`),转录里先是**父会话的全部历史**,委派
+ *   prompt 追加在 fork 点。所以「第一条 user 消息」拿到的是**宿主自己的首轮提示**——第一版就是
+ *   这么写的,live pty 实测拉回 6869 字符(委派 prompt 只有 ~330),典型的「看起来很合理的错答案」。
+ *   反过来,全新子会话型子代的转录里委派 prompt 是唯一一条 user 文本消息 —— 两种形状都满足
+ *   「最后一条非 tool_result 的 user 消息」,所以倒扫是同时正确的那一条规则。
+ *   (`tool_result` 型 user 条目 = 子代自己跑工具的回填,必须跳过。)
+ *   窗口取 `tail=N`(转录尾部)+ `blobCap`:委派 prompt 在尾部方向,而 `messages` 整段可以非常大。
+ *   诚实边界:子代被 steer 过(steerSubagent 注入 user 消息)时倒扫会拿到最新那条指令 —— 已记账,
+ *   wire 上没有「哪条是委派」的标,端不猜。
+ *
+ * 诚实边界:拉不到 / 没有 transcriptId / 读面 501/404 ⇒ **什么都不写**,Prompt 段维持留白。
+ * 绝不用「子代的首条输出」或行描述冒充委派 prompt(那是把一个看起来合理的错答案摆上屏)。
+ * 一切失败 fail-soft,绝不 throw。
+ */
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+/** 只拉转录**尾部**这么多条(委派 prompt 在尾部方向;见文件头的 fork 形状订正)。 */
+const TAIL_WINDOW = 200;
+/** 单条正文的上限:详情页自己还会截到 300 字符,这里只防拉回一个巨型 blob。 */
+const BLOB_CAP = 8 * 1024;
+// ── 转录锚台账(module-level:footer/REPL 谁重挂都不丢;写者=行帧消费臂)───────────────────────
+const transcriptIdByTask = new Map();
+/** 记一个子代行的转录锚(幂等;server <1.278 永不调用 = 台账恒空,取件腿整条静默不动)。 */
+export function recordEngineTranscriptId(taskId, transcriptId) {
+    if (!taskId || !transcriptId)
+        return;
+    transcriptIdByTask.set(taskId, transcriptId);
+}
+/** 读面(取件腿 + 测试)。 */
+export function getEngineTranscriptId(taskId) {
+    return transcriptIdByTask.get(taskId);
+}
+/** 测试钩:清台账 + 在飞记号。 */
+export function __resetEngineDelegatedPromptForTests() {
+    transcriptIdByTask.clear();
+    promptHydrateInFlight.clear();
+}
+/** 每 task 一次在飞防抖;拉不到即撤记号,下次进入查看态可重试(副本重启/瞬态 404)。 */
+const promptHydrateInFlight = new Set();
+/** 一条转录条目的 role(permissive:`role` 或 CC jsonl 形的 `type`)。 */
+function roleOf(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return undefined;
+    const e = entry;
+    if (typeof e.role === 'string')
+        return e.role;
+    if (typeof e.type === 'string')
+        return e.type;
+    // CC jsonl 形:{type:'user', message:{role:'user', content}}
+    if (typeof e.message === 'object' && e.message !== null) {
+        const m = e.message;
+        if (typeof m.role === 'string')
+            return m.role;
+    }
+    return undefined;
+}
+/** 一条转录条目的正文 content(permissive:直挂 或 嵌在 `message` 里)。 */
+function contentOf(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return undefined;
+    const e = entry;
+    if (e.content !== undefined)
+        return e.content;
+    if (typeof e.message === 'object' && e.message !== null) {
+        return e.message.content;
+    }
+    return undefined;
+}
+/**
+ * content → 纯文本。tool_result 型正文返回 undefined —— 那是子代自己跑工具的回填,**不是**委派
+ * prompt(这条判别就是「别把子代自己的消息当委派 prompt」的落点)。
+ */
+export function delegatedPromptText(content) {
+    if (typeof content === 'string')
+        return content.trim() || undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === 'string') {
+            parts.push(block);
+            continue;
+        }
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const b = block;
+        if (b.type === 'tool_result')
+            return undefined; // 子代自己的工具回填,不是委派 prompt
+        if (b.type === 'text' && typeof b.text === 'string')
+            parts.push(b.text);
+    }
+    const text = parts.join('\n').trim();
+    return text || undefined;
+}
+/**
+ * 从转录里挑出委派 prompt = **最后一条非 tool_result 的 user 消息**(倒扫)。
+ * 🔴 倒扫不是随手选的:fork 型子代的转录以**父会话历史**开头,正扫会拿到宿主自己的首轮提示
+ * (live pty 实测的错答案);全新子会话型只有一条 user 文本消息,倒扫结果与正扫相同。
+ */
+export function pickDelegatedPrompt(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const entry = messages[i];
+        if (roleOf(entry) !== 'user')
+            continue;
+        const text = delegatedPromptText(contentOf(entry));
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+let transcriptWindowReader = null;
+export function __setTranscriptWindowReaderForTests(r) {
+    transcriptWindowReader = r;
+}
+async function readTranscriptWindow(transcriptId) {
+    if (transcriptWindowReader)
+        return transcriptWindowReader(transcriptId);
+    // 🔴 B6:六份手抄 `wireConfig()` 收成 `engineWireTarget()`(env 读经 hostEnv,本包零 process)。
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return null;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return null;
+    // 窗口读:`tail=N` = 转录**尾部** N 条(server ≥1.162)。老引擎忽略 query 返回全量 ——
+    // 倒扫规则对全量同样正确,只是多传了点字节(行为等价)。
+    const rec = await client.sessions.get(transcriptId, {
+        tail: TAIL_WINDOW,
+        blobCap: BLOB_CAP,
+    });
+    const msgs = rec.messages;
+    return Array.isArray(msgs) ? msgs : null;
+}
+/**
+ * 取一个后台子代行的**委派 prompt**(判定半场:防抖 + 取锚 + 读转录 + 挑正文)。
+ * 幂等、fail-soft、绝不 throw。**不碰任何端状态** —— 落状态是端的事(见文件头拆缝说明)。
+ *
+ * 端侧用法(壳 `hydrateEngineAgentPrompt` shim):先自己判「这行是不是 local_agent、prompt 是不是
+ * 已经有了」,是才调本函数;拿到 `outcome==='hit'` 再 `setState`。
+ */
+export async function fetchDelegatedPrompt(taskId) {
+    if (promptHydrateInFlight.has(taskId))
+        return { outcome: 'skipped' };
+    const transcriptId = transcriptIdByTask.get(taskId);
+    if (!transcriptId)
+        return { outcome: 'skipped' };
+    promptHydrateInFlight.add(taskId);
+    let msgs = null;
+    try {
+        msgs = await readTranscriptWindow(transcriptId);
+    }
+    catch (e) {
+        promptHydrateInFlight.delete(taskId);
+        hostLog('debug', `[delegated-prompt] ${taskId} transcript ${transcriptId} read failed: ${String(e).slice(0, 160)}`);
+        return { outcome: 'unreadable' };
+    }
+    const prompt = msgs ? pickDelegatedPrompt(msgs) : undefined;
+    if (!prompt) {
+        if (msgs === null)
+            promptHydrateInFlight.delete(taskId);
+        hostLog('debug', `[delegated-prompt] ${taskId} transcript ${transcriptId}: ${msgs === null ? 'transcript unreadable (retryable)' : 'no delegated user message (final)'}`);
+        return { outcome: msgs === null ? 'unreadable' : 'absent' };
+    }
+    // 诊断锚(SEMA_DEBUG 才落盘):字符数 + 头 60 字符 —— 「拿到的到底是委派 prompt 还是
+    // fork 转录里宿主自己的首轮提示」只有看得见正文头才分得开(第一版倒在这上面)。
+    hostLog('debug', `[delegated-prompt] ${taskId} <- transcript ${transcriptId} (${prompt.length} chars) head=${JSON.stringify(prompt.slice(0, 60))}`);
+    return { prompt, outcome: 'hit' };
+}

package/dist/subagent/engineRowStopGate.d.ts

@@ -0,0 +1,18 @@
+/** 引擎 bridge 从 `task_progress` tick / fleet 行帧建的行(module-level:footer 重挂不丢归属)。 */
+export declare const engineOwnedRowIds: Set<string>;
+/** fleet 树 enter 时为「面板无行的 fleet 行」stub 出来的纯查看载体行。 */
+export declare const fleetViewStubRowIds: Set<string>;
+/** 这一行的真身在引擎里(本地 abortController 管不到它)。 */
+export declare function isEngineViewRow(taskId: string): boolean;
+/** 能力门同步读口(liveClient 构造期已 kick /v1/capabilities 进 engineCapsCache)。 */
+export declare function engineTaskHandlesCapable(): boolean;
+/**
+ * 停这一行**必须先拿到引擎回执**吗?
+ *
+ * true  ⇒ 行的执行者是引擎,端写 `killed` 是一句它没证实过的断言 —— 必须 `POST …/stop` 拿到 200
+ *         才翻;409 `stop.not_landed` / `stop.not_local` / `stop.parked` 一律保持原状(引擎里
+ *         可能还在跑),下一拍由行帧/`stopped-by` 归因 settle(黑板 [1754]③)。
+ * false ⇒ 行跑在本进程(CC 逐字形态),`abortController.abort()` 就是执行本身,端写 `killed`
+ *         按构造恒真 ⇒ 同步翻,与 CC 2.1.220 `UPd`(pretty220.js:507299)一字不差。
+ */
+export declare function engineRowNeedsStopConfirm(taskId: string): boolean;

package/dist/subagent/engineRowStopGate.js

@@ -0,0 +1,54 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineRowStopGate.ts` 整搬。
+ *    唯一差分 = `process.env.SEMA_LIVE_BASEURL` → `engineWireTarget()?.baseUrl`
+ *    (本包零 `process`;Node 宿主下 `hostEnv()` 返回的就是 `process.env` 同一对象 ⇒ 取值相同。
+ *    **超集**:非 Node 宿主可用 `installEngineWireTarget()` 显式装,此前那条腿恒 false)。
+ *
+ * 🔴 单实例纪律(本文件两个 module 级 Set 都是判据真源):
+ *   `engineOwnedRowIds` 写者 = 引擎 bridge 的 `task_progress` tick / fleet 行帧臂;
+ *   `fleetViewStubRowIds` 写者 = fleet 树 enter 的 stub 造行处;
+ *   读者 = 批量停/单行停的同步分诊。两份实例 ⇒ 分诊恒判「纯本地行」⇒ 引擎侧行被壳直接写
+ *   `killed` 而引擎里还在跑 = [1754]③ 那类「壳说了一句它没证实过的话」。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineRowStopGate — 「这一行是引擎侧的吗 / 停它要不要等引擎回执」的**同步**判别叶模块(#98)。
+ *
+ * 为什么单独一个叶模块:批量停(`ctrl+x ctrl+k` → `killAllRunningAgentTasks`)必须在**同步**
+ * 那一拍就把行分成两半 —— 纯本地行照 CC 逐字立刻翻 `killed`(CC 的 markNotified→kill 顺序不容
+ * 插入一个 await,否则 runner 自己的完成通知会抢在 markNotified 前面发出去),引擎侧行才走
+ * 「等 200 再翻」。而原先这两个判据分别住在 `engineAgentView`(拉 React/ink/transcript 全图)和
+ * `engineTaskHandleWire`(拉 SDK),`LocalAgentTask` 静态 import 任一都是循环依赖风险 —— 所以此前
+ * 只能 `await import(...)`,分类天然异步。把判据本身下沉成零依赖叶(只依赖同样零依赖的
+ * `engineCapsCache`),两边改成 re-export,判据单一真源不变,调用方拿到同步口。
+ *
+ * 🔴 语义与单行 `x`(BackgroundTasksDialog.killEngineAwareAgentTask)必须逐字一致:
+ *   引擎视图行 ∧ `capabilities.taskHandles` 在场 → 发真停止动词、**只有 200 才翻行**;
+ *   缺任一(老引擎 / 无 wire / 纯本地 AgentTool 行) → 回落旧行为(本地 abort 即真停,立即翻)。
+ */
+import { engineCapTrue } from '../engineCapsCache.js';
+import { engineWireTarget } from '../engineWireTarget.js';
+/** 引擎 bridge 从 `task_progress` tick / fleet 行帧建的行(module-level:footer 重挂不丢归属)。 */
+export const engineOwnedRowIds = new Set();
+/** fleet 树 enter 时为「面板无行的 fleet 行」stub 出来的纯查看载体行。 */
+export const fleetViewStubRowIds = new Set();
+/** 这一行的真身在引擎里(本地 abortController 管不到它)。 */
+export function isEngineViewRow(taskId) {
+    return engineOwnedRowIds.has(taskId) || fleetViewStubRowIds.has(taskId);
+}
+/** 能力门同步读口(liveClient 构造期已 kick /v1/capabilities 进 engineCapsCache)。 */
+export function engineTaskHandlesCapable() {
+    return engineCapTrue(engineWireTarget()?.baseUrl, 'taskHandles');
+}
+/**
+ * 停这一行**必须先拿到引擎回执**吗?
+ *
+ * true  ⇒ 行的执行者是引擎,端写 `killed` 是一句它没证实过的断言 —— 必须 `POST …/stop` 拿到 200
+ *         才翻;409 `stop.not_landed` / `stop.not_local` / `stop.parked` 一律保持原状(引擎里
+ *         可能还在跑),下一拍由行帧/`stopped-by` 归因 settle(黑板 [1754]③)。
+ * false ⇒ 行跑在本进程(CC 逐字形态),`abortController.abort()` 就是执行本身,端写 `killed`
+ *         按构造恒真 ⇒ 同步翻,与 CC 2.1.220 `UPd`(pretty220.js:507299)一字不差。
+ */
+export function engineRowNeedsStopConfirm(taskId) {
+    return isEngineViewRow(taskId) && engineTaskHandlesCapable();
+}

package/dist/subagent/engineSubagentOutput.d.ts

@@ -0,0 +1,15 @@
+/** 测试钩:清 caps 缓存。 */
+export declare function __resetSubagentOutputCapCacheForTests(): void;
+export interface EngineSubagentReport {
+    /** 子代最终 assistant 正文(server 对 running 态给状态文本——由 status 区分)。 */
+    content: string;
+    /** output.status 原样(completed/failed/killed/running…;undefined = wire 未带)。 */
+    status?: string;
+}
+/**
+ * 拉取一个后台子代的终报正文。null = 读不到(无 wire / caps 缺 / 404 域外或副本重启 / 网错)——
+ * 调用方回落 bg 事实渲染。绝不 throw。
+ */
+export declare function fetchEngineSubagentReport(taskId: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<EngineSubagentReport | null>;

package/dist/subagent/engineSubagentOutput.js

@@ -0,0 +1,98 @@
+/**
+ * ⇄ 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 { engineWireTarget } from '../engineWireTarget.js';
+import { getBgParentRun } from '../subagentContentStore.js';
+import { activeEngineRunId, engineSessionParam } from '../engineSessionParam.js';
+// ── caps 探测(true 固化 / false TTL / 失败不缓存)────────────────────────────────────────────
+const capByBase = new Map();
+const CAP_FALSE_RETRY_TTL_MS = 5 * 60_000;
+async function subagentOutputCapable(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.subagentOutput === true;
+        capByBase.set(baseUrl, { ok, at: Date.now() });
+        return ok;
+    }
+    catch {
+        return false; // 探测失败不缓存(引擎瞬断):本次回落,下次再判
+    }
+}
+/** 测试钩:清 caps 缓存。 */
+export function __resetSubagentOutputCapCacheForTests() {
+    capByBase.clear();
+}
+/**
+ * 拉取一个后台子代的终报正文。null = 读不到(无 wire / caps 缺 / 404 域外或副本重启 / 网错)——
+ * 调用方回落 bg 事实渲染。绝不 throw。
+ */
+export async function fetchEngineSubagentReport(taskId, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg)
+        return null;
+    const runId = getBgParentRun(taskId) ?? activeEngineRunId();
+    if (!runId)
+        return null;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return null;
+    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 回落,下次重试自然带上。
+        const session = engineSessionParam();
+        const r = await client.runs.subagentOutput(runId, taskId, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...(session ? { session } : {}),
+        });
+        const content = typeof r?.content === 'string' ? r.content : '';
+        if (!content.trim())
+            return null;
+        const status = typeof r?.output?.status === 'string' ? r.output.status : undefined;
+        return { content, ...(status !== undefined ? { status } : {}) };
+    }
+    catch (e) {
+        const status = e?.status;
+        hostLog('debug', `[subagent-output] ${taskId} via run ${runId}: ${typeof status === 'number' ? status : String(e).slice(0, 160)}`);
+        return null;
+    }
+}

package/dist/subagent/engineSubagentSteer.d.ts

@@ -0,0 +1,10 @@
+export type SubagentSteerOutcome = {
+    ok: true;
+    receipt: string;
+} | {
+    ok: false;
+    reason: 'no-wire' | 'no-run' | 'not-running' | 'error';
+    detail?: string;
+};
+/** Steer a running engine subagent (target = its parentToolCallId, or agentName). */
+export declare function steerEngineSubagent(target: string, text: string): Promise<SubagentSteerOutcome>;