@sema-agent/client-core 0.3.0 → 0.4.0

package/README.md

@@ -84,13 +84,35 @@ keys).
 0.2.0 is the repo/name migration: **no behaviour change**, both guard suites carried over and
 green (22 + 203 checks).
 
+0.3.0 moved in the **dependency-free pure functions and side-channel ledgers** (subagent content,
+engine agent-panel, fleet panel projection, live question store, inline task stats, print
+tool-result frame, caps cache, tool-label store, task-description projection) with 140 new
+behaviour checks.
+
+0.4.0 moved in the **request-shaping gate family and the notification family**:
+
+- `notifications.ts` absorbed the whole background-completion subsystem — the process-lifetime
+  dedup ledgers (model-notification vs completion-card are **separate key spaces**), the idle
+  completion watcher for workflow + background-agent runs, the outstanding-run counter with its
+  subscription, the own-run ledger used for frame ownership, the delivery-failure supplement, and
+  the `hook_notice` classifier half (ownership fail-closed mirrored from the server).
+- 17 `*WireCaps` projections (attachments, client context, cloud config, fork, images, mcp, model,
+  permission, prompt profile, retain-background, rewind, self-orchestration, skills, ultracode,
+  web search, agents, plus the wire client factory), the SSE idle triage, the classifier-verdict
+  recogniser, the control router, and the model-budget/catalog/latch/effort rules.
+- New `hostEnv.ts`: the single host-environment read port. The moved projections used to default
+  their `env` parameter to `process.env`, which throws in a browser; they now default to
+  `hostEnv()` (the very same object under Node, `{}` where there is no `process`).
+- 🔴 One host assembly duty: `installNotificationQueuePort()`. Without it, task-notification
+  delivery is dropped — `notificationQueuePortMisses()` must stay 0.
+
 Known intentional deltas from the CLI are enumerated in `ADAPTER_DIVERGENCES`.
 
 ## Guards
 
 ```bash
 npm install
-node scripts/run-client-core-pure-test.mjs   # 22 consumer-view checks; no CLI tree needed
+node scripts/run-client-core-pure-test.mjs   # 370 consumer-view checks (22 + 140 + 208); no CLI tree needed
 node scripts/run-client-core-diff-test.mjs   # 203 checks: differential + replay-id + ledger
 ```
 

package/dist/agentsWireCaps.d.ts

@@ -0,0 +1,112 @@
+export declare const MAX_TASK_AGENTS = 32;
+export declare const MAX_AGENT_NAME_CHARS = 64;
+export declare const MAX_AGENT_TEXT_CHARS = 4096;
+export declare const MAX_AGENT_SYSTEM_PROMPT_CHARS = 65536;
+export declare const MAX_AGENT_TOOLS = 64;
+export declare const MAX_AGENT_TOOL_NAME_CHARS = 128;
+export declare const MAX_AGENT_SKILLS = 10;
+export declare const MAX_AGENT_SKILL_CONTENT_CHARS = 1048576;
+export declare const MAX_AGENT_MAX_TURNS = 1000;
+/** server 1.205 TASK_AGENT_FIELD_SHAPES 的 15 字段白名单(permissionMode 显式拒收,不在表内)。 */
+export declare const TASK_AGENT_WIRE_FIELDS: readonly ["name", "whenToUse", "whenToUseLean", "allowTools", "denyTools", "skills", "background", "isolation", "model", "thinking", "systemPrompt", "maxTurns", "memory", "observer", "observerMessage"];
+/** core ThinkingLevel 词表(effortWire.ReasoningEffort 与之完全一致)。 */
+export type WireThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export type TaskAgentWireSkill = {
+    name: string;
+    description: string;
+    content: string;
+};
+/** 发往 server 的单个 agent 定义(白名单内字段的壳侧子集——memory/observer 面壳无语义,恒不发)。 */
+export type TaskAgentWireItem = {
+    name: string;
+    whenToUse?: string;
+    allowTools?: string[];
+    denyTools?: string[];
+    skills?: TaskAgentWireSkill[];
+    background?: boolean;
+    isolation?: 'worktree';
+    model?: string;
+    thinking?: WireThinkingLevel;
+    systemPrompt?: string;
+    maxTurns?: number;
+};
+/** 投影输入的结构型(loadAgentsDir.AgentDefinition 的窄切片——纯模块不拉运行时依赖图)。 */
+export type AgentDefLike = {
+    agentType: string;
+    whenToUse?: string;
+    tools?: string[];
+    disallowedTools?: string[];
+    skills?: string[];
+    model?: string;
+    effort?: unknown;
+    maxTurns?: number;
+    background?: boolean;
+    isolation?: 'worktree' | 'remote';
+    source: string;
+    getSystemPrompt?: (arg?: unknown) => string;
+};
+/** 纯投影的注入读面(单测注入 fixture;产品缺省真读面在 prepare 里拼)。 */
+export type ProjectAgentsDeps = {
+    /** F5a 中央解析器切片:frontmatter model 词 → 真模型名或 'inherit'(warning 一次性)。 */
+    resolveModel: (frontmatterModel: string | undefined) => {
+        model: string;
+        warning?: string;
+    };
+    /** 壳 effort 值 → ThinkingLevel(词表外 → undefined 不发)。 */
+    effortToThinking: (effort: unknown) => WireThinkingLevel | undefined;
+    /** 已加载的 skill 全文(名字 join 用);undefined = 本次不点亮 skills 字段。 */
+    skillSpecs?: TaskAgentWireSkill[];
+};
+export type ProjectAgentsResult = {
+    agents: TaskAgentWireItem[] | undefined;
+    /** 剪裁/降级告警(调用层一次性打 stderr)。 */
+    warnings: string[];
+};
+/**
+ * 纯投影:壳 AgentDefinition[](F5a activeAgents)→ server 白名单载荷。built-in 恒过滤(引擎有
+ * 自己的内置 roster);形状违规壳侧收紧(server 是整请求 400,不能把脏字段交出去)。
+ */
+export declare function projectAgentsForWire(defs: readonly AgentDefLike[], deps: ProjectAgentsDeps): ProjectAgentsResult;
+/**
+ * SDK 0.0.52 client.capabilities()(GET /v1/capabilities,Capabilities 全类型面)→ 顶层
+ * `taskAgents` 布尔(SDK 宪法迁移批:raw fetch + body 裸读退役,改 typed 读)。
+ *   true  = 确证支持;false = 确证不支持(200 但 taskAgents !== true:旧 server 无该字段,或多租
+ *           requirePrincipal fail-closed 报 false);undefined = 无法确证(不可达/超时/非 2xx/不可
+ *           解析 —— SDK 对这些统一抛错,catch 归一)⇒ 调用层 fail-soft 照发(旧 server 静默剥字段
+ *           无害;引擎真死 stream 自己 fail-loud)。
+ * 等价性:3s 预算改经 client timeoutMs;maxRetries=0 单发(否则 503 会按 SDK 缺省重试,探测预算
+ * 语义变形)。差分:SDK 恒 stamp x-agent-principal(缺省 'anon:shell-live'),原手抄缺 principal
+ * 时省略该头——principal-first 宪法姿势,fail-open 改善(engineWireSdk 头注记账)。
+ */
+export declare function engineSupportsTaskAgents(baseUrl: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    authToken?: string;
+    principal?: string;
+}): Promise<boolean | undefined>;
+export type WireConfig = {
+    baseUrl: string;
+    authToken?: string;
+    principal?: string;
+};
+/** IO 半场注入的产品投影闭包(F5a 定义加载 + model 解析 + skills join)。 */
+export type ProjectorFn = () => Promise<ProjectAgentsResult>;
+/**
+ * kick 探测 + 加载 + 投影(createLiveConversationClient 构造时调;幂等——同 baseUrl 只跑一次)。
+ */
+export declare function prepareTaskAgentsWireWith(cfg: WireConfig, projector: ProjectorFn): Promise<void>;
+/**
+ * 有界就绪门(liveClient.stream 首帧前 await;缺省 4s 上限)。prepare 未 kick(mock 车道/测试)或
+ * 超时 ⇒ 立即放行(本 turn 不带 agents,fail-soft)。永不抛。
+ */
+export declare function awaitTaskAgentsWire(timeoutMs?: number): Promise<void>;
+/**
+ * 同步读面(liveClient.toLiveRequest 消费):当前投影好的 agents 载荷。每次读取后 kick 一次后台
+ * re-project(热加载 next-turn freshness:watcher clear loadAgentsDir memoize 后,下一 turn 拿新定义;
+ * 缓存未清时 re-project 近零开销)。能力已确证 false ⇒ 恒 {}。
+ */
+export declare function taskAgentsField(): {
+    agents?: TaskAgentWireItem[];
+};
+/** 测试钩子:清空模块态(prepare 缓存/一次性告警集)。 */
+export declare function _resetAgentsWireForTest(): void;

package/dist/agentsWireCaps.js

@@ -0,0 +1,319 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/agentsWireCaps.ts 逐字搬入(依赖 engineWireSdk,同批)。
+ */
+/**
+ * src/sema/agentsWireCaps.ts — F5b agents wire 纯半场(skillsWireCaps 同款拆分:规则/投影/探测/
+ * 模块态全在这,零产品依赖图;IO 半场见 agentsWire.ts——产品读面 dynamic import 后注入 projector)。
+ * 契约与决策的完整记账见 agentsWire.ts 头注释。
+ * (engineWireSdk 亦是纯半场——只 import 外部零依赖 SDK,不破本模块零产品图纪律。)
+ */
+import { hostEnv } from './hostEnv.js';
+import { makeEngineWireClient } from './engineWireSdk.js';
+// ── server 1.205 契约常量(实拆 dist/spec-fields.js,数值逐字)────────────────────────────────────
+export const MAX_TASK_AGENTS = 32;
+export const MAX_AGENT_NAME_CHARS = 64;
+export const MAX_AGENT_TEXT_CHARS = 4_096;
+export const MAX_AGENT_SYSTEM_PROMPT_CHARS = 65_536;
+export const MAX_AGENT_TOOLS = 64;
+export const MAX_AGENT_TOOL_NAME_CHARS = 128;
+export const MAX_AGENT_SKILLS = 10;
+export const MAX_AGENT_SKILL_CONTENT_CHARS = 1_048_576;
+export const MAX_AGENT_MAX_TURNS = 1_000;
+/** server 1.205 TASK_AGENT_FIELD_SHAPES 的 15 字段白名单(permissionMode 显式拒收,不在表内)。 */
+export const TASK_AGENT_WIRE_FIELDS = [
+    'name',
+    'whenToUse',
+    'whenToUseLean',
+    'allowTools',
+    'denyTools',
+    'skills',
+    'background',
+    'isolation',
+    'model',
+    'thinking',
+    'systemPrompt',
+    'maxTurns',
+    'memory',
+    'observer',
+    'observerMessage',
+];
+/** 五档来源优先级(managed > --agents flag > project > user > plugin)——32 帽裁剪的排序键。 */
+const SOURCE_RANK = {
+    policySettings: 0,
+    flagSettings: 1,
+    projectSettings: 2,
+    userSettings: 3,
+    plugin: 4,
+};
+function sourceRank(source) {
+    return SOURCE_RANK[source] ?? 5;
+}
+/**
+ * 纯投影:壳 AgentDefinition[](F5a activeAgents)→ server 白名单载荷。built-in 恒过滤(引擎有
+ * 自己的内置 roster);形状违规壳侧收紧(server 是整请求 400,不能把脏字段交出去)。
+ */
+export function projectAgentsForWire(defs, deps) {
+    const warnings = [];
+    const customs = defs
+        .filter(d => d.source !== 'built-in')
+        .slice()
+        .sort((a, b) => sourceRank(a.source) - sourceRank(b.source));
+    let capped = customs;
+    if (customs.length > MAX_TASK_AGENTS) {
+        capped = customs.slice(0, MAX_TASK_AGENTS);
+        const dropped = customs.slice(MAX_TASK_AGENTS).map(d => d.agentType);
+        warnings.push(`agents wire: ${customs.length} custom agents exceed the engine cap of ${MAX_TASK_AGENTS} — keeping the ${MAX_TASK_AGENTS} highest-precedence definitions, dropped: ${dropped.join(', ')}`);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const def of capped) {
+        const name = def.agentType;
+        if (typeof name !== 'string' || name.length === 0)
+            continue;
+        if (name.length > MAX_AGENT_NAME_CHARS) {
+            // name 是身份,截断可能撞名——整个丢弃 + warn(server 对超长 name 是整请求 400)。
+            warnings.push(`agents wire: agent name "${name.slice(0, 40)}…" exceeds ${MAX_AGENT_NAME_CHARS} chars — definition skipped`);
+            continue;
+        }
+        if (seen.has(name))
+            continue; // server 对 duplicate name 整请求 400——防御性去重(activeAgents 已按名唯一)
+        seen.add(name);
+        const item = { name };
+        if (typeof def.whenToUse === 'string' && def.whenToUse.length > 0) {
+            item.whenToUse =
+                def.whenToUse.length > MAX_AGENT_TEXT_CHARS
+                    ? def.whenToUse.slice(0, MAX_AGENT_TEXT_CHARS)
+                    : def.whenToUse;
+            if (def.whenToUse.length > MAX_AGENT_TEXT_CHARS) {
+                warnings.push(`agents wire: agent "${name}" description truncated to ${MAX_AGENT_TEXT_CHARS} chars`);
+            }
+        }
+        const projectTools = (list, label) => {
+            if (!Array.isArray(list) || list.length === 0)
+                return undefined;
+            const kept = list.filter(t => typeof t === 'string' && t.length > 0 && t.length <= MAX_AGENT_TOOL_NAME_CHARS);
+            if (kept.length !== list.length) {
+                warnings.push(`agents wire: agent "${name}" ${label} had invalid entries — dropped`);
+            }
+            if (kept.length === 0)
+                return undefined; // 全剪空 ≠ 显式空单(空 allow 语义歧义,宁可回落继承)
+            if (kept.length > MAX_AGENT_TOOLS) {
+                warnings.push(`agents wire: agent "${name}" ${label} truncated to ${MAX_AGENT_TOOLS} entries`);
+                return kept.slice(0, MAX_AGENT_TOOLS);
+            }
+            return kept;
+        };
+        const allowTools = projectTools(def.tools, 'tools');
+        if (allowTools)
+            item.allowTools = allowTools;
+        const denyTools = projectTools(def.disallowedTools, 'disallowedTools');
+        if (denyTools)
+            item.denyTools = denyTools;
+        // skills:名字 → 已加载全文对象 join;join 不上剪掉 + warn。
+        if (Array.isArray(def.skills) && def.skills.length > 0 && deps.skillSpecs) {
+            const byName = new Map(deps.skillSpecs.map(s => [s.name.toLowerCase(), s]));
+            const joined = [];
+            const missing = [];
+            for (const skillName of def.skills) {
+                if (typeof skillName !== 'string' || skillName.length === 0)
+                    continue;
+                const spec = byName.get(skillName.toLowerCase());
+                if (spec &&
+                    spec.name.length <= MAX_AGENT_NAME_CHARS &&
+                    spec.content.length > 0 &&
+                    spec.content.length <= MAX_AGENT_SKILL_CONTENT_CHARS) {
+                    joined.push(spec);
+                }
+                else {
+                    missing.push(skillName);
+                }
+            }
+            if (missing.length > 0) {
+                warnings.push(`agents wire: agent "${name}" skills not found in the loaded skill set (dropped): ${missing.join(', ')}`);
+            }
+            if (joined.length > MAX_AGENT_SKILLS) {
+                warnings.push(`agents wire: agent "${name}" skills truncated to ${MAX_AGENT_SKILLS}`);
+            }
+            if (joined.length > 0)
+                item.skills = joined.slice(0, MAX_AGENT_SKILLS);
+        }
+        if (typeof def.background === 'boolean')
+            item.background = def.background;
+        if (def.isolation === 'worktree') {
+            item.isolation = 'worktree';
+        }
+        else if (def.isolation !== undefined) {
+            warnings.push(`agents wire: agent "${name}" isolation "${String(def.isolation)}" is not accepted by the engine (only "worktree") — dropped`);
+        }
+        // model:F5a 中央解析器已把档位词/CC 别名/catalog 名/完整 ID 解析成真模型名;'inherit' 不发
+        // (core 对 def.model 走 resolveModel fail-loud,'inherit' 字面会被判 unknown_model)。
+        const resolution = deps.resolveModel(def.model);
+        if (resolution.warning)
+            warnings.push(resolution.warning);
+        if (resolution.model !== 'inherit')
+            item.model = resolution.model;
+        const thinking = deps.effortToThinking(def.effort);
+        if (thinking)
+            item.thinking = thinking;
+        if (typeof def.getSystemPrompt === 'function') {
+            let prompt;
+            try {
+                prompt = def.getSystemPrompt();
+            }
+            catch {
+                prompt = undefined; // prompt 闭包抛错 fail-soft:agent 仍发(引擎给基本 env),别拖死整个载荷
+            }
+            if (typeof prompt === 'string' && prompt.length > 0) {
+                if (prompt.length > MAX_AGENT_SYSTEM_PROMPT_CHARS) {
+                    warnings.push(`agents wire: agent "${name}" system prompt truncated to ${MAX_AGENT_SYSTEM_PROMPT_CHARS} chars`);
+                    prompt = prompt.slice(0, MAX_AGENT_SYSTEM_PROMPT_CHARS);
+                }
+                item.systemPrompt = prompt;
+            }
+        }
+        if (def.maxTurns !== undefined) {
+            if (typeof def.maxTurns === 'number' &&
+                Number.isInteger(def.maxTurns) &&
+                def.maxTurns >= 1 &&
+                def.maxTurns <= MAX_AGENT_MAX_TURNS) {
+                item.maxTurns = def.maxTurns;
+            }
+            else {
+                warnings.push(`agents wire: agent "${name}" maxTurns ${String(def.maxTurns)} out of range (1..${MAX_AGENT_MAX_TURNS}) — dropped`);
+            }
+        }
+        out.push(item);
+    }
+    return { agents: out.length > 0 ? out : undefined, warnings };
+}
+// ── 能力探测(taskAgents capability,按 baseUrl 缓存)────────────────────────────────────────────
+/**
+ * SDK 0.0.52 client.capabilities()(GET /v1/capabilities,Capabilities 全类型面)→ 顶层
+ * `taskAgents` 布尔(SDK 宪法迁移批:raw fetch + body 裸读退役,改 typed 读)。
+ *   true  = 确证支持;false = 确证不支持(200 但 taskAgents !== true:旧 server 无该字段,或多租
+ *           requirePrincipal fail-closed 报 false);undefined = 无法确证(不可达/超时/非 2xx/不可
+ *           解析 —— SDK 对这些统一抛错,catch 归一)⇒ 调用层 fail-soft 照发(旧 server 静默剥字段
+ *           无害;引擎真死 stream 自己 fail-loud)。
+ * 等价性:3s 预算改经 client timeoutMs;maxRetries=0 单发(否则 503 会按 SDK 缺省重试,探测预算
+ * 语义变形)。差分:SDK 恒 stamp x-agent-principal(缺省 'anon:shell-live'),原手抄缺 principal
+ * 时省略该头——principal-first 宪法姿势,fail-open 改善(engineWireSdk 头注记账)。
+ */
+export async function engineSupportsTaskAgents(baseUrl, opts) {
+    const client = makeEngineWireClient({
+        baseUrl,
+        ...(opts?.authToken ? { token: opts.authToken } : {}),
+        ...(opts?.principal ? { principal: opts.principal } : {}),
+        timeoutMs: opts?.timeoutMs ?? 3000,
+        ...(opts?.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    if (!client)
+        return undefined;
+    try {
+        const caps = await client.capabilities();
+        return caps?.taskAgents === true;
+    }
+    catch {
+        return undefined;
+    }
+}
+let activeProjector = null;
+let preparedKey = null;
+let preparedPromise = null;
+let payload;
+let capsVerdict; // 按 prepare 时的 baseUrl 缓存
+const emittedWarnings = new Set();
+function warnOnce(msg) {
+    if (emittedWarnings.has(msg))
+        return;
+    emittedWarnings.add(msg);
+    // eslint-disable-next-line no-console
+    console.error(`[sema] ${msg}`);
+}
+async function runPrepare(cfg, projector) {
+    try {
+        const [caps, projected] = await Promise.all([
+            engineSupportsTaskAgents(cfg.baseUrl, {
+                authToken: cfg.authToken,
+                principal: cfg.principal,
+            }),
+            projector(),
+        ]);
+        capsVerdict = caps;
+        if (projected.agents && caps === false) {
+            // 确证无能力:不发 + 一次性诚实告警(用户会误信自定义 agents 已生效)。
+            warnOnce(`agents wire: this engine does not support per-task custom agents (capabilities.taskAgents absent/false — server <1.205 or multi-tenant) — ${projected.agents.length} custom agent definition(s) will NOT be sent`);
+            payload = undefined;
+            return;
+        }
+        for (const w of projected.warnings)
+            warnOnce(w);
+        payload = projected.agents;
+        if (payload && hostEnv().SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] agents wire: ${payload.length} custom agent(s) → TaskRequest.agents (${payload.map(a => a.name).join(', ')})`);
+        }
+    }
+    catch (e) {
+        // 任何 prepare 失败 fail-soft:不发 agents,绝不拖死 turn。
+        payload = undefined;
+        if (hostEnv().SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('[sema] agents wire prepare soft-failed (no agents stamped):', e);
+        }
+    }
+}
+/**
+ * kick 探测 + 加载 + 投影(createLiveConversationClient 构造时调;幂等——同 baseUrl 只跑一次)。
+ */
+export function prepareTaskAgentsWireWith(cfg, projector) {
+    const key = cfg.baseUrl;
+    if (preparedPromise && preparedKey === key)
+        return preparedPromise;
+    preparedKey = key;
+    preparedPromise = runPrepare(cfg, projector);
+    activeProjector = projector;
+    return preparedPromise;
+}
+/**
+ * 有界就绪门(liveClient.stream 首帧前 await;缺省 4s 上限)。prepare 未 kick(mock 车道/测试)或
+ * 超时 ⇒ 立即放行(本 turn 不带 agents,fail-soft)。永不抛。
+ */
+export async function awaitTaskAgentsWire(timeoutMs = 4000) {
+    if (!preparedPromise)
+        return;
+    await Promise.race([
+        preparedPromise.catch(() => { }),
+        new Promise(resolve => {
+            const t = setTimeout(resolve, timeoutMs);
+            t.unref?.();
+        }),
+    ]);
+}
+/**
+ * 同步读面(liveClient.toLiveRequest 消费):当前投影好的 agents 载荷。每次读取后 kick 一次后台
+ * re-project(热加载 next-turn freshness:watcher clear loadAgentsDir memoize 后,下一 turn 拿新定义;
+ * 缓存未清时 re-project 近零开销)。能力已确证 false ⇒ 恒 {}。
+ */
+export function taskAgentsField() {
+    const current = payload;
+    // 后台刷新(fire-and-forget;capsVerdict 沿用——能力不随热加载变)
+    if (preparedPromise && capsVerdict !== false && activeProjector) {
+        void activeProjector()
+            .then(p => {
+            for (const w of p.warnings)
+                warnOnce(w);
+            payload = p.agents;
+        })
+            .catch(() => { });
+    }
+    return current ? { agents: current } : {};
+}
+/** 测试钩子:清空模块态(prepare 缓存/一次性告警集)。 */
+export function _resetAgentsWireForTest() {
+    activeProjector = null;
+    preparedKey = null;
+    preparedPromise = null;
+    payload = undefined;
+    capsVerdict = undefined;
+    emittedWarnings.clear();
+}

package/dist/attachmentsWireCaps.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/attachmentsWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * 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).
+ *
+ * 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
+ * boundaries — a TOC user gets that behavior without flipping anything. The default therefore
+ * carries the G1 announce pair `{backgroundTasks, toolsDelta}`:
+ *   - both are ONE-SHOT/quiet engine-side (no compaction ⇒ backgroundTasks permanently silent; no
+ *     deferred-tool materialization ⇒ toolsDelta permanently silent), so the default costs nothing
+ *     on an ordinary session;
+ *   - the design/133 reminder trio (todoReminder/changedFiles/planModeReminder) stays OPT-IN
+ *     (`SEMA_ATTACHMENTS=full`) — core's own default-face judgment (evidence from autonomous legs
+ *     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.
+ *
+ * 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. `off|0|false|none` ⇒ no stamp; `full|all` ⇒ all five producers;
+ *  unset/anything else ⇒ the CC-parity default pair. */
+export declare const ATTACHMENTS_ENV: "SEMA_ATTACHMENTS";
+/** Mirror of core `TaskSpec.attachments` (types.ts:1139) — literal-true unions. */
+export interface AttachmentsSpec {
+    todoReminder?: true;
+    changedFiles?: true | {
+        maxFiles?: number;
+    };
+    planModeReminder?: true;
+    backgroundTasks?: true;
+    toolsDelta?: true;
+}
+/**
+ * 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).
+ */
+export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;

package/dist/attachmentsWireCaps.js

@@ -0,0 +1,46 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/attachmentsWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * 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).
+ *
+ * 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
+ * boundaries — a TOC user gets that behavior without flipping anything. The default therefore
+ * carries the G1 announce pair `{backgroundTasks, toolsDelta}`:
+ *   - both are ONE-SHOT/quiet engine-side (no compaction ⇒ backgroundTasks permanently silent; no
+ *     deferred-tool materialization ⇒ toolsDelta permanently silent), so the default costs nothing
+ *     on an ordinary session;
+ *   - the design/133 reminder trio (todoReminder/changedFiles/planModeReminder) stays OPT-IN
+ *     (`SEMA_ATTACHMENTS=full`) — core's own default-face judgment (evidence from autonomous legs
+ *     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.
+ *
+ * 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 { hostEnv } from './hostEnv.js';
+/** The env key the shell reads. `off|0|false|none` ⇒ no stamp; `full|all` ⇒ all five producers;
+ *  unset/anything else ⇒ the CC-parity default pair. */
+export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
+/**
+ * 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).
+ */
+export function attachmentsForRequest(env = hostEnv()) {
+    const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+    if (raw === 'off' || raw === '0' || raw === 'false' || raw === 'none')
+        return undefined;
+    if (raw === 'full' || raw === 'all') {
+        return { todoReminder: true, changedFiles: true, planModeReminder: true, backgroundTasks: true, toolsDelta: true };
+    }
+    // default (TOC CC parity): post-compact background-task recap + deferred-tools boundary notice.
+    return { backgroundTasks: true, toolsDelta: true };
+}

package/dist/classifierVerdictWire.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/classifierVerdictWire.ts 的
+ * **判定半场**搬入(帧识别 + 文案),`surfaceClassifierDeny()` 的**执行半场**留宿主
+ * (它写 Ink `AppState.notifications` 并 lazy `require('../utils/autoModeDenials.js')`——
+ * 两者都是 TUI/Node 私有面,进不了端无关包)。
+ * 🔴 本文件零模块级可变状态(只有常量),故不受 B1「写读口必须同实例」纪律约束:壳侧留
+ * 执行半场、判定走本包,是安全的拆缝(B6 T35/T36/T44 同款「判定半场搬入」姿势)。
+ * 逐字纪律:CLASSIFIER_DENY_SIGNATURE / NOTICE_REASON_MAX(80)/ 通知行三段格式一字节不改。
+ */
+/**
+ * src/sema/classifierVerdictWire.ts — auto-mode 分类器裁决帧的壳侧消费(分类器批3 壳半场,黑板 [907])。
+ *
+ * WIRE 形状(gap-check 2026-07-16 实勘,core 1.279 dist 亲核):
+ *   引擎侧分类器 block(core hooks.js runToolGate)→ decision = deny + decisionReason:"classifier",
+ *   permissionDenied 钩子收 source:"classifier"(server 1.209 只作 metrics 计量,不出独立 deny 帧)——
+ *   壳能看见的唯一 wire 事实 = `tool_end` 帧:
+ *     { type:'tool_end', isError:true, output: [{type:'text', text:'<system-reminder>\n
+ *       auto-mode classifier blocked this call[: <reason>|: [<category>]]\n</system-reminder>'}] }
+ *   (core hooks.js L138 deny message 逐字 + formatHookFeedback 包 system-reminder;
+ *    agent-loop createErrorToolResult 落 content 数组;runtask toolOutputFrom 原样上 wire。)
+ *   ⇒ 消费面按此签名结构性识别,等价于「deny 帧带 source:'classifier'」的判定(签名字符串是
+ *   core 的机器产文面,非模型作文——模型 echo 不会以该签名做 tool_end 错误体开头)。
+ *
+ * 🔴 fail-soft 铁律:识别不中一律静默走原路,绝不伤害事件流。
+ * 🔴 UNTRUSTED:reason 为分类器(模型)产文,只渲染绝不回喂;通知行截断 ≤80(207 同款)。
+ */
+/** core hooks.js 分类器 deny message 的机器签名(逐字锚;lockstep:core 改文案这里必须跟)。 */
+export declare const CLASSIFIER_DENY_SIGNATURE = "auto-mode classifier blocked this call";
+export interface ClassifierDenyVerdict {
+    /** core 裁决原文(已去 system-reminder 包裹),= render 面 stamp 体。 */
+    message: string;
+    /** 签名后的 reason 尾巴(`: ` 之后),无则 undefined。 */
+    reason?: string;
+}
+/**
+ * 结构性识别一张 tool_end 帧是否为分类器 deny 裁决帧。
+ * 判定 = isError:true ∧ 错误体(去包裹后)以 core 机器签名开头。识别不中 ⇒ undefined(原路)。
+ */
+export declare function classifierDenyFromToolEnd(ev: {
+    type?: unknown;
+    isError?: unknown;
+    output?: unknown;
+}): ClassifierDenyVerdict | undefined;
+/** 通知行文案(exported for tests;CC 207 三段 text 化)。 */
+export declare function classifierDenyNoticeText(toolName: string, reason: string | undefined): string;