@sema-agent/client-core 0.5.0 → 0.6.0

package/dist/request/taskRequest.d.ts

@@ -0,0 +1,135 @@
+/**
+ * request/taskRequest.ts — **请求面合一**(B4,多端改造设计稿 §3 B4 第二件 + §8-5 裁决)。
+ *
+ * ## 它解决的是什么
+ *
+ * 搬迁前壳里有 **三个**独立的请求构造器,谁也不知道对方长什么样:
+ *   · `S/seamQuery.toTaskRequest`(:535-869)—— 交互 REPL 车道;
+ *   · `S/seamQueryEngine`(:546-578)—— headless `-p` 车道,**自己另拼一份**;
+ *   · `S/liveClient.toLiveRequest`(:322-448)—— 两条车道共用的 live 兜底层。
+ *
+ * census §3.4 实测的漂移(B4 复核确认,逐字段见 `REQUEST_FIELD_MATRIX`):
+ *   · **print 独有** `finalVerification` / `limits` / `interactiveTools`;
+ *   · **TUI 独有** `ultracode` / `systemPrompt` / `reasoningEffort` / `images` / `model` /
+ *     rewind 三件 / `clientContext` / `scratchpadDir` / 已解析 settings。
+ * 这不是「两条车道本来就该不同」——里面**一部分是有理由的,一部分纯粹是漏了**。合一的目的不是
+ * 把它们抹平(那是行为改动),而是把「谁有谁没有、为什么」变成**一张表**:再漏就会在 diff 里显形。
+ *
+ * ## 分工铁律
+ *
+ * 🔴 本模块**零 env、零全局状态、零 IO**——所有值由端解析好之后放进 `TaskRequestInput`。
+ * 壳读 `process.env` / `getAppState()` / `getSessionId()` / `process.argv`,web 读 BFF 下发的配置,
+ * 桌面读主进程。包只负责三件**端无关**的事:
+ *   ① **字段集**:哪条车道 stamp 哪些字段(`REQUEST_FIELD_MATRIX`,带逐条理由);
+ *   ② **合并语义**:`settings` 四源合并、objective 的一次性装饰序、sessionId 三态;
+ *   ③ **live 门**:一个 `input.live` 布尔,替掉壳里散落的 20 处 `process.env.SEMA_LIVE_BASEURL` 判读。
+ */
+import type { TaskRequest } from '@sema-agent/sdk';
+/** 请求车道(§8-5:print lane 收编进来,但 stderr 分诊文案与 PrintStreamProjector 留壳)。 */
+export type RequestLane = 'interactive' | 'print';
+/** `TaskRequest` 的可写投影(包内按结构操作;SDK 型只做出口约束)。 */
+export type TaskRequestLike = Record<string, unknown>;
+/**
+ * 字段矩阵的一条 —— **这就是「不许静默统一」的载体**。
+ *
+ * `lanes` 是**事实**(今天哪条车道 stamp 它),`why` 是**理由**(为什么另一条没有)。
+ * 两者分开写:`lanes` 变了会被下面的自洽断言逮住,`why` 让下一棒知道该不该补齐。
+ * `gap:true` = 这条差异**没有正当理由,是漏的**(候补齐;补齐是行为改动,要单独一条测试)。
+ */
+export interface RequestFieldSpec {
+    field: string;
+    lanes: readonly RequestLane[];
+    /** 仅在 live 车道 stamp(mock/pty fixture 车道请求形状恒不变)。 */
+    live: boolean;
+    why: string;
+    gap?: true;
+}
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+export declare const REQUEST_FIELD_MATRIX: readonly RequestFieldSpec[];
+/** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
+export declare const LIVE_DEFAULT_FIELDS: readonly ["cwd", "additionalDirectories", "forwardSubagentEvents", "retainSubagentSessions", "agents", "appendSystemPrompt|settings.outputStyle", "suggestNextPrompts", "compactionModel", "sessionId(三态解析)"];
+/** 端解析好的输入 —— 每一项都是**值**,不是取值方式(取值方式属端)。 */
+export interface TaskRequestInput {
+    /** 本 turn 的模型面输入(已含 slash-skill 正文 / 注入式 meta / 历史种子等端侧组装)。 */
+    objective: string;
+    /** 壳会话 id(单命名空间);print 非 live 车道传 mock 常量。 */
+    sessionId: string;
+    /** live 车道(= 壳的 `process.env.SEMA_LIVE_BASEURL` 判真)。false ⇒ 全部 live-gated 字段不 stamp。 */
+    live: boolean;
+    scenario?: string;
+    systemPrompt?: string;
+    reasoningEffort?: string;
+    model?: string;
+    images?: readonly unknown[];
+    skills?: unknown;
+    mcpServers?: unknown;
+    agents?: unknown;
+    clientContext?: Record<string, unknown>;
+    scratchpadDir?: string;
+    sandboxImageProfile?: string;
+    permissionMode?: string;
+    selfOrchestration?: boolean;
+    deferTools?: readonly string[];
+    retainBackgroundProcesses?: boolean;
+    promptProfile?: string;
+    enableFork?: boolean;
+    attachments?: Record<string, unknown>;
+    finalVerification?: boolean;
+    limits?: Record<string, unknown>;
+    interactiveTools?: false;
+    /** rewind 三件(E18);端自己判空。 */
+    rewind?: Record<string, unknown>;
+    /** `settings` 的四个来源(端各自解析;本模块只负责合并序与「全空则不 stamp」)。 */
+    settings?: {
+        resolved?: Record<string, unknown>;
+        webSearch?: Record<string, unknown>;
+        ultracode?: boolean;
+        hooks?: Record<string, unknown>;
+        outputStyle?: string;
+    };
+}
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export declare function buildTaskRequest(input: TaskRequestInput, lane: RequestLane): TaskRequestLike;
+/** `applyLiveRequestDefaults` 的宿主输入(端解析好的值,同样零取值方式)。 */
+export interface LiveDefaultsInput {
+    cwd?: string;
+    additionalDirectories?: readonly string[];
+    agents?: unknown;
+    /** 引擎 caps 判真 ⇒ 走 `appendSystemPrompt` 一等位;否则借道 `settings.outputStyle`。 */
+    appendSystemPromptCapable: boolean;
+    /** 自我认知块的合并结果(端把既有值传进来,包只决定落哪个位)。 */
+    selfKnowledge?: {
+        forAppend: string;
+        forOutputStyle: string;
+    };
+    /** E12 opt-in(缺省关 —— 开着 = 每个 completed run 后端多跑一次 LLM pass)。 */
+    suggestNextPrompts?: boolean;
+    /** 三重门都过之后的 cheap 槽模型名;端负责 caps + 配置 + 目录同步校验。 */
+    compactionModel?: string;
+    /** 前一 turn 捕获的引擎 session id(连续性最高优先)。 */
+    capturedSessionId?: string;
+    /** 端的 mock session 常量(命中 ⇒ 删 sessionId 让引擎新铸)。 */
+    mockSessionIdConstant?: string;
+    /** 需要从 scenario 位剔除的 mock 关键字。 */
+    mockScenarioKeys?: ReadonlySet<string>;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export declare function applyLiveRequestDefaults(req: TaskRequestLike, host: LiveDefaultsInput): TaskRequestLike;
+/** 出口约束:构造结果确实是一个 `TaskRequest`(型只在这里碰 SDK,运行时零依赖)。 */
+export type BuiltTaskRequest = TaskRequest;

package/dist/request/taskRequest.js

@@ -0,0 +1,176 @@
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+export const REQUEST_FIELD_MATRIX = [
+    // ── 两条车道都有 ────────────────────────────────────────────────────────────────────────────
+    { field: 'objective', lanes: ['interactive', 'print'], live: false, why: '本 turn 的真实输入,两条车道都必需' },
+    { field: 'sessionId', lanes: ['interactive', 'print'], live: false, why: '单命名空间(TP-A Step 2):壳 id 即引擎 session id;print 在非 live 下保留 mock 常量' },
+    { field: 'scenario', lanes: ['interactive', 'print'], live: false, why: 'TUI 走 selectScenario(objective) 嗅探,print 走 --scenario/SEMA_HEADLESS_SCENARIO 显式值' },
+    { field: 'sandboxImageProfile', lanes: ['interactive', 'print'], live: true, why: '[686]② 显式 profile;auto 档只在 TUI 有(一次性 advisory 进 objective)' },
+    { field: 'permissionMode', lanes: ['interactive', 'print'], live: true, why: 'TUI 读 AppState.toolPermissionContext(带 stampDefault 门),print 读 flag>env(headlessPermissionModeWire)' },
+    { field: 'selfOrchestration', lanes: ['interactive', 'print'], live: true, why: 'SEMA_SELF_ORCHESTRATION opt-in → core 挂 run_workflow' },
+    { field: 'deferTools', lanes: ['interactive', 'print'], live: true, why: '[1052]① Workflow 延迟披露;selfOrchestration 前置门' },
+    { field: 'retainBackgroundProcesses', lanes: ['interactive', 'print'], live: true, why: '缺省 ON(clay 2026-07-26 翻转);SEMA_RETAIN_BACKGROUND=0 逃生' },
+    { field: 'promptProfile', lanes: ['interactive', 'print'], live: true, why: 'core 1.328 呈现轴 A/B 口,缺省不 stamp = 引擎缺省 simple' },
+    { field: 'enableFork', lanes: ['interactive', 'print'], live: true, why: '显式布尔才 stamp([503]② fail-OPEN 教训:off 必须显式)' },
+    { field: 'attachments', lanes: ['interactive', 'print'], live: true, why: 'design/133 + G1 缺省开的 turn 边界 attachment' },
+    { field: 'skills', lanes: ['interactive', 'print'], live: true, why: '本地 .claude/skills 投影;两条车道都由 launchRepl 载入面注入' },
+    { field: 'mcpServers', lanes: ['interactive', 'print'], live: true, why: '本地 .mcp.json 投影;service 单用户门决定是否兑现' },
+    { field: 'settings.webSearch', lanes: ['interactive', 'print'], live: true, why: 'SEMA_WEBSEARCH_* / settings.json;per-request 配置赢过部署 env' },
+    { field: 'settings.hooks', lanes: ['interactive', 'print'], live: true, why: '[495]① 用户 settings 文件 hooks 逐字上 wire' },
+    // ── print 独有(§8-5 认定的**有理由**的差异)──────────────────────────────────────────────
+    { field: 'finalVerification', lanes: ['print'], live: true, why: 'P1-1 终验:无人值守车道才需要引擎自证;交互 REPL 由人当场看结果。#106 裁 B(让位+告知)后交互面默认关' },
+    { field: 'limits', lanes: ['print'], live: true, why: 'P2-3-b:`-p` 的预算护栏(--max-* flag 族),交互 REPL 由人随时 Esc' },
+    { field: 'interactiveTools', lanes: ['print'], live: true, why: '[909]B 件3:无人值守 stamp false,从 roster 源头灭掉 AskUserQuestion/plan 门。交互车道 stamp false 等于自废武功' },
+    // ── TUI 独有 ────────────────────────────────────────────────────────────────────────────────
+    { field: 'settings.ultracode', lanes: ['interactive'], live: true, why: 'design/111:sticky `/effort ultracode` 拨盘 + 当轮关键词嗅探,两个来源都只在交互面存在', gap: true },
+    { field: 'systemPrompt', lanes: ['interactive'], live: false, why: 'CC QueryParams.systemPrompt;print 腿的 params 没有这一位' },
+    { field: 'reasoningEffort', lanes: ['interactive'], live: false, why: '`/effort` 拨盘存在 AppState,print 无 AppState', gap: true },
+    { field: 'model', lanes: ['interactive'], live: false, why: '`/model` 中途换模型读 toolUseContext.options.mainLoopModel;print 的模型走 MODEL_ID/--model 另一条路', gap: true },
+    { field: 'images', lanes: ['interactive'], live: false, why: '贴图提交是交互动作,`-p` 的 stdin 没有图片块' },
+    { field: 'resumeAt/rewindFiles/rewindFilesTo', lanes: ['interactive'], live: false, why: 'E18 `/rewind` 是交互命令' },
+    { field: 'clientContext', lanes: ['interactive'], live: false, why: 'IANA 时区 + 可选邮箱 → core 本地化 `# Environment` 的 today;print 同样跑在用户机器上,缺席让引擎误标 (UTC)', gap: true },
+    { field: 'scratchpadDir', lanes: ['interactive'], live: true, why: '[816]③ per-session 暂存目录;print 也有 session,缺席让 `-p` 的工具写不进 exemptDir', gap: true },
+    { field: 'settings.<resolved>', lanes: ['interactive'], live: true, why: 'settings resolver 的 effective 快照(hooks/env/model + 已解析权限);print 只带 webSearch+hooks 两键', gap: true },
+];
+/** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
+export const LIVE_DEFAULT_FIELDS = [
+    'cwd',
+    'additionalDirectories',
+    'forwardSubagentEvents',
+    'retainSubagentSessions',
+    'agents',
+    'appendSystemPrompt|settings.outputStyle',
+    'suggestNextPrompts',
+    'compactionModel',
+    'sessionId(三态解析)',
+];
+const laneHas = (field, lane) => REQUEST_FIELD_MATRIX.find(f => f.field === field)?.lanes.includes(lane) ?? false;
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export function buildTaskRequest(input, lane) {
+    const live = input.live;
+    /** stamp 门:字段在本车道的表里 ∧(非 live-gated ∨ 本次是 live 车道)∧ 值非空。 */
+    const on = (field, value) => {
+        if (value === undefined || value === null)
+            return false;
+        const spec = REQUEST_FIELD_MATRIX.find(f => f.field === field);
+        if (spec === undefined)
+            return false;
+        if (!spec.lanes.includes(lane))
+            return false;
+        if (spec.live && !live)
+            return false;
+        return true;
+    };
+    // settings 四源合并(cli 原式:任一存在则 stamp,全缺则整个 `settings` 键都不出现)。
+    // ultracode 只在交互车道进表 ⇒ print 传了也不 stamp(表说了算,不是调用方说了算)。
+    const s = input.settings ?? {};
+    const settingsOut = {
+        ...(laneHas('settings.<resolved>', lane) && live ? (s.resolved ?? {}) : {}),
+        ...(on('settings.webSearch', s.webSearch) ? { webSearch: s.webSearch } : {}),
+        ...(on('settings.ultracode', s.ultracode) ? { ultracode: s.ultracode } : {}),
+        ...(on('settings.hooks', s.hooks) ? { hooks: s.hooks } : {}),
+        ...(s.outputStyle !== undefined ? { outputStyle: s.outputStyle } : {}),
+    };
+    const out = {
+        objective: input.objective,
+        sessionId: input.sessionId,
+        ...(on('scenario', input.scenario) ? { scenario: input.scenario } : {}),
+        ...(on('systemPrompt', input.systemPrompt) ? { systemPrompt: input.systemPrompt } : {}),
+        ...(on('reasoningEffort', input.reasoningEffort) ? { reasoningEffort: input.reasoningEffort } : {}),
+        ...(on('model', input.model) ? { model: input.model } : {}),
+        ...(on('images', input.images) && (input.images?.length ?? 0) > 0 ? { images: input.images } : {}),
+        ...(on('skills', input.skills) ? { skills: input.skills } : {}),
+        ...(on('mcpServers', input.mcpServers) ? { mcpServers: input.mcpServers } : {}),
+        ...(on('resumeAt/rewindFiles/rewindFilesTo', input.rewind) ? input.rewind : {}),
+        ...(on('permissionMode', input.permissionMode) ? { permissionMode: input.permissionMode } : {}),
+        ...(on('sandboxImageProfile', input.sandboxImageProfile)
+            ? { sandboxImageProfile: input.sandboxImageProfile }
+            : {}),
+        ...(on('selfOrchestration', input.selfOrchestration) ? { selfOrchestration: input.selfOrchestration } : {}),
+        ...(on('deferTools', input.deferTools) ? { deferTools: input.deferTools } : {}),
+        ...(on('retainBackgroundProcesses', input.retainBackgroundProcesses)
+            ? { retainBackgroundProcesses: input.retainBackgroundProcesses }
+            : {}),
+        ...(on('promptProfile', input.promptProfile) ? { promptProfile: input.promptProfile } : {}),
+        ...(on('enableFork', input.enableFork) ? { enableFork: input.enableFork } : {}),
+        ...(on('attachments', input.attachments) ? { attachments: input.attachments } : {}),
+        ...(on('clientContext', input.clientContext) ? { clientContext: input.clientContext } : {}),
+        ...(on('scratchpadDir', input.scratchpadDir) ? { scratchpadDir: input.scratchpadDir } : {}),
+        ...(on('finalVerification', input.finalVerification)
+            ? { finalVerification: input.finalVerification }
+            : {}),
+        ...(on('limits', input.limits) ? { limits: input.limits } : {}),
+        ...(on('interactiveTools', input.interactiveTools) && input.interactiveTools === false
+            ? { interactiveTools: false }
+            : {}),
+        ...(Object.keys(settingsOut).length > 0 ? { settings: settingsOut } : {}),
+    };
+    return out;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export function applyLiveRequestDefaults(req, host) {
+    const out = { ...req };
+    if (out.cwd == null && host.cwd !== undefined)
+        out.cwd = host.cwd;
+    if (out.additionalDirectories === undefined && (host.additionalDirectories?.length ?? 0) > 0) {
+        out.additionalDirectories = [...(host.additionalDirectories ?? [])];
+    }
+    // C1 / design/144:交互与 headless 都常开 —— 不开则引擎不建 SubagentRetainLedger,
+    // 后台子代 SendMessage 唤醒直接 "session was not retained" 拒绝。老引擎按 body→spec 白名单
+    // 忽略未知字段,version-safe。
+    if (out.forwardSubagentEvents === undefined)
+        out.forwardSubagentEvents = true;
+    if (out.retainSubagentSessions === undefined)
+        out.retainSubagentSessions = true;
+    if (out.agents === undefined && host.agents !== undefined)
+        out.agents = host.agents;
+    if (typeof out.scenario === 'string' && host.mockScenarioKeys?.has(out.scenario)) {
+        delete out.scenario;
+    }
+    // 自我认知块双臂([1487]/[1478] R1 终形):caps 判真走一等位,否则借道 outputStyle。
+    // 两臂同一合并序(知识块恒前、调用方块恒后)——序由端在 selfKnowledge 里拼好,包只选位。
+    if (host.selfKnowledge !== undefined) {
+        if (host.appendSystemPromptCapable) {
+            out.appendSystemPrompt = host.selfKnowledge.forAppend;
+        }
+        else {
+            const settings = (out.settings ?? {});
+            out.settings = { ...settings, outputStyle: host.selfKnowledge.forOutputStyle };
+        }
+    }
+    // E12:与 verify/cascade 互斥(那两个返 result 非 streamed run ⇒ 400)。
+    if (out.suggestNextPrompts === undefined &&
+        out.verify === undefined &&
+        out.cascade === undefined &&
+        host.suggestNextPrompts === true) {
+        out.suggestNextPrompts = true;
+    }
+    if (out.compactionModel === undefined && host.compactionModel !== undefined) {
+        out.compactionModel = host.compactionModel;
+    }
+    // 单命名空间三态(cli 逐字):① 已捕获的引擎 session 赢(连续性 —— 引擎 session 绝不在
+    // 会话中途被换掉);③ 还带着 mock 常量 ⇒ 删掉让引擎新铸;② 其余保留(首 turn 壳 id 直传)。
+    if (host.capturedSessionId) {
+        out.sessionId = host.capturedSessionId;
+    }
+    else if (host.mockSessionIdConstant !== undefined &&
+        out.sessionId === host.mockSessionIdConstant) {
+        delete out.sessionId;
+    }
+    return out;
+}

package/dist/scratchpadWireCaps.d.ts

@@ -0,0 +1,16 @@
+export interface ScratchpadDirField {
+    scratchpadDir?: string;
+}
+/**
+ * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
+ * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
+ *
+ * 与 cli 的差分记账:
+ *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
+ *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
+ *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
+ *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
+ */
+export declare function scratchpadDirField(): ScratchpadDirField;
+/** 测试钩:复位 module 级建目录闩。 */
+export declare function _resetScratchpadEnsuredForTest(): void;

package/dist/scratchpadWireCaps.js

@@ -0,0 +1,65 @@
+/**
+ * ⇄ B4 批搬迁(2026-07-27,多端改造设计稿 §3 B4 第五件):cli `src/sema/scratchpadWireCaps.ts` 搬入。
+ * 拆缝 = 两条外向边换 host port:`utils/permissions/filesystem`(getScratchpadDir /
+ * isScratchpadEnabled / ensureScratchpadDir)→ `hostFs()`;`utils/debug.logForDebugging` → `hostLog()`。
+ * 本文件是 B2 判给 B4 的两件「宿主耦合 WireCaps」里的**小的那件**,同时充当 `FsPort` 的端到端证明。
+ */
+/**
+ * scratchpad 域的 wire 半场([816] 壳侧承诺③ / [819]④ / [820]③,2026-07-14)。
+ *
+ * 链路:core `TaskSpec.envFacts.scratchpadDir` 字段 + 提示词消费链(buildScratchpadSection)1.257.3
+ * 起全在;server 半场 = buildEnvFacts 填字段 + 建目录 + 塞进 createFsWriteGatePolicy 的 exemptDirs。
+ * 客户端把 getScratchpadDir()(CC 同型:`/tmp/claude-{uid}/{sanitized-cwd}/{sessionId}/scratchpad`)
+ * stamp 到 `TaskRequest.scratchpadDir` —— server 半场没到时字段发了引擎忽略 = 无害(additive 铁律);
+ * 到货后 server 以客户端带的路径为准(本机 TOC 引擎与壳同 fs,壳造的目录引擎直接可写),或自造(TOB 远端)。
+ *
+ * 🔴 [1840] 勘误:G3 `scratchpadDir` **不是死键** —— server 已把「死键」的说法收回改接单
+ * ([816]③/[820]③ additive 预挂)。别再按「没人读」把这条 stamp 删掉。
+ *
+ * 🔴 单实例纪律:本模块持 module 级 `ensured` 闩(整进程只 fire-and-forget 建一次目录)。
+ * 两份实例 = 建两次(幂等无害),但与本包其余台账同理,壳侧必须只解析到一份。
+ */
+import { hostFs, hostLog } from './host.js';
+let ensured = false;
+/**
+ * Per-turn scratchpadDir stamp。gate off(tengu_scratch)⇒ 空对象(请求形状不变,mock parity)。
+ * 路径 per-session 稳定(sessionId 定 getScratchpadDir),重复调用幂等。
+ *
+ * 与 cli 的差分记账:
+ *  · `ensureScratchpadDir` 在壳里是 async(mkdir 0o700),这里 **两种返回都吞**(端可给同步实现);
+ *    建失败只影响引擎首写时自建(server 半场也建),**不阻 turn** —— 与 cli 逐字同语义。
+ *  · fs 口缺席(浏览器宿主)⇒ 返回空对象 = 不 stamp。additive 字段缺席对引擎无害,
+ *    但会计一次 `hostPortMisses().fs`,让「Node 宿主漏装」与「浏览器本就没有」在自检里可区分。
+ */
+export function scratchpadDirField() {
+    try {
+        const fs = hostFs();
+        if (fs === undefined)
+            return {};
+        if (!fs.isScratchpadEnabled())
+            return {};
+        const dir = fs.getScratchpadDir();
+        if (!ensured) {
+            ensured = true;
+            try {
+                const r = fs.ensureScratchpadDir();
+                if (r !== undefined && typeof r.catch === 'function') {
+                    void r.catch((e) => {
+                        hostLog('debug', `scratchpadWireCaps: ensureScratchpadDir failed (non-fatal): ${String(e)}`);
+                    });
+                }
+            }
+            catch (e) {
+                hostLog('debug', `scratchpadWireCaps: ensureScratchpadDir threw (non-fatal): ${String(e)}`);
+            }
+        }
+        return dir !== undefined ? { scratchpadDir: dir } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 测试钩:复位 module 级建目录闩。 */
+export function _resetScratchpadEnsuredForTest() {
+    ensured = false;
+}

package/dist/seam.d.ts

@@ -80,7 +80,15 @@ export type ChromeEvent = {
     kind: 'retry_status';
     laneProof: LaneProof;
     status: unknown;
-} | {
+}
+/**
+ * footer 面板行事件(载荷 = 本包 `EngineAgentPanelEvent`,B1 已搬入)。
+ * 宿主消费义务:原样 `publishEngineAgentPanelEvent(event)`。
+ * 🔴 **session 常驻台账(`markEnginePanelTaskResident`/`clearEnginePanelTaskResident`)不在宿主义务里**
+ * —— B4 起由适配器**整臂自持**(读者 `isEnginePanelTaskResident` 也在本包,写读同包 = R4 纪律)。
+ * 宿主再写一遍不会更对,只会两臂打架。
+ */
+ | {
     kind: 'panel_task';
     laneProof: LaneProof;
     event: unknown;
@@ -149,10 +157,14 @@ export type ChromeEvent = {
 }
 /**
  * 一条终态 task_notification 抵达(引擎已 server-side steer-inject 过,壳侧只做记账)。
- * 宿主消费义务(cli 现役三件,缺一即回归):
- *  ① drop 壳队列里同 run 的 Path B 条目(workflow_complete/probe feeder),否则 idle
- *     auto-submit 会把同一完成再喂模型一遍(跨进程双投的壳侧半场);
- *  ② 非 background_bash:清 resident 台账(面板行终态由本帧落,不由 turn sweep 假结)。
+ * 宿主消费义务(cli 现役三件里 **B4 起只剩零件**——见下,本臂现在纯属「告知」):
+ *  ① ~~drop 壳队列里同 run 的 Path B 条目~~ → B2 起 `dropQueuedNotificationsForRun` 已在本包,
+ *     B4 起由适配器自己调(宿主只需在启动时 `installNotificationQueuePort`);
+ *  ② ~~清 resident 台账~~ → B4 起由适配器自己调(`clearEnginePanelTaskResident` 在本包)。
+ *  ⇒ 宿主对本臂的义务 = **可选的 UI 提示**(如"后台任务完成"toast)。<br>
+ *  🔴 配对纪律([paired-mechanisms-must-share-premise]):这两件从「宿主义务」改成「库自持」是
+ *     **整臂让位**,不是两边都做——宿主若仍照旧实现,两次 drop/clear 幂等无害,但**记号必须删**,
+ *     否则下一棒会以为库没做。
  * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
  * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
  * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
@@ -166,10 +178,14 @@ export type ChromeEvent = {
 }
 /**
  * 子代生命周期 hook 触发点(cli fireSubagentStartHook / fireSubagentStopHook)。
- * `guard:'if-started'` = 宿主必须先查自己的「已 fire Start」台账,没 fire 过 Start 的
- * taskId(workflow runId / 外来 id)绝不 fire Stop。
- * 宿主消费义务:fire SubagentStart/SubagentStop hooks(observe-only,fail-soft,永不阻塞流);
- * Start 对一个 taskId 一生只许一次(进程级台账去重,frame-lane-matrix #4)。
+ * 宿主消费义务:fire SubagentStart/SubagentStop hooks(observe-only,fail-soft,永不阻塞流)。
+ *
+ * 🔴 **B4 起「一生只许一次」的台账由适配器自持**(实例级 = 一个 session 一份,cli 的 module 级
+ * 等价物):`phase:'start'` 对同一 taskId **本臂只会发一次**,宿主收到就 fire,不必再去重。
+ * `guard:'if-started'` 同理已由适配器解掉——**只有真 fire 过 Start 的 taskId 才会收到带 guard 的
+ * stop**(cli `task_notification` 臂 `firedSubagentStartHookTaskIds.has()` 的等价面)。guard 字段
+ * 保留只为让宿主能识别这条 stop 的来源臂,**不是**要宿主再判一次(判据锚在能决定结果的量上:
+ * 台账在库里,宿主手上根本没有那个量)。
  */
  | {
     kind: 'subagent_lifecycle';
@@ -179,6 +195,44 @@ export type ChromeEvent = {
     agentType?: string;
     guard?: 'if-started';
 }
+/**
+ * B4 新臂 ①(A 层 `task_progress` 搬入)—— **inline 群组行**的累计统计(cli
+ * `engineInlineTaskStats` 的三个写口:`publishEngineInlineTaskTick` / `settleEngineInlineTaskStats`
+ * / `settleAllEngineInlineTaskStats`)。转录里那条 "Running N agents… ├ … 12 tool uses" 的数字面。
+ *
+ * 为什么与 `panel_task` 分臂:两者键不同 —— 本臂按**委派卡 id**(`cardId` = tool_use id,渲染面
+ * 的 AgentProgressLine 只有卡 id 在手),`panel_task` 按 **taskId**(footer 面板行)。同一 tick
+ * 同时喂两面是 cli 现役行为,合臂会逼消费端反解键。
+ *
+ * 宿主消费义务(三个 op 逐一,缺一即回归):
+ *  · `op:'tick'` → `publishEngineInlineTaskTick(cardId, stats)`(已 settle 的卡是 no-op);
+ *  · `op:'settle'` → `settleEngineInlineTaskStats(cardId, isError)`(冻结终值,幂等);
+ *  · `op:'settle_all'` → `settleAllEngineInlineTaskStats()`(turn 末/abort 的防御 sweep 孪生腿)。
+ * 三个函数本包已导出(B1 搬入),宿主直接转发即可,不必自己实现语义。
+ */
+ | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'tick';
+    /** 委派 tool_use id(渲染面订阅键)。 */
+    cardId: string;
+    stats: {
+        toolUses: number;
+        totalTokens: number;
+        durationMs: number;
+        currentAction?: string;
+    };
+} | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'settle';
+    cardId: string;
+    isError: boolean;
+} | {
+    kind: 'inline_task_stats';
+    laneProof: LaneProof;
+    op: 'settle_all';
+}
 /**
  * 带外后台 workflow 完成推送(service 1.75 Path B:引擎**没有** server-side 注入,壳负责喂模型)。
  * 宿主消费义务:把 `message`(模型面 `<task-notification>` 正文,适配器已按 core 同形铸好)
@@ -246,6 +300,24 @@ export type ChromeEvent = {
     laneProof: LaneProof;
     result: unknown;
 };
+/** `ChromeEvent` 的判别键(臂名)—— 覆盖率断言与宿主装配自检都锚在它上。 */
+export type ChromeArmKind = ChromeEvent['kind'];
+/**
+ * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
+ *
+ * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
+ * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
+ * 所以把义务做成**数据**而不是散落在注释里。
+ *
+ * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
+ * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
+ * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ */
+export declare const CHROME_ARMS: readonly {
+    kind: ChromeArmKind;
+    required: boolean;
+    duty: string;
+}[];
 /** 车道纪律一等公民([1617] 家族固化):chrome 事件构造必须携判别证明。 */
 export type LaneProof = {
     lane: 'main';

package/dist/seam.js

@@ -1,3 +1,33 @@
+/**
+ * chrome 臂**覆盖率断言出口**(§8-1 裁决的一半:client-core 定接口不定实现)。
+ *
+ * 用途:任何宿主(TUI / web / 桌面)在自检里遍历本表,对 `required:true` 的臂断言"我实现了消费口"。
+ * 不实现 = 该 UI 面在那个宿主上是**哑的**(不是报错,是静默没有)—— 这正是多端最容易漏的一类,
+ * 所以把义务做成**数据**而不是散落在注释里。
+ *
+ * `required` 判据:**不实现会让已发生的行为丢失**(转录/模型输入/hook/去重)⇒ true;
+ * 只影响可选装饰(spinner 计量、活体预览、chips)⇒ false。
+ * `duty` = 一句话义务(完整义务在上方每臂的注释里,那里是真源)。
+ */
+export const CHROME_ARMS = [
+    { kind: 'retry_status', required: false, duty: '渲/清 spinner 的重试覆盖层' },
+    { kind: 'panel_task', required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
+    { kind: 'bgshell_settle', required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
+    { kind: 'tasks_expand', required: false, duty: '展开 ctrl+t 任务面板' },
+    { kind: 'thinking_activity', required: false, duty: '开/收活体 "∴ Thinking…" 行' },
+    { kind: 'request_start', required: false, duty: 'spinner 置 requesting 态' },
+    { kind: 'stream_delta', required: false, duty: '渲活体预览 + 推进 responseLength' },
+    { kind: 'response_metrics', required: false, duty: '驱动 responseLength reducer(ttft/对账)' },
+    { kind: 'attachment', required: false, duty: '渲 attachment 行(必须带 default 臂)' },
+    { kind: 'notification_terminal', required: false, duty: '可选 UI 提示(记账已由库自持)' },
+    { kind: 'subagent_lifecycle', required: true, duty: 'fire SubagentStart/Stop hooks(去重已由库解)' },
+    { kind: 'workflow_notification_enqueue', required: true, duty: 'message 入完成通知队列,idle 时喂模型' },
+    { kind: 'task_ledger_sync', required: true, duty: '按 toolUseId 幂等落 TaskCreate/TaskUpdate' },
+    { kind: 'inline_task_stats', required: true, duty: 'tick/settle/settle_all 转发给 engineInlineTaskStats' },
+    { kind: 'prompt_suggestions', required: false, duty: '推 composer 上方 chips(绝不回喂模型)' },
+    { kind: 'last_turn_usage', required: true, duty: '落最近一次 turn 真 usage(statusline 回落源)' },
+    { kind: 'plan_review_park', required: true, duty: '弹 plan 审批卡(fail-soft,不挡后续终态帧)' },
+];
 /**
  * transcript id 确定性派生([1653] 定案):稳定键优先序 = 帧 id > seq > toolCallId;
  * 全缺才用 ctx.uuid()。同流重放 ⇒ 同 id 序列(往返守卫钉此不变量)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.5.0",
+  "version": "0.6.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",