@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/sqlEngineCapability.js

@@ -1,63 +1,9 @@
-/**
- * sqlEngineCapability — S-131「SQL 引擎姿态」的**三端共用读面**(server ≥7.60.0 的
- * `GET /v1/capabilities` 新增 `sql` 位;sdk 8.3.0 `Capabilities.sql`)。
- *
- * ── 归层出身(不掩盖:这份窄读器**本来就该在这里**)────────────────────────────────────────
- * 0.58.0 时本件写在壳里(cli `src/sema/sqlEngineCapability.ts`),理由是当时 client-core 的
- * `engineCapsCache` 公面只到「平铺布尔 / 平铺串 / 嵌套布尔」三形,**没有嵌套对象的读口** ⇒ 这一格
- * 在包侧结构上读不出来。0.59.0 两件同批补齐:`engineCapsCache` 加四态读口
- * {@link import("./engineCapsCache.js").engineCapValue},本模块把壳那份窄读器**逐字上收**。
- * 🔴 **导出名与壳侧那份逐字相同**,这是 drift-lock:包一发同名符号,壳的
- * `run-layer-shadow-export-gate-test.mjs`(同名影子导出门)当场红,逼那份壳侧副本换装成
- * `export { … } from '@sema-agent/client-core'`,而不是两边各自演进(DISEASE-SHAPES S37 的病形
- * 正是「包侧有了、壳侧没删」)。
- *
- * ── 上游事实(fixture 直证,不采信 CHANGELOG)──────────────────────────────────────────────
- * `@sema-agent/server/dist/http/routes/capabilities.js` 的回体里多一位
- * `sql: projectSqlEngineCapability(deps.sqlEngineFacts?.())`;7.59.0 的同一文件**没有这个键**。
- * 值的形(`server/dist/sql-engine-posture.d.ts` 逐字):
- *   · `{ engine, isolation, txnMode }` —— 驱动在**真连接**上 `SET` 完之后**回读**的值
- *     (「取实例真值,不按配置推断」);
- *   · `null` —— **本部署没有 SQL 后端**(env-only / local 文件后端)。逐字:「缺席就是缺席…
- *     不铸一个看起来像答案的空壳」。
- *
- * ── 🔴 四态,不是两态([honest-absence-not-fabricated-zero])────────────────────────────────
- * 这一格上有**四件互不相同**的事,消费端一件都不许折进另一件:
- *   ① `unobserved` —— **本进程一次 caps 响应都没观测到**。一次性 `sema doctor` 就是这一档
- *      (它不起 live client ⇒ caps tee 从来没触发过)。它**不是**「引擎没有 SQL」。
- *   ② `not_reported` —— caps 观测到了,而回体上**没有** `sql` 这个键 ⇒ 老引擎(<7.60.0)。
- *      它**不是**「这台部署没有 SQL 后端」—— 老引擎有没有库,这个读面答不了。
- *   ③ `none` —— 引擎**明确说** `null`:这台部署没有 SQL 后端。这是一个**正面事实**,不是缺席;
- *      把它渲成「未观测」等于把引擎真给的答案丢掉(壳自 spawn 的单机形恒落这一档,是常态读数)。
- *   ④ `present` —— 三座俱全,原样渲。
- * 🔴 **绝不渲 0 / 绝不编一个姿态**:读不出来就说读不出来,哪一种读不出来也要分清楚。
- * ⇄ 这四个词与 {@link import("./engineCapsCache.js").EngineCapValueState} 的四态**同一套词汇**
- *   (`unobserved` / `not_reported` / `null`→`none` / `value`→`present`):通用读口答「这一格上有
- *   没有值」,本模块答「这一格的值成不成形」,刻意分层 —— 通用口不认识 `sql` 的三座,窄读器不该
- *   重新实现一遍缓存与代际。
- *
- * ── 🔴 UNTRUSTED-for-display ──────────────────────────────────────────────────────────────
- * `isolation` 是从**数据库服务器**变量里回读的串(`@@transaction_isolation` 一族),不是引擎铸的
- * 闭词;三座一律只渲染、绝不参与任何判定,呈现前过本包的单行消毒 + 封长单源
- * ({@link capForDisplay}:先转义、后按转义结果封长)。
- */
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
 import { createEngineCapReader } from './engineCapReader.js';
-/**
- * caps 回体 → 本格读数;**畸形一律 `undefined`**(= 这一格不写 ⇒ 读口答 `unobserved`)。
- *
- * 🔴 `undefined`(键不在)与 `null`(引擎说没有)**是两件事**,本函数是本包唯一区分它们的地方:
- *    前者 ⇒ `not_reported`(老引擎),后者 ⇒ `none`(这台部署没库)。用 `??` / falsy 判会把
- *    两者压成一件,而它们对运维的意思完全不同。
- * 🔴 三座**任一**不是非空串 ⇒ 整条判畸形(`undefined`)。绝不留一个缺座的对象:一行写着
- *    「isolation: 」的诊断比不渲这一行更坏(它看起来像一个答案)。
- */
 export function projectSqlEngineCapability(caps) {
     if (caps === null || typeof caps !== 'object')
         return undefined;
-    // 0.77.0 整族改齐:① 非对象 / 数组 caps 不是能力表 ⇒ 畸形(投影答 undefined ⇒ 删格 ⇒ 读口答 unobserved),不再答 not_reported
-    //    (那是把「取不到」冒充「报了但没提」);② 在场判据改 hasOwn —— 原型链上的同名键永远不会被序列化上 wire,读成在场 = 凭空造一格。
     if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
         return undefined;
     if (!Object.hasOwn(caps, 'sql'))
@@ -70,7 +16,6 @@ export function projectSqlEngineCapability(caps) {
     if (typeof sql !== 'object')
         return undefined;
     const s = sql;
-    // 🔴 只读一次(0.74.2 CC-69 复审 R1 族扫):校验与返回各读一次,变化的 getter 会让校验读到合形、返回读到别的。
     const engine = s.engine;
     const isolation = s.isolation;
     const txnMode = s.txnMode;
@@ -78,102 +23,38 @@ export function projectSqlEngineCapability(caps) {
         return undefined;
     if (typeof isolation !== 'string' || isolation === '')
         return undefined;
-    // 🔴 `txnMode`:`null` 是**铸点域内的合法值**(见 SqlEngineCapabilityView 顶注),不是畸形。
-    //    但这一位在铸点上**恒在场** ⇒ 键缺席(`undefined`)与非串非 null 仍判载体坏了。
     if (txnMode !== null && (typeof txnMode !== 'string' || txnMode === ''))
         return undefined;
     return { kind: 'present', view: { engine, isolation, txnMode } };
 }
-/**
- * 本格的 per-baseUrl 读账 + tee / 读口 / 失效口 / 测试钩四口 —— 各只能力位读器**共用同一份实现**
- * ({@link createEngineCapReader});本文件只留这一格真正不同的部分:投影函数 {@link projectSqlEngineCapability}、doctor 措辞表,以及本位自己的判据助手(如有)。
- * 🔴 Map 在工厂闭包里,**一只读器一张**:收到读不懂的回体只删自己这一格,绝不连坐别的能力面。
- */
 const reader = createEngineCapReader({
     name: 'sql',
     project: projectSqlEngineCapability,
     makeUnobserved: () => ({ kind: 'unobserved' }),
 });
-/**
- * 宿主 caps probe 的**读面 tee** 落点(壳侧与 mcpGate / sessionBackground / projectContext /
- * crashConverged / workflowsGate 五条并列)。绝不 throw —— 读面腿不许反噬 caps 探测链。
- *
- * 🔴 投影 `undefined`(caps 畸形)⇒ 这一格**被删**而不是留着上一台引擎的旧值 —— 留旧值 = 拿一台
- *    已经不在的引擎的读数去回答「这台现在是什么姿态」。
- * ⚠️ **这一条只覆盖「收到了一份读不懂的回体」**。「同端口 respawn / 版本回滚之后新探测**失败或
- *    还在飞**」是**另一条路** —— 那时本 tee 一次都不触发,挡不住旧读数继续被当成当代事实。
- *    那一形由 {@link forgetSqlEngineReading} 在装配口(宿主的引擎温切臂)上收。
- * 🔴 **不按 principal 分域**:SQL 姿态是**这台 worker 的连接事实**,与调用者是谁无关
- *    (与 `workflows` 那种 per-caller 的位刻意不同)—— 加一个用不上的去重域只会造出一条
- *    「换主体就读不到」的假缺席。
- *
- * 🔴 **`opts.generation` = 关掉「旧探测覆盖新读数」那条竞态的唯一正确供给**(0.60.0;异源对抗复审
- *    [medium] 采纳,真病):`kickEngineCapsProbe` 的代际闸在 **probe 返回之后**才跑,而本 tee 是在
- *    probe **内部**落地的 ⇒ 一次慢的旧探测能在 `invalidateEngineCaps` + 新探测都走完之后才返回,
- *    把**上一台引擎**的读数重新写回来。宿主在**起探测那一刻**调 `engineCapsGeneration(baseUrl)` 抓号、
- *    在这里原样交回,陈旧那一发就会被整只丢掉。
- *    ⚠️ **不传 = 与本位到货之前逐字节同行为**(照写)—— additive 供给,不是强制门;端没跟上之前不会
- *    有任何东西变坏。🔴 **tee 自己抓号是假判据**(陈旧那一发在这里读到的是新代号,永远像当代的)。
- */
 export function noteEngineCapsForSqlEngine(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
 }
-/**
- * 本进程观测到的 SQL 姿态;这一格空缺 ⇒ `{kind:'unobserved'}`(**绝不**折成 `none`)。
- *
- * 缺省读锚 = {@link engineWireTarget} 的 `baseUrl`(本包零 `process` —— portability 门盯着;
- * 壳那份直读 `process.env.SEMA_LIVE_BASEURL`,而 `engineWireTarget()` 的 env 臂读的就是同一个变量
- * ⇒ Node 壳上行为一字节不变,浏览器/桌面宿主则由 `installEngineWireTarget()` 显式装)。
- */
 export function observedSqlEngine(baseUrl = engineWireTarget()?.baseUrl) {
     return reader.observed(baseUrl);
 }
-/** 单行 UNTRUSTED 座的展示上限(UTF-16 单元;与壳侧那份同值)。 */
 const SQL_DETAIL_MAX = 40;
-/**
- * 单行 UNTRUSTED 座的呈前规整:**先转义、后按转义结果封长**({@link capForDisplay})。
- *
- * 🔴 0.62.0 改了顺序,理由记全(此前这里刻意写的是先截后转义):旧注释担心的是「先清后截会把一个
- *    转义序列拦腰截断,屏上留下 `\u20` 这种既不是字符也不是转义的残片」—— 那个顾虑是对的,但它的
- *    解法不是把顺序反过来,而是**截点避让**:共用铸点在截点落进一枚 `\uXXXX` 中间时回退到该 token
- *    之前(合法代理对同理回退一位)。两个毛病只能同时消掉一次:先截后转义留下的是**预算失守**
- *    (纯控制字符的 40 字符原文转义后占 240 个显示字符,是承诺列宽的六倍),那是比残片更硬的一条。
- * ⚠️ **与壳那份的已知呈现差分**(换装时随批裁一次):壳 `sqlEngineDoctorDetail` 走的是
- *    `.` 占位形消毒器(1:1,先截后清与先清后截等价),而壳自己的头注写着「单行字段(路径/URL/
- *    参数键值)**必须**用可见转义形」—— 三座正是单行标量。本包按那条规则实现,所以对**正常读数**
- *    (`tidb` / `REPEATABLE-READ` / `pessimistic`)两侧逐字节相同,只有含控制符的病态值渲染形不同。
- */
 function cleanSqlDetailScalar(v) {
     return capForDisplay(v, SQL_DETAIL_MAX);
 }
-/**
- * 四态 → doctor 那一行的 detail 串。**唯一措辞真源**(三端共用一句话;别在各端的行装配里另写
- * 一遍 —— 那正是这次上收要消灭的东西)。
- *
- * 🔴 三座是 UNTRUSTED-for-display(`isolation` 是从**数据库服务器**变量里回读的串):呈前消毒 +
- *    封长。消毒放在这一处而不是各呈现点,是因为本函数的产物就是屏上那一串(单一出口)。
- * 🔴 四句话刻意**互不相同、也互不蕴含**:「未观测」不许说成「没有库」,「老引擎不报」也不许
- *    说成「没有库」—— 三种「读不出」对运维是三条不同的下一步。
- */
 export function sqlEngineDoctorDetail(reading) {
     switch (reading.kind) {
         case 'unobserved':
-            // 0.59.2(cli B-038):不点名任何端的命令 —— 「去哪里看」是端的事,包只说事实。
             return ('not observed — the engine reports it on /v1/capabilities; this process has no usable ' +
                 'capabilities reading cached for it (none received, or the last one was unreadable)');
         case 'not_reported':
             return 'not reported by this engine — the capability position needs a newer engine';
         case 'none':
-            // 0.59.2(cli 1.0.102 异源复审 [medium]):server 7.61.0 起 `sql:null` 同时覆盖「没配 SQL 后端」与
-            //    「池初始化被拒」,wire 上不可分 ⇒ 这句话**不推断因由**,两种可能都点名并指向引擎日志。
             return ('none — the engine reports no SQL engine posture: either this deployment has no SQL backend, ' +
                 'or its initialization was refused (the engine log says which)');
         case 'present': {
             const e = cleanSqlDetailScalar(reading.view.engine);
             const i = cleanSqlDetailScalar(reading.view.isolation);
-            // 🔴 `null` 是上游明说的「这个引擎没有这个指示位」,**不是** `optimistic`(d.ts 逐字点名的
-            //    误读),也不是「读不出来」⇒ 渲一句显式的话,既不留白也不编一个档位。
-            //    消毒器对 `null` 无意义(它只吃串),所以这一格必须在消毒**之前**分臂。
             const t = reading.view.txnMode === null
                 ? 'no txn-mode indicator on this engine'
                 : cleanSqlDetailScalar(reading.view.txnMode);
@@ -181,24 +62,9 @@ export function sqlEngineDoctorDetail(reading) {
         }
     }
 }
-/**
- * **换代失效口**(与 {@link import("./engineCapsCache.js").invalidateEngineCaps} 并列,由宿主在
- * 引擎温切成功后调)。
- *
- * 🔴 **代际闸挡不住这一形**:那道闸挡的是「旧响应**写脏**新一代」(tee 只在确认代际仍当代之后
- *    才落地),而本格的病是反过来的 —— 新一代的探测**根本没成功**(超时 / reject / 还在飞),
- *    tee 于是一次都没触发,上一台引擎留在同一端口上的读数就继续被 {@link observedSqlEngine}
- *    当成**当代事实**答出去。同端口 respawn / 版本回滚 / 引擎起不来三条路都走这里,而它在
- *    doctor 上的形态最坏:一行**肯定句**(「这台部署是 tidb 悲观事务」/「这台引擎不报这一位,
- *    要升级」),说的却是一台已经不在的引擎。
- * 🔴 处置是**清成未观测**,不是留旧值也不是铸一个 `none` —— 「我这一代还没听到答案」是这一格
- *    唯一诚实的话(与 {@link noteEngineCapsForSqlEngine} 对畸形回体的处置同向)。
- * 空串 ⇒ no-op;绝不 throw(它跑在引擎温切路径上)。
- */
 export function forgetSqlEngineReading(baseUrl) {
     reader.forget(baseUrl);
 }
-/** 测试钩子。 */
 export function __resetSqlEngineReadingsForTests() {
     reader.__resetForTests();
 }

package/dist/sseIdleTriage.d.ts

@@ -1,93 +1,14 @@
-/**
- * ⇄ 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;

package/dist/sseIdleTriage.js

@@ -1,107 +1,39 @@
-/**
- * ⇄ 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 { hostEnv } from './hostEnv.js';
 import { SseIdleError, probeHealth as sdkProbeHealth } from '@sema-agent/sdk';
-/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。整数毫秒。 */
 export const SSE_HEARTBEAT_GRACE_ENV = 'SEMA_SSE_HEARTBEAT_GRACE_MS';
-/** 合法域下界:低于 5s 会把正常 token 间隙误判成静默。 */
 export const SSE_GRACE_MIN_MS = 5_000;
-/** 合法域上界:10min——超过引擎自身各级 idle 顶,再长没有意义。 */
 export const SSE_GRACE_MAX_MS = 600_000;
-/** SDK 默认(readSseFrames HEARTBEAT_GRACE_MS)——文案引用用,不在本模块生效。 */
 export const SDK_DEFAULT_GRACE_MS = 45_000;
-/**
- * S4 — resolve the turn-stream heartbeat grace override. Unset/empty → undefined(SDK 默认 45s,
- * 不透传);非纯十进制整数 / 超出 [5000,600000] → undefined(静默落默认,fail-soft)。
- */
 export function resolveSseHeartbeatGraceMs(env = hostEnv()) {
     const raw = env[SSE_HEARTBEAT_GRACE_ENV]?.trim();
     if (!raw)
         return undefined;
     if (!/^\d+$/.test(raw))
-        return undefined; // 纯十进制整数——'45e3'/'45000.5'/'-1' 全部落默认
+        return undefined;
     const n = Number(raw);
     if (!Number.isSafeInteger(n) || n < SSE_GRACE_MIN_MS || n > SSE_GRACE_MAX_MS)
         return undefined;
     return n;
 }
-/** 给 SseIdleError 打 engine-alive-idle 标(引擎 /health 已确认活着)。返回同一对象。 */
 export function markEngineAliveIdle(err) {
     ;
     err.semaTearVerdict = 'engine-alive-idle';
     return err;
 }
-/**
- * engine-alive-idle 判型:命中返回静默时长 elapsedMs(SseIdleError 0.0.47 自带;缺失兜 0),
- * 未命中返回 undefined。seamQuery tearVerdict 腿与 headless `-p` 的 stderr 面共用。
- */
 export function engineAliveIdleElapsedMs(err) {
     const e = err;
     if (!e || e.semaTearVerdict !== 'engine-alive-idle')
         return undefined;
     return typeof e.elapsedMs === 'number' && Number.isFinite(e.elapsedMs) ? e.elapsedMs : 0;
 }
-/**
- * SseIdleError 判型:instanceof 为主;双包风险(bundle 内外两份 SDK class identity 分叉)下
- * name 兜底——name 由 SDK 构造器冻结为 'SseIdleError',非我方铸造。
- */
 export function isSseIdleError(err) {
     if (err instanceof SseIdleError)
         return true;
     return err?.name === 'SseIdleError';
 }
-/**
- * 引擎活性探针 — 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 async function probeEngineAlive(baseUrl, timeoutMs = 2_000) {
     return (await sdkProbeHealth(baseUrl, timeoutMs)).alive;
 }
-/**
- * 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 async function* diagnoseSseIdleTear(inner, baseUrl, signal) {
     try {
         yield* inner;
@@ -113,17 +45,6 @@ export async function* diagnoseSseIdleTear(inner, baseUrl, signal) {
         throw err;
     }
 }
-/**
- * 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 function engineAliveIdleContent(elapsedMs, detach) {
     const secs = Math.max(1, Math.round((elapsedMs > 0 ? elapsedMs : SDK_DEFAULT_GRACE_MS) / 1000));
     const graceTail = `If your tasks legitimately go quiet this long (e.g. a long build), raise the idle grace: set ${SSE_HEARTBEAT_GRACE_ENV} ` +

package/dist/steering.d.ts

@@ -1,71 +1,17 @@
-/**
- * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
- * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
- *
- * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
- * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
- * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
- *
- * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
- * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
- * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:
- * `deadline_nudge` / `finalize` (TB telemetry B3) and the design/133 turn-boundary attachment
- * producers `todo_reminder` / `task_reminder` / `changed_files` / `plan_mode`, plus the G1 [482]
- * members `background_tasks` / `tools_delta` (core 1.253).
- *
- * [479] ask-1 contract: a renderer that branches on `source` MUST carry a default arm — core may add
- * sources without a cross-repo lockstep. This mapper is that branch point: known sources get their
- * copy (the 四值文案), everything else falls to the generic default row (never dropped, never a
- * crash). PURE (no env/IO) so it unit-tests without the render graph — the wireCaps pattern.
- *
- * Render policy (CC 2.1.198 parity): CC NULL-renders its own turn-boundary reminders
- * (`todo_reminder` / `task_reminder` / `plan_mode` are in NULL_RENDERING_TYPES — the user never sees
- * them in the normal transcript). The projected `steering_injected` attachment therefore renders
- * ONLY in transcript (ctrl+o) / verbose mode (AttachmentMessage arm) — normal-mode output stays
- * byte-identical to CC, while sema's two-process split keeps engine-side injections observable.
- */
-/** A sema `steering_injected` attachment (transcript/verbose-only dim row). */
 export interface SteeringInjectedAttachment {
     type: 'steering_injected';
-    /** The wire source verbatim (open set — core may extend). */
     source: string;
-    /** Per-source display copy (the [479] ask-1 四值 + defaults). */
     label: string;
-    /** The injected body's first 220 chars (wire-clipped), newline-flattened by the renderer. */
     preview: string;
 }
-/**
- * The CC `task_status` attachment shape ([487]② G1 backgroundTasks): the SAME attachment the LOCAL
- * post-compact path produces (services/compact/compact.ts task_status rows), so the engine's
- * post-compact recap renders through the SAME GenericTaskStatus (vbl) component — `Task "{desc}"
- * completed in background / still running in background / stopped`, 198 verbatim. VISIBLE (CC
- * renders these, unlike the reminders). `outputFilePath` omitted — the task lives engine-side.
- */
 export interface EngineTaskStatusAttachment {
     type: 'task_status';
     taskId: string;
     taskType: 'local_bash';
-    /** 0.73.3(CC-60 A-D13):+`parked`(core 第四个 vbl 臂:停在待批检查点 —— 恰是最需要用户看见的状态)。 */
     status: 'pending' | 'running' | 'completed' | 'failed' | 'killed' | 'parked';
     description: string;
     deltaSummary: null;
 }
 export type SteeringRenderable = SteeringInjectedAttachment | EngineTaskStatusAttachment;
-/** Default-arm label for a source this shell build predates.
- *
- *  🔴 **按自有属性查表**(0.63.0 同形存量清剿;与 `gateVocabulary` / `permissionRuleIssue` /
- *     `engineNoticeCodes` 三处同一条病形):`SOURCE_LABELS` 是对象表而 `source` **来自 wire**,
- *     裸下标会命中 `Object.prototype` 上的成员 —— `steeringLabel('constructor')` 返回一个**函数**,
- *     而 `??` 对函数不生效 ⇒ 它被原样拼进 attachment 的 label。默认臂在这一形上等于不存在。 */
 export declare function steeringLabel(source: string): string;
-/**
- * Project one `steering_injected` wire event into its renderable attachment(s). Always returns at
- * least one attachment (default 兜底) — an engine injection is never silently invisible in
- * transcript mode, whatever the source.
- *
- * `background_tasks` ([487]② G1): the preview lines parse into CC `task_status` attachments — the
- * SAME (VISIBLE) GenericTaskStatus/vbl rendering the LOCAL post-compact path uses, three-state copy
- * 198 verbatim, `[task_id]` addressable via TaskOutput/TaskStop. A preview clipped beyond
- * recognition falls back to the generic (transcript-only) row — never invisible, never a crash.
- */
 export declare function steeringInjectedToAttachments(source: string, preview: string): SteeringRenderable[];

package/dist/steering.js

@@ -1,31 +1,3 @@
-/**
- * steering.ts — `steering_injected` → renderable attachment projection (PURE)。
- * cli src/sema/steeringAttachments.ts 的逐字搬运(#52a;差分守卫钉两侧等价)。
- *
- * B1 批(2026-07-27):本文件正文与 cli `steeringAttachments.ts` 实测**逐字节相同**(`diff` 空),
- * 按设计稿 §2.4.1-A 裁决「不留两份实现」⇒ 本文件即唯一实现,壳侧文件改成本包的 re-export。
- * 双份消解方式是「壳侧让位」而非合并 —— 无需改动本文件任何一行行为码。
- *
- * core 1.251 (design/133, board [479] ask-1) echoes every engine-side SYSTEM steering injection as a
- * `steering_injected` wire event `{source, preview}` — `preview` = the injected body's first 220 chars
- * (runtask.ts:2320), echo-only (the model-facing message is unchanged). Sources today:
- * `deadline_nudge` / `finalize` (TB telemetry B3) and the design/133 turn-boundary attachment
- * producers `todo_reminder` / `task_reminder` / `changed_files` / `plan_mode`, plus the G1 [482]
- * members `background_tasks` / `tools_delta` (core 1.253).
- *
- * [479] ask-1 contract: a renderer that branches on `source` MUST carry a default arm — core may add
- * sources without a cross-repo lockstep. This mapper is that branch point: known sources get their
- * copy (the 四值文案), everything else falls to the generic default row (never dropped, never a
- * crash). PURE (no env/IO) so it unit-tests without the render graph — the wireCaps pattern.
- *
- * Render policy (CC 2.1.198 parity): CC NULL-renders its own turn-boundary reminders
- * (`todo_reminder` / `task_reminder` / `plan_mode` are in NULL_RENDERING_TYPES — the user never sees
- * them in the normal transcript). The projected `steering_injected` attachment therefore renders
- * ONLY in transcript (ctrl+o) / verbose mode (AttachmentMessage arm) — normal-mode output stays
- * byte-identical to CC, while sema's two-process split keeps engine-side injections observable.
- */
-/** Per-source display copy. [479] ask-1 四值 + the pre-existing TB sources. Open set — an unknown
- *  source falls to the default label (never dropped). */
 const SOURCE_LABELS = {
     todo_reminder: 'Todo list reminder re-surfaced to the model',
     task_reminder: 'Task list reminder re-surfaced to the model',
@@ -33,39 +5,20 @@ const SOURCE_LABELS = {
     plan_mode: 'Plan mode constraint re-surfaced to the model',
     deadline_nudge: 'Deadline nudge injected',
     finalize: 'Finalize instruction injected',
-    // G1 [482]/[487]② — background_tasks normally projects to VISIBLE task_status rows below; this
-    // label is its parse-failure fallback (clipped-beyond-recognition preview) + the tools_delta row.
     background_tasks: 'Background tasks from before compaction announced to the model',
     tools_delta: 'Newly available tools announced to the model',
 };
-/** Default-arm label for a source this shell build predates.
- *
- *  🔴 **按自有属性查表**(0.63.0 同形存量清剿;与 `gateVocabulary` / `permissionRuleIssue` /
- *     `engineNoticeCodes` 三处同一条病形):`SOURCE_LABELS` 是对象表而 `source` **来自 wire**,
- *     裸下标会命中 `Object.prototype` 上的成员 —— `steeringLabel('constructor')` 返回一个**函数**,
- *     而 `??` 对函数不生效 ⇒ 它被原样拼进 attachment 的 label。默认臂在这一形上等于不存在。 */
 export function steeringLabel(source) {
     const known = typeof source === 'string' && Object.hasOwn(SOURCE_LABELS, source)
         ? SOURCE_LABELS[source]
         : undefined;
     return known ?? `Steering injected (${source})`;
 }
-/**
- * core turn-attachments.ts renderBackgroundTasks line shape (198 vbl VERBATIM phrases):
- *   `- [${task_id}] Task "${description}" ${phrase}`
- * phrase: completed → "completed in background" · killed → "stopped" · running → "still running in
- * background" · anything else → the raw status word (core's own fallback arm). The wire preview is
- * clipped at 220 chars, so the LAST line may be cut — a non-matching line is skipped, never fails
- * the batch.
- */
 const PHRASE_TO_STATUS = [
     ['completed in background', 'completed'],
     ['still running in background', 'running'],
     ['stopped', 'killed'],
-    // 0.73.3(A-D13):core 第四个 vbl 臂,排在 raw-status 兜底组之前(此前恒不命中 ⇒ compaction 后停在待批检查点的行整行消失)。
     ['parked awaiting an out-of-band approval — do NOT re-issue the gated call', 'parked'],
-    // core's raw-status fallback arm for the non-vbl states (announce snapshots pending/running, but
-    // parse defensively — a settle can race the boundary).
     ['pending', 'pending'],
     ['running', 'running'],
     ['completed', 'completed'],
@@ -82,11 +35,6 @@ function parseBackgroundTaskLine(line) {
         const m = /^- \[([^\]]+)\] Task "([\s\S]*)$/.exec(head);
         if (!m)
             return null;
-        // 🔴 [2393] sweep-F16(2026-08-03 全窗复审):这里**不许**回落成空串。两个捕获组都是非可选的,
-        // `m` 非空时它们必在场(所以这条早退今天不可达),但 `?? ''` 的**形**是「不知道就渲空串」——
-        // 与同窗刚立的口径(`fleetAgentPanelProjection`「缺席就是 undefined,这里不许兜 0」/
-        // `seatContract`「绝不回落成 0(那会渲成 1970)」)相反,且真出问题时会静默产出一条 taskId
-        // 为空串的任务行(谁也定位不到)。noUncheckedIndexedAccess 适配的正解是**如实拒绝**。
         const taskId = m[1];
         const description = m[2];
         if (taskId === undefined || description === undefined)
@@ -102,16 +50,6 @@ function parseBackgroundTaskLine(line) {
     }
     return null;
 }
-/**
- * Project one `steering_injected` wire event into its renderable attachment(s). Always returns at
- * least one attachment (default 兜底) — an engine injection is never silently invisible in
- * transcript mode, whatever the source.
- *
- * `background_tasks` ([487]② G1): the preview lines parse into CC `task_status` attachments — the
- * SAME (VISIBLE) GenericTaskStatus/vbl rendering the LOCAL post-compact path uses, three-state copy
- * 198 verbatim, `[task_id]` addressable via TaskOutput/TaskStop. A preview clipped beyond
- * recognition falls back to the generic (transcript-only) row — never invisible, never a crash.
- */
 export function steeringInjectedToAttachments(source, preview) {
     if (source === 'background_tasks') {
         const tasks = preview
@@ -120,7 +58,6 @@ export function steeringInjectedToAttachments(source, preview) {
             .filter((t) => t !== null);
         if (tasks.length > 0)
             return tasks;
-        // fall through: clipped/unrecognized body → generic row (default 兜底)
     }
     return [{ type: 'steering_injected', source, label: steeringLabel(source), preview }];
 }