@sema-agent/client-core 0.11.23 → 0.12.1

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.11.23
+**Version:** 0.12.1
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver
@@ -216,6 +216,8 @@ itself (FAILED names + skipped names + arithmetic reconciliation). All-SKIP repo
 | `scripts/run-streamjson-timing-honesty-test.mjs` | Stream timing & terminal honesty ([2084]): held errored fs-write results release on model progress; wall-clock timeout maps to `error_during_execution` with a truthful salvage note; the synthetic API-error assistant row carries the `<synthetic>` in-message sentinel |
 | `scripts/run-background-view-test.mjs` | `createBackgroundView` lifecycle: polling/notify pairing, per-source degrade (`501 → not-configured` vs `unavailable`), the capabilities `scheduler` probe, and dispose really aborting the in-flight fleet snapshot (pure projection lives in the pure suite's W-A segment) |
 | `scripts/run-fleet-view-keys-test.mjs` | The fleet projection views, **both directions**: `FleetTaskView`/`FleetWorkflowView` ⇄ their key lists (compile-pinned) ⇄ what a maximal/minimal row really projects, plus a wire-key coverage ledger (every `FleetTaskRow` key is either projected or carries a written reason why not) and a drift ledger against the shell's render contract. A one-directional assignability check is blind to optional keys — which is how `startedAt` was silently dropped |
+| `scripts/run-usage-verbatim-channel-test.mjs` | The two complementary usage disciplines (core 3.0.0 metering semantics): the CC `ModelUsage` mirror stays pure (five pinned keys, `totalInputTokens` has no seat), while the sema-owned channel forwards the engine `turn_end.usage` object **verbatim** (six keys, incl. `totalInputTokens`) via `last_turn_usage.engineUsage` / `handle.latestEngineUsage` — honest absence on pre-3.0.0 engines, no fabricated zeros |
+| `scripts/run-plan-review-decide-verify-test.mjs` | `decidePlanReview`'s post-decide honesty ([2315]/[2316], engine RB-471 family): a 2xx from the decide endpoint is **not** a terminal — the wire re-pulls the task status and words the outcome by the real shape (still-locked / legal new gate / genuinely left park / unverified), never claiming success it hasn't earned. Driven against a real fake-engine HTTP server through the shipped dist |
 | `scripts/run-public-surface-test.mjs` | The outward promises: the npm export surface baseline, the peer floor witness, and this README's claims |
 
 Each suite carries a floor that only moves up — a refactor that stops executing a group of

package/dist/adapter/downstream/turnUsageToModelUsage.d.ts

@@ -16,11 +16,25 @@
  * `maxOutputTokens` — the missing `contextWindow` denominator is mock-fill from
  * a static per-model table (contract 02 §2.7 VERIFY). Defaulted to 0 to satisfy
  * the CC `ModelUsage` shape without inventing a number.
+ *
+ * core 3.0.0 语义翻转注(2026-08-02,[2318] 提货):wire 的 `inputTokens` 从「含 cache 总量」
+ * 翻为「归一化未命中分量(cache-MISS)」。本映射**一个字节没动**,但语义上恰好从错变对 ——
+ * CC `ModelUsage.inputTokens` 的本义就是不含 cache 的 input_tokens(Anthropic API 同义),
+ * 旧协议下这里灌总量其实是跨层同名不同义病([C7] 家族)。总量(含 cache)自 3.0.0 起走
+ * `totalInputTokens`,在本文件的 CC 镜像里**没有座位**(CC 形状不承载非 CC 语义,[2295]),
+ * 消费方要总量请走逐字通道 {@link EngineTurnUsage}(runStream `engineUsage` 键)。
  */
 import type { AgentEvent } from '@sema-agent/sdk';
 import type { ModelUsage } from '../types.js';
-type TurnUsage = NonNullable<Extract<AgentEvent, {
+/**
+ * 引擎 `turn_end.usage` 的**逐字原形**(SDK 3.0.0 六键全必填,含 `totalInputTokens`)。
+ * [2295] 裁 ②(2026-08-02):sema 自有 usage 通道逐字透传这个对象,不做再策展的子集映射 ——
+ * 这次断链的根因就是「中间层五键定型丢多余键」。导出类型 = 通道的契约面(runStream 折叠点
+ * 的 `engineUsage` 键与宿主消费端同用这一个名字)。
+ */
+export type EngineTurnUsage = NonNullable<Extract<AgentEvent, {
     type: 'turn_end';
 }>['usage']>;
+type TurnUsage = EngineTurnUsage;
 export declare function turnUsageToModelUsage(usage: TurnUsage): ModelUsage;
 export {};

package/dist/adapter/runStream.d.ts

@@ -30,9 +30,16 @@
  */
 import type { AgentEvent } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext, type ModelUsage } from './types.js';
+import type { EngineTurnUsage } from './downstream/turnUsageToModelUsage.js';
 export interface RunStreamHandle {
     /** The latest folded turn usage (footer counters); updated on each turn_end. */
     latestUsage?: ModelUsage;
+    /**
+     * [2295] 裁 ② 逐字通道:与 latestUsage 同拍更新的引擎 `turn_end.usage` **原形**(六键含
+     * `totalInputTokens`)。镜像键求和≠总量(仅 cache 族一致时相等),总量消费面吃这份。
+     * 旧引擎(core <3.0.0)wire 缺形时为 undefined —— 诚实缺席,不造零值。
+     */
+    latestEngineUsage?: EngineTurnUsage;
 }
 export declare function isRunStreamActive(): boolean;
 export declare function runStream(events: AsyncIterable<AgentEvent>, ctx: EmitContext, handle?: RunStreamHandle): AsyncGenerator<SDKMessage>;

package/dist/adapter/runStream.js

@@ -81,6 +81,8 @@ async function* runStreamInner(events, ctx, handle = {}) {
             const isSubFlow = ev.parentToolCallId !== undefined;
             if (usage) {
                 handle.latestUsage = usage;
+                // [2295] 裁 ② 逐字通道:与镜像同拍存一份引擎原形(六键含 totalInputTokens)。
+                handle.latestEngineUsage = ev.usage;
                 // plugins 专项 G1(2026-07-21):同一折叠点多发一份给 lastTurnUsageStore——StatusLine
                 // 的 statusline 命令 stdin(context_window.current_usage)在消息面无 usage(seam 合成
                 // 消息不带)时回落到这里,claude-hud 类插件的 Context 条才有真值。sub-flow 的 turn_end
@@ -91,7 +93,9 @@ async function* runStreamInner(events, ctx, handle = {}) {
                 // 与原式同样**不 await**(fire-and-forget),sink 抛错不影响流(fail-soft 原语义)。
                 if (!isSubFlow && ctx.emitChrome) {
                     try {
-                        void ctx.emitChrome({ kind: 'last_turn_usage', laneProof: MAIN, usage });
+                        // engineUsage = [2295] 裁 ② 逐字原形(additive 键,契约见 seam.ts 本臂 doc):
+                        // 总量/命中率消费面吃它,镜像 usage 保纯。
+                        void ctx.emitChrome({ kind: 'last_turn_usage', laneProof: MAIN, usage, engineUsage: ev.usage });
                     }
                     catch { /* fail-soft — statusline 退回 null,原语义 */ }
                 }

package/dist/fleet/fleetProjection.js

@@ -320,6 +320,7 @@ export const FLEET_WORKFLOW_VIEW_KEYS = FLEET_WORKFLOW_VIEW_KEY_TUPLE;
 const FLEET_TASK_ROW_WIRE_KEY_TUPLE = [
     'id',
     'name',
+    'sourceLane',
     'description',
     'agentType',
     'agentName',
@@ -367,6 +368,9 @@ export const FLEET_WORKFLOW_ROW_WIRE_KEYS = FLEET_WORKFLOW_ROW_WIRE_KEY_TUPLE;
  * 腿上当场红,不给「悄悄没人管」留位置。
  */
 export const FLEET_TASK_ROW_KEYS_NOT_PROJECTED = {
+    sourceLane: 'SDK 3.0.0 新键([2070]① 让位半场:前台 delegation 复合 id 行带 "run-leg" 标)。两仓现零消费面 ——' +
+        '#95 纪律:没人读的键不盲投。已知潜在消费方=壳 wf-panel 的双生行过滤(现走 taskId 台账补偿),' +
+        '若迁到本键判别则届时投影并删本条(那是行为改动,单独批)。',
     agentType: '折进 `name`(deriveAgentLabel:agentName ?? agentType,都缺才退 objective 派生)——渲染契约只有一个身份列,187 的 tjl 同形。',
     agentName: '同 agentType:两位在本层合成一个身份 label,分开带出去等于把 187 的 tjl 规则推给每个消费端各写一遍。',
     workflowRunId: 'workflow 归属**不走行字段**:权威判定在 adapt 的 task_progress 臂(recordWorkflowAgentTaskId,判据④),端按 taskId 尾段查台账过滤双生行。行上再带一份 = 第二真源。',

package/dist/hitl/planReviewWire.js

@@ -119,7 +119,48 @@ export async function decidePlanReview(taskId, decision) {
     try {
         const body = await client.assistant.planReview(taskId, { decision });
         hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
-        outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${body?.status ?? 'unknown'}.`;
+        // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
+        // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
+        // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
+        // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
+        // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
+        let postStatus;
+        try {
+            const probe = makeEngineWireClient({
+                baseUrl: cfg.baseUrl,
+                ...(cfg.token ? { token: cfg.token } : {}),
+                principal: cfg.principal,
+                timeoutMs: 15_000,
+            });
+            const post = probe ? (await probe.runs.get(taskId)) : null;
+            postStatus = typeof post?.status === 'string' ? post.status : undefined;
+        }
+        catch (e) {
+            hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
+        }
+        // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
+        const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+        if (effective === 'needs_review') {
+            // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
+            // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
+            // 决定权经卡的重开路径还给用户)。
+            outcome =
+                `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
+                    `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
+                    `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
+        }
+        else if (effective === 'suspended') {
+            // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
+            outcome =
+                `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
+                    `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
+        }
+        else if (effective !== undefined) {
+            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
+        }
+        else {
+            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
+        }
     }
     catch (e) {
         // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。

package/dist/seam.d.ts

@@ -7,6 +7,7 @@
  * 往返守卫不变量:同流重放 ⇒ 同 id 序列。
  */
 import type { ModelUsage, SDKMessage } from '@sema-agent/agent-types';
+import type { EngineTurnUsage } from './adapter/downstream/turnUsageToModelUsage.js';
 /**
  * `AbortSignal` 的结构型(B3 扩容,SEAM-GAP-4)。
  *
@@ -327,11 +328,19 @@ export type ChromeEvent = {
  * 宿主消费义务:落「最近一次 turn 的真 usage」槽,供 statusline 类消费面在消息面取不到 usage
  * 时回落(不落 = 插件的 Context 条恒 0%,原病复发)。子流 turn_end **不发本臂**(判据同 §E2:
  * statusline 显示的是主会话窗口,子代 usage 会把 Context% 打成孩子的窗口占用)。
+ *
+ * `engineUsage`([2295] 裁 ② 逐字通道,2026-08-02 加,additive):引擎 `turn_end.usage`
+ * **整对象原形**(SDK 3.0.0 六键必填,含 `totalInputTokens`=归一化总输入含 cache)。
+ * `usage`(CC ModelUsage 镜像)保持纯净不加键 —— CC 形状不承载非 CC 语义;要总量/命中率的
+ * 消费面(context% 分子、cacheHitRate 分母)一律吃这份原形,别把镜像键求和当总量
+ * (求和等式仅 cache 族一致时成立,唯一硬保证=弱式 ≥,[2318])。optional:旧引擎
+ * (core <3.0.0)wire 无此形时缺席,消费方按诚实缺席处理,不造零值。
  */
  | {
     kind: 'last_turn_usage';
     laneProof: LaneProof;
     usage: ModelUsage;
+    engineUsage?: EngineTurnUsage;
 }
 /**
  * B3 新臂 ③(runStream 外向边切除,设计稿 §5.2 头号污染源)—— `done{status:"needs_review"}` +

package/dist/subagent/engineDelegatedPrompt.js

@@ -104,8 +104,10 @@ function contentOf(entry) {
  * prompt(这条判别就是「别把子代自己的消息当委派 prompt」的落点)。
  */
 export function delegatedPromptText(content) {
+    // 字符串形也要过信封剥离 —— 这条早退曾经绕过它(自家红测抓到:剥的是数组形,而真转录里
+    // 两种形都出现)。任何「返回 prompt 正文」的出口都必须经同一道剥离,否则就是半修。
     if (typeof content === 'string')
-        return content.trim() || undefined;
+        return stripEnvelopes(content);
     if (!Array.isArray(content))
         return undefined;
     const parts = [];
@@ -122,8 +124,28 @@ export function delegatedPromptText(content) {
         if (b.type === 'text' && typeof b.text === 'string')
             parts.push(b.text);
     }
-    const text = parts.join('\n').trim();
-    return text || undefined;
+    return stripEnvelopes(parts.join('\n'));
+}
+/**
+ * 剥掉委派 prompt 外面那两层**运行时信封**,再判空。
+ *
+ * 🔴 为什么必须剥(2026-08-01 真机实测):引擎会话里那条 user 消息的前 ~1330 字符是
+ * `<system-reminder>…技能不可用清单…</system-reminder>` 与 `<fork-boilerplate>…worker fork 交代…
+ * </fork-boilerplate>` 两层信封,真正的委派 prompt 排在后面。而详情页的 `displayPrompt` 只渲**前 300
+ * 字符** ⇒ 用户在「Prompt」标题下看到的是一份技能清单,不是他派下去的那句话。
+ *
+ * 判空也必须在剥完之后做:只有信封、没有正文的消息应当算**没有委派 prompt**(让取件腿如实留白),
+ * 而不是把信封当成 prompt 渲出去 —— 后者是「渲了个东西」冒充「渲对了东西」。
+ *
+ * 信封是**成对标签**,所以用配对正则整段剥;不配对(被截断等)时保守不动,宁可多渲也不吃掉正文。
+ */
+const PROMPT_ENVELOPE_TAGS = ['system-reminder', 'fork-boilerplate'];
+function stripEnvelopes(raw) {
+    let text = raw;
+    for (const tag of PROMPT_ENVELOPE_TAGS) {
+        text = text.replace(new RegExp(`<${tag}>[\\s\\S]*?</${tag}>`, 'g'), '');
+    }
+    return text.trim() || undefined;
 }
 /**
  * 从转录里挑出委派 prompt = **最后一条非 tool_result 的 user 消息**(倒扫)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.23",
+  "version": "0.12.1",
   "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",
@@ -28,11 +28,11 @@
   },
   "peerDependencies": {
     "@sema-agent/agent-types": ">=0.2.0",
-    "@sema-agent/sdk": ">=2.0.0"
+    "@sema-agent/sdk": ">=3.0.0"
   },
   "devDependencies": {
     "@sema-agent/agent-types": "^0.2.0",
-    "@sema-agent/sdk": "^2.0.0",
+    "@sema-agent/sdk": "^3.0.0",
     "esbuild": "^0.27.4",
     "typescript": "^6.0.2"
   }