@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/agentSession/contract.d.ts

@@ -1,71 +1,21 @@
-/**
- * design/161 — client-core 顶层单入口:**契约收敛物**(纯类型,零运行时;实现分批跟进)。
- *
- * 这是立项的唯一权威签名源(clay 三裁 2026-07-30 + 对抗复审 r1 收敛;两份文档签名互不相容的
- * 教训 = 收敛物必须是 tsc 管得住的代码,见 sema-internal design-161-review-r1.md §〇)。
- * 实现工单以本文件为锚:W1 per-session 化 → 入口实现 → W5 冷接 → 三端迁移(desktop → sema-web
- * 聊天区 → web-client)。**本文件不进 index.ts barrel,实现落地一件出口一件。**
- *
- * ══ 三个入口,不是一个 ═══════════════════════════════════════════════════════════════════
- * 1. `createAgentSession(config)` —— per-session 会话流面(AgentEvent → SDKMessage + HITL 桥 +
- *    终态投影)。wire 只有一种:SDK 的 `AgentClientConfig` 判别联合(client/relay 本就是它的两臂,
- *    r1 E3 —— 在这里再判一次就是复制 SDK)。
- * 2. `attachSeatSession(seatApi)` —— 层 2 远程代理:座位(Electron renderer / web seat lane)侧
- *    **没有 AgentEvent 流**(收到的已是 main 进程 adapt 后的 SDKMessage,seatContract:49-56),
- *    所以它不是第三个 wire 臂,是层 1 返回面的**同型转发**(内部零 wire、零 adapt)。
- * 3. `createBackgroundView(client)` —— 平行入口(clay 二裁 2026-07-30):`assistant.tasks` 与
- *    `fleet` 都是**会话外读面**(assistant 跨 session;fleet 是 idle 壳唯一保持订阅的常驻 SSE),
- *    生命周期不该绑在某个会话的 dispose() 上,所以归一投影不进 createAgentSession。
- */
 import type { AgentClient, AgentClientConfig } from '@sema-agent/sdk';
-/**
- * 已构造 client 的接入臂 **必须同时带构造参数** —— `AgentClient.config` 是 private
- * (sdk client.d.ts:124),包拿不回 baseUrl/authToken/principal,而入口要用它们做四件事:
- * caps 探针 kick ×2、task-agents wire 预备、durable 读面的 client 另建(planReview 同款)。
- * 不带这三样的「裸 client」臂在 r1 E3-2 已证伪。
- */
 export interface ProvidedClientWire {
     readonly client: AgentClient;
     readonly baseUrl: string;
     readonly authToken: AgentClientConfig['authToken'];
     readonly principal?: string;
 }
-/** wire 入参:给配置则入口自建 client;给 ProvidedClientWire 则复用宿主的(参数齐备)。 */
 export type AgentSessionWire = AgentClientConfig | ProvidedClientWire;
 export interface AgentSessionHostSurface {
-    /** 转录消费口(SDKMessage 流的宿主端)。缺席 ⇒ 入口拒绝启动(没有它整个入口无意义)。 */
     onTranscript(msg: unknown): void;
-    /**
-     * chrome 装饰臂(seam.ts CHROME_ARMS 表)。缺席的 required 臂 = 功能静默不出现
-     * (desktop 今天缺 7/8,r1 E8c)——所以本口的自检是**表驱动**的:实现必须提供
-     * `chromeArmMisses()`,对 `required:true` 且未被消费的臂逐臂计数,门断言恒 0。
-     */
     onChrome?(event: unknown): void;
-    /**
-     * 工具审批卡口。两条腿:
-     *   sync-frame 腿:缺席 ⇒ 主动 respond deny(现行为,保留);
-     *   durable-park 腿:缺席 ⇒ 🔴 **主动 decide deny + 一条诚实告知行**(行为变更,替换今天的
-     *     fail-stuck;candidates 见下方 OPEN-1 —— headless「留 park 待接手」场景是否豁免候 clay)。
-     */
     approvalCard?: unknown;
-    /** AskUserQuestion overlay 口。durable 腿缺席后果同上(deny 语义 = respond 取消形)。 */
     askQuestion?: unknown;
-    /**
-     * plan review 口。缺席 ⇒ 今天是「卡永不出现且静默」(planReviewWire.ts:77 fail-soft)——
-     * 改为:至少产出一条可见终态行(引擎在等,人必须知道)。卡的**皮肤归端**(desktop 的
-     * ExitPlanMode 权限卡形 vs cli 的 overlay 形都合法,包只出数据与决断口;OPEN-2)。
-     */
     planReview?: unknown;
-    /** 通知队列口(缺席=计 miss,静默可接受 —— 引擎不等)。 */
     notify?: unknown;
-    /** 后台任务转发口(会话自己流上的 task_notification / subagent_lifecycle;跨会话视图归 createBackgroundView)。 */
     onBackgroundTask?(event: unknown): void;
-    /** 身份采集口(meta.taskId + done.result.sessionId;三端各写一份的第 5 缺口)。 */
     onIdentity?(identity: AgentSessionIdentity): void;
-    /** 未知帧告警口(包内四层 default 静默的补偿;milestone 节流姿势收编 web-client frame-warnings)。 */
     onUnknownFrame?(frame: unknown): void;
-    /** turn 级错误口(9 类 taxonomy + 状态码链 + wire-code 闭集表 —— 收编 web-client 三件套并接
-     *  controlRouter.errCodes 单源,r1 E7:不是「三分诊」)。 */
     onTurnError?(err: unknown): void;
 }
 export interface AgentSessionIdentity {
@@ -74,23 +24,12 @@ export interface AgentSessionIdentity {
 }
 export interface AgentSessionConfig {
     readonly wire: AgentSessionWire;
-    /** 请求车道(taskRequest.ts 的 RequestLane;web 传输 lane 是另一个轴,别混,r1 角度2)。 */
     readonly lane: 'interactive' | 'print';
     readonly hostSurface: AgentSessionHostSurface;
-    /**
-     * per-session 键(W1):包内单槽位全部改「sessionKey → 注册表」,零参旧 API = default-key
-     * 兼容层(cli 的 module-load 装配不动)。多会话宿主(desktop)每会话一键,互不顶盖。
-     */
     readonly sessionKey?: string;
 }
 export interface AgentSession {
-    /** 发起一个 turn(内部:buildTaskRequest 唯一构造口 + runStream 内建去重 + HITL 桥)。 */
     query(input: unknown): AsyncIterable<unknown>;
-    /**
-     * 冷接(W5,r1 E9):按调用方给的 id 接上一个**不是本进程发起**的在飞 run(页面刷新 / 桌面
-     * 重启 / 跨端接手)。与 query() 同一消费面;park 帧在冷接腿上同样可决断。
-     * 这是 sema-web stream-core 旧腿退役的前置能力 —— 没有它退役 = 删掉唯一的刷新恢复路径。
-     */
     attach(target: {
         taskId: string;
         sessionId?: string;
@@ -98,28 +37,18 @@ export interface AgentSession {
     interrupt(): Promise<void>;
     steer(text: string): Promise<void>;
     resumeAfterDecision(): Promise<void>;
-    /** 面缺席自检出口(测试面,恒 0 断言;不是运行期告警 —— Ink 吞 console,r1 E6)。 */
     surfaceMisses(): Readonly<Record<string, number>>;
     identity(): AgentSessionIdentity;
     dispose(): void;
 }
-/** 层 1:唯一的 wire 入口。 */
 export type CreateAgentSession = (config: AgentSessionConfig) => AgentSession;
-/**
- * 层 2:座位远程代理 —— 与 AgentSession **同型**(同一个接口),内部把每个方法转发给座位 IPC
- * (seatContract 的 verb 面),零 wire 零 adapt。座位可达字段集是 9 键闭集(< interactive 的
- * ~25 键)—— 该不对称必须**显式暴露**(supportedFields),端上的控件按它显隐,不许各自再判。
- */
 export type AttachSeatSession = (seatApi: unknown) => AgentSession & {
     readonly supportedFields: readonly string[];
 };
 export type BackgroundSource = 'assistant' | 'fleet';
-/** not-configured = assistant 无 TiDB 时的 `{tasks:[]}` 形 —— 与「真没有任务」必须可区分。 */
 export type BackgroundSourceHealth = 'ok' | 'unavailable' | 'not-configured';
-/** 第三套中性词表(不用任一方词表:3 值压不住 9 值,9 值会造 assistant 侧不存在的态)。 */
 export type BackgroundStatus = 'running' | 'waiting-on-human' | 'queued' | 'stopping' | 'done' | 'failed' | 'stopped' | 'unknown';
 export interface BackgroundRow {
-    /** 带来源判别;fleet 复合 id("<runId> <taskId>")不拆 —— 裸 id union 会重复计数。 */
     readonly key: {
         readonly source: 'assistant';
         readonly taskId: string;
@@ -128,34 +57,9 @@ export interface BackgroundRow {
         readonly rowId: string;
     };
     readonly status: BackgroundStatus;
-    /** 统一 epoch ms;assistant 的 ISO 串只在边界转一次。 */
     readonly updatedAtMs?: number;
-    /**
-     * 行**创建**时刻(统一 epoch ms)。语义 = 这一行是什么时候被排上的,不是什么时候开跑的。
-     *   · assistant 臂:`AssistantTask.createdAt`(wire 是 ISO 串,与 updatedAt 同一个边界转换器);
-     *   · fleet 臂:wire 上**没有这个量** ⇒ fleet 行恒缺席(fleet 给的是 {@link startedAtMs})。
-     * 缺席后果:端渲不出「排了多久」,必须不渲 —— 🔴 绝不 `?? Date.now()`/`?? 0` 冒充,也绝不拿
-     * updatedAtMs 顶替(那是「最后一次动」,不是「什么时候来的」)。
-     */
     readonly createdAtMs?: number;
-    /**
-     * 行**开跑**时刻(统一 epoch ms)= elapsed 的锚。
-     *   · fleet 臂:`FleetTaskRow.startedAt`(server ≥1.250,fleet-bus.ts:94;launch 时刻,revive 行
-     *     = 本 revive 周期的 wake 时刻)。契约级别 **ADDITIVE / tolerate-absent** —— 排队中的行本就
-     *     没有它(server 侧据此把显示态落 queued),消费端**不能当必填**。
-     *   · assistant 臂:wire 上没有 launch 时刻 ⇒ assistant 行恒缺席(它给的是 {@link createdAtMs})。
-     * 为什么是它而不是 server 的 `elapsedMs`:后者是发帧那一刻的快照,客户端拿着自算会漂;
-     * 锚是绝对时刻才稳(server [C36])。缺席后果:端**不渲时长**(假 0s 比不渲更坏)。
-     */
     readonly startedAtMs?: number;
-    /**
-     * 这一行所属的引擎会话 id。语义 = 「跳到该会话 / 按会话归组」这类 affordance 的目标。
-     *   · assistant 臂:`AssistantTask.sessionId`(wire 恒在场);
-     *   · fleet 臂:server 在 `stripT`(routes/fleet.ts:95)里把 `sessionId`/`scope` 剥掉不上 wire
-     *     ⇒ fleet 行恒缺席,别在投影里等它([C36] 事实②)。
-     * 缺席后果:那条跳转/归组的 affordance **必须显隐** —— 没有已挣得的目标就不摆入口
-     * (假 affordance 比没有更坏);🔴 绝不 `?? ''` 造一个空会话 id 出来。
-     */
     readonly sessionId?: string;
     readonly needsAttention?: boolean;
     readonly name?: string;
@@ -167,9 +71,7 @@ export interface BackgroundRow {
     readonly gate?: unknown;
 }
 export interface BackgroundView {
-    /** 🔴 一等返回位,端必须渲它 —— 源不可用/未配置与「空列表」是三件事。 */
     readonly sources: Readonly<Record<BackgroundSource, BackgroundSourceHealth>>;
-    /** fleet 子行(parentId 在场)不进跨 session 视图(子代不是用户的独立后台任务)。 */
     readonly rows: readonly BackgroundRow[];
 }
 export type CreateBackgroundView = (client: AgentClient) => {

package/dist/agentSession/contract.js

@@ -1,13 +1 @@
 export {};
-// ── 已裁定(clay 终裁 2026-07-31,档 sema-internal e2b874c;实现必须遵守)──────────────────────
-// RULED-1 durable park 腿面缺席 = **分形**:
-//   · 面「注册过但坏了」(卡口异常)→ 主动 decide deny + 诚实告知行(解锁优先);
-//   · 面「从未注册」(print/headless 本无卡口)→ 保留 park + 打印含 resume 指令的告知行
-//     (接手优先 —— headless 故意留 park 换 REPL/desktop 决断是合法场景)。
-//   🔴 附加不变式(clay 原话「danger 权限保证全部畅通即可」):bypassPermissions/danger 模式下
-//   审批链全程畅通 —— 零 park、零卡、零 deny,本缺席矩阵整表不适用;实现必带一条 danger-lane
-//   e2e 断言(danger 会话跑到审批点零停顿直通)。
-// RULED-2 plan review 卡形 = **皮肤归端**:包只出数据+决断口;desktop 保持 ExitPlanMode 权限
-//   卡形(CC 对位),cli 保持 overlay 形,不强制统一 UI。
-// OPEN-3(实现期):file_link / live elicitation 两条 wire 缺口先补进 adapt(E8a/E8b,
-//   elicitation 方向 = 把 desktop/web 那份**上交**成包件)。

package/dist/agentsWireCaps.d.ts

@@ -7,36 +7,18 @@ export declare const MAX_AGENT_TOOLS = 64;
 export declare const MAX_AGENT_TOOL_NAME_CHARS = 128;
 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;
 };
-/** CC 形自定义 agent 的 `memory:` 三词(cli `loadAgentsDir` 的 zod 枚举同源)。 */
 export declare const AGENT_MEMORY_WORDS: ReadonlySet<string>;
-/**
- * `agents[].memory` 上 wire 的形(上游闭合白名单 `{ scopes?, writeScope?, enabled?, scopeContract? }` 的子集:本包只用前两键)。
- *
- * 🔴 **CC-96 放宽**:`writeScope` 此前写死成 `string`(恒在、且不可为 `null`),而 wire 的取值域是 `string | null`
- *    (上游直讯确认该域不变)。写死的后果是**读得出却铸不出** —— {@link import('./memorySpecWire.js').readAgentMemorySpec}
- *    能把显式 `null` 读成「这一次 run 对记忆面只读」(无 remember 工具、不做 consolidation 写,recall 仍可),
- *    而端**没有任何办法经本包声明**这一形:只剩「写到某一层」一条路。半条腿的读面比没有更坏,因为它让
- *    「本端支持只读记忆」看起来是真的。
- *    · `writeScope: null`      = 显式声明只读;
- *    · `writeScope` 键缺席     = 未指定(缺省归引擎);
- *    · `writeScope: '<层名>'`  = 写到那一层。
- * 🔴 放宽的是**类型**,不是本包投影器的纪律:{@link projectAgentsForWire} 仍**恒显式钉** `writeScope`
- *    (见下方投影处的 🔴 注),漏钉会让新条目静默写进全局层 —— 那条约束一个字都没松。
- */
 export type TaskAgentWireMemory = {
     scopes: string[];
     writeScope?: string | null;
 };
-/** 发往 server 的单个 agent 定义(白名单内字段的壳侧子集——observer 面壳无语义,恒不发;`memory` 自 0.72.3 按定义发)。 */
 export type TaskAgentWireItem = {
     name: string;
     whenToUse?: string;
@@ -49,15 +31,8 @@ export type TaskAgentWireItem = {
     thinking?: WireThinkingLevel;
     systemPrompt?: string;
     maxTurns?: number;
-    /**
-     * CC-39①(0.72.3,core #863 G-5 / R-6):自定义 agent 的 `memory: user|project|local` **三词同映射**为引擎平面
-     * `{ scopes: ["agent:<type>"], writeScope: "agent:<type>" }`(= CC `user` 语义;in-repo 两形候裁,`project` / `local`
-     * 各出一条一次性 warn)。🔴 `writeScope` 必须显式钉:core `normalizeMemorySpec` 缺省取 scopes 末层,漏钉 = 新条目
-     * 静默写进全局层。词表外 ⇒ 不发本键 + warn(server `memoryOk` 是闭合白名单,脏形整 agent 400)。缺席 ⇒ 键不在场。
-     */
     memory?: TaskAgentWireMemory;
 };
-/** 投影输入的结构型(loadAgentsDir.AgentDefinition 的窄切片——纯模块不拉运行时依赖图)。 */
 export type AgentDefLike = {
     agentType: string;
     whenToUse?: string;
@@ -69,80 +44,33 @@ export type AgentDefLike = {
     maxTurns?: number;
     background?: boolean;
     isolation?: 'worktree' | 'remote';
-    /** CC 形 `memory:` 前置字段(cli zod 枚举 user|project|local;本包按开集串收,词表外不发)。 */
     memory?: string;
     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 缺省重试,探测预算
- * 语义变形)。principal 头:SDK 6.11 起值检查删头——缺席不发(与原手抄同义;F-011 停发后
- * 单机形恒缺席,owner-null)。
- */
 export declare function engineSupportsTaskAgents(baseUrl: string, opts?: EngineProbeOpts): Promise<boolean | undefined>;
-/**
- * prepare 腿的连线配置。`authToken` 是**串或取值函数**({@link WireAuthTokenSource},0.62.0 放宽):
- * 函数形每发一次请求读一次 ⇒ 引擎换代、凭证换新之后端只换值,不必重建 client。串形零行为差。
- */
 export type WireConfig = {
     baseUrl: string;
     authToken?: WireAuthTokenSource;
     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)。永不抛。
- *
- * 🔴 域词表-13(RB-447 同形):这个 race 的唯一有界退出臂**绝不 unref**——它是被调用方真
- * await 的控制流(liveClient.ts `await awaitTaskAgentsWire()`),不是后台保活豁免;unref 会让
- * 宿主进程能在它 settle 前提前退出,届时这个 await 永远等不到结果。对照组:
- * askGateWire.ts 的 budget 定时器同样 unref,但它挂在无人 await 的 `void Promise.race(...)` 上,
- * 后果只是丢一行 warn——两处形状相同后果不同,分野在于「这个 promise 有没有被 await」,不能
- * 套用同一个 unref 兼容套(见 unrefTimer.ts 头注)。race settle 后 clearTimeout 掉该句柄
- * (此前完全没有 clear,超时臂即使先输也留着一个已到期的句柄)。
- */
 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

@@ -1,25 +1,13 @@
-/**
- * ⇄ 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;
-// 0.71.0(CC-18 收口):`MAX_AGENT_SKILLS` 常量已删(0.70.2 退役保留一版;server 7.78.1 起 agents[].skills 无条数帽)。
 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',
@@ -37,9 +25,7 @@ export const TASK_AGENT_WIRE_FIELDS = [
     'observer',
     'observerMessage',
 ];
-/** CC 形自定义 agent 的 `memory:` 三词(cli `loadAgentsDir` 的 zod 枚举同源)。 */
 export const AGENT_MEMORY_WORDS = new Set(['user', 'project', 'local']);
-/** 五档来源优先级(managed > --agents flag > project > user > plugin)——32 帽裁剪的排序键。 */
 const SOURCE_RANK = {
     policySettings: 0,
     flagSettings: 1,
@@ -50,10 +36,6 @@ const SOURCE_RANK = {
 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
@@ -73,12 +55,11 @@ export function projectAgentsForWire(defs, deps) {
         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 已按名唯一)
+            continue;
         seen.add(name);
         const item = { name };
         if (typeof def.whenToUse === 'string' && def.whenToUse.length > 0) {
@@ -98,7 +79,7 @@ export function projectAgentsForWire(defs, deps) {
                 warnings.push(`agents wire: agent "${name}" ${label} had invalid entries — dropped`);
             }
             if (kept.length === 0)
-                return undefined; // 全剪空 ≠ 显式空单(空 allow 语义歧义,宁可回落继承)
+                return undefined;
             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);
@@ -111,7 +92,6 @@ export function projectAgentsForWire(defs, deps) {
         const denyTools = projectTools(def.disallowedTools, 'disallowedTools');
         if (denyTools)
             item.denyTools = denyTools;
-        // CC-39①:memory 三词 → 引擎平面 agent:<type>(见 TaskAgentWireItem.memory 顶注)
         if (def.memory !== undefined) {
             if (typeof def.memory === 'string' && AGENT_MEMORY_WORDS.has(def.memory)) {
                 item.memory = { scopes: [`agent:${name}`], writeScope: `agent:${name}` };
@@ -123,7 +103,6 @@ export function projectAgentsForWire(defs, deps) {
                 warnings.push(`agents wire: agent "${name}" memory: ${String(def.memory)} is not one of user|project|local — memory not sent`);
             }
         }
-        // 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 = [];
@@ -132,9 +111,6 @@ export function projectAgentsForWire(defs, deps) {
                 if (typeof skillName !== 'string' || skillName.length === 0)
                     continue;
                 const spec = byName.get(skillName.toLowerCase());
-                // 🔴 CC-18(0.70.2):**不再按名字长度滤**(server `skillOk` 里 name 只判非空)。修前名字超 64 的
-                //    技能会落进下面的 `missing`,再被措辞说成「not found in the loaded skill set」—— 它明明加载了,
-                //    那句话是假的。`content` 两条判**保留**:server `skillOk` 至今逐字判非空且 ≤1MB(超了整请求 400)。
                 if (spec && spec.content.length > 0 && spec.content.length <= MAX_AGENT_SKILL_CONTENT_CHARS) {
                     joined.push(spec);
                 }
@@ -145,9 +121,6 @@ export function projectAgentsForWire(defs, deps) {
             if (missing.length > 0) {
                 warnings.push(`agents wire: agent "${name}" skills not found in the loaded skill set (dropped): ${missing.join(', ')}`);
             }
-            // 🔴 CC-18(0.70.2):**零条数帽**,join 上几条发几条(server 7.78.1 的 skills 臂已无
-            //    `v.length <= MAX_AGENT_SKILLS`)。修前在第 10 条处 `slice` + warn —— warn 落在运维日志里,
-            //    用户看到的只是「我声明的第 11 个技能没生效」,没有任何一层会响。
             if (joined.length > 0)
                 item.skills = joined;
         }
@@ -159,8 +132,6 @@ export function projectAgentsForWire(defs, deps) {
         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);
@@ -175,7 +146,7 @@ export function projectAgentsForWire(defs, deps) {
                 prompt = def.getSystemPrompt();
             }
             catch {
-                prompt = undefined; // prompt 闭包抛错 fail-soft:agent 仍发(引擎给基本 env),别拖死整个载荷
+                prompt = undefined;
             }
             if (typeof prompt === 'string' && prompt.length > 0) {
                 if (prompt.length > MAX_AGENT_SYSTEM_PROMPT_CHARS) {
@@ -200,18 +171,6 @@ export function projectAgentsForWire(defs, deps) {
     }
     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 缺省重试,探测预算
- * 语义变形)。principal 头:SDK 6.11 起值检查删头——缺席不发(与原手抄同义;F-011 停发后
- * 单机形恒缺席,owner-null)。
- */
 export async function engineSupportsTaskAgents(baseUrl, opts) {
     const client = makeEngineWireClient({
         baseUrl,
@@ -234,13 +193,12 @@ let activeProjector = null;
 let preparedKey = null;
 let preparedPromise = null;
 let payload;
-let capsVerdict; // 按 prepare 时的 baseUrl 缓存
+let capsVerdict;
 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) {
@@ -254,7 +212,6 @@ async function runPrepare(cfg, 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;
@@ -263,22 +220,16 @@ async function runPrepare(cfg, projector) {
             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)
@@ -288,18 +239,6 @@ export function prepareTaskAgentsWireWith(cfg, projector) {
     activeProjector = projector;
     return preparedPromise;
 }
-/**
- * 有界就绪门(liveClient.stream 首帧前 await;缺省 4s 上限)。prepare 未 kick(mock 车道/测试)或
- * 超时 ⇒ 立即放行(本 turn 不带 agents,fail-soft)。永不抛。
- *
- * 🔴 域词表-13(RB-447 同形):这个 race 的唯一有界退出臂**绝不 unref**——它是被调用方真
- * await 的控制流(liveClient.ts `await awaitTaskAgentsWire()`),不是后台保活豁免;unref 会让
- * 宿主进程能在它 settle 前提前退出,届时这个 await 永远等不到结果。对照组:
- * askGateWire.ts 的 budget 定时器同样 unref,但它挂在无人 await 的 `void Promise.race(...)` 上,
- * 后果只是丢一行 warn——两处形状相同后果不同,分野在于「这个 promise 有没有被 await」,不能
- * 套用同一个 unref 兼容套(见 unrefTimer.ts 头注)。race settle 后 clearTimeout 掉该句柄
- * (此前完全没有 clear,超时臂即使先输也留着一个已到期的句柄)。
- */
 export async function awaitTaskAgentsWire(timeoutMs = 4000) {
     if (!preparedPromise)
         return;
@@ -317,14 +256,8 @@ export async function awaitTaskAgentsWire(timeoutMs = 4000) {
             clearTimeout(timeoutHandle);
     }
 }
-/**
- * 同步读面(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 => {
@@ -336,7 +269,6 @@ export function taskAgentsField() {
     }
     return current ? { agents: current } : {};
 }
-/** 测试钩子:清空模块态(prepare 缓存/一次性告警集)。 */
 export function _resetAgentsWireForTest() {
     activeProjector = null;
     preparedKey = null;

package/dist/approvalsStreamLiveCapability.d.ts

@@ -1,18 +1,3 @@
-/**
- * approvalsStreamLiveCapability — `GET /v1/capabilities.approvalsStreamLive`(server ≥7.87.1;sdk 9.7.1 `Capabilities.approvalsStreamLive?: boolean`)
- * 的三端共用读面(0.73.3;与 sql / writeProtection / webSearch.backend / executionLane 四只兄弟同一套四态词汇)。
- *
- * ── 这一位答的是哪一个问题 ────────────────────────────────────────────────────────────────
- * 「这台引擎会不会在 `approvals.stream` 上推流内 ask 的进出(`live_pending` / `live_resolved`)」= checkpointStore ∧ toolApproval。
- * 它决定 feed 消费方要不要**靠**推面:位为 true ⇒ 推面可靠,对账节拍(`ApprovalsFeedOptions.reconcile`)只是兜底;
- * 位为 false / 键缺席 / 从没观测 ⇒ 推面**不可靠或判不出**,对账节拍是悬挂 ask 的唯一拉面 —— **别等** `live_pending`。
- *
- * ── 🔴 读法 ─────────────────────────────────────────────────────────────────────────────────
- *  ① **键缺席 ≠ false**:老 server(<7.87.1)不报这一位 ⇒ `not_reported`(判不出),按「要拉」处理;折成 false 是替引擎断言「不推」。
- *  ② 严格布尔;`null` / 串 / 数 / 数组 / 对象 ⇒ 畸形(删格 ⇒ `unobserved`)。
- *  ③ 「要不要对账」的判据归包:{@link livePendingNeedsReconcile} —— 只有 present 且 true 才 false;其余一律 true(少查一次 = 一只等人的 ask 迟迟不出现)。
- */
-/** 四态读数。`unobserved` 由读口在这一格空缺时铸,不由投影铸。 */
 export type ApprovalsStreamLiveReading = {
     kind: 'unobserved';
 } | {
@@ -21,22 +6,12 @@ export type ApprovalsStreamLiveReading = {
     kind: 'present';
     live: boolean;
 };
-/** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写 ⇒ 读口答 `unobserved`)。 */
 export declare function projectApprovalsStreamLiveCapability(caps: unknown): ApprovalsStreamLiveReading | undefined;
-/** 宿主 caps probe 的读面 tee 落点(与四只兄弟并列)。绝不 throw;畸形 ⇒ 删格;`opts.generation` 关掉旧探测覆盖新读数的竞态。 */
 export declare function noteEngineCapsForApprovalsStreamLive(baseUrl: string, caps: unknown, opts?: {
     generation?: number;
 }): void;
-/** 本进程观测到的读数;这一格空缺 ⇒ `{kind:'unobserved'}`。 */
 export declare function observedApprovalsStreamLive(baseUrl?: string | undefined): ApprovalsStreamLiveReading;
-/**
- * feed 消费方「要不要靠对账节拍拉悬挂 ask」的判据单源:只有引擎明说会推(present ∧ true)才 `false`;
- * 位为 false / 老 server 判不出 / 从没观测 ⇒ `true`。fail-safe 方向定在「查」(与 `shouldPoll` 同一条理由)。
- */
 export declare function livePendingNeedsReconcile(reading: ApprovalsStreamLiveReading): boolean;
-/** doctor 那一行的 detail 串,唯一措辞真源。🔴 `not_reported` 句不许暗示「不推」。 */
 export declare function approvalsStreamLiveDoctorDetail(reading: ApprovalsStreamLiveReading): string;
-/** 换代失效口(引擎温切成功后调):清成未观测。空串 ⇒ no-op;绝不 throw。 */
 export declare function forgetApprovalsStreamLiveReading(baseUrl: string | undefined): void;
-/** 测试钩子。 */
 export declare function __resetApprovalsStreamLiveReadingsForTests(): void;