@sema-agent/client-core 0.2.0 → 0.3.0

package/dist/subagentContentStore.js

@@ -0,0 +1,322 @@
+/**
+ * ⇄ 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.
+ */
+const MAX_ITEMS_PER_TASK = 200;
+const MAX_TASKS = 32;
+const NOTIFY_COALESCE_MS = 250;
+const tasks = new Map();
+// parentToolCallId ↔ engine taskId aliasing: CONTENT events carry ONLY {eventId, parentToolCallId}
+// (EventIdentity — no taskId on the wire), while the panel rows / 查看态 lookups key by the ENGINE task id
+// (task_progress carries BOTH). Content arriving before the first tick parks under the parent key and is
+// RE-KEYED when the alias registers.
+const parentToTask = new Map();
+const taskToParent = new Map();
+let notifyListener = null;
+const pendingNotify = new Set();
+let notifyTimer = null;
+/** LRU touch:Map 迭代序=插入序,容量淘汰取「最老」——不刷新的话是纯 FIFO,长会话里第 33 个
+ *  子代会把【仍在流式/正被查看】的最早行挤掉(扩散面复审 F11)。访问即 re-insert,活跃项恒新。 */
+function touchLru(map, key) {
+    const v = map.get(key);
+    if (v !== undefined) {
+        map.delete(key);
+        map.set(key, v);
+    }
+}
+function stateFor(taskId, parentToolCallId) {
+    let s = tasks.get(taskId);
+    if (!s) {
+        // Bound total task footprint: evict the LEAST-RECENTLY-USED task's log (reads/writes touch below).
+        if (tasks.size >= MAX_TASKS) {
+            const oldest = tasks.keys().next().value;
+            if (oldest !== undefined)
+                tasks.delete(oldest);
+        }
+        s = { items: [], textBuf: '', thinkBuf: '', openTools: new Map(), parentToolCallId };
+        tasks.set(taskId, s);
+    }
+    else {
+        touchLru(tasks, taskId);
+    }
+    return s;
+}
+function pushItem(s, item) {
+    s.items.push(item);
+    if (s.items.length > MAX_ITEMS_PER_TASK) {
+        s.items.splice(0, s.items.length - MAX_ITEMS_PER_TASK);
+        // open-tool indexes shifted — rebuild from the surviving items
+        s.openTools.clear();
+        s.items.forEach((it, i) => {
+            if (it.kind === 'tool' && it.output === undefined)
+                s.openTools.set(it.id, i);
+        });
+    }
+}
+/** Close out streaming buffers into items (segment boundary: a tool starts, or the run settles). */
+function flushBuffers(s) {
+    if (s.thinkBuf.trim())
+        pushItem(s, { kind: 'thinking', text: s.thinkBuf });
+    s.thinkBuf = '';
+    if (s.textBuf.trim())
+        pushItem(s, { kind: 'text', text: s.textBuf });
+    s.textBuf = '';
+}
+function scheduleNotify(taskId) {
+    pendingNotify.add(taskId);
+    if (notifyTimer)
+        return;
+    notifyTimer = setTimeout(() => {
+        notifyTimer = null;
+        const ids = [...pendingNotify];
+        pendingNotify.clear();
+        if (!notifyListener)
+            return;
+        for (const id of ids) {
+            try {
+                notifyListener(id);
+            }
+            catch {
+                // a consumer render error must never tear down the stream drain
+            }
+        }
+    }, NOTIFY_COALESCE_MS);
+}
+/** 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 function registerSubagentAlias(parentToolCallId, taskId) {
+    if (!parentToolCallId || !taskId || parentToolCallId === taskId)
+        return;
+    parentToTask.set(parentToolCallId, taskId);
+    taskToParent.set(taskId, parentToolCallId);
+    // a notify queued under the parent key before the alias landed must fire under the canonical key
+    if (pendingNotify.delete(parentToolCallId))
+        pendingNotify.add(taskId);
+    const parked = tasks.get(parentToolCallId);
+    if (parked && !tasks.has(taskId)) {
+        tasks.delete(parentToolCallId);
+        tasks.set(taskId, parked);
+        scheduleNotify(taskId);
+    }
+}
+function canonicalKey(ev) {
+    // the wire's content events carry no taskId — runStream passes parentToolCallId in both slots
+    if (ev.taskId !== ev.parentToolCallId)
+        return ev.taskId;
+    return parentToTask.get(ev.parentToolCallId) ?? ev.parentToolCallId;
+}
+export function publishSubagentContentEvent(ev) {
+    const key = canonicalKey(ev);
+    const s = stateFor(key, ev.parentToolCallId);
+    switch (ev.type) {
+        case 'text_delta':
+            if (typeof ev.delta === 'string')
+                s.textBuf += ev.delta;
+            break;
+        case 'reasoning_delta':
+            if (typeof ev.delta === 'string')
+                s.thinkBuf += ev.delta;
+            break;
+        case 'tool_start': {
+            flushBuffers(s);
+            const id = ev.toolCallId ?? `${ev.taskId}-tool-${s.items.length}`;
+            pushItem(s, { kind: 'tool', id, name: ev.toolName ?? 'Tool', input: ev.args ?? {} });
+            s.openTools.set(id, s.items.length - 1);
+            break;
+        }
+        case 'tool_end': {
+            const id = ev.toolCallId;
+            const idx = id !== undefined ? s.openTools.get(id) : undefined;
+            if (idx !== undefined && s.items[idx]?.kind === 'tool') {
+                const it = s.items[idx];
+                it.output = ev.output ?? '';
+                it.isError = ev.isError === true;
+                if (id !== undefined)
+                    s.openTools.delete(id);
+            }
+            else {
+                // orphan close (start lost to the ring / arrived first) — synthesize a resolved card
+                pushItem(s, {
+                    kind: 'tool',
+                    id: id ?? `${ev.taskId}-tool-${s.items.length}`,
+                    name: ev.toolName ?? 'Tool',
+                    input: ev.args ?? {},
+                    output: ev.output ?? '',
+                    isError: ev.isError === true,
+                });
+            }
+            break;
+        }
+    }
+    scheduleNotify(key);
+}
+/** 查看态 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 function pushSubagentLocalEcho(taskId, text) {
+    const s = stateFor(taskId, tasks.get(taskId)?.parentToolCallId ?? '');
+    flushBuffers(s);
+    pushItem(s, { kind: 'echo', text });
+    scheduleNotify(taskId);
+}
+export function getSubagentContentSnapshot(taskId) {
+    const key = tasks.has(taskId) ? taskId : (taskToParent.get(taskId) ?? '');
+    const s = tasks.get(key);
+    if (!s)
+        return null;
+    touchLru(tasks, key); // 正被查看的转录不因容量淘汰当场清空(F11)
+    return { items: [...s.items], textBuf: s.textBuf, thinkBuf: s.thinkBuf };
+}
+/**
+ * 把一个子代的内容账本投影成查看态渲染计划。
+ *
+ * [1568] 之前的形(壳侧 engineAgentView 里)有两处「等段闭合」:①遇到第一个未闭合工具就 break;
+ * ②textBuf/thinkBuf 完全不投影。实测(engine 1.275.0 真跑):数据面 ~23 帧/s 的 delta 连续到壳,
+ * 查看态却只在 tool 边界更新(进查看态后 6.0s 全空,之后每 5–15s 才动一次)。现形:在飞工具照投,
+ * 流式尾巴作为 live 槽投 —— 屏面粒度 = wire 粒度(store notify 已按 250ms 合并)。
+ */
+export function planSubagentViewSlots(taskId) {
+    const snap = getSubagentContentSnapshot(taskId);
+    if (!snap)
+        return [];
+    const out = [];
+    snap.items.forEach((it, i) => {
+        if (it.kind === 'tool') {
+            out.push({
+                kind: 'tool',
+                slot: `u${i}`,
+                id: it.id,
+                name: it.name,
+                input: it.input,
+                ...(it.output !== undefined ? { output: it.output } : {}),
+                ...(it.isError === true ? { isError: true } : {}),
+            });
+        }
+        else if (it.kind === 'text') {
+            out.push({ kind: 'text', slot: `t${i}`, text: it.text });
+        }
+        else if (it.kind === 'thinking') {
+            out.push({ kind: 'thinking', slot: `k${i}`, text: it.text });
+        }
+        else {
+            out.push({ kind: 'echo', slot: `e${i}`, text: it.text });
+        }
+    });
+    // 尾巴顺序与 flushBuffers 落项顺序一致(thinking 先、text 后)——段闭合时屏面内容连续不跳。
+    if (snap.thinkBuf.trim()) {
+        out.push({ kind: 'thinking', slot: 'live-think', text: snap.thinkBuf, live: true });
+    }
+    if (snap.textBuf.trim()) {
+        out.push({ kind: 'text', slot: 'live-text', text: snap.textBuf, live: true });
+    }
+    return out;
+}
+/** C2 steer target: the service routes subagent steer by the delegating tool call's id. */
+export function parentToolCallIdOf(taskId) {
+    return taskToParent.get(taskId) ?? tasks.get(taskId)?.parentToolCallId;
+}
+/** Settle a task's streaming buffers (turn ended / run settled) so the snapshot is complete. */
+export function settleSubagentContent(taskId) {
+    const s = tasks.get(taskId);
+    if (!s)
+        return;
+    flushBuffers(s);
+    scheduleNotify(taskId);
+}
+export function clearSubagentContent(taskId) {
+    tasks.delete(taskId);
+}
+const bgFacts = new Map();
+export function recordBgTerminalFacts(taskId, facts) {
+    if (!taskId)
+        return;
+    if (bgFacts.size >= MAX_TASKS && !bgFacts.has(taskId)) {
+        const oldest = bgFacts.keys().next().value;
+        if (oldest !== undefined)
+            bgFacts.delete(oldest);
+    }
+    bgFacts.delete(taskId); // LRU touch(F11):重录/更新即刷新插入序
+    bgFacts.set(taskId, facts);
+    scheduleNotify(taskId); // 打开中的查看态借既有 notify 链重建消息
+}
+export function getBgTerminalFacts(taskId) {
+    const key = bgFacts.has(taskId) ? taskId : (taskToParent.get(taskId) ?? '');
+    touchLru(bgFacts, key);
+    return bgFacts.get(key);
+}
+// ── bg 子代 → spawn 它的 leader run(server 1.244 subagentOutput 读面的寻址元组)──────────────
+// GET /v1/runs/:runId/subagents/:handle/output 的 runId = spawn 该子代的 run(registry access 从
+// run 行推导,[1491]①)。来源两路:fleet 行 parentId(出生帧即带)+ bg_notification.parentTaskId。
+const bgParentRun = new Map();
+export function recordBgParentRun(taskId, runId) {
+    if (!taskId || !runId || taskId === runId)
+        return;
+    if (bgParentRun.size >= MAX_TASKS * 2 && !bgParentRun.has(taskId)) {
+        const oldest = bgParentRun.keys().next().value;
+        if (oldest !== undefined)
+            bgParentRun.delete(oldest);
+    }
+    bgParentRun.delete(taskId); // LRU touch(F11):活跃映射不被容量淘汰挤掉 → 读面退错 runId
+    bgParentRun.set(taskId, runId);
+}
+export function getBgParentRun(taskId) {
+    touchLru(bgParentRun, taskId);
+    return bgParentRun.get(taskId);
+}
+// ── 本壳自己发起过的引擎 run 台账([1498]④ 帧级校验换锚)────────────────────────────────────
+// 喂给:engineToolDetach.setActiveEngineTaskId(liveClient 从 run_started 帧绑定,本壳每个交互
+// turn 的 run 必经)。与 bgParentRun 的关键区别:bgParentRun 由 fleet 行/通知帧喂(≤1.244 事实
+// 广播下可能混入别的壳的行),这份台账**只**记本进程亲手驱动的 run,是帧级 own/foreign 判别的
+// 唯一可信锚。进程内存态,壳重启即空(跨壳 resume 的历史 run 判不了 own——诚实边界,见
+// fleetClient 帧级校验注释)。
+const ownEngineRuns = new Set();
+export function recordOwnEngineRun(runId) {
+    if (!runId)
+        return;
+    // 防御性上限:一个壳进程生命周期内 turn 数远小于此;溢出丢最老(Set 迭代序=插入序)。
+    if (ownEngineRuns.size >= 8192 && !ownEngineRuns.has(runId)) {
+        const oldest = ownEngineRuns.values().next().value;
+        if (oldest !== undefined)
+            ownEngineRuns.delete(oldest);
+    }
+    ownEngineRuns.add(runId);
+}
+export function isOwnEngineRun(runId) {
+    return ownEngineRuns.has(runId);
+}
+/** Single consumer (the panel hook). Returns an unsubscribe. */
+export function subscribeSubagentContent(fn) {
+    notifyListener = fn;
+    // replay: anything already accumulated gets one notify so a late-mounting consumer catches up
+    for (const id of tasks.keys())
+        pendingNotify.add(id);
+    if (pendingNotify.size > 0)
+        scheduleNotify([...pendingNotify][0]);
+    return () => {
+        if (notifyListener === fn)
+            notifyListener = null;
+    };
+}

package/dist/types/engineState.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
+ * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
+ * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
+ * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
+ */
+/**
+ * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
+ *
+ * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
+ * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
+ *
+ * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
+ * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
+ * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
+ */
+/** 引擎 GET /health 返回体(与 ai-agent-service server.ts:645-660 对齐;字段大多 additive 可缺)。 */
+export interface HealthResponse {
+    /** 恒为 'ok';非 200 / 非此值 = 不健康。 */
+    status: string;
+    /** 当前模型 id(configHash 的一部分,信息性)。 */
+    model?: string;
+    /** 会话存储后端('file' for TOC local)。 */
+    sessionBackend?: string;
+    /** 活跃 session 数(信息性)。 */
+    sessions?: number;
+    /** 引擎实例身份(uuidv7,每次 boot 唯一)。陈旧 port 连错引擎时此值会变 → 拒连。 */
+    instanceId?: string;
+    /** 引擎 localDataRoot 解析结果。壳校验 === assembleChildEnv 注入的 LOCAL_DATA_ROOT。 */
+    dataRoot?: string;
+    /** restart-relevant config 的稳定指纹(无 secret)。drift 检测:configHash 变 → 拒连旧引擎。 */
+    configHash?: string;
+    /** 引擎进程 pid。orphan reap 的 kill-0 目标 + heartbeat 死活判定。 */
+    pid?: number;
+    /** 引擎监听端口。 */
+    port?: number;
+    /** 引擎请求重启(center restart 信号);壳侧信息性。 */
+    restartRequired?: boolean;
+    /** 引擎 build 版本自述(service 1.96+,[392]ask②)。复用时与本地 dist 版本比对,不一致=陈旧代码拒复用。 */
+    version?: string;
+}
+/**
+ * engine.port 文件落盘的 JSON 形状(write-temp+fsync+mv 原子写)。
+ * 壳启动时读此文件做引擎发现:存在且 kill-0 活 + /health 身份匹配 → 复用;否则 reap + spawn。
+ * 🔴 secrets 边界:绝不写入任何明文 token/secret(只透传到 child env)。grep engine.port 不得见 secret。
+ */
+export interface EnginePortFile {
+    /** 引擎监听端口。 */
+    port: number;
+    /** spawn 出的引擎子进程 pid(kill-0 存活检测 / orphan reap 目标)。 */
+    pid: number;
+    /** 引擎实例身份(uuidv7);连接前用 /health 复验,不匹配 = 陈旧 port。 */
+    instanceId?: string;
+    /** 引擎 localDataRoot;身份校验用。 */
+    dataRoot?: string;
+    /** boot 时记录的 configHash;drift 检测基线。 */
+    configHash?: string;
+    /** 引擎日志文件路径(<configHome>/engine-<pid>.log),壳可 tail 诊断。 */
+    logPath: string;
+    /** 落盘时间戳(epoch ms);信息性 / 调试用。 */
+    startedAt: number;
+    /** 写文件的格式版本(向后兼容);当前 1。 */
+    version: number;
+    /**
+     * P2 云配置整体开关:spawn 该引擎时生效的配置源标签('local' | 'cloud:<profile>')。
+     * ADDITIVE 可缺(老文件缺 = 'local')。boot 复用检查:与当前 desiredEngineConfigSource() 不一致
+     * → 视同配置漂移 reap+respawn(models 域走 CONFIG_LOCAL_DIR shadow,restart-to-apply)。
+     */
+    configSource?: string;
+}
+/**
+ * 内存中持有的「已托管引擎实例」句柄。lifecycle 全程持有,shutdown 时据此 SIGTERM/SIGKILL。
+ */
+export interface EngineInstance {
+    /** 监听端口。 */
+    port: number;
+    /** 子进程 pid。 */
+    pid: number;
+    /** baseUrl = http://127.0.0.1:<port>,壳设到 SEMA_LIVE_BASEURL。 */
+    baseUrl: string;
+    /** /health 校验拿到的身份(复用既有引擎时可能来自 probe,而非自己 spawn)。 */
+    instanceId?: string;
+    /** 引擎 dataRoot。 */
+    dataRoot?: string;
+    /** boot configHash 基线(heartbeat drift 检测)。 */
+    configHash?: string;
+    /** 日志文件路径(自己 spawn 的才有;复用既有引擎为 undefined)。 */
+    logPath?: string;
+    /** true = 本壳 spawn 出来的(shutdown 时负责回收);false = 复用既有引擎(不杀)。 */
+    ownedByThisShell: boolean;
+    /** node ChildProcess 句柄(仅自己 spawn 时有;复用既有为 undefined)。as unknown 避免类型耦合 child_process。 */
+    child?: unknown;
+}
+/**
+ * 壳注入给引擎子进程的 TOC env pack(§3.1)。引擎默认偏云(PORT=8090/DB_BACKEND=tidb/
+ * CONFIG_PROVIDER=undefined),壳必须显式覆盖为 local 单用户模式,绝不依赖引擎默认。
+ * secrets(ANTHROPIC_API_KEY/E2B_API_KEY 等)仅在父 env 存在时透传到 child,不落任何文件。
+ */
+export interface TOCConfig {
+    /** 选定端口(显式 pin SEMA_ENGINE_PORT 优先;无 pin 按 config dir 派生 + 空闲探测,P0-2)。 */
+    port: number;
+    /** 引擎数据根 = <configHome>/engine-data;引擎 LOCAL_DATA_ROOT 优先级链最高项。 */
+    localDataRoot: string;
+    /** 本地 config.d 目录 = <configHome>/config.d(引擎 CONFIG_LOCAL_DIR)。 */
+    configLocalDir: string;
+    /** 壳配置主目录(getClaudeConfigHomeDir());也作 SEMA_CONFIG_DIR 注入对齐路径。 */
+    configHome: string;
+    /** per-spawn 随机服务令牌(uuid),SERVICE_AUTH_TOKENS="<uuid>=system:shell-local";不落 .env。 */
+    serviceAuthToken: string;
+    /** 引擎入口文件绝对路径(ai-agent-service/dist/main.js,缺则回退 tsx src/main.ts)。 */
+    engineEntry: string;
+    /** 引擎入口的工作目录(ai-agent-service 根)。 */
+    engineCwd: string;
+    /** 引擎日志输出文件(<configHome>/engine-<pid>.log;pid spawn 后回填,先用占位)。 */
+    logPath: string;
+}

package/dist/types/engineState.js

@@ -0,0 +1,17 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
+ * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
+ * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
+ * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
+ */
+/**
+ * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
+ *
+ * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
+ * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
+ *
+ * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
+ * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
+ * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
+ */
+export {};

package/dist/workflow.d.ts

@@ -1,18 +1,50 @@
 /**
- * workflow 车道纯函数(抽自 sema-cli footerRowBelt/workflowTaskOutputProjection,围栏见
- * cli 仓 frameLaneGuards/taskOutputWorkflowEnvelope 套;[1617] 幽灵行家族的判别资产)。
+ * workflow 车道纯函数 + workflow-agent 台账。
+ *
+ * 沿革(B1 批,2026-07-27):0.2.0 时本文件是 cli `footerRowBelt.ts` / `workflowTaskOutputProjection.ts`
+ * 的**双份抄件**;B1 批按设计稿 §2.4.1-A/B 裁决「以壳侧现文件为真身、包内不留两份实现」:
+ *   · `parseWorkflowPollEnvelope` / `projectWorkflowTaskOutput` = cli `workflowTaskOutputProjection.ts`
+ *     的逐字搬入(0.2.0 抄件漏了 `agent_runs[].errorCode` 类型位,已按真身补齐);
+ *   · `rowIdTail` / `isWorkflowAgentTaskId` / `recordWorkflowAgentTaskId` / `isKnownWorkflowAgentTaskId`
+ *     = cli `footerRowBelt.ts` 的**belt 半场**(判据①④),按设计稿 §2.4.1-B「拆」搬入。
+ *     ⚠️ 留在 TUI 的是 `isFooterTaskRow` / `filterFooterTaskRows`(判据②③)—— 那两条含
+ *     「丢弃所有无 parentId 顶层行」的**端专属决策**(主 run 头部行由壳侧 fleetClient 合成渲染,
+ *     设计稿 §2.4.2-B),壳侧文件改成 import 本包的四个出口 + 自留那两个函数。
+ *   🔴 台账(`workflowAgentTaskIds`)是 module 级单实例:壳侧 bridge 的 task_progress lane 门写、
+ *     壳侧 belt 的 `isFooterTaskRow` 读 —— 两边都必须走**本包同一个模块实例**,否则台账写进一个
+ *     副本、读另一个副本(判据④ 静默失效,幽灵行回归)。
+ *
+ * 围栏见 cli 仓 frameLaneGuards / taskOutputWorkflowEnvelope / footerRowBelt 套;
+ * [1617] 幽灵行家族的判别资产。
  */
-/** core 1.356 BCE 合成 workflow-agent id 形:wa+16hex。
+/** 复合行键(`<runId> <taskId>`,fleet-bus fleetRunPublisher.childId)的尾段 = 引擎 taskId。
+ *  导出给壳侧 belt 半场复用(判据②③ 的行 id 归一);包内 fleetAgentPanelProjection 保留了它
+ *  自己的同语义私有副本(零依赖叶模块纪律,drift 由两侧测试各自锁)。 */
+export declare function rowIdTail(id: string): string;
+/** core 1.356 BCE 合成 workflow-agent id 形:wa+16hex(判据①)。
  *  真实 fleet 子行 id 是 `${runId} ${engineTaskId}` 复合形——必须取空白分隔尾段再匹配
- *  (cli footerRowBelt 原版语义;codex 对抗复审抓的等价性破坏,0.1.1 修)。 */
+ *  (cli footerRowBelt 原版语义;codex 对抗复审抓的等价性破坏,0.1.1 修)。
+ *  upstreamBridge 的 task_progress 前台 lane 门在 wire 无 workflowRunId 时(server <a76bd77,
+ *  黑板 [1619]:1.272.0 投影白名单仍剥该键)以此为次级判别——与 belt 双判据同模板。 */
 export declare function isWorkflowAgentTaskId(taskId: string): boolean;
-/** TaskOutput workflow 轮询信封识别(core task-registry formatWorkflowRun 真形:
- *  {task_id, type:"workflow", status, name?, …};type+task_id 双门,非该形返回 null)。 */
+export declare function recordWorkflowAgentTaskId(taskId: string): void;
+export declare function isKnownWorkflowAgentTaskId(taskId: string): boolean;
+/** 测试钩:清台账(壳侧原版无此口——module 级 Set 在壳里靠进程边界隔离;包内多组断言同进程跑,
+ *  必须能清,否则前一组的登记污染后一组)。 */
+export declare function __resetWorkflowAgentTaskIdsForTests(): void;
+/**
+ * TaskOutput legacy 腿(tool_end 无 structured)的 workflow 信封识别(#49 C3)。
+ * 判据=core task-registry formatWorkflowRun 真形:`{task_id, type:"workflow", status, name?, …}`
+ * ——type 判别位 + task_id 字符串双门,非该形返回 null(绝不误吞 bash/agent 轮询)。
+ */
 export declare function parseWorkflowPollEnvelope(body: string): {
     taskId: string;
     status: string;
     name?: string;
 } | null;
-/** workflow 轮询 JSON → 人话多行投影(agents 汇总行 + per-agent ✓/✗ 明细 + note/error 尾透传);
- *  非 JSON 原样返回(fail-soft)。 */
+/**
+ * workflow 轮询 JSON → 人话多行投影(agents 汇总行 + per-agent ✓/✗ 明细 + note/error 尾透传);
+ * 非 JSON 原样返回(fail-soft,`description [status]` 行仍在)。
+ * 输入=引擎 formatWorkflowRun 的 JSON 原文(core 1.352 起带 agent_runs per-agent 明细 + 失败 note 指路)。
+ */
 export declare function projectWorkflowTaskOutput(jsonSrc: string): string;

package/dist/workflow.js

@@ -1,16 +1,66 @@
 /**
- * workflow 车道纯函数(抽自 sema-cli footerRowBelt/workflowTaskOutputProjection,围栏见
- * cli 仓 frameLaneGuards/taskOutputWorkflowEnvelope 套;[1617] 幽灵行家族的判别资产)。
+ * workflow 车道纯函数 + workflow-agent 台账。
+ *
+ * 沿革(B1 批,2026-07-27):0.2.0 时本文件是 cli `footerRowBelt.ts` / `workflowTaskOutputProjection.ts`
+ * 的**双份抄件**;B1 批按设计稿 §2.4.1-A/B 裁决「以壳侧现文件为真身、包内不留两份实现」:
+ *   · `parseWorkflowPollEnvelope` / `projectWorkflowTaskOutput` = cli `workflowTaskOutputProjection.ts`
+ *     的逐字搬入(0.2.0 抄件漏了 `agent_runs[].errorCode` 类型位,已按真身补齐);
+ *   · `rowIdTail` / `isWorkflowAgentTaskId` / `recordWorkflowAgentTaskId` / `isKnownWorkflowAgentTaskId`
+ *     = cli `footerRowBelt.ts` 的**belt 半场**(判据①④),按设计稿 §2.4.1-B「拆」搬入。
+ *     ⚠️ 留在 TUI 的是 `isFooterTaskRow` / `filterFooterTaskRows`(判据②③)—— 那两条含
+ *     「丢弃所有无 parentId 顶层行」的**端专属决策**(主 run 头部行由壳侧 fleetClient 合成渲染,
+ *     设计稿 §2.4.2-B),壳侧文件改成 import 本包的四个出口 + 自留那两个函数。
+ *   🔴 台账(`workflowAgentTaskIds`)是 module 级单实例:壳侧 bridge 的 task_progress lane 门写、
+ *     壳侧 belt 的 `isFooterTaskRow` 读 —— 两边都必须走**本包同一个模块实例**,否则台账写进一个
+ *     副本、读另一个副本(判据④ 静默失效,幽灵行回归)。
+ *
+ * 围栏见 cli 仓 frameLaneGuards / taskOutputWorkflowEnvelope / footerRowBelt 套;
+ * [1617] 幽灵行家族的判别资产。
  */
-/** core 1.356 BCE 合成 workflow-agent id 形:wa+16hex。
+/** 复合行键(`<runId> <taskId>`,fleet-bus fleetRunPublisher.childId)的尾段 = 引擎 taskId。
+ *  导出给壳侧 belt 半场复用(判据②③ 的行 id 归一);包内 fleetAgentPanelProjection 保留了它
+ *  自己的同语义私有副本(零依赖叶模块纪律,drift 由两侧测试各自锁)。 */
+export function rowIdTail(id) {
+    return id.split(/\s+/).pop() ?? id;
+}
+/** core 1.356 BCE 合成 workflow-agent id 形:wa+16hex(判据①)。
  *  真实 fleet 子行 id 是 `${runId} ${engineTaskId}` 复合形——必须取空白分隔尾段再匹配
- *  (cli footerRowBelt 原版语义;codex 对抗复审抓的等价性破坏,0.1.1 修)。 */
+ *  (cli footerRowBelt 原版语义;codex 对抗复审抓的等价性破坏,0.1.1 修)。
+ *  upstreamBridge 的 task_progress 前台 lane 门在 wire 无 workflowRunId 时(server <a76bd77,
+ *  黑板 [1619]:1.272.0 投影白名单仍剥该键)以此为次级判别——与 belt 双判据同模板。 */
 export function isWorkflowAgentTaskId(taskId) {
-    const tail = taskId.split(/\s+/).pop() ?? taskId;
-    return /^wa[0-9a-f]{16}$/.test(tail);
+    return /^wa[0-9a-f]{16}$/.test(rowIdTail(taskId));
+}
+// ── 判据④:bridge task_progress lane 门台账([1641])────────────────────────────────────────────
+// bridge 的 workflow lane 门(帧带 workflowRunId 的权威判定)把子代 taskId 登记进来,行按尾段查。
+// ③④ 互为兜底:③(集合级双生识别,TUI 半场)不依赖时序但要求 wa 行在场;④ 不依赖 wa 行但要求
+// 本壳在读该 run 的会话流。
+const workflowAgentTaskIds = new Set();
+const MAX_WORKFLOW_TASK_IDS = 4096;
+export function recordWorkflowAgentTaskId(taskId) {
+    if (!taskId)
+        return;
+    workflowAgentTaskIds.delete(taskId);
+    workflowAgentTaskIds.add(taskId);
+    if (workflowAgentTaskIds.size > MAX_WORKFLOW_TASK_IDS) {
+        const oldest = workflowAgentTaskIds.values().next().value;
+        if (oldest !== undefined)
+            workflowAgentTaskIds.delete(oldest);
+    }
+}
+export function isKnownWorkflowAgentTaskId(taskId) {
+    return workflowAgentTaskIds.has(taskId);
+}
+/** 测试钩:清台账(壳侧原版无此口——module 级 Set 在壳里靠进程边界隔离;包内多组断言同进程跑,
+ *  必须能清,否则前一组的登记污染后一组)。 */
+export function __resetWorkflowAgentTaskIdsForTests() {
+    workflowAgentTaskIds.clear();
 }
-/** TaskOutput workflow 轮询信封识别(core task-registry formatWorkflowRun 真形:
- *  {task_id, type:"workflow", status, name?, …};type+task_id 双门,非该形返回 null)。 */
+/**
+ * TaskOutput legacy 腿(tool_end 无 structured)的 workflow 信封识别(#49 C3)。
+ * 判据=core task-registry formatWorkflowRun 真形:`{task_id, type:"workflow", status, name?, …}`
+ * ——type 判别位 + task_id 字符串双门,非该形返回 null(绝不误吞 bash/agent 轮询)。
+ */
 export function parseWorkflowPollEnvelope(body) {
     try {
         const j = JSON.parse(body);
@@ -26,8 +76,11 @@ export function parseWorkflowPollEnvelope(body) {
         return null;
     }
 }
-/** workflow 轮询 JSON → 人话多行投影(agents 汇总行 + per-agent ✓/✗ 明细 + note/error 尾透传);
- *  非 JSON 原样返回(fail-soft)。 */
+/**
+ * workflow 轮询 JSON → 人话多行投影(agents 汇总行 + per-agent ✓/✗ 明细 + note/error 尾透传);
+ * 非 JSON 原样返回(fail-soft,`description [status]` 行仍在)。
+ * 输入=引擎 formatWorkflowRun 的 JSON 原文(core 1.352 起带 agent_runs per-agent 明细 + 失败 note 指路)。
+ */
 export function projectWorkflowTaskOutput(jsonSrc) {
     try {
         const j = JSON.parse(jsonSrc);
@@ -35,19 +88,24 @@ export function projectWorkflowTaskOutput(jsonSrc) {
         if (j.agents && typeof j.agents.done === 'number' && typeof j.agents.total === 'number') {
             parts.push(`agents: ${j.agents.done}/${j.agents.total} done${typeof j.agents.failed === 'number' && j.agents.failed > 0 ? ` (${j.agents.failed} failed)` : ''}`);
         }
+        // per-agent 明细([1411]③/[1408] 围栏 M1):✓/✗ label [status] — error 首行/output 摘要。
+        // 缺席(老 core)零行=形状不变。
         if (Array.isArray(j.agent_runs)) {
             for (const r of j.agent_runs) {
                 if (!r || typeof r !== 'object')
                     continue;
                 const label = typeof r.label === 'string' && r.label.length > 0 ? r.label : '(agent)';
                 const st = typeof r.status === 'string' ? r.status : '?';
-                const errLine = typeof r.error === 'string' && r.error.length > 0 ? ` — ${r.error.split('\n')[0].slice(0, 120)}` : '';
+                const errLine = typeof r.error === 'string' && r.error.length > 0
+                    ? ` — ${r.error.split('\n')[0].slice(0, 120)}`
+                    : '';
                 const outLine = !errLine && typeof r.output === 'string' && r.output.length > 0
                     ? ` — ${r.output.split('\n')[0].slice(0, 80)}`
                     : '';
                 parts.push(`  ${st === 'completed' ? '✓' : st === 'failed' ? '✗' : '·'} ${label} [${st}]${errLine}${outLine}`);
             }
         }
+        // note 尾透传(core 失败指路:TaskOutput+resumeFromRunId)——不留死胡同(围栏 M2)。
         if (typeof j.note === 'string' && j.note.length > 0)
             parts.push(j.note);
         if (typeof j.error === 'string' && j.error.length > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",