@sema-agent/client-core 0.3.0 → 0.5.0

package/dist/retainBackgroundWireCaps.js

@@ -0,0 +1,58 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/retainBackgroundWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/retainBackgroundWireCaps.ts — PURE projection: the shell's "retain background processes past
+ * task teardown" opt-in → the TOP-LEVEL `TaskRequest.retainBackgroundProcesses` boolean the SERVICE consumes
+ * (spec-fields.js `retainBackgroundProcessesFromBody`: `raw !== true` ⇒ dropped;requirePrincipal 多租户形
+ * 服务端另有门)。Mirrors selfOrchestrationWireCaps(the verified top-of-body wire pattern)。
+ *
+ * 背景([1046] 核谳,TB [991]② reap 族):core 直跑腿(sema-tb)出厂显式
+ * `retainBackgroundProcesses:true`(design/128 T1-1——「交付存活服务」任务的 verifier 在进程退出后
+ * 才连接),而组合腿产品曾默认关 ⇒ 两腿在 reap 族不是同一场考试。
+ *
+ * ⚠️ 缺省已翻转为 ON(clay 亲报「后台 shell 命令跑到一半被杀」案,2026-07-26;[1046]④ 的裁量件本次
+ * 由真实场景需求兑现)。缺省不发时,引擎 turn finally 的**两道门**都关着:
+ *   ① `settleKilledForOwner({retainProcesses})` 的 retain 豁免;
+ *   ② `retainBgBySpec = spec.retainBackgroundProcesses === true && !ownedEnvDying` —— 为真才整块跳过
+ *      `bgEnv.disposeBackgroundShells(...)`(该 blanket sweep 不经 task-registry,故被它收掉的任务
+ *      `stopSource` 为空,终态归因落到 `stoppedBy = "system"` 缺省 = clay 观察到的 `stopped-by: system`)。
+ *
+ * 三问(宪法 NO-SHIP 检查):
+ *   谁需要:真人用户 —— `run_in_background` 起的构建/测试/服务在当轮结束后必须还活着,否则
+ *           BashOutput/TaskOutput 续读到的是尸体(clay 案:输出文件 0 字节 + status killed)。
+ *   谁受害:隔离执行环境(e2b/k8s/ssh 等 `isIsolated(env)`)—— 那里 `ownedEnvDying` 为真,retain 被
+ *           **无条件覆盖**(core 侧 `!opts.envDying` / `&& !ownedEnvDying`),进程随宿主一起走。这是
+ *           正确的:进程宿主没了,留 handle 无意义。故本翻转对隔离腿零语义变化。
+ *           次级受害面 = 本机资源泄漏(后台进程活过当轮)—— 但这正是 CC 的既定契约,不是回归。
+ *   补偿机制:`SEMA_RETAIN_BACKGROUND=0|false|no|off` 逃生口 ⇒ 不 stamp ⇒ 回引擎缺省 reap;
+ *           进程始终可由 KillShell/TaskStop 显式收,`/bashes` 面板可见可停;引擎 hard-wall
+ *           (defaultBgTimeoutSec 30min / maxBgTimeoutSec 2h)仍是兜底上限。
+ *
+ * CC 逐字锚(对标纲领 = 100% 达 CC 效果):CC 的 Bash `run_in_background` 契约 = 进程活过当轮,
+ * 由 BashOutput 续读、KillShell 显式收 —— **不在 turn 边界回收**。缺省 reap 是对 CC 的偏离,本次钉回。
+ *
+ * 语义:缺省 ON —— unset / 未识别值 ⇒ `true`(stamp);显式 truthy(1/true/yes/on)⇒ `true`;
+ * 只有显式 falsy(0/false/no/off)⇒ `undefined`(不 stamp ⇒ 引擎缺省 reap)。
+ * 服务端 `retainBackgroundProcessesFromBody` 是 `raw !== true ⇒ 丢弃` 的严格刻度,所以 opt-out 一律
+ * 表达为**不 stamp**,绝不发 `false`(形状诚实)。
+ * PURE — callers pass `env`;caller gates to LIVE mode(mock request shape 不变)。
+ */
+import { hostEnv } from './hostEnv.js';
+/** The env key the shell reads(SEMA_ 命名空间,与引擎自己的 spec∨env 通道正交——这里是壳→
+ *  TaskRequest 的 per-request 意图面,非引擎部署面)。 */
+export const RETAIN_BACKGROUND_ENV = 'SEMA_RETAIN_BACKGROUND';
+/** FALSY spellings that opt OUT (case-insensitive, trimmed). Conservative allowlist —— 只有这些
+ *  拼写能关掉 retain;其它一切(含未识别值/空串)落缺省 ON,绝不静默 opt-out。 */
+function isFalsy(v) {
+    const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return s === '0' || s === 'false' || s === 'no' || s === 'off';
+}
+/**
+ * ENV source → `true`(缺省 ON = CC `run_in_background` 契约:后台进程活过当轮),
+ * 只有显式 falsy 逃生口(`SEMA_RETAIN_BACKGROUND=0|false|no|off`)⇒ `undefined`(不 stamp ⇒ 引擎缺省 reap)。
+ * 返回型刻意是 `true | undefined` —— 服务端 `raw !== true ⇒ 丢弃`,opt-out 只能表达为「不 stamp」。
+ */
+export function retainBackgroundFromEnv(env = hostEnv()) {
+    return isFalsy(env[RETAIN_BACKGROUND_ENV]) ? undefined : true;
+}

package/dist/rewindWireCaps.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/rewindWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/rewindWireCaps.ts — PURE CC Rewind (E18) field projection (no deps, testable). seamQuery imports it.
+ *
+ * Maps the CC /rewind MessageSelector modes → the engine's rewind fields (SDK TaskRequest, core 1.166.0;
+ * resumeAtMode: core 1.292 [833]):
+ *   both         = { resumeAt, resumeAtMode:"before", rewindFiles:true }   fork BEFORE the user message + tree
+ *   conversation = { resumeAt, resumeAtMode:"before" }                     fork BEFORE the user message only
+ *   code         = { rewindFilesTo }                restore the tree only, NO conversation fork (no setLeafId)
+ * The target is a USER-MESSAGE SessionTreeEntry.id (server anchors user-message boundaries). Plus the per-turn
+ * CAPTURE stamp (rewindFiles:true on a normal turn) so the engine snapshots the tree (else nothing to restore).
+ *
+ * resumeAtMode "before"(排他截,core 1.292):CC /rewind 的语义是「回到发这条消息之前」——被选中的
+ * user message 回填输入框、从对话里移除;engine 侧对应 setLeafId(entry.parentId)。旧的含目标(inclusive
+ * "at")形状会把该 user message 留在引擎历史里 → 模型仍记得(暗号复现 bug)。老 server 未透传该字段时
+ * 行为退回含目标(version-safe,无回归——等 server 透传)。
+ */
+/** A one-shot rewind RESTORE instruction (or the per-turn capture stamp) projected onto a request. */
+export interface SeamRewindSpec {
+    resumeAt?: string;
+    /** core 1.292([833]):"before" = 排他截(setLeafId(entry.parentId));缺省 "at" = 含目标。 */
+    resumeAtMode?: 'at' | 'before';
+    rewindFiles?: boolean;
+    rewindFilesTo?: string;
+}
+/** The CC /rewind restore modes that hit the engine (summarize = compact, handled elsewhere). */
+export type RewindMode = 'both' | 'conversation' | 'code';
+/** Build the engine rewind fields for a chosen mode + target user-message entryId. */
+export declare function rewindSpecForMode(mode: RewindMode, targetEntryId: string): SeamRewindSpec;
+/**
+ * PURE projection (no state): an armed one-shot RESTORE wins; else the per-turn CAPTURE stamp (when enabled);
+ * else nothing. The caller consumes (clears) the arm after a restore.
+ */
+export declare function projectRewind(pending: SeamRewindSpec | undefined, captureEnabled: boolean): SeamRewindSpec;

package/dist/rewindWireCaps.js

@@ -0,0 +1,41 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/rewindWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/rewindWireCaps.ts — PURE CC Rewind (E18) field projection (no deps, testable). seamQuery imports it.
+ *
+ * Maps the CC /rewind MessageSelector modes → the engine's rewind fields (SDK TaskRequest, core 1.166.0;
+ * resumeAtMode: core 1.292 [833]):
+ *   both         = { resumeAt, resumeAtMode:"before", rewindFiles:true }   fork BEFORE the user message + tree
+ *   conversation = { resumeAt, resumeAtMode:"before" }                     fork BEFORE the user message only
+ *   code         = { rewindFilesTo }                restore the tree only, NO conversation fork (no setLeafId)
+ * The target is a USER-MESSAGE SessionTreeEntry.id (server anchors user-message boundaries). Plus the per-turn
+ * CAPTURE stamp (rewindFiles:true on a normal turn) so the engine snapshots the tree (else nothing to restore).
+ *
+ * resumeAtMode "before"(排他截,core 1.292):CC /rewind 的语义是「回到发这条消息之前」——被选中的
+ * user message 回填输入框、从对话里移除;engine 侧对应 setLeafId(entry.parentId)。旧的含目标(inclusive
+ * "at")形状会把该 user message 留在引擎历史里 → 模型仍记得(暗号复现 bug)。老 server 未透传该字段时
+ * 行为退回含目标(version-safe,无回归——等 server 透传)。
+ */
+/** Build the engine rewind fields for a chosen mode + target user-message entryId. */
+export function rewindSpecForMode(mode, targetEntryId) {
+    switch (mode) {
+        case 'both':
+            return { resumeAt: targetEntryId, resumeAtMode: 'before', rewindFiles: true };
+        case 'conversation':
+            return { resumeAt: targetEntryId, resumeAtMode: 'before' };
+        case 'code':
+            return { rewindFilesTo: targetEntryId };
+    }
+}
+/**
+ * PURE projection (no state): an armed one-shot RESTORE wins; else the per-turn CAPTURE stamp (when enabled);
+ * else nothing. The caller consumes (clears) the arm after a restore.
+ */
+export function projectRewind(pending, captureEnabled) {
+    if (pending)
+        return { ...pending };
+    if (captureEnabled)
+        return { rewindFiles: true };
+    return {};
+}

package/dist/seam.d.ts

@@ -6,13 +6,69 @@
  * (StampedAgentEvent.id/seq/toolCallId),ctx.uuid() 仅兜底无稳定键合成帧;
  * 往返守卫不变量:同流重放 ⇒ 同 id 序列。
  */
-import type { SDKMessage } from '@sema-agent/agent-types';
-/** 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。 */
+import type { ModelUsage, SDKMessage } from '@sema-agent/agent-types';
+/**
+ * `AbortSignal` 的结构型(B3 扩容,SEAM-GAP-4)。
+ *
+ * 🔴 **别写成 `AbortSignal`**:本包 tsconfig 是 `"types": []` + 无 DOM lib(浏览器可移植性的
+ * 静态保障),`AbortSignal` 这个名字在本包里根本不存在。真 `AbortSignal`(浏览器原生 / Node
+ * globalThis)结构上满足本型,直接传即可,零适配。
+ */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+}
+/** 宿主定时器句柄(不透明:Node 是 Timeout 对象、浏览器是 number,库侧只负责回传)。 */
+export type TimerHandle = unknown;
+/** `ctx.log` 的级别词表(cli utils/debug logForDebugging 的等价面)。 */
+export type AdapterLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * 宿主注入的适配上下文(时钟/铸号可测,B 形跨端确定性)。
+ *
+ * **B3 扩容(0.5.0,契约 minor —— 只加可选位,既有宿主零改动)**:下面五个可选口是
+ * 「客户端内核需要、但实现方式因端而异」的能力(设计稿 §5.4①)。浏览器实现全部原生零 polyfill:
+ * `log`→console/上报、`probe`→省略、`signal`→AbortController.signal、
+ * `setTimer/clearTimer`→setTimeout/clearTimeout。
+ *
+ * 🔴 **缺席语义都是「该能力不启用」,不是「报错」也不是「换个方式偷偷做」**:
+ * 内核绝不 `require('fs')` 写探针、绝不 `console.log`、绝不 `setTimeout` 兜底 ——
+ * 那正是这批要切掉的东西(§5.2 的 33 个 `utils/debug` 消费点)。
+ */
 export interface AdapterContext {
     sessionId: string;
     /** 兜底铸号——仅当帧无稳定键时使用(见 deriveTranscriptId)。 */
     uuid(): string;
     now(): number;
+    /**
+     * 诊断日志(替 cli `utils/debug.logForDebugging` —— 那一行 import 就把 1565 个文件拉进闭包,
+     * 是浏览器可移植性的头号污染源,设计稿 §2.1.3)。缺席 = 内核静默(绝不回落 console)。
+     */
+    log?(level: AdapterLogLevel, msg: string, data?: unknown): void;
+    /**
+     * 行式探针(替 cli 的 6 处 `SEMA_*_PROBE` 文件探针 —— Ink 挂载后 console 被吞,壳侧靠写文件
+     * 取证)。`channel` = 探针名(如 `'stream'`),`line` = 单行载荷。浏览器宿主直接省略。
+     */
+    probe?(channel: string, line: string): void;
+    /**
+     * turn 级中断信号(SEAM-GAP-4)。Esc/abort 后内核立刻停止投影,**不产终答**
+     * (CC 自己的 abort 路径渲 InterruptedByUser chrome,由宿主负责)。
+     * 缺席 = 该 turn 不可中断(既有行为)。
+     */
+    signal?: AbortSignalLike;
+    /**
+     * 宿主定时器(T40 IDLE-FLUSH 竞速需要)。`fn` 到点执行一次。
+     * 🔴 **缺席 = IDLE-FLUSH 过渡修不启用**(纯等下一帧,与 0.4.0 逐字同行为)——绝不用
+     * `setTimeout` 兜底:那会在没有宏任务概念的宿主上凭空造出一个时钟。
+     */
+    setTimer?(ms: number, fn: () => void): TimerHandle;
+    clearTimer?(handle: TimerHandle): void;
+    /**
+     * 活体增量攒批节拍(T29)。缺席 = `FLUSH_INTERVAL_MS` 默认值。
+     * 🔴 这是**宿主渲染策略**,不是 wire 语义:CC 自己两个端就是两个值(桌面宿主
+     * `makeStreamDeltaCoalescer`=16ms 单帧攒批;我们对标的 CC 2.1.207 CLI 口径=100ms,
+     * 降重绘频率让长回答滚动更稳)。合并**语义**(先思考后文本、段边界重开块)与节拍无关,
+     * 所以节拍下放给宿主、语义留库里。
+     */
+    coalesceIntervalMs?: number;
 }
 /** chrome 平面事件 v1 枚举(cli 现役 UI 面归纳;additive 演进,臂只增不改)。
  *
@@ -150,6 +206,45 @@ export type ChromeEvent = {
     toolName: string;
     toolUseId: string;
     input: unknown;
+}
+/**
+ * B3 新臂 ①(T38 三清的第三清 + T57 五处断闸的第五处)—— E12「下一步可问什么」建议**批**。
+ * `suggestions: null` = 作废(turn 开场必发一次:上一轮的建议对新上下文是噪声,挂着不掉会让人
+ * 以为是这一轮的产出);非空数组 = 本轮产出。
+ * 🔴 UNTRUSTED 模型文本(service 已 redact),**仅 UI**:宿主消费义务 = 推给 composer 上方的
+ * chips 面;**绝不回喂模型、绝不落转录、绝不进 /compact 的对话体**。
+ * 子流(parentToolCallId 标)的建议不发本臂 —— 断闸在库里,不摊给宿主。
+ */
+ | {
+    kind: 'prompt_suggestions';
+    laneProof: LaneProof;
+    suggestions: readonly string[] | null;
+}
+/**
+ * B3 新臂 ②(runStream 外向边切除,设计稿 §5.2 第二条边)—— 每个 leader `turn_end` 折叠出的
+ * 真 usage。此前是 runStream 里一条 `void import('lastTurnUsageStore')` 的壳内动态边。
+ * 宿主消费义务:落「最近一次 turn 的真 usage」槽,供 statusline 类消费面在消息面取不到 usage
+ * 时回落(不落 = 插件的 Context 条恒 0%,原病复发)。子流 turn_end **不发本臂**(判据同 §E2:
+ * statusline 显示的是主会话窗口,子代 usage 会把 Context% 打成孩子的窗口占用)。
+ */
+ | {
+    kind: 'last_turn_usage';
+    laneProof: LaneProof;
+    usage: ModelUsage;
+}
+/**
+ * B3 新臂 ③(runStream 外向边切除,设计稿 §5.2 头号污染源)—— `done{status:"needs_review"}` +
+ * gate `plan_review` 的 park 终帧。此前是 runStream 里一条 `await import('planReviewWire')`,
+ * 而 planReviewWire → `utils/debug` → **整棵 1565 文件的 CC 树**进闭包(浏览器可移植性归零)。
+ * 宿主消费义务:弹审批卡(cli 借 AskUserQuestion overlay 合成 question,决断走
+ * `/v1/assistant/tasks/:id/plan_review` resume verb);**fail-soft**——不实现或实现失败都不影响
+ * 紧随其后的终态帧照常投影(用户至少看到 plan fence + 一条普通完成)。
+ * `result` = done 帧的 RAW `result` 载荷(判形与取 taskId 都由宿主做,库不猜)。
+ */
+ | {
+    kind: 'plan_review_park';
+    laneProof: LaneProof;
+    result: unknown;
 };
 /** 车道纪律一等公民([1617] 家族固化):chrome 事件构造必须携判别证明。 */
 export type LaneProof = {

package/dist/selfOrchestrationWireCaps.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/selfOrchestrationWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/selfOrchestrationWireCaps.ts — PURE projection: the shell's "enable the LLM-authored workflow engine"
+ * opt-in → the TOP-LEVEL `TaskRequest.selfOrchestration` boolean the SERVICE consumes. Mirrors webSearchWireCaps.ts
+ * (the verified wire pattern), but the field rides at the TOP of the body (not under `settings`).
+ *
+ * The SERVICE reads `body.selfOrchestration` STRICTLY (ai-agent-service task-workflow.ts `selfOrchestrationFromBody`:
+ * `body.selfOrchestration !== true` ⇒ dropped) → core `TaskSpec.selfOrchestration`, the gate that MOUNTS core's
+ * LLM-authored `run_workflow` engine (the workflow.ts agent/parallel/pipeline/phase/nested orchestrator). The
+ * service then gates it on the DEPLOYMENT's `SELF_ORCHESTRATION_ENABLED` (else a harmless no-op, dropped) + the
+ * MULTI-TENANT per-principal entitlement RESOLVER (fail-closed: no resolver ⇒ dropped); a single-user worker honors
+ * it directly. So the shell's job is ONLY to STAMP the intent when the user opted in — the service owns every gate.
+ * We mirror the service's strict `=== true` semantics here: only an explicit truthy env opt-in returns `true`;
+ * everything else returns `undefined` (⇒ NO stamp ⇒ the engine never mounts run_workflow ⇒ default behaviour
+ * unchanged, exactly like an absent webSearch config).
+ *
+ * Config source (clay 决定 2026-07-01 §4 — DEFAULT-ON,opt-out):
+ *   - DEFAULT ON: unset / 其它 ⇒ stamp `selfOrchestration:true`(RunWorkflow 默认可用,体验像 CC 超集)。
+ *   - ENV opt-OUT: `SEMA_SELF_ORCHESTRATION=0/false/no/off` ⇒ undefined(no stamp)。
+ *
+ * 前身是 opt-in(parity-safe 保守默认 OFF);clay 拍 §4 后翻转为默认 ON(TOC 单用户本机无 entitlement 顾虑,
+ * 引擎侧 SELF_ORCHESTRATION_ENABLED 也在 assembleChildEnv 默认开)。可后续接 settings.json 驱动,这里仍是单一投影点。
+ *
+ * PURE — no env/file IO of its OWN (callers pass `env`), so it bundles + unit-tests without the heavy settings
+ * graph, exactly like webSearchWireCaps. The CALLER (seamQuery / seamQueryEngine) gates the env read to LIVE mode
+ * so the mock request shape never changes; the selfOrchestration stamp IS the opt-in (no extra flag needed).
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The env key the shell reads. SEMA_-namespaced so it never collides with the worker's OWN deploy
+ *  `SELF_ORCHESTRATION_ENABLED` env (the service's DEPLOYMENT gate — a different axis the service owns). */
+export declare const SELF_ORCHESTRATION_ENV: "SEMA_SELF_ORCHESTRATION";
+/** ENV source → `true` by DEFAULT (clay 决定 2026-07-01 §4:RunWorkflow 默认可用),unless the user explicitly
+ *  opts OUT (`SEMA_SELF_ORCHESTRATION=0/false/no/off`) ⇒ `undefined` (no stamp; engine never mounts run_workflow).
+ *  Still `true | undefined` (never `false`) to mirror the service's strict `=== true` read. A stamped `true` only
+ *  makes run_workflow AVAILABLE — the engine still owns the final gate (its own `SELF_ORCHESTRATION_ENABLED`, set
+ *  default-on in TOC assembleChildEnv, + per-principal entitlement; TOC single-user honors it directly). The caller
+ *  gates this to LIVE mode, so the MOCK request shape is unchanged; only the live default path now stamps true. */
+export declare function selfOrchestrationFromEnv(env?: EnvLike): true | undefined;

package/dist/selfOrchestrationWireCaps.js

@@ -0,0 +1,48 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/selfOrchestrationWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/selfOrchestrationWireCaps.ts — PURE projection: the shell's "enable the LLM-authored workflow engine"
+ * opt-in → the TOP-LEVEL `TaskRequest.selfOrchestration` boolean the SERVICE consumes. Mirrors webSearchWireCaps.ts
+ * (the verified wire pattern), but the field rides at the TOP of the body (not under `settings`).
+ *
+ * The SERVICE reads `body.selfOrchestration` STRICTLY (ai-agent-service task-workflow.ts `selfOrchestrationFromBody`:
+ * `body.selfOrchestration !== true` ⇒ dropped) → core `TaskSpec.selfOrchestration`, the gate that MOUNTS core's
+ * LLM-authored `run_workflow` engine (the workflow.ts agent/parallel/pipeline/phase/nested orchestrator). The
+ * service then gates it on the DEPLOYMENT's `SELF_ORCHESTRATION_ENABLED` (else a harmless no-op, dropped) + the
+ * MULTI-TENANT per-principal entitlement RESOLVER (fail-closed: no resolver ⇒ dropped); a single-user worker honors
+ * it directly. So the shell's job is ONLY to STAMP the intent when the user opted in — the service owns every gate.
+ * We mirror the service's strict `=== true` semantics here: only an explicit truthy env opt-in returns `true`;
+ * everything else returns `undefined` (⇒ NO stamp ⇒ the engine never mounts run_workflow ⇒ default behaviour
+ * unchanged, exactly like an absent webSearch config).
+ *
+ * Config source (clay 决定 2026-07-01 §4 — DEFAULT-ON,opt-out):
+ *   - DEFAULT ON: unset / 其它 ⇒ stamp `selfOrchestration:true`(RunWorkflow 默认可用,体验像 CC 超集)。
+ *   - ENV opt-OUT: `SEMA_SELF_ORCHESTRATION=0/false/no/off` ⇒ undefined(no stamp)。
+ *
+ * 前身是 opt-in(parity-safe 保守默认 OFF);clay 拍 §4 后翻转为默认 ON(TOC 单用户本机无 entitlement 顾虑,
+ * 引擎侧 SELF_ORCHESTRATION_ENABLED 也在 assembleChildEnv 默认开)。可后续接 settings.json 驱动,这里仍是单一投影点。
+ *
+ * PURE — no env/file IO of its OWN (callers pass `env`), so it bundles + unit-tests without the heavy settings
+ * graph, exactly like webSearchWireCaps. The CALLER (seamQuery / seamQueryEngine) gates the env read to LIVE mode
+ * so the mock request shape never changes; the selfOrchestration stamp IS the opt-in (no extra flag needed).
+ */
+import { hostEnv } from './hostEnv.js';
+/** The env key the shell reads. SEMA_-namespaced so it never collides with the worker's OWN deploy
+ *  `SELF_ORCHESTRATION_ENABLED` env (the service's DEPLOYMENT gate — a different axis the service owns). */
+export const SELF_ORCHESTRATION_ENV = 'SEMA_SELF_ORCHESTRATION';
+/** The FALSY spellings that opt OUT (case-insensitive, trimmed). Conservative allowlist — only an explicit
+ *  `0`/`false`/`no`/`off` disables; everything else (incl. unset/empty) is the DEFAULT-ON path. */
+function isFalsy(v) {
+    const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return s === '0' || s === 'false' || s === 'no' || s === 'off';
+}
+/** ENV source → `true` by DEFAULT (clay 决定 2026-07-01 §4:RunWorkflow 默认可用),unless the user explicitly
+ *  opts OUT (`SEMA_SELF_ORCHESTRATION=0/false/no/off`) ⇒ `undefined` (no stamp; engine never mounts run_workflow).
+ *  Still `true | undefined` (never `false`) to mirror the service's strict `=== true` read. A stamped `true` only
+ *  makes run_workflow AVAILABLE — the engine still owns the final gate (its own `SELF_ORCHESTRATION_ENABLED`, set
+ *  default-on in TOC assembleChildEnv, + per-principal entitlement; TOC single-user honors it directly). The caller
+ *  gates this to LIVE mode, so the MOCK request shape is unchanged; only the live default path now stamps true. */
+export function selfOrchestrationFromEnv(env = hostEnv()) {
+    return isFalsy(env[SELF_ORCHESTRATION_ENV]) ? undefined : true;
+}

package/dist/sessionModelLatch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sessionModelLatch.ts 逐字搬入(零依赖;🔴 三个模块级 latch 是单实例态)。
+ */
+/**
+ * sessionModelLatch — 件13 (rev2 2026-07-14, CC 2.1.207 对锚): support module for the /model `s`
+ * (use this session only) split, anchored on the 207 mechanism (verified against the 2.1.198 pretty
+ * source, semantics identical in 207):
+ *
+ *   wsr(model, get, set, setDefault):                        // pretty.js:493226 (198 coords)
+ *     set(a => ({ ...a, mainLoopModel: model, mainLoopModelForSession: null }))   // ALWAYS in-memory
+ *     if (setDefault) RQt(model)                              // RQt = eo("userSettings",{model}) —
+ *                                                             // the ONLY settings write (493244)
+ *     message = `Set model to X${setDefault ? " and saved as your default for new sessions"
+ *                                            : " for this session only"}`
+ *
+ * i.e. in 207 BOTH Enter and `s` write the in-memory mainLoopModel and CLEAR the plan-mode session
+ * field; persistence is EXPLICIT (RQt) and only runs on set-as-default. 207 has no auto-persisting
+ * model choke point. sema's bundled base DOES auto-persist every mainLoopModel change in
+ * state/onChangeAppState.ts, so to reproduce the 207 state shape exactly the session-only commit
+ * marks its write with a ONE-SHOT skip-persist flag which the choke consumes: the write then behaves
+ * exactly like 207's no-RQt branch (mainLoopModel set in-memory, mainLoopModelForSession null,
+ * userSettings untouched → restart reverts to the persisted default).
+ *
+ * The latch half mirrors "the active model is UNPERSISTED" for NON-React consumers (seamQuery's
+ * modelEndpointSwitch runs outside the component tree): a session-only pick must not be promoted to
+ * next-boot roster/env state when the engine can route the model by itself. Kept in sync from the
+ * onChangeAppState choke (single funnel for every setAppState write): set on a session-only
+ * mainLoopModel write OR a plan-mode mainLoopModelForSession write, cleared on a persisted write.
+ */
+export declare function setSessionModelLatch(model: string | null): void;
+export declare function getSessionModelLatch(): string | null;
+export declare function markSessionOnlyModelWrite(): void;
+export declare function consumeSessionOnlyModelWrite(): boolean;
+export declare function markUserModelPickThisSession(): void;
+export declare function hasUserModelPickThisSession(): boolean;

package/dist/sessionModelLatch.js

@@ -0,0 +1,63 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sessionModelLatch.ts 逐字搬入(零依赖;🔴 三个模块级 latch 是单实例态)。
+ */
+/**
+ * sessionModelLatch — 件13 (rev2 2026-07-14, CC 2.1.207 对锚): support module for the /model `s`
+ * (use this session only) split, anchored on the 207 mechanism (verified against the 2.1.198 pretty
+ * source, semantics identical in 207):
+ *
+ *   wsr(model, get, set, setDefault):                        // pretty.js:493226 (198 coords)
+ *     set(a => ({ ...a, mainLoopModel: model, mainLoopModelForSession: null }))   // ALWAYS in-memory
+ *     if (setDefault) RQt(model)                              // RQt = eo("userSettings",{model}) —
+ *                                                             // the ONLY settings write (493244)
+ *     message = `Set model to X${setDefault ? " and saved as your default for new sessions"
+ *                                            : " for this session only"}`
+ *
+ * i.e. in 207 BOTH Enter and `s` write the in-memory mainLoopModel and CLEAR the plan-mode session
+ * field; persistence is EXPLICIT (RQt) and only runs on set-as-default. 207 has no auto-persisting
+ * model choke point. sema's bundled base DOES auto-persist every mainLoopModel change in
+ * state/onChangeAppState.ts, so to reproduce the 207 state shape exactly the session-only commit
+ * marks its write with a ONE-SHOT skip-persist flag which the choke consumes: the write then behaves
+ * exactly like 207's no-RQt branch (mainLoopModel set in-memory, mainLoopModelForSession null,
+ * userSettings untouched → restart reverts to the persisted default).
+ *
+ * The latch half mirrors "the active model is UNPERSISTED" for NON-React consumers (seamQuery's
+ * modelEndpointSwitch runs outside the component tree): a session-only pick must not be promoted to
+ * next-boot roster/env state when the engine can route the model by itself. Kept in sync from the
+ * onChangeAppState choke (single funnel for every setAppState write): set on a session-only
+ * mainLoopModel write OR a plan-mode mainLoopModelForSession write, cleared on a persisted write.
+ */
+/** The model that is currently ACTIVE but UNPERSISTED (session-only pick or plan-mode override). */
+let sessionModelOverride = null;
+export function setSessionModelLatch(model) {
+    sessionModelOverride = model;
+}
+export function getSessionModelLatch() {
+    return sessionModelOverride;
+}
+/** One-shot mark: the NEXT mainLoopModel change is session-only (207 no-RQt branch) — do not persist. */
+let sessionOnlyWritePending = false;
+export function markSessionOnlyModelWrite() {
+    sessionOnlyWritePending = true;
+}
+export function consumeSessionOnlyModelWrite() {
+    const v = sessionOnlyWritePending;
+    sessionOnlyWritePending = false;
+    return v;
+}
+// ── 件3(F1 模型面批,S3 铁律半场):本会话「用户显式选过模型」标记 ─────────────────────
+// boot 目录回读(replEntry 把 /v1/models default 写进 initialState.mainLoopModel)不经过
+// setAppState ⇒ 不置位;任何经 setAppState 的 mainLoopModel 变更(cmd-model Enter、`s` 键、
+// /model <name>、config 面板)都算显式 pick —— 由 onChangeAppState choke(每个 setAppState
+// 写的单一漏斗)置位,散在 UI 调用点零改动。ensureEngineServesModel 据此区分「运行时回声」
+// (boot 回读的目录 default)vs「用户意图」:回声绝不允许持久化写(不 switchRoster 改 env /
+// 不重排 models.json / 不改档位绑定)。注意与上面 latch 的分工:latch=「当前活跃值未持久化」
+// (s 键/plan override),本标记=「本会话内发生过显式选择」——s 键 pick 也置位(它是显式意图,
+// 是否持久化由件13 latch 在 instant 路径拦截,语义不变)。
+let userModelPickThisSession = false;
+export function markUserModelPickThisSession() {
+    userModelPickThisSession = true;
+}
+export function hasUserModelPickThisSession() {
+    return userModelPickThisSession;
+}

package/dist/skillsWireCaps.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/skillsWireCaps.ts 逐字搬入(只 import SDK)。
+ */
+/**
+ * src/sema/skillsWireCaps.ts — the PURE projection + server caps for the skills engine wire.
+ *
+ * Split out from skillsWire.ts so this logic (the part worth pinning) is testable WITHOUT the heavy on-disk
+ * loader graph (loadSkillsDir / loadPluginCommands pull analytics/signals/fs). It imports ONLY the `SkillSpec`
+ * type (erased at build), so a test can esbuild-bundle THIS file alone — no runtime side effects.
+ *
+ * The caps mirror the SDK `TaskRequest.skills` server caps (types.ts:82): ≤10 items, name ≤64, description
+ * ≤1024, content ≤32768 — a violation is a 400, so we truncate/limit HERE to make the live request well-formed
+ * by construction.
+ */
+import type { SkillSpec } from '@sema-agent/sdk';
+/** Server caps for `TaskRequest.skills` (SDK types.ts:82 — violations are a 400). */
+export declare const SKILL_CAPS: {
+    readonly items: 10;
+    readonly name: 64;
+    readonly description: 1024;
+    readonly content: 32768;
+};
+/** The minimal shape of a loaded skill `Command` this projection reads (a structural subset of CC's Command,
+ *  cast at the call site so we stay decoupled from the wide Command union). */
+export interface SkillCmdLike {
+    type?: string;
+    name?: string;
+    description?: string;
+    whenToUse?: string;
+    /** loader origin ('builtin' | 'plugin' | SettingSource…) — read by the skillOverrides four-state
+     *  resolution when the wire prunes hidden skills (skillsWire.ts). */
+    source?: string;
+    disableModelInvocation?: boolean;
+    /** the skill's own directory (`createSkillCommand` baseDir → command.skillRoot); SKILL.md lives at root/SKILL.md. */
+    skillRoot?: string;
+}
+/** Build one capped `SkillSpec`, or null when there is no usable name/body. description folds in `whenToUse`
+ *  (CC's progressive-disclosure metadata is name+description+whenToUse) so the engine's Skill tool can select
+ *  it. All three fields are truncated to the server caps. */
+export declare function toCappedSpec(name: string, description: string, whenToUse: string, body: string): SkillSpec | null;
+/**
+ * PURE projection: loaded skill commands → `SkillSpec[]` (capped, deduped by name, ≤10 items). `resolveBody`
+ * supplies each command's raw SKILL.md body (null ⇒ skip); injecting it keeps this function IO-free and
+ * unit-testable. Only MODEL-INVOCABLE prompt skills are sent — UI-only / `disableModelInvocation` commands
+ * are excluded (engine injection feeds the model's Skill tool, not the slash menu).
+ */
+export declare function skillCommandsToSpecs(cmds: SkillCmdLike[], resolveBody: (cmd: SkillCmdLike) => string | null): SkillSpec[];

package/dist/skillsWireCaps.js

@@ -0,0 +1,41 @@
+/** Server caps for `TaskRequest.skills` (SDK types.ts:82 — violations are a 400). */
+export const SKILL_CAPS = { items: 10, name: 64, description: 1024, content: 32768 };
+/** Build one capped `SkillSpec`, or null when there is no usable name/body. description folds in `whenToUse`
+ *  (CC's progressive-disclosure metadata is name+description+whenToUse) so the engine's Skill tool can select
+ *  it. All three fields are truncated to the server caps. */
+export function toCappedSpec(name, description, whenToUse, body) {
+    const n = name.trim().slice(0, SKILL_CAPS.name);
+    const c = body.trim().slice(0, SKILL_CAPS.content);
+    if (!n || !c)
+        return null;
+    const desc = [description.trim(), whenToUse.trim()]
+        .filter((s) => s.length > 0)
+        .join(' — ')
+        .slice(0, SKILL_CAPS.description);
+    return { name: n, description: desc, content: c };
+}
+/**
+ * PURE projection: loaded skill commands → `SkillSpec[]` (capped, deduped by name, ≤10 items). `resolveBody`
+ * supplies each command's raw SKILL.md body (null ⇒ skip); injecting it keeps this function IO-free and
+ * unit-testable. Only MODEL-INVOCABLE prompt skills are sent — UI-only / `disableModelInvocation` commands
+ * are excluded (engine injection feeds the model's Skill tool, not the slash menu).
+ */
+export function skillCommandsToSpecs(cmds, resolveBody) {
+    const specs = [];
+    const seen = new Set();
+    for (const cmd of cmds) {
+        if (specs.length >= SKILL_CAPS.items)
+            break;
+        if (cmd.type !== 'prompt' || cmd.disableModelInvocation)
+            continue;
+        const body = resolveBody(cmd);
+        if (!body)
+            continue;
+        const spec = toCappedSpec(cmd.name ?? '', cmd.description ?? '', cmd.whenToUse ?? '', body);
+        if (!spec || seen.has(spec.name))
+            continue;
+        seen.add(spec.name);
+        specs.push(spec);
+    }
+    return specs;
+}

package/dist/sseIdleTriage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sseIdleTriage.ts 逐字搬入(只 import SDK)。
+ */
+/**
+ * src/sema/sseIdleTriage.ts — turn-stream SSE idle-silence triage(TB2.0 反馈批 D · P0-2 壳半场,2026-07-15)。
+ *
+ * WHY: TB2.0 bench 真实案例 —— agent 长跑前台编译 ~9.5min,工具完成前壳侧 45s 空闲监测器
+ * (`@sema-agent/sdk` readSseFrames HEARTBEAT_GRACE_MS)命中 `SSE: no data for 45000ms (heartbeat
+ * silence)` → 整轮 rc=1 丢弃,引擎不知情继续跑完(access log 499)。分诊报告判决①修正段拍定:
+ * 壳侧独立可发 = S1(SDK grace 透传+typed SseIdleError,0.0.47 已发)+ S4(grace 旋钮)+
+ * S3 缩水版(engine-alive-idle 分诊,只改报错文案,不重连)。本模块 = S4 + S3 的共享件。
+ *
+ * S4 · SEMA_SSE_HEARTBEAT_GRACE_MS(settings.json `env` 块 → 1a-envseed → process.env,其它 wire
+ * 旋钮同一车道):整数毫秒,合法域 [5000, 600000];非法/缺省 = 不透传(SDK 默认 45s)——静默
+ * fail-soft,一个 settings typo 绝不 brick 任何 run(scenarioWire settings-lane 纪律)。
+ * ⚠️ 作用面 = 会话 turn 流(tasks.stream / liveClient)一条车道。SDK 控制通道(SSETransport.ts:21
+ * LIVENESS_TIMEOUT_MS=45s)自带重连+give-up 自愈,本旋钮【不】达那条车道——这不是全局 grace。
+ *
+ * S3 缩水版 · engine-alive-idle 分诊:liveClient 的 tasks.stream 包装 catch 到 SseIdleError 时,
+ * 先判 signal.aborted(用户中止契约先行,seamQuery.ts:1073——Esc 撕流绝不被分诊吞),再 GET
+ * `/health`(非 /healthz;server dist server.js:290)短超时探引擎活性:引擎死 → 原样抛(现行
+ * engine-down/not-restart 路径不变);引擎活 → 给同一错误对象打 engine-alive-idle 标记,
+ * seamQuery 的 tearVerdict 恢复腿据此渲染诚实分诊文案(engineAliveIdleContent)。
+ *
+ * 【本模块绝不重连】(判决①修正段圣旨,范围随 M2 精化):非 detach 车道上 tasks/stream 客户端
+ * 断连 = server onDisconnect ac.abort() 终止 run(anti token-burn by design),且该车道帧无 id
+ * 不可位置续传——空闲监测器抛出的那一刻 finally 已 cancel res.body,run 已被这次断连自身中止,
+ * 同 key in-flight 重放拿到的只是 aborted 结局。前台另有既有裁决:mid-turn 工具副作用非幂等,
+ * 绝不自动重发。引擎 E2(server ≥1.196 x-detach-on-disconnect,[854]①)已到货:headless `-p`
+ * detach 车道的 R1 换道重连 = 重连腿 M2,住在 headlessReconnectWire.ts(liveClient 管线最内层,
+ * 只在 detach 头已发出的流上武装);本模块保持「探活+打标,不重连」——交互 REPL 与一切非
+ * detach 车道的取消契约一根毛不动,M2 耗尽预算后判死文案也仍由这里的打标驱动。
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。整数毫秒。 */
+export declare const SSE_HEARTBEAT_GRACE_ENV = "SEMA_SSE_HEARTBEAT_GRACE_MS";
+/** 合法域下界:低于 5s 会把正常 token 间隙误判成静默。 */
+export declare const SSE_GRACE_MIN_MS = 5000;
+/** 合法域上界:10min——超过引擎自身各级 idle 顶,再长没有意义。 */
+export declare const SSE_GRACE_MAX_MS = 600000;
+/** SDK 默认(readSseFrames HEARTBEAT_GRACE_MS)——文案引用用,不在本模块生效。 */
+export declare const SDK_DEFAULT_GRACE_MS = 45000;
+/**
+ * S4 — resolve the turn-stream heartbeat grace override. Unset/empty → undefined(SDK 默认 45s,
+ * 不透传);非纯十进制整数 / 超出 [5000,600000] → undefined(静默落默认,fail-soft)。
+ */
+export declare function resolveSseHeartbeatGraceMs(env?: EnvLike): number | undefined;
+/** 给 SseIdleError 打 engine-alive-idle 标(引擎 /health 已确认活着)。返回同一对象。 */
+export declare function markEngineAliveIdle<E extends Error>(err: E): E;
+/**
+ * engine-alive-idle 判型:命中返回静默时长 elapsedMs(SseIdleError 0.0.47 自带;缺失兜 0),
+ * 未命中返回 undefined。seamQuery tearVerdict 腿与 headless `-p` 的 stderr 面共用。
+ */
+export declare function engineAliveIdleElapsedMs(err: unknown): number | undefined;
+/**
+ * SseIdleError 判型:instanceof 为主;双包风险(bundle 内外两份 SDK class identity 分叉)下
+ * name 兜底——name 由 SDK 构造器冻结为 'SseIdleError',非我方铸造。
+ */
+export declare function isSseIdleError(err: unknown): boolean;
+/**
+ * 引擎活性探针 — SDK probeHealth(GET `${baseUrl}/health`;端点是 /health 非 /healthz),默认 2s
+ * 预算,永不抛:alive = 200 且 status==='ok';非 2xx / 不可达 / 超时 = not alive(引擎死 → 现行
+ * 失败路径,分诊绝不让真死引擎空等)。与 engineUpgradeCoordinator 的 classifyStreamTear 同款姿势。
+ * SDK 宪法迁移批差分记账:原实现只看 res.ok(200 非 JSON / status!=='ok' 也判活);SDK 额外要
+ * status==='ok'——service /health 200 恒报 status:'ok',契约面等价,对「200 但引擎自述非 ok」的
+ * 病态更严格诚实。
+ */
+export declare function probeEngineAlive(baseUrl: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * S3 缩水版 — the tasks.stream diagnose wrapper(liveClient 出口整流罩)。
+ * 透传 inner 的每个事件;仅当 inner 以 SseIdleError 收场时介入:
+ *   1. signal.aborted 先行 — 用户中止(Esc)撕流原样抛,绝不探活/绝不改判(seamQuery.ts:1073 契约);
+ *   2. GET /health 探引擎活性(2s 预算);
+ *   3. 引擎活 → 同一错误对象打 engine-alive-idle 标后重抛(下游 tearVerdict 腿改文案;detach `-p`
+ *      车道的 R1 重连发生在更内层的 headlessReconnectWire——错误能到这里 = 重连已耗尽/不可换道);
+ *      引擎死/探测失败 → 原样重抛(现行 classifyStreamTear 会诚实判 engine-down)。
+ * 非 SseIdleError 一律原样穿透。
+ */
+export declare function diagnoseSseIdleTear<T>(inner: AsyncGenerator<T>, baseUrl: string, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * engine-alive-idle 的用户可见分诊文案(升级自裸 "API Error: SSE: no data for …" 行)。
+ * 措辞如实(判决②契约),按 detach 态分叉:
+ *  · 非 detach(默认/旋钮关/版本门拒/交互车道):tasks/stream 断连 = server 端 abort 这次 run——
+ *    不许说"任务仍在继续"的安慰话;能给的出路只有 grace 旋钮 + 手动重发。字节与批 D 发运稿一致
+ *    (存量脚本可能 grep)。
+ *  · detach 态(重连腿 M1,`x-detach-on-disconnect: true` 已随首次 POST 发出,server ≥1.196):
+ *    断连【不再】abort run——run 已 detach,引擎会把它后台跑完并落 durable 账本;文案如实改述并
+ *    指 `GET /v1/runs/<id>`(taskId 已知时带上)/ `sema resume` 查终局。M1 不重连(M2/M3),
+ *    本轮前台 rc 仍非零——这是净改善:结果不再整轮丢弃。
+ */
+export declare function engineAliveIdleContent(elapsedMs: number, detach?: {
+    detached: true;
+    taskId?: string;
+}): string;