@sema-agent/client-core 0.2.0 → 0.4.0

package/dist/engineAgentPanelStore.js

@@ -0,0 +1,93 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineAgentPanelStore.ts 逐字搬入(零 import;壳侧改 re-export)。
+ * 🔴 同 subagentContentStore:buffer/listener/residentTaskIds 是单实例语义,发布侧(bridge/fleet
+ * 投影)与订阅侧(chrome-agentprogress 的面板 hook)必须同实例,否则事件发进一个副本、面板订另一个。
+ */
+/**
+ * engineAgentPanelStore — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks, design/99 MF-10) to CC's CoordinatorTaskPanel (the footer live-agent panel).
+ *
+ * WHY A STORE (the retryStatusStore / liveQuestionStore pattern): the upstream bridge is a plain
+ * generator with no React/AppState access, while the panel reads `AppState.tasks` — so the bridge
+ * PUBLISHES neutral events here and a sema-owned hook inside chrome-agentprogress.tsx (already mounted
+ * under the footer) SUBSCRIBES and applies them to AppState via registerTask/updateTaskState. CC files
+ * stay verbatim; the AppState write side lives in the sema override that owns the panel.
+ *
+ * WHY THE PANEL (CC-187 parity): a local sync AgentTool renders an inline progress TRAIL from the
+ * subagent's real messages. An engine tick carries ONLY rollup numbers ({toolUses, totalTokens}) — the
+ * exact shape of CC's `AgentProgress` — and CC's own precedent for out-of-process agents (remote agent
+ * tasks) is the TASK PANEL + task-notification, not a synthetic inline trail. Faithful mapping, no
+ * fabricated subagent messages.
+ *
+ * Buffering: ticks published before the panel mounts are buffered (bounded) and replayed to the first
+ * subscriber, so early frames in a fast turn aren't lost to mount timing.
+ */
+// ── #6(frame-lane-matrix)session 常驻行台账 ─────────────────────────────────────────────────
+// 行寿命 ≠ turn 寿命:跨 turn 存活的 bg 子代行(tick 绑不到本 turn 开着的卡 = inert/unbound)不该被
+// turn 末防御 sweep(bridge settlePanelTasks(null) / seamQuery 'sweep' 事件)结成假 completed——一旦
+// 假结,消费端 tick 门(status!=='running' ⇒ return prev)会把后续真 tick 全丢,真终态(failed)也
+// 改不动(冻死)。台账 module-level(publisher=bridge 按绑定活性写;两个 sweep 消费点按它跳过;
+// 真终态通知(task_notification 帧 / enqueueBgChildNotification 合成)settle 时摘除)。
+const residentTaskIds = new Set();
+export function markEnginePanelTaskResident(taskId) {
+    residentTaskIds.add(taskId);
+}
+export function clearEnginePanelTaskResident(taskId) {
+    residentTaskIds.delete(taskId);
+}
+export function isEnginePanelTaskResident(taskId) {
+    return residentTaskIds.has(taskId);
+}
+const MAX_BUFFER = 200;
+let listener = null;
+const buffer = [];
+export function publishEngineAgentPanelEvent(ev) {
+    if (listener) {
+        try {
+            listener(ev);
+        }
+        catch {
+            // A consumer render error must never tear down the bridge's stream drain.
+        }
+        return;
+    }
+    // Buffered (panel not mounted yet / temporarily unmounted). Ticks COALESCE per taskId (only the
+    // latest rollup matters — usage is cumulative), so lifecycle events ('end'/'sweep') are never the
+    // ones squeezed out by a long unmount (adversarial review w0zwpa251 #4: dropping a buffered 'end'
+    // left a row running forever).
+    if (ev.kind === 'tick') {
+        const i = buffer.findIndex(b => b.kind === 'tick' && b.taskId === ev.taskId);
+        if (i >= 0) {
+            buffer[i] = ev;
+            return;
+        }
+    }
+    if (buffer.length < MAX_BUFFER)
+        buffer.push(ev);
+    else if (ev.kind !== 'tick') {
+        // Lifecycle events must survive a full buffer: evict the oldest tick to make room.
+        const i = buffer.findIndex(b => b.kind === 'tick');
+        if (i >= 0)
+            buffer.splice(i, 1);
+        buffer.push(ev);
+    }
+}
+/** Single consumer (the panel hook). Replays any buffered events, returns an unsubscribe. */
+export function subscribeEngineAgentPanel(fn) {
+    listener = fn;
+    if (buffer.length > 0) {
+        const pending = buffer.splice(0, buffer.length);
+        for (const ev of pending) {
+            try {
+                fn(ev);
+            }
+            catch {
+                // ignore — same guard as publish
+            }
+        }
+    }
+    return () => {
+        if (listener === fn)
+            listener = null;
+    };
+}

package/dist/engineCapsCache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineCapsCache.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 **本批刻意不做「三套 caps 缓存收编成一套」**(设计稿 §2.4.1-B 风险点 + census §2.4):收编是
+ * 行为改动,要单独一条测试与单独一批(B1 只搬现行为,不夹带)。selfKnowledge / sideChannel 的
+ * 两套单键探测仍在壳侧,记账给下一批。
+ */
+/**
+ * engineCapsCache — 引擎 /v1/capabilities 的通用 boot-kick 缓存(同步读口)。
+ *
+ * selfKnowledge/sideChannel 各自有单键探测(先行件,语义已钉测试);本模块是后续键的通用面
+ * (首个消费者:compactionModel,[1487]② server 1.243 接线的 cli 半场)。纪律同款:
+ *   · kick 幂等(in-flight 去重),绝不 throw;
+ *   · 判定固化;探测失败不缓存(引擎未起/瞬断 → 下次 kick 再判);
+ *   · 同步读口 boolean(未判 = false = 调用方回落,version-safe)。
+ * 与单键探测不同处:缓存整个 caps 对象(一次探测服务后续所有键),false 不设 TTL——本缓存随
+ * 每次 createLiveConversationClient 构造重 kick(引擎温切重启后新构造自然重探)。
+ */
+/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
+export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
+/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。 */
+export declare function engineCapTrue(baseUrl: string | undefined, key: string): boolean;
+/**
+ * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
+ *
+ * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
+ * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
+ * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
+ * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
+ */
+export declare function engineCapString(baseUrl: string | undefined, key: string): string | undefined;
+/** 测试钩子。 */
+export declare function __resetEngineCapsCacheForTests(): void;

package/dist/engineCapsCache.js

@@ -0,0 +1,64 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineCapsCache.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 **本批刻意不做「三套 caps 缓存收编成一套」**(设计稿 §2.4.1-B 风险点 + census §2.4):收编是
+ * 行为改动,要单独一条测试与单独一批(B1 只搬现行为,不夹带)。selfKnowledge / sideChannel 的
+ * 两套单键探测仍在壳侧,记账给下一批。
+ */
+/**
+ * engineCapsCache — 引擎 /v1/capabilities 的通用 boot-kick 缓存(同步读口)。
+ *
+ * selfKnowledge/sideChannel 各自有单键探测(先行件,语义已钉测试);本模块是后续键的通用面
+ * (首个消费者:compactionModel,[1487]② server 1.243 接线的 cli 半场)。纪律同款:
+ *   · kick 幂等(in-flight 去重),绝不 throw;
+ *   · 判定固化;探测失败不缓存(引擎未起/瞬断 → 下次 kick 再判);
+ *   · 同步读口 boolean(未判 = false = 调用方回落,version-safe)。
+ * 与单键探测不同处:缓存整个 caps 对象(一次探测服务后续所有键),false 不设 TTL——本缓存随
+ * 每次 createLiveConversationClient 构造重 kick(引擎温切重启后新构造自然重探)。
+ */
+const capsByBase = new Map();
+const inFlight = new Set();
+/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
+export function kickEngineCapsProbe(baseUrl, probe) {
+    if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
+        return;
+    inFlight.add(baseUrl);
+    void (async () => {
+        try {
+            const caps = await probe();
+            if (caps && typeof caps === 'object') {
+                capsByBase.set(baseUrl, caps);
+            }
+        }
+        catch {
+            // 失败不缓存:下次 kick 再判
+        }
+        finally {
+            inFlight.delete(baseUrl);
+        }
+    })();
+}
+/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。 */
+export function engineCapTrue(baseUrl, key) {
+    if (!baseUrl)
+        return false;
+    return capsByBase.get(baseUrl)?.[key] === true;
+}
+/**
+ * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
+ *
+ * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
+ * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
+ * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
+ * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
+ */
+export function engineCapString(baseUrl, key) {
+    if (!baseUrl)
+        return undefined;
+    const v = capsByBase.get(baseUrl)?.[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** 测试钩子。 */
+export function __resetEngineCapsCacheForTests() {
+    capsByBase.clear();
+    inFlight.clear();
+}

package/dist/engineInlineTaskStats.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineInlineTaskStats.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 单实例语义:写方 = bridge 的 task_progress tick,读方 = 行内 group 行的 useSyncExternalStore。
+ */
+/**
+ * engineInlineTaskStats — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks) to the INLINE transcript group row ("Running N agents…" / AgentProgressLine).
+ *
+ * WHY (clay dogfood 2026-07-03): in engine mode the shell AgentTool's call() never runs, so the inline
+ * group row's per-agent stats (tool uses / tokens) and status line — both computed from LOCAL
+ * ProgressMessages (overrides/agent.tsx calculateAgentStats / extractLastToolInfo) — stay frozen at
+ * `0 tool uses` / `Initializing…` for the whole run and after completion. The engine's `task_progress`
+ * ticks DO carry the rollup ({toolUses, totalTokens, durationMs}) and the bridge already binds each
+ * tick to its delegating tool_use card (bindTaskCard, P1② explicit parentToolCallId) — but only fed
+ * the FOOTER panel store. This store is the inline twin: keyed by the delegating tool_use id (cardId),
+ * latest cumulative tick per card, frozen on the card's close (tool_end) / turn-end sweep so the
+ * finished group row keeps the final values.
+ *
+ * Same pattern as engineAgentPanelStore (module-level, no React/AppState deps on the write side); the
+ * read side is a useSyncExternalStore hook inside the sema-owned AgentProgressLine override — a
+ * subscription, NOT a render-time map read, because the memoized transcript tree won't re-render on
+ * ticks by itself. Local (non-engine) AgentTool runs never write here, so the local path is untouched
+ * (fallback only consulted when the card id has an entry).
+ */
+export interface EngineInlineTaskStats {
+    /** Cumulative tool uses off the latest tick (frozen at settle). */
+    toolUses: number;
+    /** Cumulative tokens off the latest tick (frozen at settle). */
+    totalTokens: number;
+    /** Cumulative run duration off the latest tick — feeds the "Working…" status line. */
+    durationMs: number;
+    /** core 1.262.0 [558]B (service 1.154.0 wire) — the child's most recent tool intent as ONE human
+     *  line ("Bash npm test"), service-redacted. Replaces the generic "Working…" status line while the
+     *  card is live; absent on old engines ⇒ the status line is unchanged. */
+    currentAction?: string;
+    /** The card closed (tool_end or turn-end sweep): values above are final. */
+    done: boolean;
+    isError: boolean;
+}
+/** Bridge write side — latest cumulative tick for the card. No-op once the card settled (frozen finals). */
+export declare function publishEngineInlineTaskTick(cardId: string, tick: {
+    toolUses: number;
+    totalTokens: number;
+    durationMs: number;
+    currentAction?: string;
+}): void;
+/** Bridge write side — the delegating card closed: freeze the finals. Idempotent. */
+export declare function settleEngineInlineTaskStats(cardId: string, isError: boolean): void;
+/** Turn-end / abort sweep twin — settle every card still live (a subagent never emits a terminal tick). */
+export declare function settleAllEngineInlineTaskStats(): void;
+/** Read side — reference-stable snapshot per card (object replaced only on update). */
+export declare function getEngineInlineTaskStats(cardId: string): EngineInlineTaskStats | undefined;
+/**
+ * Read side, id-less — the SOLE live (un-settled) card's stats, or undefined when 0 or ≥2 are live.
+ *
+ * WHY (#64 B 面 pty 实测,2026-07-11): the SINGLE-card in-flight render path
+ * (overrides/agent.tsx renderToolUseProgressMessage, zero local progressMessages in engine mode)
+ * has NO toolUseID in scope — the CC Tool-interface method signature doesn't carry it, and the
+ * call-site wrapper (AssistantToolUseMessage.tsx) is CC-verbatim. Attribution without an id is only
+ * safe when it is unambiguous, so this returns the stats ONLY when exactly one live card exists
+ * (the adversarial-review posture of bindTaskCard: better honest-generic than bound wrong; with ≥2
+ * live engine subagents the row keeps today's Initializing…). Reference-stable (returns the same
+ * per-card snapshot object the keyed getter hands out).
+ */
+export declare function getSoleLiveEngineInlineTaskStats(): EngineInlineTaskStats | undefined;
+export declare function subscribeEngineInlineTaskStats(fn: () => void): () => void;

package/dist/engineInlineTaskStats.js

@@ -0,0 +1,97 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineInlineTaskStats.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 单实例语义:写方 = bridge 的 task_progress tick,读方 = 行内 group 行的 useSyncExternalStore。
+ */
+/**
+ * engineInlineTaskStats — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks) to the INLINE transcript group row ("Running N agents…" / AgentProgressLine).
+ *
+ * WHY (clay dogfood 2026-07-03): in engine mode the shell AgentTool's call() never runs, so the inline
+ * group row's per-agent stats (tool uses / tokens) and status line — both computed from LOCAL
+ * ProgressMessages (overrides/agent.tsx calculateAgentStats / extractLastToolInfo) — stay frozen at
+ * `0 tool uses` / `Initializing…` for the whole run and after completion. The engine's `task_progress`
+ * ticks DO carry the rollup ({toolUses, totalTokens, durationMs}) and the bridge already binds each
+ * tick to its delegating tool_use card (bindTaskCard, P1② explicit parentToolCallId) — but only fed
+ * the FOOTER panel store. This store is the inline twin: keyed by the delegating tool_use id (cardId),
+ * latest cumulative tick per card, frozen on the card's close (tool_end) / turn-end sweep so the
+ * finished group row keeps the final values.
+ *
+ * Same pattern as engineAgentPanelStore (module-level, no React/AppState deps on the write side); the
+ * read side is a useSyncExternalStore hook inside the sema-owned AgentProgressLine override — a
+ * subscription, NOT a render-time map read, because the memoized transcript tree won't re-render on
+ * ticks by itself. Local (non-engine) AgentTool runs never write here, so the local path is untouched
+ * (fallback only consulted when the card id has an entry).
+ */
+const statsByCardId = new Map();
+const listeners = new Set();
+function emit() {
+    for (const fn of listeners) {
+        try {
+            fn();
+        }
+        catch {
+            // a consumer render error must never disturb the bridge's stream drain
+        }
+    }
+}
+/** Bridge write side — latest cumulative tick for the card. No-op once the card settled (frozen finals). */
+export function publishEngineInlineTaskTick(cardId, tick) {
+    const prev = statsByCardId.get(cardId);
+    if (prev?.done)
+        return;
+    statsByCardId.set(cardId, { ...tick, done: false, isError: false });
+    emit();
+}
+/** Bridge write side — the delegating card closed: freeze the finals. Idempotent. */
+export function settleEngineInlineTaskStats(cardId, isError) {
+    const prev = statsByCardId.get(cardId);
+    if (!prev || prev.done)
+        return;
+    statsByCardId.set(cardId, { ...prev, done: true, isError });
+    emit();
+}
+/** Turn-end / abort sweep twin — settle every card still live (a subagent never emits a terminal tick). */
+export function settleAllEngineInlineTaskStats() {
+    let changed = false;
+    for (const [cardId, s] of statsByCardId) {
+        if (s.done)
+            continue;
+        statsByCardId.set(cardId, { ...s, done: true, isError: false });
+        changed = true;
+    }
+    if (changed)
+        emit();
+}
+/** Read side — reference-stable snapshot per card (object replaced only on update). */
+export function getEngineInlineTaskStats(cardId) {
+    return statsByCardId.get(cardId);
+}
+/**
+ * Read side, id-less — the SOLE live (un-settled) card's stats, or undefined when 0 or ≥2 are live.
+ *
+ * WHY (#64 B 面 pty 实测,2026-07-11): the SINGLE-card in-flight render path
+ * (overrides/agent.tsx renderToolUseProgressMessage, zero local progressMessages in engine mode)
+ * has NO toolUseID in scope — the CC Tool-interface method signature doesn't carry it, and the
+ * call-site wrapper (AssistantToolUseMessage.tsx) is CC-verbatim. Attribution without an id is only
+ * safe when it is unambiguous, so this returns the stats ONLY when exactly one live card exists
+ * (the adversarial-review posture of bindTaskCard: better honest-generic than bound wrong; with ≥2
+ * live engine subagents the row keeps today's Initializing…). Reference-stable (returns the same
+ * per-card snapshot object the keyed getter hands out).
+ */
+export function getSoleLiveEngineInlineTaskStats() {
+    let sole;
+    for (const s of statsByCardId.values()) {
+        if (s.done)
+            continue;
+        if (sole !== undefined)
+            return undefined; // ≥2 live — ambiguous, stay honest
+        sole = s;
+    }
+    return sole;
+}
+export function subscribeEngineInlineTaskStats(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}

package/dist/engineToolLabelStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineToolLabelStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/engineToolLabelStore.ts — core 工具**展示名**(`tool_start.label` / `tool_end.label`)的
+ * 壳侧侧信道(sema-owned 新文件,零 CC 基座改动)。
+ *
+ * 为什么是侧信道而不是把 label 留在 tool_use block 上(P0-2 的关键判断):
+ *   tool_use content block 会**进壳 transcript**(jsonl 持久 + /compact 时原样直发 provider)。
+ *   Anthropic/OpenAI 两侧对 tool_use block 都是严格形 `{type,id,name,input}`,多一个 `label` 键
+ *   = 400 invalid_request —— 这正是「件1 中断事故批 G」踩过的坑(裸对象 content 落 transcript,
+ *   /compact 直发 ark/volces 400)。所以 bridge 在渲染前把 label 从 block 上摘掉(同
+ *   eventId/parentToolCallId 待遇),存到这里,渲染面按 toolCallId 查。
+ *
+ * 消费面:components/messages/AssistantToolUseMessage.tsx 的 **unknown-tool fallback** ——
+ * 也只在那里消费。已注册工具(壳本地 registry 命中)的卡标题恒走 CC 的 `tool.userFacingName()`,
+ * 绝不被引擎 label 覆盖(CC 逐字对齐优先;core label 与 CC 的 MCP 卡形 `server - tool (MCP)` 不同形,
+ * 覆盖 = 制造分叉)。
+ *
+ * 今天的真实命中面(2026-07-26 直连钉版 core 1.416 实测):core 只在 `label !== name` 时才上 wire
+ * (runtask.js:1406),而唯一这样的一族是 **MCP 远端工具** —— `name = mcp__<server>__<tool>`、
+ * `label = <server>:<tool>`(core/mcp.js:902)。即:引擎侧连着、壳侧没连的那台 MCP server 的工具,
+ * 修前卡头是裸 `mcp__foo__bar`,修后是 core 的展示名 `foo:bar`。
+ *
+ * 生命周期:按 toolCallId 键的有界 Map(FIFO 淘汰),纯 chrome 数据,不持久、不回喂模型。
+ */
+/** 登记一个 tool call 的 core 展示名(空/非串忽略)。 */
+export declare function recordEngineToolLabel(toolCallId: unknown, label: unknown): void;
+/** 读一个 tool call 的 core 展示名(未登记 ⇒ undefined,调用方回落原有形状)。 */
+export declare function engineToolLabel(toolCallId: unknown): string | undefined;
+/** 测试用:清空台账。 */
+export declare function resetEngineToolLabels(): void;

package/dist/engineToolLabelStore.js

@@ -0,0 +1,55 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineToolLabelStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/engineToolLabelStore.ts — core 工具**展示名**(`tool_start.label` / `tool_end.label`)的
+ * 壳侧侧信道(sema-owned 新文件,零 CC 基座改动)。
+ *
+ * 为什么是侧信道而不是把 label 留在 tool_use block 上(P0-2 的关键判断):
+ *   tool_use content block 会**进壳 transcript**(jsonl 持久 + /compact 时原样直发 provider)。
+ *   Anthropic/OpenAI 两侧对 tool_use block 都是严格形 `{type,id,name,input}`,多一个 `label` 键
+ *   = 400 invalid_request —— 这正是「件1 中断事故批 G」踩过的坑(裸对象 content 落 transcript,
+ *   /compact 直发 ark/volces 400)。所以 bridge 在渲染前把 label 从 block 上摘掉(同
+ *   eventId/parentToolCallId 待遇),存到这里,渲染面按 toolCallId 查。
+ *
+ * 消费面:components/messages/AssistantToolUseMessage.tsx 的 **unknown-tool fallback** ——
+ * 也只在那里消费。已注册工具(壳本地 registry 命中)的卡标题恒走 CC 的 `tool.userFacingName()`,
+ * 绝不被引擎 label 覆盖(CC 逐字对齐优先;core label 与 CC 的 MCP 卡形 `server - tool (MCP)` 不同形,
+ * 覆盖 = 制造分叉)。
+ *
+ * 今天的真实命中面(2026-07-26 直连钉版 core 1.416 实测):core 只在 `label !== name` 时才上 wire
+ * (runtask.js:1406),而唯一这样的一族是 **MCP 远端工具** —— `name = mcp__<server>__<tool>`、
+ * `label = <server>:<tool>`(core/mcp.js:902)。即:引擎侧连着、壳侧没连的那台 MCP server 的工具,
+ * 修前卡头是裸 `mcp__foo__bar`,修后是 core 的展示名 `foo:bar`。
+ *
+ * 生命周期:按 toolCallId 键的有界 Map(FIFO 淘汰),纯 chrome 数据,不持久、不回喂模型。
+ */
+/** 上界:一个长会话里 tool call 无限增长,标签只是渲染辅助,超界按 FIFO 淘汰最旧的。 */
+const MAX_ENTRIES = 500;
+const labels = new Map();
+/** 登记一个 tool call 的 core 展示名(空/非串忽略)。 */
+export function recordEngineToolLabel(toolCallId, label) {
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0)
+        return;
+    if (typeof label !== 'string' || label.trim().length === 0)
+        return;
+    // 已有值不覆盖:tool_start 先到,tool_end 只是补位(两者同源同值)。
+    if (labels.has(toolCallId))
+        return;
+    if (labels.size >= MAX_ENTRIES) {
+        const oldest = labels.keys().next();
+        if (!oldest.done)
+            labels.delete(oldest.value);
+    }
+    labels.set(toolCallId, label.trim());
+}
+/** 读一个 tool call 的 core 展示名(未登记 ⇒ undefined,调用方回落原有形状)。 */
+export function engineToolLabel(toolCallId) {
+    if (typeof toolCallId !== 'string' || toolCallId.length === 0)
+        return undefined;
+    return labels.get(toolCallId);
+}
+/** 测试用:清空台账。 */
+export function resetEngineToolLabels() {
+    labels.clear();
+}

package/dist/engineWireSdk.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/engineWireSdk.ts 逐字搬入(纯半场 client 工厂;agentsWireCaps 的静态依赖,故同批过来)。
+ */
+/**
+ * engineWireSdk — SDK 宪法迁移批(0.0.52)的纯半场 client 工厂:壳内各 wire 子模块(compact/steer/
+ * plan-review/auto-title/recap/caps 探测)从手抄 raw fetch 改接 @sema-agent/sdk AgentClient 的共用
+ * 构造点。ZERO 产品依赖(只 import 外部零依赖 SDK)——agentsWireCaps/liveInitToolFace 等「纯半场/
+ * 零产品图」模块可安全 import,不拖 engineTarget 的 fs 图,亦无循环依赖。
+ *
+ * 凭证解析 = engineTarget.resolveLiveAuthToken 的逐字镜像(#118 三态;那边是产品半场真源,这里为
+ * 纯半场复刻,两处语义必须一致):
+ *   · token 有            → 原样 Bearer;
+ *   · 无 token ∧ loopback → { mode: 'loopback-unauthed' }(出站零 Authorization 头,绝不伪造);
+ *   · 无 token ∧ 非 loopback → 'anon'(fail-closed worker 换来诚实 401;与主车道 replEntry 同姿势)。
+ * ⚠️ 迁移差分记账:旧 raw fetch 在「无 token ∧ 非 loopback」时不带任何 Authorization 头;SDK 恒需
+ * 合法 authToken 形,这里按主车道姿势出 'anon'——该态本就是残破配置(connect 未登录),两种姿势对
+ * fail-closed worker 都是 401,对 owner-gated 路由都是 owner 不匹配,行为面等价。
+ *
+ * 缺省 maxRetries=0:raw fetch 原语义是单发不重试(探针有自己的预算窗;fire-and-forget 不该静默
+ * 翻倍打点)。要 SDK 缺省重试的调用方显式传。principal 缺省 'anon:shell-live'(replEntry live 车道
+ * 同款)——SDK Transport 恒 stamp x-agent-principal(principal-first 宪法);旧 raw fetch 在缺
+ * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
+ */
+import { AgentClient } from '@sema-agent/sdk';
+export type WireAuthToken = string | {
+    mode: 'loopback-unauthed';
+};
+/** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
+export declare function isLoopbackWireUrl(url: string): boolean;
+/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
+export declare function wireAuthTokenFor(baseUrl: string, token?: string): WireAuthToken;
+export type EngineWireClientConfig = {
+    baseUrl: string;
+    /** 真 token 串;缺省经 wireAuthTokenFor 三态解析(loopback-unauthed / 'anon')。 */
+    token?: string;
+    /** 缺省 'anon:shell-live'(replEntry live 车道同款)。 */
+    principal?: string;
+    /** 每次请求的超时预算(SDK 缺省 60s)。 */
+    timeoutMs?: number;
+    /** 缺省 0(raw fetch 单发语义);要 SDK 重试的调用方显式传。 */
+    maxRetries?: number;
+    /** 测试注入面(探针单测的 fetch stub)。 */
+    fetchImpl?: typeof fetch;
+};
+/**
+ * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
+ * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
+ */
+export declare function makeEngineWireClient(cfg: EngineWireClientConfig): AgentClient | null;

package/dist/engineWireSdk.js

@@ -0,0 +1,61 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/engineWireSdk.ts 逐字搬入(纯半场 client 工厂;agentsWireCaps 的静态依赖,故同批过来)。
+ */
+/**
+ * engineWireSdk — SDK 宪法迁移批(0.0.52)的纯半场 client 工厂:壳内各 wire 子模块(compact/steer/
+ * plan-review/auto-title/recap/caps 探测)从手抄 raw fetch 改接 @sema-agent/sdk AgentClient 的共用
+ * 构造点。ZERO 产品依赖(只 import 外部零依赖 SDK)——agentsWireCaps/liveInitToolFace 等「纯半场/
+ * 零产品图」模块可安全 import,不拖 engineTarget 的 fs 图,亦无循环依赖。
+ *
+ * 凭证解析 = engineTarget.resolveLiveAuthToken 的逐字镜像(#118 三态;那边是产品半场真源,这里为
+ * 纯半场复刻,两处语义必须一致):
+ *   · token 有            → 原样 Bearer;
+ *   · 无 token ∧ loopback → { mode: 'loopback-unauthed' }(出站零 Authorization 头,绝不伪造);
+ *   · 无 token ∧ 非 loopback → 'anon'(fail-closed worker 换来诚实 401;与主车道 replEntry 同姿势)。
+ * ⚠️ 迁移差分记账:旧 raw fetch 在「无 token ∧ 非 loopback」时不带任何 Authorization 头;SDK 恒需
+ * 合法 authToken 形,这里按主车道姿势出 'anon'——该态本就是残破配置(connect 未登录),两种姿势对
+ * fail-closed worker 都是 401,对 owner-gated 路由都是 owner 不匹配,行为面等价。
+ *
+ * 缺省 maxRetries=0:raw fetch 原语义是单发不重试(探针有自己的预算窗;fire-and-forget 不该静默
+ * 翻倍打点)。要 SDK 缺省重试的调用方显式传。principal 缺省 'anon:shell-live'(replEntry live 车道
+ * 同款)——SDK Transport 恒 stamp x-agent-principal(principal-first 宪法);旧 raw fetch 在缺
+ * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
+ */
+import { AgentClient } from '@sema-agent/sdk';
+/** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
+export function isLoopbackWireUrl(url) {
+    try {
+        const h = new URL(url).hostname;
+        return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
+export function wireAuthTokenFor(baseUrl, token) {
+    if (token)
+        return token;
+    if (isLoopbackWireUrl(baseUrl))
+        return { mode: 'loopback-unauthed' };
+    return 'anon';
+}
+/**
+ * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
+ * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
+ */
+export function makeEngineWireClient(cfg) {
+    try {
+        return new AgentClient({
+            baseUrl: cfg.baseUrl,
+            authToken: wireAuthTokenFor(cfg.baseUrl, cfg.token),
+            principal: cfg.principal ?? 'anon:shell-live',
+            ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
+            maxRetries: cfg.maxRetries ?? 0,
+            ...(cfg.fetchImpl ? { fetch: cfg.fetchImpl } : {}),
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/fleetAgentPanelProjection.d.ts

@@ -0,0 +1,31 @@
+/** 行帧投影后的最小 agent 行形(fleet-tree 的 FleetTask 是它的超集)。 */
+export interface FleetAgentRowLike {
+    id: string;
+    /** fleet 行 label 列 = agent identity(agentName ?? agentType),如 'fork'。 */
+    name?: string;
+    /** fleet 行描述列 = 任务描述,如 'alpha-probe'(面板行 label 用它)。 */
+    description?: string;
+    status?: string;
+    tokens?: number;
+    /** server 1.278.0 `toolUses` —— 子代**累计**工具调用数。🔴 三态:有键真值(含真 0)/无键
+     *  `undefined`=老引擎不知道。绝不在本层 `?? 0`(那等于把「不知道」冒充成「跑了 0 个」)。 */
+    toolUses?: number;
+    /** server 1.278.0 `transcriptId`(子代 childSessionId)—— 委派 prompt 的取件锚,不是 prompt 本身。 */
+    transcriptId?: string;
+    /** server 1.288.0 / core 1.429.0([1831]②)—— 子代当前工具的结构化形。缺席=旧端或从未跑过工具。 */
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
+}
+/** 行从投影集消失多久之后按 completed 兜底 settle(重连空窗 / snapshot 清表远小于此)。 */
+export declare const ABSENT_SETTLE_MS = 30000;
+/** 测试钩:清投影台账。 */
+export declare function resetFleetAgentPanelProjection(): void;
+/** 台账读面(测试/诊断):当前记着的行数。 */
+export declare function fleetAgentProjectionSize(): number;
+/**
+ * 把一次 fleet 投影(已经过 own 判别 + workflow belt 的 FleetTask[])喂给面板事件流。
+ * 幂等、无副作用地重复调用安全 —— 每秒被 footer 调用两次就是常态。
+ */
+export declare function projectFleetAgentRows(rows: readonly FleetAgentRowLike[], nowMs?: number): void;

package/dist/fleetTaskDesc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/fleetTaskDesc.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/fleetTaskDesc.ts — footer fleet 行「label/描述列」纯投影助手(零依赖,从 fleetClient.ts 提出
+ * 供单测直取——fleetClient 拖 SDK/appState/notification 重图,无法轻量 bundle;行为与提出前逐字同源)。
+ */
+/** collapse a wire label to a single trimmed line (drops embedded newlines/runs). 187 row labels are always
+ *  one short line; the <FleetTree/> column (Math.min(28,…) + wrap="truncate") does the visible ellipsis, so we
+ *  only normalize here — no double-ellipsis, faithful to the 187 render. */
+export declare function collapseLabel(s: string): string;
+/** CC row-body fallback(CC 真身锚 2026-07-20 人类剧本帧:`◯ general-purpose  t1calc`——row body 从第一帧
+ *  起就是 Agent 工具的 description)。引擎子行帧不带 `description` 字段,任务描述只在 `name` 里,且有两形
+ *  (07-24 D2 wire 实证,engine 1.271.0 帧 dump):
+ *    ① 出生帧:name = `${agentType}: ${description}` 合成形(如 "fork: t1calc")→ 剥前缀复原;
+ *    ② 后续帧:引擎把 name 重写为【裸任务描述】(如 "t1calc",无前缀)→ 直接按描述投影——
+ *      修前只认①,②一到描述列即塌空(footer 只剩 `◯ fork`,D2 症状)。
+ *  防重复列 belt:裸 name 恰为 identity 回声(=agentType 或 =agentName)时不当描述(label 列已渲它)。
+ *  纯投影非双源;真进度(last tool name)到帧后仍然优先(调用侧 projectDescription 先行)。 */
+export declare function taskDescFromName(name: string | undefined, agentType: string | undefined, agentName?: string): string;

package/dist/fleetTaskDesc.js

@@ -0,0 +1,35 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/fleetTaskDesc.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ */
+/**
+ * src/sema/fleetTaskDesc.ts — footer fleet 行「label/描述列」纯投影助手(零依赖,从 fleetClient.ts 提出
+ * 供单测直取——fleetClient 拖 SDK/appState/notification 重图,无法轻量 bundle;行为与提出前逐字同源)。
+ */
+/** collapse a wire label to a single trimmed line (drops embedded newlines/runs). 187 row labels are always
+ *  one short line; the <FleetTree/> column (Math.min(28,…) + wrap="truncate") does the visible ellipsis, so we
+ *  only normalize here — no double-ellipsis, faithful to the 187 render. */
+export function collapseLabel(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/** CC row-body fallback(CC 真身锚 2026-07-20 人类剧本帧:`◯ general-purpose  t1calc`——row body 从第一帧
+ *  起就是 Agent 工具的 description)。引擎子行帧不带 `description` 字段,任务描述只在 `name` 里,且有两形
+ *  (07-24 D2 wire 实证,engine 1.271.0 帧 dump):
+ *    ① 出生帧:name = `${agentType}: ${description}` 合成形(如 "fork: t1calc")→ 剥前缀复原;
+ *    ② 后续帧:引擎把 name 重写为【裸任务描述】(如 "t1calc",无前缀)→ 直接按描述投影——
+ *      修前只认①,②一到描述列即塌空(footer 只剩 `◯ fork`,D2 症状)。
+ *  防重复列 belt:裸 name 恰为 identity 回声(=agentType 或 =agentName)时不当描述(label 列已渲它)。
+ *  纯投影非双源;真进度(last tool name)到帧后仍然优先(调用侧 projectDescription 先行)。 */
+export function taskDescFromName(name, agentType, agentName) {
+    if (!name || !agentType)
+        return '';
+    const prefix = `${agentType}: `;
+    if (name.startsWith(prefix))
+        return collapseLabel(name.slice(prefix.length));
+    const collapsed = collapseLabel(name);
+    if (collapsed &&
+        collapsed !== collapseLabel(agentType) &&
+        collapsed !== collapseLabel(agentName ?? '')) {
+        return collapsed;
+    }
+    return '';
+}