@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/scenarioWire.js

@@ -0,0 +1,115 @@
+/**
+ * src/sema/scenarioWire.ts — `--scenario <name>` wire (clay 拍, 2026-07-15): expose the engine's
+ * REQUEST-LEVEL scenario routing axis on the headless `-p` path. The server has shipped scenario
+ * routing since day one (ai-agent-service capabilities/scenarios.ts — `TaskRequest.scenario` picks the
+ * tool roster + prompt provider per request: default / code-review / scan / oa / team + center-declared
+ * overlays); the shell simply never exposed the field to users. This module is the CLI face.
+ *
+ * PRECEDENCE (flag > settings > default):
+ *  a) `--scenario <name>` (explicit flag)                 → stamp `TaskRequest.scenario`.
+ *  b) `SEMA_HEADLESS_SCENARIO` env — the settings lane:   → stamp when no flag. Set it in the user
+ *     settings.json `env` block (seeded into process.env by the SAME 1a-envseed both the REPL boot and
+ *     printModeEngine run), the lane every other wire config rides (SEMA_SELF_ORCHESTRATION,
+ *     SEMA_WEBSEARCH_*, SEMA_ENABLE_FORK). One mechanism serves both "env var" and "settings file".
+ *  c) neither                                             → NO stamp = today's behaviour, verbatim.
+ *
+ * VOCABULARY = the server's scenario registry (builtin + center-declared). The shell does NOT
+ * pre-validate against it (the registry is deployment-side truth): an UNKNOWN name falls back to the
+ * `default` scenario server-side (scenarios.ts selectScenario — safe), and a center allowlist violation
+ * comes back as an honest 400 `scenario_not_allowed` (already rendered by scenarioNotAllowedCopy.ts).
+ * We only mirror the server's NAME-SHAPE rule (scenarios.ts:318 SCENARIO_NAME_RE) locally — same rule,
+ * earlier and cheaper, and it keeps prompt-looking values (whitespace etc.) from being eaten as a name.
+ *
+ * NOTE (mock-key shadow): the seam also uses `scenario` as the MOCK transcript selector
+ * (seamQuery.selectScenario / SEMA_SCENARIO). liveClient strips those mock keys before a live forward;
+ * a `--scenario` value that collides with a mock key (e.g. `bash`) is therefore equivalent to `default`
+ * on the live engine — which is exactly what the server would resolve for it anyway (no such scenario).
+ *
+ * SEMA_SCENARIO (the mock harness opt-in — "never spawn a real engine", printModeEngine.ts) is
+ * deliberately NOT reused here: it selects offline mock transcripts, not live engine routing.
+ */
+import { hostEnv } from './hostEnv.js';
+/** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
+export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+/** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
+export const HEADLESS_SCENARIO_ENV = 'SEMA_HEADLESS_SCENARIO';
+const USAGE_HINT = "sema: --scenario expects a scenario name (lowercase letters/digits/hyphens, starting with a letter, ≤32 chars).\n" +
+    '  --scenario <name>    route this run through the named engine scenario (deployment-defined tool\n' +
+    '                       roster + system prompt; unknown names fall back to the default scenario)\n' +
+    '  (no flag)            the default scenario — today\'s behaviour';
+/**
+ * Parse `--scenario` out of an argv slice (everything before a bare `--`; both `--scenario <v>` and
+ * `--scenario=<v>` forms — the sandboxWire idiom). No flag ⇒ `{ok:true}` with no scenario. Repeated
+ * flag ⇒ LAST wins (commander convention). Missing value / flag-shaped value / name-shape violation ⇒
+ * fail-LOUD parse error (never a silent default — a mis-typed routing choice must not quietly run on
+ * the wrong tool surface; same stance as `--sandbox`).
+ */
+export function parseScenarioArgv(argv) {
+    let scenario;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        let raw;
+        if (a === '--scenario') {
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                return { ok: false, error: USAGE_HINT };
+            }
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith('--scenario=')) {
+            raw = a.slice('--scenario='.length);
+        }
+        else {
+            continue;
+        }
+        const v = raw.trim();
+        // sandboxWire audit #17 lesson: a bare `--scenario` EATS the following positional — a value with
+        // whitespace is almost certainly the user's prompt; say exactly that instead of mis-parsing.
+        if (/\s/.test(v)) {
+            return {
+                ok: false,
+                error: `sema: --scenario got "${v.length > 48 ? `${v.slice(0, 48)}…` : v}" — that looks like your prompt, not a scenario name.\n` +
+                    'Put the flag AFTER the value form (--scenario=<name>) or keep the name and prompt as separate tokens.\n' +
+                    USAGE_HINT,
+            };
+        }
+        if (!SCENARIO_NAME_RE.test(v)) {
+            return { ok: false, error: USAGE_HINT };
+        }
+        scenario = v;
+    }
+    return { ok: true, ...(scenario ? { scenario } : {}) };
+}
+/**
+ * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +
+ * no stamp): a settings-file typo must not hard-brick every headless run the way an explicit flag
+ * typo fails the one run it was typed on.
+ */
+export function headlessScenarioFromEnv(env = hostEnv()) {
+    const v = env[HEADLESS_SCENARIO_ENV]?.trim();
+    if (!v)
+        return undefined;
+    if (!SCENARIO_NAME_RE.test(v)) {
+        // eslint-disable-next-line no-console
+        console.error(`[sema] ${HEADLESS_SCENARIO_ENV}="${v}" is not a valid scenario name (want ${String(SCENARIO_NAME_RE)}) — ignoring the settings default`);
+        return undefined;
+    }
+    return v;
+}
+/**
+ * Resolve the scenario for a headless `-p` submit: explicit `--scenario` flag > `SEMA_HEADLESS_SCENARIO`
+ * settings default > none (= the engine's default scenario, today's behaviour). Flag parse errors
+ * propagate fail-loud; the caller exits.
+ */
+export function scenarioForPrint(argv, env = hostEnv()) {
+    const parsed = parseScenarioArgv(argv);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.scenario)
+        return parsed;
+    const fromEnv = headlessScenarioFromEnv(env);
+    return { ok: true, ...(fromEnv ? { scenario: fromEnv } : {}) };
+}

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;
@@ -90,6 +98,20 @@ export type ChromeEvent = {
     taskId: string;
     status: string;
     outputPath?: string;
+}
+/**
+ * B5 新臂(#117a,E 层 Bash 分臂的**执行半场**)—— 模型发起的后台 Bash 回执被认出来了。
+ * 判定在库(`detectEngineBgShellReceipt`,纯文案锚定 + `run_in_background` 门);执行留宿主:
+ * 宿主消费义务 = ① 把 registration 发给自己的后台 shell 面板 store(壳 =
+ * `publishEngineBgShellPanelEvent`)② 登记「句柄 → 宿主 run」映射(壳 = `recordBgParentRun(
+ * taskId, getActiveEngineTaskId())`,[1501] A/B 寻址的硬证据)。
+ * 缺席 = ctrl+B 面板看不到这条后台命令(不是报错,是这一面在该宿主上哑掉)。
+ */
+ | {
+    kind: 'bgshell_register';
+    laneProof: LaneProof;
+    taskId: string;
+    registration: unknown;
 } | {
     kind: 'tasks_expand';
     laneProof: LaneProof;
@@ -149,12 +171,19 @@ 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 假结)。
- * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
- * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
+ * 宿主消费义务(cli 现役三件里 **B4 起只剩零件**——见下,本臂现在纯属「告知」):
+ *  ① ~~drop 壳队列里同 run 的 Path B 条目~~ → B2 起 `dropQueuedNotificationsForRun` 已在本包,
+ *     B4 起由适配器自己调(宿主只需在启动时 `installNotificationQueuePort`);
+ *  ② ~~清 resident 台账~~ → B4 起由适配器自己调(`clearEnginePanelTaskResident` 在本包)。
+ *  ⇒ 宿主对本臂的义务 = **可选的 UI 提示**(如"后台任务完成"toast)。<br>
+ *  🔴 配对纪律([paired-mechanisms-must-share-premise]):这两件从「宿主义务」改成「库自持」是
+ *     **整臂让位**,不是两边都做——宿主若仍照旧实现,两次 drop/clear 幂等无害,但**记号必须删**,
+ *     否则下一棒会以为库没做。
+ * 跨通道去重(「补发通道不得再注入模型一遍」)由**库自持**,不摊给宿主 —— B5 起台账回到
+ * `notifications.ts` 的 **module 级** `notifiedRunIds` / `cardEnqueuedRunIds`(0.6.0 曾放在适配器
+ * 实例上,与清账/记账的另一半不共享前提 = [1857] 那个缺口)。
+ * 🔴 宿主**不要**再在本臂上调 `markEngineWorkflowNotified` —— 库已在同一位置调过(幂等,
+ *   宿主照调无害,但记号该删:整臂让位,不是两边都做)。
  * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
  */
  | {
@@ -166,10 +195,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 +212,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 同形铸好)
@@ -207,6 +278,20 @@ export type ChromeEvent = {
     toolUseId: string;
     input: unknown;
 }
+/**
+ * B5 —— 同一台账的**第二个来源**:core 1.217([379])的 `task` / `task-list` structured 权威全量态。
+ * `source:'tool_use'` 那条是旧引擎兜底(从 input 重建),本条是引擎真实 id 的精确同步。
+ * 宿主消费义务:壳 = `handleEngineTaskStructured(structured)`(两路经 engineToShellTaskId 收敛)。
+ * 🔴 两条**不是**二选一 —— 旧引擎只有前者、新引擎两者都来且后者更准,宿主按幂等处理即可。
+ */
+ | {
+    kind: 'task_ledger_sync';
+    laneProof: LaneProof;
+    source: 'structured';
+    /** `'task' | 'task-list'`(白名单已在库内判过)。 */
+    structuredType: string;
+    structured: unknown;
+}
 /**
  * B3 新臂 ①(T38 三清的第三清 + T57 五处断闸的第五处)—— E12「下一步可问什么」建议**批**。
  * `suggestions: null` = 作废(turn 开场必发一次:上一轮的建议对新上下文是噪声,挂着不掉会让人
@@ -246,6 +331,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,34 @@
+/**
+ * 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: 'bgshell_register', required: true, duty: '后台 shell 面板行建行 + 登记「句柄→宿主 run」' },
+    { 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/dist/toolResult.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 引擎会在 `tool_end.structured` 顶层 `type` 上发的**全部**取值。
+ * 用途**不是**「只处理这些」——下面的 switch 只认得其中一部分,认不得的照旧走 text 回落;
+ * 用途是「**structured 在场**」这个判据本身:顶层 type 命中白名单 ⇒ 引擎这一版是发结构化的,
+ * 于是模型面正文的**正则反解**(T11 bash / T13+T24 task-output / T14 后台回执三代文案)退位。
+ * 反过来,一个 `{type:'something-else'}` 或裸对象**不算** structured 在场 —— 宁可回落到正则,
+ * 也不许把「有个对象」当成「引擎发了结构化」(判据锚在决定结果的量上:决定的是「该不该信正则」)。
+ * ⚠️ 与设计稿的口径差:任务书写「29 项」,[1840] 清单逐条数是 **30 项**(见交接报告「设计稿错漏」)。
+ */
+export declare const STRUCTURED_DETAIL_TYPES: ReadonlySet<string>;
+/** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
+export declare function structuredDetailType(structured: unknown): string | undefined;
+export declare function modelFacingParseCalls(): number;
+export declare function _resetModelFacingParseCountForTest(): void;
+export declare function parseModelFacingBash(text: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+} | null;
+/**
+ * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。
+ * 围栏是给模型看的注入防护,人类转录卡显示正文(clay 07-03 审计 #1/#9 视觉 bug 的修)。
+ */
+export declare function stripUntrustedFence(text: string): {
+    label: string;
+    body: string;
+} | null;
+/**
+ * T13 回落 —— 引擎 TaskOutput 的模型面正文(core task-registry.ts 的 bash/agent 两形,整体
+ * delimitUntrusted 包裹、label = `TaskOutput <id>`)反解回卡片槽位。`kind` 报哪一形命中,
+ * 'unknown' ⇒ 调用方回落原文。
+ */
+export declare function parseModelFacingTaskOutput(text: string): {
+    kind: 'bash' | 'agent' | 'unknown';
+    taskId?: string;
+    status?: string;
+    output?: string;
+};
+/**
+ * T14 回落 —— 后台回执**三代文案**正则(#117a:core ≥1.283 的 `Command running in background` 是
+ * 第三代)。structured bash 在场时由 `background`/`task_id` 位取代(见 `wireOutputToBody`)。
+ */
+export declare function parseBackgroundReceipt(text: string): {
+    taskId: string;
+} | null;
+/**
+ * T8 —— 压平非均匀 §E1 `output`(`string` | `(Text|Image)[]`)。
+ * ⚠️ 真源在 adapt.ts(A 层 settle 报告也用同一份),本文件只 import,别再写第二份。
+ */
+export type FlattenWireOutput = (output: unknown) => string;
+/** wire 没带 output 时的降级原因码(UI 显示决策留端;客户端绝不编造执行结果)。 */
+export declare const TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT: "wire_carried_no_output";
+export interface ToolResultBody {
+    content: unknown;
+    isError: boolean;
+    toolUseResult?: unknown;
+    /** 只在「wire 没带正文」时出现;在场 = 这张卡**没有真实执行结果**,不是空结果。 */
+    degraded?: typeof TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT;
+}
+/**
+ * T7 —— `tool_end.output === undefined`(events.d.ts:79 文档化的「工具没有正文」情形)时的卡体。
+ *
+ * cli 旧形:调 mock 注册表 `synthesizeToolIO(name, input)` **反造**一个结果体(stdout/hunks/匹配列表),
+ * 卡片于是显示「看起来像真的、但根本不是这次执行产物」的内容。§8-4 按宪法「诚实优先于产出」裁定
+ * 搬的时候就改掉:**输出诚实缺席 + degraded 标记**,由 UI 决定显示「结果不可用」。
+ * 🔴 `content` 保持**字符串**(件1:tool_result block content 恒字符串,裸对象经 /compact 直发
+ * provider = 400 invalid_request);空串 = 无正文,`degraded` 才是判别位。
+ */
+export declare function degradedToolResultBody(isError: boolean): ToolResultBody;
+/**
+ * 真实 §E1 `tool_end.output` → 卡片读的 typed 正文。
+ *
+ * B5 新增第 5 个入参 `structured`:**structured 在场 ⇒ 正则退位**(①)。
+ * 三臂:`bash`(T11/T14)· `taskoutput|task_output`(T13,无 structured 的老腿)· 泛化兜底。
+ * 🔴 `truncated` 只做中性提示,截断正文**绝不**回喂模型(events.d.ts:80-85)。
+ */
+export declare function wireOutputToBody(toolName: string, output: unknown, isError: boolean, truncated: boolean, flatten: FlattenWireOutput, structured?: unknown): ToolResultBody;
+/**
+ * design/64 CC-parity `toolUseResult`:引擎结构化细节 → 各卡 outputSchema **精确** typed 形
+ * (safeParse 过了才渲富卡,不过就回落 12 行文本兜底)。
+ * `structuredPatch` 在**这里**算(T20,core 裁定:引擎发 originalFile、客户端算 hunks)。
+ * 全部**防御读**:形状不认得 ⇒ null ⇒ 调用方回落 text 路径(降保真,绝不炸)。
+ */
+export declare function structuredToToolUseResult(structured: unknown, 
+/** 压平后的模型面正文 —— 有些形(task-output)只带 identity/status,正文仍在模型面。 */
+modelText?: string): {
+    toolUseResult: unknown;
+    isError?: boolean;
+} | null;
+export interface EngineBgShellRegistration {
+    kind: 'register';
+    /** 回执上的**引擎** task id(`task_id=…`,TaskOutput/TaskStop 的句柄)。 */
+    taskId: string;
+    /** Bash tool_use input 的 command(面板行的命令行)。 */
+    command: string;
+    /** 模型给了 description 才有。 */
+    description?: string;
+    /** 引擎模型面回执原文,逐字 —— 详情视图显示它(里面的 output-file 路径因此可见可复制)。 */
+    receipt: string;
+}
+export declare function detectEngineBgShellReceipt(rawInput: unknown, outputText: string | undefined): EngineBgShellRegistration | null;
+/**
+ * TodoWrite 清单卡:引擎不发 todo structured,全量新表骑在 tool_use INPUT 上 ⇒ 从它合成 typed 结果。
+ * `oldTodos` = 上一次的活体清单(调用方持:一个 session 一份,正是划删线 diff 要的粒度)。
+ */
+export declare function todoWriteToolUseResult(rawInput: unknown, oldTodos: unknown[], isError: boolean): {
+    toolUseResult: unknown;
+    isError: boolean;
+    newTodos: unknown[];
+} | null;
+/**
+ * ReportFindings(core 1.288 [811]b,引擎侧执行的合成回声工具):details 是 `{count, level?, findings}`
+ * **没有 type 判别位**(core synthetic-tools.js)⇒ B 层的 type-keyed switch 认领不了,按**工具名**认。
+ * 双腿:优先 wire structured;引擎没发就从 tool_use INPUT 合成(回声工具:input.findings ≡ output.findings)。
+ */
+export declare function reportFindingsToolUseResult(structured: unknown, rawInput: unknown): {
+    toolUseResult: unknown;
+} | null;