@sema-agent/client-core 0.7.0 → 0.8.1

package/dist/fleet/fleetLedger.js

@@ -0,0 +1,393 @@
+import { hostLog } from '../host.js';
+import { engineWireDebugEnabled } from '../engineWireTarget.js';
+import { engineSessionParam } from '../engineSessionParam.js';
+// `isHookNoticeFrame` 不在这里 re-export —— 它已由 index.ts 的 `export * from './notifications.js'`
+// 出口(重复 re-export 只会让同名绑定在包根变含糊)。端要先分诊再喂台账,从包根 import 即可。
+import { enqueueBgChildNotification, isOwnWorkflowRun } from '../notifications.js';
+import { isOwnEngineRun, recordBgParentRun, recordBgTerminalFacts, recordOwnEngineRun, } from '../subagentContentStore.js';
+import { rowIdTail } from '../workflow.js';
+import { recordEngineTranscriptId } from '../subagent/engineDelegatedPrompt.js';
+import { TERMINAL_FLEET_TASK_STATUSES, projectTasks, projectWorkflows, } from './fleetProjection.js';
+/** 终态行留存宽限窗(187 的 agents 页把完成会话留在列表;窗过即净,防长会话堆行)。 */
+export const TERMINAL_RETAIN_MS = 60_000;
+const liveBgViews = new Set();
+/**
+ * server 代际证据读面:任一 live fleet 源的 meta 报过 `sessionScoped=true`。
+ * true ⇒ 到达本连接的**行帧**已经过 server 会话过滤,端侧行级 own 判别可以让位。
+ * 🔴 只覆盖【行帧】:通知帧的 own-run 台账判别不看本标,恒开(1.244 对缺 ownerSessionId 的通知
+ *    仍广播,fail-closed 是 1.245+)。
+ */
+export function isFleetSessionScoped() {
+    for (const view of liveBgViews) {
+        try {
+            if (view.sessionScoped() === true)
+                return true;
+        }
+        catch {
+            /* 单视图炸不拖累读面 */
+        }
+    }
+    return false;
+}
+/** 引擎侧在飞 bg 子代读数(union 所有未 dispose 的源,按 row.id 去重)。无 live 源 ⇒ `{[], false}`。 */
+export function readEngineActiveBgTasks() {
+    const byId = new Map();
+    let fresh = false;
+    for (const view of liveBgViews) {
+        try {
+            const r = view.read();
+            if (r.connected)
+                fresh = true;
+            for (const row of r.rows)
+                byId.set(row.id, row);
+        }
+        catch {
+            /* 单视图炸不拖累读面 */
+        }
+    }
+    return { tasks: [...byId.values()], fresh };
+}
+/**
+ * 清空所有 live 源的终态留存池 —— 会话切换(/clear、REPL 内 resume、fork)信号一到就调。
+ * R7:留存池是渲染层宽限窗,快照臂刻意不清它(重连不该抽走行);但换了会话继续渲上一会话的
+ * 终态行(名字 = objective 派生)就是跨会话残影。
+ */
+export function clearAllRetainedFleetRows() {
+    for (const view of liveBgViews) {
+        try {
+            view.clearRetained();
+        }
+        catch {
+            /* 单视图炸不拖累信号 */
+        }
+    }
+}
+/** 测试钩:摘掉所有登记的视图(同进程多组断言之间互不污染)。 */
+export function __resetFleetLedgerRegistryForTests() {
+    liveBgViews.clear();
+}
+// ── P1-4:会话过滤参数(取代壳侧 makeSessionScopingFetch)───────────────────────────────────────
+/**
+ * `client.fleet.stream(...)` 的会话过滤参数。缺席(端未装 SessionPort / 还没有会话 id)⇒ `{}`
+ * = principal 级视图,**与 1.37 之前逐字同行为**(不是错误态)。
+ */
+export function fleetStreamOptions() {
+    const s = engineSessionParam();
+    return s ? { session: s } : {};
+}
+/** G19:`client.fleet.snapshot(...)` 的参数(同上;首屏/温切探针用)。 */
+export function fleetSnapshotOptions(opts) {
+    return {
+        ...fleetStreamOptions(),
+        ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+    };
+}
+/**
+ * 建一个 fleet 帧台账。**不开流、不构造 client** —— 宿主的 consume 循环把解码后的帧喂进来。
+ * (这条切缝就是设计稿 §2.5 给 fleetClient 划的那一刀:帧体归库、连接归端。)
+ */
+export function createFleetLedger(hooks = {}) {
+    const taskMap = new Map();
+    const wfMap = new Map();
+    /** [1481]①「elapsed 恒 0s」补偿:记每行最后一帧到达时刻(引擎只在活动边界重发行)。 */
+    const rowMeta = new Map();
+    /** [1481]②「完成即消失」补偿:终态行进留存池,宽限窗内继续投影。 */
+    const retained = new Map();
+    let connected = false;
+    let version = null;
+    let scoped = null;
+    let sessionScopedMeta;
+    let bgNotifyFailClosedMeta = false;
+    let disposed = false;
+    const debug = (line) => {
+        if (engineWireDebugEnabled())
+            hostLog('debug', line);
+    };
+    const bgView = {
+        read: () => ({
+            connected,
+            rows: [...taskMap.values()]
+                .filter(r => !TERMINAL_FLEET_TASK_STATUSES.has(r.status ?? ''))
+                .map(r => ({
+                id: r.id,
+                name: r.name,
+                status: r.status ?? 'running',
+                ...(r.parentId ? { parentId: r.parentId } : {}),
+            })),
+        }),
+        sessionScoped: () => sessionScopedMeta,
+        clearRetained: () => {
+            retained.clear();
+        },
+    };
+    liveBgViews.add(bgView);
+    function applyFrame(frame) {
+        switch (frame.type) {
+            case 'meta': {
+                version = frame.version;
+                scoped = frame.scoped;
+                // 🔴 B6 typed 直读(SDK 0.0.117 `FleetFrame.meta` 已 declare 这两键;此前是
+                //    `(frame as {sessionScoped?: unknown})` 兜读)。server 1.291.0 实发
+                //    `{version:1, scoped, sessionScoped: callerSession!==null, bgNotifyFailClosed:true}`。
+                sessionScopedMeta = typeof frame.sessionScoped === 'boolean' ? frame.sessionScoped : undefined;
+                // [1510] 代际标:fail-closed 语义只在 session-bound 连接生效(CHANGELOG 钉「仅 session-bound
+                // 连接适用」),所以让位判定必须叠加 sessionScoped —— 亲拆 1.247 dist:meta 恒带 true。
+                bgNotifyFailClosedMeta = frame.bgNotifyFailClosed === true;
+                // [1521]F1 教训:让位路径此前是死代码而围栏全绿(未断言路径本身)——数据面日志让围栏能锚
+                // 「代际标真的到达且被消费」,防中继剥键类回归再度静默。
+                debug(`[fleet-frame] meta sessionScoped=${String(sessionScopedMeta)} bgNotifyFailClosed=${String(bgNotifyFailClosedMeta)}`);
+                break;
+            }
+            case 'snapshot': {
+                // 新快照 REPLACE 整个活跃集(重连间隙里被删掉的行不该 linger)。
+                taskMap.clear();
+                wfMap.clear();
+                rowMeta.clear();
+                const at = frame.ts;
+                for (const row of frame.tasks) {
+                    taskMap.set(row.id, row);
+                    rowMeta.set(row.id, { receivedAt: at });
+                }
+                for (const row of frame.workflows)
+                    wfMap.set(row.id, row);
+                break;
+            }
+            case 'task': {
+                const row = frame.row;
+                if (!row?.id)
+                    break;
+                taskMap.set(row.id, row); // POST-MERGE FULL row → replace by id
+                rowMeta.set(row.id, { receivedAt: frame.ts });
+                debug(`[fleet-row] id=${row.id} parent=${row.parentId ?? '-'} agentType=${row.agentType ?? '-'}` +
+                    ` agentName=${row.agentName ?? '-'} name=${row.name ?? '-'} status=${row.status ?? '-'}` +
+                    ` tokens=${row.tokens ?? 0} parentToolCallId=${row.parentToolCallId ?? '-'}`);
+                // [1491] subagentOutput 寻址:子代行出生帧带 parentId(spawn run)——记映射供查看态终报读面。
+                // 归属判别与通知臂同锚(R1/F1,2026-07-22):
+                //   · parent ∈ own-run 台账 → own:登映射 + 把本行 taskId 也登进台账(F1 闭包 —— 嵌套孙代的
+                //     bg_notification.parentTaskId 是**直接父**,不闭包的话孙代完成通知会被当 foreign 丢);
+                //   · parent ∉ 台账但 meta.sessionScoped===true → server 已按会话过滤行帧,到达即本会话
+                //     (或无标行)→ 登映射**不登台账**(台账只收硬证据,防无标外来行污染台账后反过来给
+                //     通知臂放行);这也保住「壳重启+resume 接回会话」的终报 hydrate;
+                //   · 两者都不是(老代际广播窗)→ 不登映射(隔离优先)。
+                if (row.parentId) {
+                    const childTid = rowIdTail(row.id);
+                    const parentTid = rowIdTail(row.parentId);
+                    const parentOwned = isOwnEngineRun(parentTid);
+                    if (parentOwned)
+                        recordOwnEngineRun(childTid);
+                    if (parentOwned || sessionScopedMeta === true) {
+                        recordBgParentRun(childTid, parentTid);
+                    }
+                    else {
+                        debug(`[fleet-frame] task row parent-map SKIPPED foreign/unowned(row=${row.id} parent=${parentTid})`);
+                    }
+                }
+                // [1839]① 终态行帧四键:transcriptId 现在**行上也可能有**(此前只在通知帧),有就登锚 ——
+                // 委派 prompt 取件腿据此在「只看行卡」的场景也能补齐详情页 Prompt 段。
+                if (typeof row.transcriptId === 'string' && row.transcriptId.length > 0) {
+                    recordEngineTranscriptId(rowIdTail(row.id), row.transcriptId);
+                }
+                // 终态帧 → 留存池(remove 同毫秒尾随,probe 实证;留存让 completed band 数得到它)。
+                if (TERMINAL_FLEET_TASK_STATUSES.has(row.status ?? '')) {
+                    retained.set(row.id, { row, expireAt: frame.ts + TERMINAL_RETAIN_MS });
+                }
+                break;
+            }
+            case 'task_remove':
+                taskMap.delete(frame.id);
+                rowMeta.delete(frame.id);
+                break;
+            case 'workflow':
+                if (frame.row?.id)
+                    wfMap.set(frame.row.id, frame.row);
+                break;
+            case 'workflow_remove':
+                wfMap.delete(frame.id);
+                break;
+            case 'hook_notice':
+                // hook_notice(server 1.280.0,[1790]):「本轮 Stop 守卫未能评估」纯 observe 帧。
+                // 判定本体在 notifications.classifyHookNoticeFrame(#105 F3:判别不许留在分发处,否则
+                // 离线门只能 grep);写 store 归宿主。SDK 0.0.117 起本帧**已在 FleetFrame 联合里**,
+                // 不再走 default 臂的 `type` 字面判别。
+                hooks.onHookNotice?.(frame, sessionScopedMeta === true);
+                break;
+            case 'bg_notification':
+                applyBgNotification(frame.notification);
+                break;
+            default:
+                // 未知未来帧 —— 开集,忽略。
+                // ⚠️ 老 SDK 时代这里还兜着「平铺形 bg_notification / 字面 hook_notice」两条 belt;
+                //   0.0.117 的 FleetFrame 两者都是具名臂,belt 随之退役(旧回放素材由端自己升级)。
+                break;
+        }
+    }
+    /** bg 子代终态通知帧([446] 帧契约,service 1.119):常开 lane 即时到达 → 转注入链。 */
+    function applyBgNotification(n) {
+        if (typeof n?.taskId !== 'string' || typeof n?.status !== 'string')
+            return;
+        // 🔴 own/foreign 判别(双开泄漏案帧级防线;[1498]④ 换锚重写):payload `sessionId` 是**子代
+        //   自身** session uuid,宿主会话在 ownerSessionId 上且出 wire 前被剥 —— 所以判别锚
+        //   `parentTaskId`(spawn 该子代的 leader run id)对 own-run 台账:
+        //     · ∈ 台账 → own,放行;
+        //     · 在但不在台账 → 隔离优先丢弃;
+        //     · 缺席 → 放行(absent-放行姿势)。
+        // [1510] 代际让位:meta 报 bgNotifyFailClosed 且本连接 session-bound ⇒ server 侧注入路已
+        //   fail-closed,到达即本会话 → 端侧台账判别整体让位。
+        const serverFailClosed = bgNotifyFailClosedMeta && sessionScopedMeta === true;
+        // [1518] δ 投影:通知带 `rootSessionId`(委托树 root 宿主会话,固定点语义)=== 本会话即 own
+        //   硬证据。🔴 与行帧的 `rowSessionTag` 不同 —— server `streamFleet` 只从**行**上剥
+        //   scope/sessionId,通知帧只剥 ownerScope/ownerSessionId,`rootSessionId` **照发**
+        //   (1.291.0 dist 实读)⇒ 这条腿是活的,不在 G12 删除范围内。
+        const ownByRoot = typeof n.rootSessionId === 'string' &&
+            n.rootSessionId.length > 0 &&
+            n.rootSessionId === engineSessionParam();
+        if (!serverFailClosed &&
+            !ownByRoot &&
+            typeof n.parentTaskId === 'string' &&
+            n.parentTaskId.length > 0 &&
+            !isOwnEngineRun(n.parentTaskId)) {
+            debug(`[fleet-frame] bg_notification DROPPED foreign/unowned parentRun(taskId=${n.taskId} parentRun=${n.parentTaskId})`);
+            return;
+        }
+        debug(`[fleet-frame] bg_notification taskId=${n.taskId} status=${n.status} seq=${n.seq ?? '-'}`);
+        if (TERMINAL_FLEET_TASK_STATUSES.has(n.status)) {
+            if (typeof n.parentTaskId === 'string' && n.parentTaskId) {
+                recordBgParentRun(n.taskId, n.parentTaskId);
+            }
+            // `transcriptId`(server 1.278.0)= 委派 prompt 的取件锚。现势:通知帧是它**今天真的在场**
+            // 的主要位置(行帧那条腿已同款接好,引擎一发即亮 —— 见 case 'task')。
+            if (typeof n.transcriptId === 'string' && n.transcriptId.length > 0) {
+                recordEngineTranscriptId(n.taskId, n.transcriptId);
+            }
+            // [1481]① 查看态事实喂给:终态通知带 summary+recentSteps,这是端当前能拿到的关于后台子代
+            // 结局的【全部】内容(终报正文不在 wire 上)。查看态对无终报的终态行渲染这些真实事实。
+            recordBgTerminalFacts(n.taskId, {
+                status: n.status,
+                ...(typeof n.summary === 'string' ? { summary: n.summary } : {}),
+                // 🔴 SDK 0.0.117 把 `recentSteps` 的三键 declare 成**必填** string,但那是**声称**不是保证:
+                //    帧从 wire 上来,脏项(null / 缺键 / 非串)在类型面之外仍可能到达,而 BgTerminalFacts
+                //    那侧三键**全可选** ⇒ 这里的逐键 typeof 不是「防御读没退干净」,是 wire 脏值过滤(与
+                //    fleetProjection 的 `wire*` 值域校验同一档次)。谓词类型必须是元素型本身,不能是
+                //    `Record<string, unknown>`(那不是参数型的子型 ⇒ TS2677)。
+                ...(Array.isArray(n.recentSteps)
+                    ? {
+                        recentSteps: n.recentSteps
+                            .filter((s) => Boolean(s) && typeof s === 'object')
+                            .map(s => ({
+                            ...(typeof s.tool === 'string' ? { tool: s.tool } : {}),
+                            ...(typeof s.target === 'string' ? { target: s.target } : {}),
+                            ...(typeof s.outcome === 'string' ? { outcome: s.outcome } : {}),
+                        })),
+                    }
+                    : {}),
+            });
+            // belt:终态**行帧**丢失(kill 竞态等)时,已知行也随通知转终态进留存池。
+            const known = taskMap.get(n.taskId);
+            if (known && !retained.has(n.taskId)) {
+                retained.set(n.taskId, {
+                    row: { ...known, status: n.status },
+                    expireAt: Date.now() + TERMINAL_RETAIN_MS,
+                });
+            }
+        }
+        enqueueBgChildNotification({
+            taskId: n.taskId,
+            status: n.status,
+            // seq = 周期号(SendMessage 复活即 +1)—— 去重键必须带,否则 revive 周期的完成通知被首周期
+            // 同 (taskId,status) 键吞掉(clay 图2 案根因,1.355 复验 seq=2 帧实锤)。
+            ...(typeof n.seq === 'number' ? { seq: n.seq } : {}),
+            ...(typeof n.summary === 'string' ? { summary: n.summary } : {}),
+        });
+    }
+    function project(nowMs, opts) {
+        const viewingTaskId = opts.viewingTaskId;
+        // ① 帧间时钟推进(非终态行):elapsedMs 基值 + 帧后空窗。终态行冻结在 wire 终值(诚实)。
+        const liveRows = [...taskMap.values()].map(r => {
+            if (TERMINAL_FLEET_TASK_STATUSES.has(r.status ?? ''))
+                return r;
+            // [1518] δ:server 1.250 起行带 startedAt(launch 真锚)⇒ elapsed 自算,不再依赖补偿链。
+            const started = r.startedAt;
+            if (typeof started === 'number' && started > 0 && started <= nowMs) {
+                return { ...r, elapsedMs: nowMs - started };
+            }
+            const meta = rowMeta.get(r.id);
+            if (!meta)
+                return r;
+            const idle = Math.max(0, nowMs - meta.receivedAt);
+            return idle > 0 ? { ...r, elapsedMs: (r.elapsedMs ?? 0) + idle } : r;
+        });
+        // ② 终态留存池:live 集没有的行在宽限窗内继续投影;被查看中的行不过期。
+        const retainedRows = [];
+        for (const [id, r] of retained) {
+            if (taskMap.has(id))
+                continue;
+            const isViewed = viewingTaskId !== undefined && rowIdTail(id) === viewingTaskId;
+            if (nowMs > r.expireAt && !isViewed) {
+                retained.delete(id);
+                continue;
+            }
+            retainedRows.push(r.row);
+        }
+        // ③ 行级 own 判别(clay 2026-07-23 双 session 串扰案,1.251 引擎对行帧广播,B 壳 FleetView
+        //    直接看到 A 壳的子代行)。与通知帧的台账判别对称 —— 行帧此前只有连接级 `?session=`
+        //    一道防线,server 旁路(≤1.252 无标行广播 / 无 auth 部署)即裸奔。
+        //    🔴 B6:第三腿 `rowSessionTag`(rootSessionId/ownerSessionId/sessionId)已删 —— 见文件头
+        //       G12 直证(server 1.291.0 `stripT`/`stripW` 把 sessionId 与 scope 双双剥掉,另两键
+        //       在行类型上从来不存在)。剩下的两腿一字未动。
+        //    诚实边界(码注声明):老引擎 + 壳重启/resume 场景,自己的历史行会被藏 —— 宁藏勿串;
+        //    1.244+ server 过滤在场时不受此限。
+        const allRowsById = new Map();
+        for (const r of [...liveRows, ...retainedRows])
+            allRowsById.set(r.id, r);
+        const ownTaskRow = (r) => {
+            if (sessionScopedMeta === true)
+                return true;
+            // 祖链闭包:孙代行 parentId=直接父(a… handle)而非 spawn run([1502] wire 事实)——
+            // 沿 parentId 链上溯,任一环(或环的 parentId)∈ 本端 run 台账即 own。
+            const seen = new Set();
+            let cur = r;
+            while (cur && !seen.has(cur.id)) {
+                seen.add(cur.id);
+                if (isOwnEngineRun(cur.id))
+                    return true;
+                if (cur.parentId !== undefined && isOwnEngineRun(cur.parentId))
+                    return true;
+                cur = cur.parentId !== undefined ? allRowsById.get(cur.parentId) : undefined;
+            }
+            return false;
+        };
+        const ownWorkflowRow = (r) => sessionScopedMeta === true || isOwnWorkflowRun(r.id);
+        return {
+            tasks: projectTasks([...liveRows, ...retainedRows].filter(ownTaskRow), {
+                rowFilter: opts.rowFilter,
+                ...(viewingTaskId !== undefined ? { viewingTaskId } : {}),
+            }),
+            workflows: projectWorkflows([...wfMap.values()].filter(ownWorkflowRow)),
+        };
+    }
+    return {
+        applyFrame(frame) {
+            if (disposed)
+                return;
+            applyFrame(frame);
+        },
+        setConnected(v) {
+            connected = v;
+        },
+        project,
+        status: () => ({
+            connected,
+            version,
+            scoped,
+            sessionScoped: sessionScopedMeta,
+            bgNotifyFailClosed: bgNotifyFailClosedMeta,
+            taskCount: taskMap.size,
+            workflowCount: wfMap.size,
+        }),
+        dispose() {
+            disposed = true;
+            liveBgViews.delete(bgView);
+        },
+        __rowsForTest: () => [...taskMap.values()],
+    };
+}

package/dist/fleet/fleetProjection.d.ts

@@ -0,0 +1,181 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 + §2.5 拆缝表):cli `src/sema/fleetClient.ts` 的
+ *    **投影半场** —— `coerceTaskStatus` / `coerceWorkflowStatus` / `deriveAgentLabel` /
+ *    `projectDescription` / `CONTROL_TOOL_VERBS` / `projectTasks` / `projectWorkflows` /
+ *    四个 `wire*` 读取器 + `TERMINAL_FLEET_TASK_STATUSES`。
+ *
+ * 留在 TUI 的(设计稿 §2.4.2-B「看着像库、其实是端」):`main` 合成行 / `selection` 游标 /
+ * `viewed` 的**所有者**(AppState.viewingAgentTaskId)/ `footerRowBelt.isFooterTaskRow` 的
+ * 「丢弃所有无 parentId 顶层行」—— 后者是端专属决策(主 run 由壳自己合成头部行渲染),
+ * 所以本文件的 `projectTasks` 把它做成**必填**的 `rowFilter`,不是可选钩子:
+ * 🔴 做成可选 = 端漏传时主 run 行会与端自己的头部行**双渲**,而两张都长得像对的
+ *    ([paired-mechanisms-must-share-premise] 的同族失败形)。必填 ⇒ 编译期就逼端表态。
+ *
+ * 🔴 SDK 0.0.117 提货(B6):`toolUses` / `transcriptId` / `currentTool` / `startedCount` /
+ *    `parentToolCallId` / `stoppedBy` / `usage` / `resumable` / `editedFiles` **全部已进
+ *    `FleetTaskRow`/`FleetWorkflowRow` 类型面** ⇒ 壳里那四个 "permissive read"(注释自述
+ *    「SDK 类型面滞后,bump 后可改直读」)本批**兑现成 typed 直读**;保留的只有**值域校验**
+ *    (`Number.isFinite`/`>=0`/非空串),那不是防御读,是 wire 脏值的诚实过滤。
+ */
+import type { FleetTaskRow, FleetWorkflowRow } from '@sema-agent/sdk';
+/** 渲染面的 fleet 状态词汇(cli `overrides/fleet-tree.tsx` 的 `FleetTaskStatus` 同集同序)。 */
+export type FleetTaskStatus = 'queued' | 'running' | 'waiting' | 'stopping' | 'awaiting approval' | 'idle' | 'completed' | 'failed' | 'killed';
+/**
+ * 投影后的一条 task 行。
+ * 🔴 与 cli `overrides/fleet-tree.tsx` 的 `FleetTask` **结构等同**(字段名/可选性/类型逐一对齐)——
+ *    渲染器类型留在端上(它是渲染契约),这里是产出侧类型。两侧漂移由 pure 门的键集断言钉死。
+ */
+export interface FleetTaskView {
+    id: string;
+    /** agent 身份名(187 `tjl`:agentName ?? agentType;都缺才退 objective 派生的单行 label)。 */
+    name: string;
+    /** 行正文 = 进度摘要,绝不是控制面工具动词。 */
+    description: string;
+    depth: number;
+    parentId?: string;
+    status: FleetTaskStatus;
+    elapsedMs: number;
+    tokens: number;
+    tokenDir: 'down' | 'up';
+    queuedCount: number;
+    awaitingPlanApproval?: boolean;
+    descendantCount?: number;
+    viewed?: boolean;
+    /** 🔴 三态:有键 ⇒ 真值(含真 0);缺键 ⇒ 「不知道」。绝不 `?? 0`。 */
+    toolUses?: number;
+    transcriptId?: string;
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
+    /**
+     * [1832] P1-2(server ≥1.290 / engine 1.432):发起本子代的父 tool_use id **原值**。
+     * B6 新落键 —— 归属不再靠猜,按 tool_use id 建卡树的消费端直接绑定。缺席 = 旧端。
+     */
+    parentToolCallId?: string;
+    /**
+     * [1839]①(server ≥1.291)**终态行帧四键**,只在终态帧出现、全部 tolerate-absent:
+     * 看行卡(不订通知帧)的 idle 观察者此前拿不到终局,现在拿得到。
+     * `resumable`/`editedFiles` **仅 bg 子代有源**(顶层 run 的 TaskResult 无这两位,永缺席、不造)。
+     */
+    stoppedBy?: string;
+    usage?: FleetRowUsage;
+    resumable?: boolean;
+    editedFiles?: Array<{
+        path: string;
+        edits: number;
+    }>;
+}
+/** 终态行帧 / bg 通知帧共用的 usage 形(SDK `FleetTaskRow.usage` ≡ `FleetBgNotification.usage`)。 */
+export interface FleetRowUsage {
+    totalTokens?: number;
+    toolUses?: number;
+    durationMs?: number;
+    tokens?: number;
+    turns?: number;
+    costMicroUsd?: number;
+}
+/** 投影后的一条 workflow 行(与 cli `FleetWorkflow` 结构等同)。 */
+export interface FleetWorkflowView {
+    id: string;
+    name: string;
+    description: string;
+    status: FleetTaskStatus;
+    doneCount: number;
+    totalCount: number;
+    elapsedMs: number;
+    tokens: number;
+    failedCount: number;
+    /** 🔴 缺席 ≠ 0:0 = 引擎说「一个都没起」,undefined = 老引擎「不知道」(退 done+failed 下界)。 */
+    startedCount?: number;
+}
+/**
+ * SDK `FleetTaskStatus` 的终态词汇 —— 非终态即在飞(未知未来值按在飞算,保守)。
+ * cli 侧 `engineBgGate.TERMINAL_STATUSES` 是**刻意的第二份**(零模块图污染),drift 由壳的
+ * `terminalStatuses.test.ts` 锁定 —— 本批不动那份。
+ */
+export declare const TERMINAL_FLEET_TASK_STATUSES: ReadonlySet<string>;
+/**
+ * 未来/未知 wire 状态 → 渲染词汇(闭集但读侧开集)。
+ *
+ * ⚠️ **B6 未删 `parked`,与任务书的 G11 指令相反 —— 理由与直证写在这里**:
+ *  · 直证(server 1.291.0 dist,`fleet/fleet-bus.d.ts` + `fleet-bus.js` 12 处 publishTask):
+ *    `FleetTaskStatus` 闭集**不含** `parked`,且每处 publishTask 的 status 都出自
+ *    `completed|failed|killed|running` 四值三元链 ⇒ 今天 `'parked'` 在 fleet 行 wire 上**不可达**,
+ *    这一支确实是死分支。
+ *  · 但**后果方向不对称**([anchor-on-the-deciding-quantity]「先定这个量门控动作的正负号」):
+ *    本支是**保护型**映射(把非活非终态的 parked 映到 'awaiting approval');删掉之后
+ *    它落 `default` ⇒ 渲成 `running` = **谎报活跃**。core 1.382 已有该状态([1561],
+ *    design/153 §7.1),server 只是尚未投影 ⇒ 这不是「猜测层」,是**预挂**。
+ *    删的收益 = 一行;删的代价 = server 补上透传那天静默说谎。
+ *  ⇒ 保留 + 把「候 server 预挂」的注释换成上面这条可复核的直证。定谳权交回 PM。
+ */
+export declare function coerceTaskStatus(s: string | undefined): FleetTaskStatus;
+/** 中性 workflow run 状态(running|completed|failed)→ 渲染词汇。 */
+export declare function coerceWorkflowStatus(s: string | undefined): FleetTaskStatus;
+/**
+ * 187 给 fleet 行命名用的是 agent 的**身份**,从不是它的 objective:
+ * `tjl(e) = e.type==="in_process_teammate" ? e.identity.agentName : e.agentType`
+ * (ui-modules/0616_053_uiux_ejl.js:20-21)。SDK `FleetTaskRow` 带 `agentType`/`agentName`
+ * (§K-7),所以这里**重建** tjl:`agentName`(in-process teammate 实例名)优先,否则 `agentType`
+ * (subagent_type/teammate 类型名)。只有引擎还没发身份时才退到 objective 派生的 `name` ——
+ * 折成单行、绝不整段多行 prompt、绝不空(187 的显示名恒是非空短身份)。全空 → 短 id 尾。
+ */
+export declare function deriveAgentLabel(agentType: string | undefined, agentName: string | undefined, name: string | undefined, id: string): string;
+/**
+ * 引擎把 fleet 行的 `description` 设成 agent 的**最后一个工具名**(service fleet-bus
+ * `description = ev.toolName`)。187 的行正文是进度摘要、从不是工具动词,所以控制面/合成动词
+ * 泄漏进行(clay 见过的 `report_blocked`)是纯分歧。这里压掉**已知**的控制面动词(保守集合),
+ * 真实工作工具(Read/Bash/Edit…)原样放行。
+ *
+ * 集合 = core `RESERVED_AGENT_NAMES`(subagent.ts)的 CC-parity PascalCase 形 + goal 模式的
+ * `DeclareDone`。引擎 ≥ core 1.176 经 `canonicalToolName` 发 PascalCase。
+ */
+export declare const CONTROL_TOOL_VERBS: ReadonlySet<string>;
+/** 行的活动正文:控制面动词 ⇒ 空(187 从不显示它),否则原样。 */
+export declare function projectDescription(description: string | undefined): string;
+/**
+ * `toolUses` —— 子代**累计**工具调用数。语义两条(接错会显示一个「看起来很合理」的错数字):
+ *  ① **累计不是增量** —— bg 子代 sink 的 usage 是累计口径,与 `turn_end` 的每轮增量相反。直取,绝不累加。
+ *  ② **缺席 ≠ 0** —— 老 server 不发这个键。有键 ⇒ 真值(含真 0);无键 ⇒ undefined(不知道)。
+ */
+export declare function wireToolUses(r: Pick<FleetTaskRow, 'toolUses'>): number | undefined;
+/** `transcriptId` —— 子代转录锚(core 铸的 childSessionId);委派 prompt 凭它去转录读面自取。 */
+export declare function wireTranscriptId(r: Pick<FleetTaskRow, 'transcriptId'>): string | undefined;
+/** `currentTool: {toolName, target?}` —— `currentAction` 的结构化同源体(core 1.429 → server 1.288)。 */
+export declare function wireCurrentTool(r: Pick<FleetTaskRow, 'currentTool'>): {
+    toolName: string;
+    target?: string;
+} | undefined;
+/** `startedCount` —— 「已起过的 agent 数」。🔴 缺席 ≠ 0(见 FleetWorkflowView 键注)。 */
+export declare function wireStartedCount(r: Pick<FleetWorkflowRow, 'startedCount'>): number | undefined;
+/** `parentToolCallId`(P1-2)—— 归属直读键。空串按缺席处理(引擎不该发,发了也别当真)。 */
+export declare function wireParentToolCallId(r: Pick<FleetTaskRow, 'parentToolCallId'>): string | undefined;
+/** 终态四键之 `usage`(数值 verbatim,只挑数字位;全脏 ⇒ 整键缺席,不造空对象)。 */
+export declare function wireRowUsage(r: Pick<FleetTaskRow, 'usage'>): FleetRowUsage | undefined;
+/** 终态四键之 `editedFiles`(bg 子代专属;脏项逐条丢,不整键丢)。 */
+export declare function wireEditedFiles(r: Pick<FleetTaskRow, 'editedFiles'>): Array<{
+    path: string;
+    edits: number;
+}> | undefined;
+/** 终态四键之 `stoppedBy`(开放枚举 verbatim:"user"/"parent"/"system"/…)。 */
+export declare function wireStoppedBy(r: Pick<FleetTaskRow, 'stoppedBy'>): string | undefined;
+/** 终态四键之 `resumable`(仅 bg 子代有源;非 boolean ⇒ 缺席,**不当 false**)。 */
+export declare function wireResumable(r: Pick<FleetTaskRow, 'resumable'>): boolean | undefined;
+export interface ProjectTasksOptions {
+    /**
+     * 🔴 **必填的端专属过滤器**(设计稿 §2.4.2-B):壳传 `filterFooterTaskRows`
+     * (丢无 parentId 顶层行 + workflow 双生行四判据);别的端按自己的树形状给。
+     * 想要「全都要」显式传 `rows => [...rows]` —— 必须写出来,不给缺省。
+     */
+    rowFilter(rows: readonly FleetTaskRow[]): FleetTaskRow[];
+    /** 正在被查看的 agent taskId(端的 `viewingAgentTaskId`);行 id 尾段等于它 ⇒ `viewed:true`。 */
+    viewingTaskId?: string | undefined;
+}
+/**
+ * wire task 行(Map values)→ 渲染行。树 depth/parentId 来自 wire:无 parentId = 顶层(depth 0),
+ * 子行挂在父下面,depth 沿 parent 链算(自引用/环由 `seen` 断)。
+ */
+export declare function projectTasks(allRows: readonly FleetTaskRow[], opts: ProjectTasksOptions): FleetTaskView[];
+/** wire workflow 行 → 渲染行。 */
+export declare function projectWorkflows(rows: readonly FleetWorkflowRow[]): FleetWorkflowView[];