@sema-agent/client-core 0.18.0 → 0.20.0

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.18.0
+**Version:** 0.20.0
 
 - **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

package/dist/adapt/arms.js

@@ -63,7 +63,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
             uuid: idOf(m),
             session_id: ctx.sessionId,
             parent_tool_use_id: null,
-        });
+        }, ctx.now());
         if (decision === 'reject' || decision === 'cancel') {
             // S1:一个结果关闭该 model response。**yield 之前**复位 —— 矩阵 §2.2 定性为
             // 「形不一致的技术债、不是缺陷」(L1 turn 级、下一句就 return、早退时无读者),
@@ -84,7 +84,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
                 },
                 uuid: idOf(m, decision),
                 session_id: ctx.sessionId,
-            });
+            }, ctx.now());
             return;
         }
         if (decision === 'error') {
@@ -104,7 +104,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
                 },
                 uuid: idOf(m, 'error'),
                 session_id: ctx.sessionId,
-            });
+            }, ctx.now());
             return;
         }
         // ⟨帧序耦合 1/7 + 3/7⟩ 开卡:后到的 task_progress 才猜得到父、后到的 tool_end 才关得掉卡。
@@ -130,7 +130,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
             uuid: idOf(m),
             session_id: ctx.sessionId,
             parent_tool_use_id: null,
-        });
+        }, ctx.now());
         text.markEmittedText();
     }
     const thinkingBlock = blocks.find(b => b?.type === 'thinking');
@@ -141,7 +141,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
             uuid: idOf(m, 'durable-thinking'),
             session_id: ctx.sessionId,
             parent_tool_use_id: null,
-        });
+        }, ctx.now());
     }
 };
 // ══ M5 纯投影臂(零适配器状态,类型即证明)══════════════════════════════════════════════════════
@@ -149,10 +149,10 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
 const userArm = function* (m, { ctx, idOf }) {
     if (m.message === undefined)
         return;
-    yield transcript({ ...m, uuid: idOf(m), session_id: ctx.sessionId });
+    yield transcript({ ...m, uuid: idOf(m), session_id: ctx.sessionId }, ctx.now());
 };
-const systemArm = function* (m, { idOf }) {
-    yield transcript(m);
+const systemArm = function* (m, { ctx, idOf }) {
+    yield transcript(m, ctx.now());
     // core 1.219 attachWorkingFiles:compact_boundary 可携 attachedFiles → CC 的
     // "Referenced file {path}" 行(post-compact attachment,零新 UI)。
     const attachedFiles = m.attachedFiles;
@@ -212,6 +212,47 @@ const workspaceChangedArm = function* (m, { idOf }) {
         attachment: { type: 'workspace_changed', cwd },
     });
 };
+/**
+ * FIX⑦(2026-08-07,黑板 [3017]/[3020])—— `human_input` 生命周期账本帧。
+ *
+ * 姿势抄同族的 `steering_injected` / `workspace_changed`(都是「引擎侧发生了一件事,壳记一笔」的
+ * 非持久帧,归 chrome),但**不走 `attachment` 臂**:那三条 attachment 是要在转录流里渲出一行给
+ * 用户看的东西,而本帧**不带正文** —— 没有可渲的内容。硬造一行「有人输入了什么」的空 attachment
+ * 就是在编内容。所以它有自己的 chrome 臂,宿主义务是「可选地记进审计/时间线」。
+ * 子流帧(带 parentToolCallId)同族让位:不上 leader 面。
+ */
+const humanInputArm = function* (m) {
+    if (typeof m.parentToolCallId === 'string')
+        return;
+    const carrier = typeof m.carrier === 'string' ? m.carrier : '';
+    if (carrier.length === 0)
+        return; // 无载体的账本行渲出去只是噪声(投影层已判 malformed,这里是第二道)
+    const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+    const rawActor = typeof m.actor === 'object' && m.actor !== null && !Array.isArray(m.actor)
+        ? m.actor
+        : undefined;
+    const actor = rawActor === undefined
+        ? undefined
+        : {
+            ...(str(rawActor.id) !== undefined ? { id: str(rawActor.id) } : {}),
+            ...(typeof rawActor.hostAsserted === 'boolean' ? { hostAsserted: rawActor.hostAsserted } : {}),
+            ...(str(rawActor.issuer) !== undefined ? { issuer: str(rawActor.issuer) } : {}),
+        };
+    yield chrome({
+        kind: 'human_input',
+        laneProof: MAIN,
+        carrier,
+        ...(str(m.inputId) !== undefined ? { inputId: str(m.inputId) } : {}),
+        ...(typeof m.sessionSeq === 'number' && Number.isFinite(m.sessionSeq) ? { sessionSeq: m.sessionSeq } : {}),
+        ...(str(m.source) !== undefined ? { source: str(m.source) } : {}),
+        ...(str(m.delivery) !== undefined ? { delivery: str(m.delivery) } : {}),
+        ...(str(m.issuer) !== undefined ? { issuer: str(m.issuer) } : {}),
+        ...(actor !== undefined && Object.keys(actor).length > 0 ? { actor } : {}),
+        ...(str(m.entryId) !== undefined ? { entryId: str(m.entryId) } : {}),
+        // 宿主幂等落账的键(codex 复审二轮):重放同一条账本帧必须得到同一个 eventId。
+        ...(str(m.eventId) !== undefined ? { eventId: str(m.eventId) } : {}),
+    });
+};
 const promptSuggestionsArm = function* (m) {
     // T57 第五处断闸(#47 矩阵 #5 同族):子流(parentToolCallId 标)的建议绝不骑主 composer。
     if (typeof m.parentToolCallId === 'string')
@@ -271,7 +312,7 @@ const toolEndResultArm = function* (m, { ctx, idOf, cards, panel }) {
                 timestamp: new Date(ctx.now()).toISOString(),
                 uuid: idOf(m, 'memory-saved'),
                 isMeta: false,
-            });
+            }, ctx.now());
         }
     }
     // ── E 层 ②:core 1.217 task 族 structured —— 权威全量态精确同步 ctrl+t 面板(引擎真实 id)。
@@ -467,7 +508,7 @@ const resultArm = function* (m, { ctx, idOf, text, cards, panel, flags }) {
                 uuid: idOf(m, 'terminal-text'),
                 session_id: ctx.sessionId,
                 parent_tool_use_id: null,
-            });
+            }, ctx.now());
             text.markEmittedText();
         }
     }
@@ -556,7 +597,7 @@ const taskNotificationArm = function* (m, { ctx, idOf, panel, inst }) {
         message: { role: 'user', content: [{ type: 'text', text: renderTaskNotificationXml(fields) }] },
         uuid: idOf(m),
         session_id: ctx.sessionId,
-    });
+    }, ctx.now());
 };
 /**
  * ⚠️ 本臂声明成 `ProjectionArmFn`(碰不到五个适配器状态模块),但它**有副作用** ——
@@ -632,6 +673,7 @@ export const ARMS = new Map([
     ['diagnostics', diagnosticsArm],
     ['steering_injected', steeringInjectedArm],
     ['workspace_changed', workspaceChangedArm],
+    ['human_input', humanInputArm],
     ['prompt_suggestions', promptSuggestionsArm],
     ['retry_status', retryStatusArm],
 ]);

package/dist/adapt/ids.d.ts

@@ -13,7 +13,7 @@ export declare const chrome: (event: ChromeEvent) => AdapterOutput;
  * 到 `SDKMessage` 的那一步仍是 cast:CC 词汇的字面形与 SDK 类型有已登记的分歧(DIVERGENCE-2/9),
  * 这条 cast 是**有意**的边界,不是偷懒。
  */
-export declare const transcript: (message: Frame) => AdapterOutput;
+export declare const transcript: (message: Frame, nowMs: number) => AdapterOutput;
 /**
  * [1653]:稳定键优先序 = 帧 id > seq > toolCallId,全缺才 ctx.uuid()。现役 wire 的稳定键落在
  * `uuid` 字段(§E2 core 铸的 eventId / stamp 铸的帧 id),故映到 `id` 位喂进去(见 SEAM-GAP-1)。

package/dist/adapt/ids.js

@@ -9,9 +9,18 @@ export const chrome = (event) => ({ plane: 'chrome', event });
  * 到 `SDKMessage` 的那一步仍是 cast:CC 词汇的字面形与 SDK 类型有已登记的分歧(DIVERGENCE-2/9),
  * 这条 cast 是**有意**的边界,不是偷懒。
  */
-export const transcript = (message) => ({
+export const transcript = (message, nowMs) => ({
     plane: 'transcript',
-    message: message,
+    // 到达时戳补齐(#185-A1 正位收编,2026-08-08;此前是壳 upstreamBridge.stampTranscriptArrival
+    // 的消费端补偿,注释明记「长线正位在 client-core 的 adapt 臂」):transcript 消息不变式=恒带
+    // timestamp——CC 在 content_block_stop 取 wall-clock,而 transcript 帧正是块收尾时到达,到达
+    // 时刻本身就是同一个量。只补缺席不覆盖(wire 哪天带了就用 wire 的);壳侧补偿臂保留为双保险
+    // (its ③:不覆盖已有值 ⇒ 本补齐生效后壳臂自然零触发)。
+    // [C114] 请托(web jsdom-adapt-parity 门 INCONCLUSIVE 实抓):时钟**必经 ctx.now()**(调用方
+    // 注入 nowMs)——裸 `new Date()` 违 DIVERGENCE-7 可重放纪律,确定性双跑逐字节对拍当场失判别力。
+    message: (typeof message.timestamp === 'string'
+        ? message
+        : { ...message, timestamp: new Date(nowMs).toISOString() }),
 });
 /**
  * [1653]:稳定键优先序 = 帧 id > seq > toolCallId,全缺才 ctx.uuid()。现役 wire 的稳定键落在

package/dist/adapt/textStream.js

@@ -35,7 +35,7 @@ export function createTextStream(ctx, idOf) {
         thinkingBlockOpen = false;
         // P2d:活体 "∴ Thinking…" 行在 committed 块落地的**同一刻**收掉(先收行再上消息,cli 同序)
         yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
-        yield transcript(msg);
+        yield transcript(msg, ctx.now());
     }
     /** 提交累积的文本段(cli takeAnswerSegment:#27 段序铁律——工具卡前/turn 末各 flush 一次)。 */
     function* takeAnswerSegment() {
@@ -53,7 +53,7 @@ export function createTextStream(ctx, idOf) {
         segmentAnchor = null;
         emittedAssistantText = true;
         textBlockOpen = false;
-        yield transcript(msg);
+        yield transcript(msg, ctx.now());
     }
     /** 合并后的活体增量下泄(cli drainLive:思考先于文本 = 持久臂序)。 */
     function* drainLive() {

package/dist/adapt/toolCards.js

@@ -68,7 +68,7 @@ export function createToolCardLedger(ctx, idOf) {
             toolUseResult: rich !== null ? rich.toolUseResult : (body.toolUseResult ?? body.content),
             // T7:wire 没带正文的诚实标记 —— 在场 = 这张卡没有真实执行结果(UI 显示决策留端)。
             ...(body.degraded !== undefined ? { _sema_degraded: body.degraded } : {}),
-        });
+        }, ctx.now());
     }
     /** 关一张卡的**唯一**实现:出栈 + S1 复位 + 铸卡,前两步恒在第一个 yield 之前。 */
     function* closeCard(p, end) {

package/dist/adapt.d.ts

@@ -50,7 +50,7 @@ export interface AdapterLedgerState {
 /** 本批覆盖清单——差分守卫按它区分「已覆盖臂必须逐字段等价」与「已声明未覆盖臂」。 */
 export declare const ADAPTER_COVERAGE: {
     /** 已落码的帧臂。 */
-    readonly frames: readonly ["assistant", "user", "stream_event", "turn_usage", "result", "system", "task_notification", "workflow_complete", "diagnostics", "steering_injected", "workspace_changed", "prompt_suggestions", "retry_status", "task_progress", "tool_end_result(label 补位 + 关卡 settle + response-id 复位 + 开卡台账出栈 + 经 cards.close 铸 tool_result)"];
+    readonly frames: readonly ["assistant", "user", "stream_event", "turn_usage", "result", "system", "task_notification", "workflow_complete", "diagnostics", "steering_injected", "workspace_changed", "human_input", "prompt_suggestions", "retry_status", "task_progress", "tool_end_result(label 补位 + 关卡 settle + response-id 复位 + 开卡台账出栈 + 经 cards.close 铸 tool_result)"];
     /** 已落码臂产出的 transcript 消息类目(差分守卫的比对域)。 */
     readonly transcriptKinds: readonly ["assistant_text", "assistant_thinking", "assistant_tool_use", "user_tool_result_decision", "user_task_notification", "system_passthrough"];
     /** B3(0.5.0)新落码的臂/半场 —— 从 todo 移过来的,别再在 todo 里留同名条目。 */

package/dist/adapt.js

@@ -31,6 +31,8 @@ export const ADAPTER_COVERAGE = {
         'diagnostics',
         'steering_injected',
         'workspace_changed',
+        // FIX⑦(2026-08-07):`human_input` 账本帧 —— 投 chrome 记账,**不铸 transcript 行**(不带正文)。
+        'human_input',
         'prompt_suggestions',
         'retry_status',
         'task_progress',

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -63,6 +63,17 @@ function assertNeverArm(_ev) {
  * 旧写法 `if (msg)` 在新返回型上恒真(对象永远 truthy),所以这是**必须点名**的一类改动。
  */
 export function eventToSdkMessage(ev, ctx) {
+    // ── raw 预分派 —— `human_input`(core 5.14.0 design/171 / server 7.4.0 SSE,黑板 [3017]/[3020])──
+    // 🔴 为什么必须在 switch **之前**:这条臂**还没进** SDK 6.3.0 的 `AgentEvent` union
+    //    (`dist/events.d.ts` 实扫:33 条臂里没有它),`case 'human_input'` 在 `ev.type` 上是编译错。
+    //    在 union 里的那天就把它搬进 switch —— 与 `workflow_complete` 当年那条 raw 预分派臂同样的
+    //    退役条件(那一条已于 sdk 6.2.0 兑现退役,先例在本文件 `case 'workflow_complete'` 头注)。
+    // 处置:server 侧对本帧的投影明写「**本帧不带正文**(core 的臂里就没有 text 字段),所以没有
+    //    内容脱敏面」。因此它是**生命周期账本帧**,不是转录物 —— 投成中性内部臂交给 chrome 面记账,
+    //    绝不铸 transcript 行(铸一行就是替引擎编一条它没说过的话)。
+    if (ev.type === 'human_input') {
+        return humanInputProjection(ev, ctx);
+    }
     switch (ev.type) {
         // service 1.75 — `workflow_complete`: an out-of-band background-workflow completion push, ridden onto
         // the session's next stream open (BEFORE the run's own events). Projects to a NEUTRAL internal arm;
@@ -404,6 +415,53 @@ export function eventToSdkMessage(ev, ctx) {
             return dropped('unknown_arm', String(ev.type ?? 'unknown'));
     }
 }
+/**
+ * `human_input` → 中性内部账本臂(见 `eventToSdkMessage` 顶部的 raw 预分派注释)。
+ *
+ * 白名单逐键挑(禁 spread),与 server 侧 `humanInputEventData` 的投影面同源:
+ *   · `inputId` / `sessionSeq` / `carrier` / `source` / `delivery` / `entryId` = 引擎铸的标识与枚举
+ *     值,非用户内容 ⇒ verbatim;
+ *   · `issuer` / `actor.id` / `actor.issuer` = 宿主从入口凭据派生的**身份串**(自由文本形)——
+ *     server 已 redact 过再上帧,本层只透传,不再二次加工(壳侧 UNTRUSTED-for-display);
+ *   · `actor.hostAsserted` = 消费端**唯一**能判「这个署名可信吗」的位(core 的 `[from …]` 渲染靠它
+ *     决定加不加 `(unverified)`)—— 剥掉它比剥掉 id 更坏:剩下一个看不出真假的名字。
+ *   · `principal` = **刻意不投影**(与 ToolApprovalFrame 的 principal 同裁:帧本就经 owner-scoped
+ *     流投递,租户身份不必由帧自述)。
+ * `carrier` 缺席 ⇒ `malformed`:一条既没有载体也没有正文的账本行,渲出去只是一行「有人输入了什么」
+ * 的噪声,而 dropped 至少会留痕。
+ */
+function humanInputProjection(ev, ctx) {
+    const str = (v) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+    const carrier = str(ev.carrier);
+    if (carrier === undefined)
+        return dropped('malformed', 'human_input');
+    const rawActor = typeof ev.actor === 'object' && ev.actor !== null && !Array.isArray(ev.actor)
+        ? ev.actor
+        : undefined;
+    const actor = rawActor === undefined
+        ? undefined
+        : {
+            ...(str(rawActor.id) !== undefined ? { id: str(rawActor.id) } : {}),
+            ...(typeof rawActor.hostAsserted === 'boolean' ? { hostAsserted: rawActor.hostAsserted } : {}),
+            ...(str(rawActor.issuer) !== undefined ? { issuer: str(rawActor.issuer) } : {}),
+        };
+    return projected(stamp(ctx, armBody({
+        type: 'human_input',
+        carrier,
+        ...(str(ev.inputId) !== undefined ? { inputId: str(ev.inputId) } : {}),
+        ...(typeof ev.sessionSeq === 'number' && Number.isFinite(ev.sessionSeq) ? { sessionSeq: ev.sessionSeq } : {}),
+        ...(str(ev.source) !== undefined ? { source: str(ev.source) } : {}),
+        ...(str(ev.delivery) !== undefined ? { delivery: str(ev.delivery) } : {}),
+        ...(str(ev.issuer) !== undefined ? { issuer: str(ev.issuer) } : {}),
+        ...(actor !== undefined && Object.keys(actor).length > 0 ? { actor } : {}),
+        ...(str(ev.entryId) !== undefined ? { entryId: str(ev.entryId) } : {}),
+        // 🔴 `eventId` 必须带到底(codex 复审二轮):durable 腿按 `Last-Event-ID` 续读会**重放**同一条
+        //    账本帧,而本地行 id 是现铸的 —— 审计/时间线消费者若没有引擎铸的稳定键,一次人工注入会被
+        //    记成多次。`inputId`/`entryId` 在公开形上都是可选的,`eventId` 是那个恒在的身份位。
+        ...(str(ev.eventId) !== undefined ? { eventId: str(ev.eventId) } : {}),
+        ...(str(ev.parentToolCallId) !== undefined ? { parentToolCallId: str(ev.parentToolCallId) } : {}),
+    })));
+}
 /**
  * CS-7 §2.7 — turn_end usage → CC `ModelUsage` (pinned name mapping;
  * costMicroUsd/1e6 → costUSD). Surfaced separately because the slice has no

package/dist/attachmentsWireCaps.d.ts

@@ -4,8 +4,7 @@
 /**
  * src/sema/attachmentsWireCaps.ts — design/133 + G1 turn-boundary attachments WIRE pure-projection:
  * the shell's intent → the top-level `TaskRequest.attachments` object the service normalizes
- * (spec-fields.ts normalizeAttachments, @sema-ai/server 1.128.0) → core `TaskSpec.attachments`
- * (all producers opt-in engine-side; core 1.253).
+ * (spec-fields.ts normalizeAttachments) → core `TaskSpec.attachments`.
  *
  * DEFAULT ON for the TOC live path ([487]② — CC parity): CC's own /compact announces the still
  * pending/running background tasks after compaction and notices newly-available deferred tools at
@@ -19,30 +18,94 @@
  *     only; interactive deployments stay byte-identical) is respected until a behavior leg says
  *     otherwise.
  *
- * Core wire contract (board [479] ask-2): literal-true unions — "off = DELETE the key, never send
- * false". This projection never emits `false`; OFF ⇒ `undefined` ⇒ no `attachments` field at all.
+ * ══ 🔴 FIX⑤(2026-08-07)—— 这个字段下面其实躺着**两族契约**,此前只实现了一族 ═══════════════
+ *
+ * 契约真源 = `@sema-agent/sdk` `types.d.ts` 的 `TaskRequest.attachments`(6.3.0 起 10 键)。
+ * 两族的「关」是两种**不同**的动作,混为一谈就必然有一族关不掉:
+ *
+ *  ① **literal-true 族**(7 员:todoReminder / changedFiles / planModeReminder / budgetUsd /
+ *     backgroundTasks / toolsDelta / mcpInstructions,外加取值型的 todoReminderMode):
+ *     引擎侧默认**关**,键在场即开。板 [479] ask-2 的原话是「off = DELETE the key, never send
+ *     false」—— 对这一族,发 `false` 是违约(核心根本没有「显式关」这个语义位),所以本模块对
+ *     它们**永不产出 false**:OFF ⇒ 键不出现。
+ *
+ *  ② **explicit-false 族**(2 员:agentListing / skillsListing):
+ *     它们在 core 里是 **DEFAULT-ON**,SDK 头注写死「`agentListing`/`skillsListing` 是 core
+ *     DEFAULT-ON —— **explicit false 才关**(1.254 起 false 真透传;更老 server 静默丢)」。
+ *     于是「删键」在这一族上的含义是**保持开着**,而不是关掉。旧的 `AttachmentsSpec` 把全部键
+ *     钉成 `?: true`,literal 类型层面就表达不出 `false` ⇒ 这两个 DEFAULT-ON 的附件**没有任何
+ *     路径可以关闭**(不是「难关」,是类型层封死)。本批把这两键的类型放宽成 `boolean` 并给出
+ *     产出 `false` 的路径。
+ *
+ * ── env 面(`SEMA_ATTACHMENTS`)的取值语法,以及为什么选这一种 ────────────────────────────────
+ * 目标是「**默认行为逐字节不变** + 有路可关 DEFAULT-ON 两键」,所以选了**在既有值上加逗号 token
+ * 列表**,而不是新开一个 env:
+ *   · 新开一个 env(如 `SEMA_ATTACHMENTS_OFF`)会让「附件面怎么配」有两个入口,而两个入口之间的
+ *     优先级又要再定义一次 —— 这类第二真源正是本仓反复登记的病族;
+ *   · 逗号 token 列表对**存量取值零影响**:`unset` / `full` / `all` / off 拼法四种老写法解析结果
+ *     逐字节不变(FIX7 段 ⑤ 有正面钉),新语法只在用户真写了逗号 token 时才被触发。
+ * 语法(逗号分隔,大小写不敏感,允许空白):
+ *   · `off|0|false|no|none`(整值)     ⇒ **真·全关**:literal-true 族一个不发(那一族的 off 就是
+ *                                        删键)+ DEFAULT-ON 两键发 `false`。
+ *     🔴 codex 复审 [medium](2026-08-07)判的真病:这一支此前直接 `return undefined`(不发字段),
+ *     而「不发字段」对 DEFAULT-ON 两键的含义**恰恰是保持开着** —— 一个叫 off 的总开关关不掉十件里
+ *     的两件,且用户没有任何办法察觉。旧行为在 <1.254 的 server 上与新行为**逐字节等价**(那些
+ *     server 静默丢 false),在 ≥1.254 上新行为才第一次兑现这个旋钮的字面承诺。
+ *     ⚠️ **能力边界说清楚**(codex 复审二轮):本模块是**纯 env→spec 投影**,手里没有 server
+ *     版本/capability 这个量,所以对 <1.254 的部署它兑现不了「全关」—— 那两键仍会默认开着,而
+ *     壳侧无从察觉。补这个洞的正位在**请求装配层**(按已探到的 capability 判,与 limitsWire 的
+ *     两道地板同族),已记进 docs/refactor/README.md 的宿主/上游工单表。本层只保证两件:
+ *     ① 新行为在任何 server 代际上都**不比旧行为差**(旧行为在所有代际上都关不掉那两键);
+ *     ② 不在自己的能力之外说大话 —— 所以上面那句「真·全关」的适用范围就是 ≥1.254。
+ *   · `full` / `all`                   ⇒ literal-true 族 7 员全开(**不含** DEFAULT-ON 两键 ——
+ *                                        不发 = 保持 core 默认开,壳不替 core 做那个决定)
+ *   · `default`                        ⇒ CC-parity 那一对(显式写出「默认」这个意思)
+ *   · `<key>` / `+<key>`               ⇒ 单点打开一个 literal-true 族成员
+ *   · `-agentListing` / `-skillsListing` ⇒ 产出 **`false`**(explicit-false 族唯一的关法)
+ *   · `todoReminderMode=baseline|off`  ⇒ 取值型键
+ * 🔴 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值 ⇒ **fail-loud 抛错**。
+ *    静默忽略是这条链上最坏的失效形:用户以为自己关掉了 agentListing,而请求照发、附件照进上下文,
+ *    并且没有任何一处会说出来。
  *
  * PURE — no env/file IO of its own (callers pass `env`), the verified wireCaps pattern. The CALLER
  * (seamQuery / the print-mode ask) gates the read to LIVE mode so the mock request shape never
  * changes.
  */
 import { type EnvLike } from './hostEnv.js';
-/** The env key the shell reads. An {@link envFlagOff} spelling(REF-CC-141 dup-02 单源:
- *  `0`/`false`/`no`/`off`/`none`)⇒ no stamp; `full|all` ⇒ all five producers; unset/anything else
- *  ⇒ the CC-parity default pair. */
+/** The env key the shell reads. 取值语法见文件头注 §env。 */
 export declare const ATTACHMENTS_ENV: "SEMA_ATTACHMENTS";
-/** Mirror of core `TaskSpec.attachments` (types.ts:1139) — literal-true unions. */
+/**
+ * Mirror of `@sema-agent/sdk` `TaskRequest.attachments`(6.3.0,`types.d.ts`)—— **10 键全镜像**。
+ * 两族的类型形不同,而这个不同**就是**契约本身(见文件头注):literal-true 族只能是 `true`
+ * (发 `false` 违约),DEFAULT-ON 两族是 `boolean`(`false` 才是它们的关)。
+ */
 export interface AttachmentsSpec {
     todoReminder?: true;
+    /** 取值型:`"baseline"` | `"off"`(缺席 = 引擎默认)。 */
+    todoReminderMode?: 'baseline' | 'off';
     changedFiles?: true | {
         maxFiles?: number;
     };
     planModeReminder?: true;
+    budgetUsd?: true;
     backgroundTasks?: true;
     toolsDelta?: true;
+    mcpInstructions?: true;
+    agentListing?: boolean;
+    skillsListing?: boolean;
 }
+/** 键面台账(机读位):加键必须同批登记,否则下方 `Covers` 双向钉编译红。 */
+export declare const ATTACHMENTS_SPEC_KEYS: readonly ["todoReminder", "todoReminderMode", "changedFiles", "planModeReminder", "budgetUsd", "backgroundTasks", "toolsDelta", "mcpInstructions", "agentListing", "skillsListing"];
+/** ② 族(core DEFAULT-ON,explicit false 才关)。 */
+export declare const ATTACHMENTS_DEFAULT_ON_KEYS: readonly ["agentListing", "skillsListing"];
 /**
- * ENV source → the `TaskRequest.attachments` stamp. Returns `undefined` (⇒ no field) on explicit
- * opt-out; the G1 pair by default; all five on `full`. Never `false` values (core contract).
+ * ENV source → the `TaskRequest.attachments` stamp.
+ *
+ * 恒返回一个对象:literal-true 族永远只出现 `true`(core 契约:off = 删键),而
+ * `agentListing`/`skillsListing` 只在被显式关掉时出现,值恒为 `false`(它们的 core 默认是开,
+ * 不发 = 不动那个默认)。返回型保留 `| undefined` 是给未来留位,今天没有分支产出它。
+ *
+ * @throws 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值(fail-loud:
+ *         静默忽略会让「我明明关了」与「它其实还开着」同时为真)。
  */
 export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;