@sema-agent/client-core 0.7.0 → 0.8.1

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/hooksWireCaps.d.ts

@@ -0,0 +1,91 @@
+import { type EnvLike } from './hostEnv.js';
+import type { WireHooksConfig } from './finalVerifyWire.js';
+export type { WireHooksConfig };
+/** The env ESCAPE HATCH for the engine leg (see the block comment above). */
+export declare const GOAL_STOP_HOOK_WIRE_ENV = "SEMA_GOAL_STOP_HOOK_WIRE";
+export declare const CC_STOP_SEMANTICS_MIN_SERVER = "1.279.3";
+/**
+ * 引擎自报版本是否达到 CC Stop 语义线({@link CC_STOP_SEMANTICS_MIN_SERVER})。
+ *
+ * 🔴 三条纪律:
+ *   · **数值比较**,不是字典序(`1.9.0` < `1.279.0`,字符串比较会判反);
+ *   · **预发版不算达标**(`1.279.0-rc.1` 里那套可能还在改)——正则只认三段纯数字,带 `-` 的直接落
+ *     null ⇒ false;
+ *   · 读不出/探不到 ⇒ **false**(降级方向恒安全:老形在新引擎上仍能拦,新形在老引擎上一次都拦不住)。
+ */
+export declare function ccStopSemanticsFromVersion(version: string | undefined | null): boolean;
+/**
+ * 本会话连着的引擎是否具备 CC Stop 语义?判据 = live 车道的 `/v1/capabilities` 自报 `version`
+ * (engineCapsCache 的 boot-kick 缓存,与 `/health.version` 同源)。
+ *
+ * 🔴 「未判即降级」:caps 探测是构造期 fire-and-forget,`/goal` 真被敲下时通常早已落袋;万一没落袋
+ * 就按老引擎走(meta 也同步退档)——**宁可少承诺,不可多承诺**。
+ */
+export declare function engineCcStopSemantics(env?: EnvLike): boolean;
+/**
+ * Is the `/goal` Stop-hook engine leg armed? **Default ON** since 2026-07-26 — both of the premises
+ * that kept it opt-in were disproved by server-side behavior evidence ([1721]) and re-verified against
+ * a real engine + real model (cli scripts/run-goal-stop-hook-live-test.mjs). Set
+ * `SEMA_GOAL_STOP_HOOK_WIRE=0|false|no|off` to disarm (an operator escape hatch, not a default).
+ */
+export declare function isGoalStopHookWireArmed(env?: EnvLike): boolean;
+/**
+ * Register (or clear, with `null`) the session-scoped `/goal` Stop prompt hook that rides
+ * `settings.hooks.Stop` to the engine. Single-valued: a new goal replaces the previous one,
+ * exactly like CC 220's `Xdr` (remove-then-add). Projection is gated by
+ * {@link isGoalStopHookWireArmed} — storing is always safe, sending is not (yet).
+ */
+export declare function setWireSessionStopHook(prompt: string | null, opts?: {
+    /**
+     * 这条目标登记时,引擎是否已判定为 CC 语义档({@link engineCcStopSemantics})?
+     *
+     * 🔴 **为什么要在 set 那一刻锁存,而不是在 {@link hooksForWire} 里现读**:`/goal` 的 meta
+     * (对模型讲「会不会拦到条件成立为止」)是在 set 那一刻发出去的,而投影发生在随后每个 turn。
+     * 两处各读一次的话,caps 探测中途落袋就会造出「meta 承诺拦到底、投出去的却还是老门」的错配 ——
+     * 判据必须锚在**真正决定结果的那个量**上,而它只有一个:**这条目标登记时的档位**。
+     * 缺省 false ⇒ 不传就是老引擎档:翻档只能靠证据打开,不能靠默认值。
+     */
+    ccSemantics?: boolean;
+}): void;
+/** The currently registered `/goal` Stop prompt, or null (registered ≠ projected — see the gate). */
+export declare function getWireSessionStopHook(): string | null;
+/** 当前这条目标登记时锁存的档位(真 = 投裸条件,假 = 投壳自造的门)。 */
+export declare function getWireSessionStopHookCcSemantics(): boolean;
+/**
+ * 把 `/goal` 的**原始条件**包成一条对引擎 prompt 载体**可执行**的 Stop 门 prompt。
+ *
+ * 🔴 适用面(2026-07-26 提货批后):**只用于未达标线的引擎档**(见 {@link CC_STOP_SEMANTICS_MIN_SERVER})。
+ * 达标档起引擎自己按 CC
+ * 220 逐字组装(系统提示 + 会话转录 + `wrapCondition`),那一档投的是**裸条件** —— 见
+ * {@link ccStopSemanticsFromVersion} 与 {@link hooksForWire} 的分道。本函数保留,是 tolerate-absent
+ * 的实体:老引擎上退回它,仍能拦一次;删掉它等于在老引擎上静默失效。
+ *
+ * 🔴 为什么必须包(2026-07-26 live 围栏实测,不是设计偏好):CC 单进程的 prompt 钩子执行器
+ * (`src/utils/hooks/execPromptHook.ts`)会给条件**套一层系统提示**(「You are evaluating a hook…
+ * 回 `{ok:true}` / `{ok:false,reason}`」)**并把整段会话前置**,所以裸条件在 CC 那边能被真评估。
+ * 引擎侧的载体两样都没有:
+ *   · 无系统提示、无会话历史;
+ *   · Stop payload 的 `transcript_path` 是**空串**(server basePayload),评估者对本会话是**瞎的**;
+ *   · 判据 schema 也不同 —— core 只认 stdout JSON 的 `decision:"block"`。
+ * 实测(钉版 server 1.277.1 + core 1.416 + 真模型):裸条件 `the project contains a file named
+ * DONE.txt` 送过去,载体照样被调用,模型回的是**散文**(「I don't have direct access to your file
+ * system…」)⇒ `parseHookStdout` 拿不到 decision ⇒ **一次都不拦**。即:不包 = 每次停机白烧一次
+ * 模型调用、零效果。
+ *
+ * 所以这里把条件包成引擎契约里**能落地**的形状。诚实标注它**够不到 CC 的完整语义**:
+ *   · 能做到:每个 turn 的**第一次**停机尝试被拦下,目标原文重新注入给模型,逼它自查后再收尾
+ *     (`stop_hook_active` 为真时门自己收手 ⇒ 不会无限拦停);真正「条件是否成立」的判断交给
+ *     **有会话、有工具的主模型**,而不是让瞎的评估者假装判断;
+ *   · 做不到:CC 那种「拦到条件真成立为止」(需要引擎把 transcript 交给载体)、以及「条件满足后
+ *     自动清除目标」。这两条是**等件**,meta 文案因此不照抄 CC `Pwo`(见 cmd-goal.tsx)。
+ *
+ * 台账仍存**原始条件**({@link getWireSessionStopHook}),所以 `/goal clear` 读回的是用户写的那句。
+ */
+export declare function buildGoalStopHookPrompt(condition: string): string;
+/**
+ * The merged, GOVERNANCE-GATED settings-file hooks for the wire, or undefined when none apply.
+ * Per-event arrays concatenate across sources (policy → user → project → local).
+ */
+export declare function hooksForWire(): WireHooksConfig | undefined;
+/** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
+export declare function __resetHooksWireCapsForTests(): void;