@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/fleet/fleetProjection.js

@@ -0,0 +1,258 @@
+import { collapseLabel, taskDescFromName } from '../fleetTaskDesc.js';
+import { rowIdTail } from '../workflow.js';
+/**
+ * SDK `FleetTaskStatus` 的终态词汇 —— 非终态即在飞(未知未来值按在飞算,保守)。
+ * cli 侧 `engineBgGate.TERMINAL_STATUSES` 是**刻意的第二份**(零模块图污染),drift 由壳的
+ * `terminalStatuses.test.ts` 锁定 —— 本批不动那份。
+ */
+export const TERMINAL_FLEET_TASK_STATUSES = new Set([
+    'completed',
+    'failed',
+    'killed',
+]);
+/**
+ * 未来/未知 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 function coerceTaskStatus(s) {
+    switch (s) {
+        case 'queued':
+        case 'running':
+        case 'waiting':
+        case 'stopping':
+        case 'awaiting approval':
+        case 'idle':
+        case 'completed':
+        case 'failed':
+        case 'killed':
+            return s;
+        case 'parked':
+            return 'awaiting approval';
+        default:
+            return 'running'; // unknown future status → render as a generic live row (open-set fallback)
+    }
+}
+/** 中性 workflow run 状态(running|completed|failed)→ 渲染词汇。 */
+export function coerceWorkflowStatus(s) {
+    switch (s) {
+        case 'completed':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'killed':
+            return 'killed';
+        default:
+            return 'running';
+    }
+}
+/**
+ * 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 function deriveAgentLabel(agentType, agentName, name, id) {
+    const identity = collapseLabel(agentName ?? '') || collapseLabel(agentType ?? '');
+    if (identity)
+        return identity;
+    const collapsed = collapseLabel(name ?? '');
+    if (collapsed)
+        return collapsed;
+    const tail = rowIdTail(id).slice(-8);
+    return tail ? `agent ${tail}` : 'agent';
+}
+/**
+ * 引擎把 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 const CONTROL_TOOL_VERBS = new Set([
+    'Task',
+    'Fork',
+    'StructuredOutput',
+    'ReportBlocked',
+    'ReadToolResult',
+    'ToolSearch',
+    'DeclareDone',
+]);
+/** 行的活动正文:控制面动词 ⇒ 空(187 从不显示它),否则原样。 */
+export function projectDescription(description) {
+    const d = description ?? '';
+    return CONTROL_TOOL_VERBS.has(d.trim()) ? '' : d;
+}
+// ── wire 值域过滤器(B6:类型面已到货,这里只剩「脏值不当真」)──────────────────────────────────
+/**
+ * `toolUses` —— 子代**累计**工具调用数。语义两条(接错会显示一个「看起来很合理」的错数字):
+ *  ① **累计不是增量** —— bg 子代 sink 的 usage 是累计口径,与 `turn_end` 的每轮增量相反。直取,绝不累加。
+ *  ② **缺席 ≠ 0** —— 老 server 不发这个键。有键 ⇒ 真值(含真 0);无键 ⇒ undefined(不知道)。
+ */
+export function wireToolUses(r) {
+    const v = r.toolUses;
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+/** `transcriptId` —— 子代转录锚(core 铸的 childSessionId);委派 prompt 凭它去转录读面自取。 */
+export function wireTranscriptId(r) {
+    const v = r.transcriptId;
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** `currentTool: {toolName, target?}` —— `currentAction` 的结构化同源体(core 1.429 → server 1.288)。 */
+export function wireCurrentTool(r) {
+    const v = r.currentTool;
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const toolName = v.toolName;
+    if (typeof toolName !== 'string' || toolName.length === 0)
+        return undefined;
+    const target = v.target;
+    return {
+        toolName,
+        ...(typeof target === 'string' && target.length > 0 ? { target } : {}),
+    };
+}
+/** `startedCount` —— 「已起过的 agent 数」。🔴 缺席 ≠ 0(见 FleetWorkflowView 键注)。 */
+export function wireStartedCount(r) {
+    const v = r.startedCount;
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+/** `parentToolCallId`(P1-2)—— 归属直读键。空串按缺席处理(引擎不该发,发了也别当真)。 */
+export function wireParentToolCallId(r) {
+    const v = r.parentToolCallId;
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** 终态四键之 `usage`(数值 verbatim,只挑数字位;全脏 ⇒ 整键缺席,不造空对象)。 */
+export function wireRowUsage(r) {
+    const u = r.usage;
+    if (typeof u !== 'object' || u === null)
+        return undefined;
+    const out = {};
+    for (const k of ['totalTokens', 'toolUses', 'durationMs', 'tokens', 'turns', 'costMicroUsd']) {
+        const v = u[k];
+        if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** 终态四键之 `editedFiles`(bg 子代专属;脏项逐条丢,不整键丢)。 */
+export function wireEditedFiles(r) {
+    const v = r.editedFiles;
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v
+        .filter((f) => typeof f === 'object' &&
+        f !== null &&
+        typeof f.path === 'string' &&
+        f.path.length > 0 &&
+        typeof f.edits === 'number' &&
+        Number.isFinite(f.edits))
+        .map(f => ({ path: f.path, edits: f.edits }));
+    return out.length > 0 ? out : undefined;
+}
+/** 终态四键之 `stoppedBy`(开放枚举 verbatim:"user"/"parent"/"system"/…)。 */
+export function wireStoppedBy(r) {
+    const v = r.stoppedBy;
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** 终态四键之 `resumable`(仅 bg 子代有源;非 boolean ⇒ 缺席,**不当 false**)。 */
+export function wireResumable(r) {
+    return typeof r.resumable === 'boolean' ? r.resumable : undefined;
+}
+/**
+ * wire task 行(Map values)→ 渲染行。树 depth/parentId 来自 wire:无 parentId = 顶层(depth 0),
+ * 子行挂在父下面,depth 沿 parent 链算(自引用/环由 `seen` 断)。
+ */
+export function projectTasks(allRows, opts) {
+    const rows = opts.rowFilter(allRows);
+    const viewingTaskId = opts.viewingTaskId;
+    const byId = new Map(rows.map(r => [r.id, r]));
+    const depthOf = (r) => {
+        let d = 0;
+        let cur = r;
+        const seen = new Set();
+        while (cur?.parentId && byId.has(cur.parentId) && !seen.has(cur.id)) {
+            seen.add(cur.id);
+            d += 1;
+            cur = byId.get(cur.parentId);
+        }
+        return d;
+    };
+    // descendantCount:有多少行认这一行当爹(行尾的 " (+N)")。
+    const childCount = new Map();
+    for (const r of rows) {
+        if (r.parentId)
+            childCount.set(r.parentId, (childCount.get(r.parentId) ?? 0) + 1);
+    }
+    return rows.map(r => {
+        const toolUses = wireToolUses(r);
+        const transcriptId = wireTranscriptId(r);
+        const currentTool = wireCurrentTool(r);
+        const parentToolCallId = wireParentToolCallId(r);
+        const stoppedBy = wireStoppedBy(r);
+        const usage = wireRowUsage(r);
+        const resumable = wireResumable(r);
+        const editedFiles = wireEditedFiles(r);
+        const task = {
+            id: r.id,
+            name: deriveAgentLabel(r.agentType, r.agentName, r.name, r.id),
+            // 子行帧无 description → 从 name 复原任务描述(CC 锚:行正文恒显 description,不留空列)。
+            description: projectDescription(r.description) || taskDescFromName(r.name, r.agentType, r.agentName),
+            depth: depthOf(r),
+            ...(r.parentId !== undefined ? { parentId: r.parentId } : {}),
+            status: coerceTaskStatus(r.status),
+            elapsedMs: r.elapsedMs ?? 0,
+            tokens: r.tokens ?? 0,
+            // 🔴 wire 从无 tokenDir(#50 门禁盘出的真类型错:读点恒 undefined 曾靠 ?? 掩住)——恒壳侧缺省。
+            tokenDir: 'down',
+            queuedCount: r.queuedCount ?? 0,
+            awaitingPlanApproval: r.awaitingPlanApproval ?? false,
+            descendantCount: childCount.get(r.id) ?? 0,
+            // 198 isViewed:这一行就是被查看的那个 agent(行 id 尾段 = 引擎 taskId)。
+            viewed: viewingTaskId !== undefined && rowIdTail(r.id) === viewingTaskId,
+            // 🔴 「键缺席」与「值为 0/''」是两件事 —— 只有真给了才落键(下游据「键在不在」判三态)。
+            ...(toolUses !== undefined ? { toolUses } : {}),
+            ...(transcriptId !== undefined ? { transcriptId } : {}),
+            ...(currentTool !== undefined ? { currentTool } : {}),
+            ...(parentToolCallId !== undefined ? { parentToolCallId } : {}),
+            ...(stoppedBy !== undefined ? { stoppedBy } : {}),
+            ...(usage !== undefined ? { usage } : {}),
+            ...(resumable !== undefined ? { resumable } : {}),
+            ...(editedFiles !== undefined ? { editedFiles } : {}),
+        };
+        return task;
+    });
+}
+/** wire workflow 行 → 渲染行。 */
+export function projectWorkflows(rows) {
+    return rows.map(r => {
+        const startedCount = wireStartedCount(r);
+        return {
+            id: r.id,
+            // 187 workflow label = `e.summary ?? e.description`(短 label);折成单行,空 → 187 占位符。
+            name: collapseLabel(r.name ?? '') || 'Dynamic workflow',
+            description: projectDescription(r.description),
+            status: coerceWorkflowStatus(r.status),
+            doneCount: r.doneCount ?? 0,
+            totalCount: r.totalCount ?? 0,
+            elapsedMs: r.elapsedMs ?? 0,
+            tokens: r.tokens ?? 0,
+            failedCount: r.failedCount ?? 0,
+            ...(startedCount !== undefined ? { startedCount } : {}),
+        };
+    });
+}

package/dist/headlessPermissionModeWire.d.ts

@@ -0,0 +1,55 @@
+/**
+ * src/sema/headlessPermissionModeWire.ts — SEMA_HEADLESS_PERMISSION_MODE 部署旋钮
+ * (clay 拍板 2026-07-16:TB/bench 场景 headless `-p` 统一垫 bypassPermissions,对齐 CC bench 实跑的
+ * --dangerously-skip-permissions 姿势;落地形态 = 环境变量部署旋钮,产品缺省语义不动)。
+ *
+ * gap-check 现状(2026-07-16,db3c72f):
+ *   · `--permission-mode <mode>` CLI flag 存在(main.tsx:1042,choices = PERMISSION_MODES + 'manual'),
+ *     `--dangerously-skip-permissions` 亦在;但两者在 headless `-p` 车道【都不进 TaskRequest】——
+ *     seamQueryEngine.ask 自建请求从不 stamp permissionMode(交互 REPL 走 seamQuery →
+ *     permissionWireCaps.permissionModeField,print/headless 从不 stamp = server absent-mode)。
+ *   · 即:今天 `-p` 的权限面全靠 server 对 absent-mode 的缺省解释([830]① server 1.191 五模式解释层,
+ *     absent 不挂门)。core [885] 残余建议:显式垫,防未来缺省变化让 TB 静默变盘。
+ *
+ * 语义(件2 拍板逐字):
+ *   优先级:CLI flag 显式值 > SEMA_HEADLESS_PERMISSION_MODE env > 现状 absent-mode(env 是缺省态的
+ *   垫层,flag 恒赢——flag 在场时 env 完全不看,即使 flag 值不在 wire 词表内)。
+ *   值域 = 壳既有 wire permissionMode 词表(permissionWireCaps.PermissionMode:default / plan /
+ *   acceptEdits / bypassPermissions / auto——分类器批3 [907] server 五模式表,server ≥1.209 认
+ *   "auto")。非法 env 值 ⇒ 一次性 warn + 回落现状,绝不 fail 启动。
+ *   stamp 规则:
+ *     · flag 来源:非 default 的 wire 词直接 stamp(auto 自分类器批3 起入表);`default` 不 stamp
+ *       (= 今天 flag 的实际效果,零行为变化);wire 词表外的 flag 值(dontAsk/manual…是壳内部
+ *       模式,server 不认)不 stamp。
+ *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
+ *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
+ *   车道纪律:本模块只被 seamQueryEngine.ask(headless `-p`)import;交互 REPL(seamQuery)一根毛
+ *   不动——单测有 source-level lane proof(detachWire 同款)。
+ */
+import { type PermissionMode, type PermissionModeField } from './permissionWireCaps.js';
+import { type EnvLike } from './hostEnv.js';
+/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
+export declare const HEADLESS_PERMISSION_MODE_ENV = "SEMA_HEADLESS_PERMISSION_MODE";
+/** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
+ *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
+export declare const HEADLESS_PERMISSION_WIRE_MODES: readonly PermissionMode[];
+export type HeadlessPermissionResolution = {
+    /** 直接展开进 TaskRequest 的字段({} = 不 stamp,现状 absent-mode)。 */
+    fields: PermissionModeField;
+    source: 'flag' | 'env' | 'absent';
+    /** 非法 env 值的告警文案(调用层一次性打 stderr)。 */
+    warning?: string;
+};
+/**
+ * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
+ * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
+ * 返回 undefined = flag 车道未显式表态。
+ */
+export declare function permissionModeFromArgv(argv: readonly string[]): string | undefined;
+/**
+ * 解析 headless `-p` 的 permissionMode stamp。纯函数除告警 latch(同值只警一次)。
+ * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
+ */
+export declare function resolveHeadlessPermissionMode(argv: readonly string[], env?: EnvLike): HeadlessPermissionResolution;
+/** 测试钩子:重置一次性告警 latch。 */
+export declare function _resetHeadlessPermissionModeWireForTest(): void;

package/dist/headlessPermissionModeWire.js

@@ -0,0 +1,111 @@
+/**
+ * src/sema/headlessPermissionModeWire.ts — SEMA_HEADLESS_PERMISSION_MODE 部署旋钮
+ * (clay 拍板 2026-07-16:TB/bench 场景 headless `-p` 统一垫 bypassPermissions,对齐 CC bench 实跑的
+ * --dangerously-skip-permissions 姿势;落地形态 = 环境变量部署旋钮,产品缺省语义不动)。
+ *
+ * gap-check 现状(2026-07-16,db3c72f):
+ *   · `--permission-mode <mode>` CLI flag 存在(main.tsx:1042,choices = PERMISSION_MODES + 'manual'),
+ *     `--dangerously-skip-permissions` 亦在;但两者在 headless `-p` 车道【都不进 TaskRequest】——
+ *     seamQueryEngine.ask 自建请求从不 stamp permissionMode(交互 REPL 走 seamQuery →
+ *     permissionWireCaps.permissionModeField,print/headless 从不 stamp = server absent-mode)。
+ *   · 即:今天 `-p` 的权限面全靠 server 对 absent-mode 的缺省解释([830]① server 1.191 五模式解释层,
+ *     absent 不挂门)。core [885] 残余建议:显式垫,防未来缺省变化让 TB 静默变盘。
+ *
+ * 语义(件2 拍板逐字):
+ *   优先级:CLI flag 显式值 > SEMA_HEADLESS_PERMISSION_MODE env > 现状 absent-mode(env 是缺省态的
+ *   垫层,flag 恒赢——flag 在场时 env 完全不看,即使 flag 值不在 wire 词表内)。
+ *   值域 = 壳既有 wire permissionMode 词表(permissionWireCaps.PermissionMode:default / plan /
+ *   acceptEdits / bypassPermissions / auto——分类器批3 [907] server 五模式表,server ≥1.209 认
+ *   "auto")。非法 env 值 ⇒ 一次性 warn + 回落现状,绝不 fail 启动。
+ *   stamp 规则:
+ *     · flag 来源:非 default 的 wire 词直接 stamp(auto 自分类器批3 起入表);`default` 不 stamp
+ *       (= 今天 flag 的实际效果,零行为变化);wire 词表外的 flag 值(dontAsk/manual…是壳内部
+ *       模式,server 不认)不 stamp。
+ *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
+ *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
+ *   车道纪律:本模块只被 seamQueryEngine.ask(headless `-p`)import;交互 REPL(seamQuery)一根毛
+ *   不动——单测有 source-level lane proof(detachWire 同款)。
+ */
+import { permissionModeField } from './permissionWireCaps.js';
+import { hostEnv } from './hostEnv.js';
+/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
+export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
+/** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
+ *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
+export const HEADLESS_PERMISSION_WIRE_MODES = [
+    'default',
+    'plan',
+    'acceptEdits',
+    'bypassPermissions',
+    'auto',
+];
+/**
+ * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
+ * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
+ * 返回 undefined = flag 车道未显式表态。
+ */
+export function permissionModeFromArgv(argv) {
+    let mode;
+    let dsp = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--permission-mode') {
+            const v = argv[i + 1];
+            if (typeof v === 'string' && !v.startsWith('-')) {
+                mode = v;
+                i++;
+            }
+        }
+        else if (a?.startsWith('--permission-mode=')) {
+            mode = a.slice('--permission-mode='.length);
+        }
+        else if (a === '--dangerously-skip-permissions') {
+            dsp = true;
+        }
+        else if (a === '--') {
+            break; // POSIX 约定:-- 之后不是 flag
+        }
+    }
+    if (mode !== undefined)
+        return mode;
+    if (dsp)
+        return 'bypassPermissions';
+    return undefined;
+}
+// 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)
+let warnedInvalidEnv = false;
+/**
+ * 解析 headless `-p` 的 permissionMode stamp。纯函数除告警 latch(同值只警一次)。
+ * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
+ */
+export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
+    // 1) CLI flag 恒赢:flag 在场(含 wire 词表外的壳内部模式)⇒ env 完全不看。
+    const flagMode = permissionModeFromArgv(argv);
+    if (flagMode !== undefined) {
+        // permissionModeField 只放行 wire 已知的非 default 词;default/壳内部词 ⇒ {}(现状,零变化)。
+        return { fields: permissionModeField(flagMode), source: 'flag' };
+    }
+    // 2) env 垫层。
+    const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
+    if (raw === undefined || raw === '') {
+        return { fields: {}, source: 'absent' };
+    }
+    if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
+        // env 是显式垫层:五词全 stamp(含 default——stampDefault 显式垫,不依赖 absent-mode 缺省解释)。
+        return {
+            fields: permissionModeField(raw, { stampDefault: true }),
+            source: 'env',
+        };
+    }
+    // 3) 非法 env 值:一次性 warn + 回落现状(绝不 fail)。
+    const resolution = { fields: {}, source: 'absent' };
+    if (!warnedInvalidEnv) {
+        warnedInvalidEnv = true;
+        resolution.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="${raw}" is not a recognized permission mode (expected one of: ${HEADLESS_PERMISSION_WIRE_MODES.join(', ')}) — ignoring it, this run keeps the default permission behavior`;
+    }
+    return resolution;
+}
+/** 测试钩子:重置一次性告警 latch。 */
+export function _resetHeadlessPermissionModeWireForTest() {
+    warnedInvalidEnv = false;
+}

package/dist/headlessReconnectWire.d.ts

@@ -0,0 +1,96 @@
+/**
+ * src/sema/headlessReconnectWire.ts — 重连腿 M2 · R1 换车道续收(design/HEADLESS-RECONNECT-DESIGN.md
+ * §3 R1 + §6 M2,2026-07-16)。M1(detachWire 头 + 信号 cancel 兜底,2545900)已发运;本模块把
+ * engine-alive-idle 判死升级为「先重连、耗尽才判死」——但只在 headless `-p` detach 车道。
+ *
+ * 触发点(design §3,四条同时成立才进重连分支):
+ *   ① tasks/stream 以 SseIdleError 收场(流静默超 grace)——其它失败形态(engine-down/restarted/
+ *      4xx/断连 reset)原样穿透,现行路径一字不动;
+ *   ② headless `-p` ∧ detach 头已随首次 POST 发出——本 wrapper 只在 liveClient.tasks.stream 的
+ *      opts.headers 携带 x-detach-on-disconnect: 'true' 时套上(唯一 set 头的调用方 =
+ *      seamQueryEngine.ask;交互 REPL(seamQuery)与 headless-bg worker 都不传 headers ⇒ 源码级
+ *      证明这两条车道一根毛不动,断连=取消语义保持,铁律 5);
+ *   ③ durableTaskId 已捕获(X-Task-Id 早捕获,liveClient onResponse)——没有 id 无从换道,原样抛;
+ *   ④ 每次重连前置 probeEngineAlive(批 D /health 探针复用)——引擎死了绝不空等,原样抛走
+ *      现行 engine-down 判死。
+ *
+ * 铁律对表:
+ *   · signal.aborted 恒先行(铁律 3,seamQuery.ts:1073 契约):重试环每一轮入口先查 aborted,
+ *     用户中止绝不进重连分支(连探活都不做);续收中途 aborted → 干净 return(镜像 SDK parseSse
+ *     的 abort 语义),上游 print.ts 的 SIGINT 处置(M1 cancel 兜底)全权接管。
+ *   · 有界(铁律 5/任务 §4):每 run 最多 HEADLESS_RECONNECT_MAX=2 次壳级重连;耗尽 → 重抛
+ *     【原始】SseIdleError(对象恒原件,后续 diagnoseSseIdleTear 打 engine-alive-idle 标 →
+ *     seamQueryEngine 现行诚实判死文案,字节不变)。
+ *   · 15min STREAM_MAX_DURATION 硬顶(任务 §3):runs.events 车道被 cap 断开时,SDK sse.js
+ *     parseSse 自带 Last-Event-ID 立即重连(frame.id 锁存 → 重开带 lastEventId;无进展 5 连败
+ *     才放弃)——cap 重连发生在【同一次】openEvents 调用内部,计入同一次重连预算(不额外扣),
+ *     铁律 4「不动 SDK」同时满足:runs.events 消费面已有,本模块零 SDK 改动。
+ *   · 与 headless-bg 有界重发腿(bgTearResends)互斥:重发腿在 seamQuery.query(REPL 形 worker),
+ *     其触发词表本就只含 restarted/engine-down(seamQuery.ts:1143),engine-alive-idle 从不重发;
+ *     本重连腿只在 -p detach 车道。两腿车道 + 词表双重不相交,结构性互斥。
+ *
+ * ── R1 去重锚选型(任务书要求写明选型与理由)────────────────────────────────────────────────
+ * runs.events 车道:server streamRunEvents 把账本 seq 写成 SSE `id:` 行(formatEvent id: ev.seq),
+ * SDK sse.js 把 frame.id 回贴到 ev.id ⇒ 每个续收帧带单调递增数字 seq。锚 = lastSeenSeq:
+ *   a) 跨壳级 attempt 续传:第二次 openEvents 传 Last-Event-ID=lastSeenSeq(server 从其后回放);
+ *   b) 防双投:丢弃 seq ≤ lastSeenSeq 的重放帧(server 从头回放/416 回卷都兜住)。
+ * 首次换道(tasks/stream → runs.events):tasks/stream 帧无 id(SDK tasks.js 不回贴 frame.id,
+ * server sync 腿也不写 id: 行)⇒ 无从定位,只能从起点(不带 Last-Event-ID)拉。防双投依据 =
+ * server 实证(1.205/1.209 dist 逐行核对):sync /v1/tasks/stream 腿【不】逐事件落账(runs.js 的
+ * appendEvent 只在 async runs 腿与 resume 腿;sync 腿只 createRun + setTerminal(finalResult))⇒
+ * sync 腿 run 的账本在终局前恒空,从起点拉不存在「重放已消费帧」面;将来 server 若开始 sync 腿
+ * 落账,守卫 = ①终帧唯一(本 wrapper 首终帧即 return + adapter runStream 首终帧 return + 批 B
+ * 双帧守卫「恰一条 result」)②seq 锚(首帧起锁存,attempt 间绝不回放)③gap-check 记账:换道前
+ * 已消费的 delta 与账本聚合 text 事件无逐字节对齐关系,真正的精确锚需要 server 给 tasks/stream
+ * 帧发 id(引擎侧诉求,走黑板,非壳侧可解)。
+ *
+ * ── 账本空(现役 server sync 腿)时的续收降级(R1b)────────────────────────────────────────
+ * 同一实证的另一面:detach 后 run 后台跑完,账本无事件行,runs.events 只会心跳保活直到 run row
+ * 落终局,然后无终帧地收流(SDK 无进展 5 连败抛错)。此时 run 的终局【已在】run row 里
+ * (GET /v1/runs/:id → RunRecord.result = TaskResult,含完整最终文本)——续收环的 catch 里查
+ * run row:已终局 → 合成终帧(done{result} / failed)喂回同一消费管线,turn 以 rc=0 正常收尾,
+ * 最终答案全量保真(-p 的 result 面 = done.result.result 字符串,非增量拼接);未终局(还在跑/
+ * suspended)→ 计预算继续重试,耗尽才判死。中途 delta 的全帧保真(R1a 环)在账本有事件行时
+ * (resume 腿 run / 将来 sync 腿落账的 server)自动生效——两形态由同一环处理,帧结构差异
+ * (text/reasoning 聚合事件 vs *_delta)由 adapter eventToSdkMessage 既有 case 'text'/'reasoning'
+ * 消费面兜住。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。 */
+export declare const HEADLESS_RECONNECT_MAX = 2;
+/** GET /v1/runs/:id 的 run row 终局子集(SDK RunRecord;字段防御性读)。 */
+export interface RunRowLike {
+    status?: string;
+    result?: unknown;
+    errorCode?: string;
+    error?: string;
+}
+export interface HeadlessReconnectDeps {
+    /** 引擎 baseUrl(探活用;凭证不经本模块——openEvents/getRun 闭包自带)。 */
+    baseUrl: string;
+    /** X-Task-Id 早捕获读数(liveClient onResponse 闭包);null = 未捕获 ⇒ 不换道。 */
+    getTaskId: () => string | null;
+    /** runs.events 换道开流(liveClient 闭包 → client.runs.events;lastEventId = 去重锚续传)。 */
+    openEvents: (taskId: string, lastEventId?: string) => AsyncGenerator<AgentEvent>;
+    /** run row 终局读数(R1b 降级捞终局;失败返回 null,永不抛)。 */
+    getRun: (taskId: string) => Promise<RunRowLike | null>;
+    signal?: AbortSignal;
+    /** 测试注入位;缺省 = 批 D probeEngineAlive(/health,2s 预算)。 */
+    probeAlive?: (baseUrl: string) => Promise<boolean>;
+}
+/** run row → 合成终帧(R1b)。带 result 对象的引擎终态(全词表)合成 done{result}——与
+ *  tasks/stream 终帧字节同构,adapter terminalToSdkResult 全枚举分流([909]B1)原样生效
+ *  (timeout→error_max_turns、blocked→error_during_execution、park→[884]A1 臂);裸 failed
+ *  (无 result)合成 failed 事件。running / 无 result 的 park(可能还会被 approvals 解锁)null
+ *  —— 计预算继续重试,耗尽才判死。 */
+export declare function terminalEventFromRunRow(row: RunRowLike | null): AgentEvent | null;
+/**
+ * withHeadlessR1Reconnect(live, deps) — the M2 R1 lane-switch wrapper.
+ *
+ * 位置:liveClient.tasks.stream 管线【最内层】(demux/HITL 桥/captureSessionId/normalizeToolNames/
+ * diagnoseSseIdleTear 之内)——续收帧与合成终帧流经与 live 帧完全相同的下游包装(工具名规整、
+ * sessionId 捕获、HITL 桥、批 B 守卫),零特殊路径。重连成功 → 生成器以终帧正常 return ⇒
+ * diagnoseSseIdleTear/tearVerdict 永不介入,turn 正常收尾;耗尽/不可换道 → 重抛原始 SseIdleError,
+ * 外层打标 + 现行判死文案,字节不变。
+ */
+export declare function withHeadlessR1Reconnect(live: AsyncGenerator<AgentEvent>, deps: HeadlessReconnectDeps): AsyncGenerator<AgentEvent>;