@sema-agent/client-core 0.11.18 → 0.11.19

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.11.18
+**Version:** 0.11.19
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver

package/dist/agentSession/backgroundView.d.ts

@@ -22,16 +22,65 @@
  * ── 'not-configured' 判别(诚实缺席纪律)────────────────────────────────────────────────────
  *   · fleet:面 gated off 时路由在任何帧之前答 **501**(typed)—— 501 ⇒ 'not-configured',
  *     其它错 ⇒ 'unavailable'(拒绝形分档;错误判型走 controlRouter.errCodes 单源)。
- *   · assistant:无 TiDB run store 时 worker 回 `{tasks:[]}` **原样透传** —— wire 上与真空
- *     不可区分。能探则探:`GET /v1/capabilities` 的 `scheduler` 位(server `schedulerEnabled &&
- *     requirePrincipal!==true && remoteExec==="host"` 三与)为 false/缺席 ⇒ 'not-configured';
- *     caps 面自己不可达 ⇒ 判别缺席,**如实回 'ok'**(绝不编造判别)。🔴 残余缺口候引擎位:
- *     scheduler:true 而 run store 未配的 `{tasks:[]}` 仍与真空同形 —— 需要 wire 长出判别位
- *     (caps 或响应信封)才能收口,本实现不猜。
+ *   · assistant:无 run store 时 worker 回 `{tasks:[]}` **原样透传** —— wire 上与真空不可区分。
+ *     能探则探:`GET /v1/capabilities` 的 **`approvals`** 位为 false ⇒ 'not-configured';
+ *     caps 面自己不可达 ⇒ 判别缺席,**如实回 'ok'**(绝不编造判别)。
  *
- * 字段纪律:缺席=键不在场(undefined),🔴 绝不 `?? 0` / `?? false`;ISO→epoch ms 只在
- * assistant 行边界转一次;fleet 复合 id("<runId> <taskId>")整串不拆;fleet 子行(parentId
- * 在场)不进 rows(子代不是用户的独立后台任务)。
+ *     🔴 件 3 考据(读错键的定谳,小黑板 [C33]③.3 → server [C34],server 3.13.0 已把辖域写进
+ *     代码注与 ARCHITECTURE):本实现此前读 `scheduler`,那是**错的键**。
+ *       · `/v1/assistant/*` 的挂载条件是 `checkpointStore`(server `routes/approvals-assistant.ts:67`
+ *         的分支头:`if (deps.checkpointStore && (url.startsWith("/v1/approvals") ||
+ *         url.startsWith("/v1/assistant")))`),而 caps 里**同一个谓词**的键是 `approvals`
+ *         (`capabilities.ts:56` `approvals: Boolean(deps.checkpointStore)`)。键名窄(approvals)、
+ *         辖域宽(整条 assistant 车道)——按名字猜会猜错,这是上游文档欠账不是消费端不小心。
+ *       · `scheduler` 是**另一回事**:host 单用户腿的自唤醒 cron 工具(CronCreate/CronDelete/
+ *         CronList),它对自己承诺的东西是诚实的,与「计划运行视图在不在」无关。
+ *       · 实测后果(3.7.0 local 形,DB_BACKEND=local 无 DURABLE_APPROVAL):caps.scheduler=true 而
+ *         `GET /v1/assistant/tasks`=404 ⇒ 面板**永久**渲「Scheduled runs can't be reached right now」。
+ *       · 🔴 两个看似更省事的修法都**不采**(server [C34] 逐条否掉):(a) 把 404 并进
+ *         not-configured —— 会吞掉「caps 说有路由却 404」这个真信号(真的漏注册/误删就再也看不见);
+ *         (b) server 把 checkpointStore 与进 scheduler —— 会污染一个本来准确的键。
+ *         **判别规则一个字没改,只改读哪个键。**
+ *       · 🔴 换键**不**收口的残余缺口(照旧候引擎位,本实现不猜):`approvals:true`(checkpointStore
+ *         在)而 run store 未配时,worker 仍回 `{tasks:[]}` —— 那份空列表与「真的没有任务」在
+ *         wire 上依旧同形。要收口需要 wire 长出判别位(caps 或响应信封),不是客户端能推出来的。
+ *
+ * 字段纪律:缺席=键不在场(undefined),🔴 绝不 `?? 0` / `?? false` / `?? ''`;ISO→epoch ms 只在
+ * assistant 行边界转一次(updatedAt/createdAt 同一个转换器,fleet 的 startedAt 本就是 epoch ms
+ * 直出);fleet 复合 id("<runId> <taskId>")整串不拆;fleet 子行(parentId 在场)不进 rows
+ * (子代不是用户的独立后台任务)。两源的时间锚是**两个不同的量**,各占各的契约位、互不顶替:
+ * assistant 给 `createdAtMs`(创建时刻)、fleet 给 `startedAtMs`(launch 时刻)——见 contract.ts
+ * 两处逐位说明。fleet 行的 `sessionId`/`scope` 被 server `stripT` 剥掉不上 wire,别在投影里等。
+ *
+ * ── 📋 下一批工单(件 4 调研,不在本批实现):BackgroundRow 的 canonical stop 能力判别 ────────
+ * 起因(小黑板 [C33]③.4):web 报「`runs.cancel` 的 id 空间是 taskId,而 fleet 顶层行 id 是 runId、
+ * 子行是复合 id」⇒ 他们对 fleet 行**不渲 Stop**(没有已挣得的取消路径就不摆按钮 —— 这个处置本身
+ * 是对的,server [C34] 也同意)。主会话裁定:**不是「fleet 行没有停止路径」,而是要按行类型分**。
+ * 下一批要落的形状(本批只调研落档,不新建 API):
+ *   ① **能力判别**应当是行上的一等位(建议 `stop?: { verb, target }` 或等价判别),由包算、端只读
+ *      —— 端各自判 = 每端一份猜测,正是本批修的那类病。缺席即「本行不可停」,端据此**显隐** Stop。
+ *   ② **verb × id 映射**(包内既有件,全部已核实):
+ *      · agent 行(fleet 顶层/子行):`runs.taskStop(hostRunId, handle)`,包内封装 =
+ *        `src/subagent/engineTaskHandleWire.ts`(`POST /v1/runs/:id/tasks/:handle/stop?session=`)。
+ *        **handle 取法**:复合 id `"<runId> <taskId>"` 取尾段 = 引擎 taskId —— 包内已有同语义实现
+ *        `rowIdTail()`(`src/workflow.ts:24`,导出;`src/fleetAgentPanelProjection.ts:94` 有零依赖叶
+ *        的私有同款副本);宿主 run 解析走 `getBgParentRun(handle) ?? activeEngineRunId()`。
+ *        **能力门** = `capabilities.taskHandles`(`src/subagent/engineRowStopGate.ts`
+ *        `engineTaskHandlesCapable()`),🔴 别 trial-by-404。
+ *        **回执纪律**(同文件 `engineRowNeedsStopConfirm()`):只有 **200 算停了**;409
+ *        `stop.not_landed` / `stop.not_local` 一律保持原状(引擎里可能还在跑),端绝不自己翻 killed。
+ *      · 顶层 durable run 行:`runs.cancel(taskId)`(包内 `controlRouter.cancel`,202 ack)。
+ *        🔴 但 **park 住的行不能走它**:suspended/needs_review 行要 cancel-by-DENY
+ *        (`src/hitl/hitlBridge.ts:283` / `src/hitl/askGateWire.ts:417` 逐字纪律)——
+ *        所以「行在等人」(status==='waiting-on-human')时 stop 判别必须映射到决断面而不是 cancel。
+ *      · workflow 行:**今天包/SDK 面上没有 workflow 的停止 verb** —— 实装 SDK 2.0.0 的
+ *        `WorkflowsResource` 只有 list/get/journal/stream/steerAgent(逐个核过);而 `runs.d.ts:224`
+ *        写着「a workflow handle 404s — stop workflows via their cancel face」,那个 "cancel face"
+ *        **不在 SDK 公面上**。⇒ 下一批第一步是找 server 把它钉出来(是 `runs.cancel(w* runId)`
+ *        还是独立端点),🔴 在拿到 server 的确证之前不许猜、不许在端上摆 Stop。
+ *   ③ **不可停时端凭什么显隐**:凭①的键缺席,而**不是**凭 status —— 例如 'stopping' 行是「已经在
+ *      停」(不该再给 Stop),park 行是「要走决断面」,老引擎无 taskHandles 是「面不在」,三者语义
+ *      不同但都落在「不给 Stop」上;把它们压进一个 status 判断会在下一次加词时静默错。
  */
 import type { AgentClient, AssistantTask, FleetTaskRow, FleetTaskStatus } from '@sema-agent/sdk';
 import type { BackgroundRow, BackgroundSourceHealth, BackgroundStatus, BackgroundView, CreateBackgroundView } from './contract.js';
@@ -43,7 +92,9 @@ export declare function backgroundStatusFromAssistant(s: AssistantTask['status']
  *  'running'(诚实取舍:它既不 queued 也不终态,更不是在等人)。 */
 export declare function backgroundStatusFromFleet(s: FleetTaskStatus): BackgroundStatus;
 /** 一行 AssistantTask → BackgroundRow。gate 是 `AssistantGate | null`(wire 显式 null 形)——
- *  null 折成键缺席,非 null 原引用透传(契约位是 unknown,包不重构造)。 */
+ *  null 折成键缺席,非 null 原引用透传(契约位是 unknown,包不重构造)。
+ *  🔴 [C33]③.1 三键(name / sessionId / createdAtMs)按 wire 在场性投影:缺席=键缺席,绝不
+ *  `?? 0` / `?? ''` —— 端渲的是「不知道」,不是「0 秒前创建的无名任务」。 */
 export declare function assistantTaskToBackgroundRow(t: AssistantTask): BackgroundRow;
 /** 一行 FleetTaskRow → BackgroundRow;子行(parentId 在场)⇒ null(调用方剔除)。
  *  复合 id 不拆;`currentTool` 契约位是一行字符串 —— 优先 server 已 redact 的 `currentAction`

package/dist/agentSession/backgroundView.js

@@ -56,15 +56,28 @@ function isoToEpochMs(iso) {
     const ms = Date.parse(iso);
     return Number.isFinite(ms) ? ms : undefined;
 }
+/** 非空串才算「有值」:空串是「没有名字」,不是名字(占位归端)。 */
+function nonEmptyString(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
 /** 一行 AssistantTask → BackgroundRow。gate 是 `AssistantGate | null`(wire 显式 null 形)——
- *  null 折成键缺席,非 null 原引用透传(契约位是 unknown,包不重构造)。 */
+ *  null 折成键缺席,非 null 原引用透传(契约位是 unknown,包不重构造)。
+ *  🔴 [C33]③.1 三键(name / sessionId / createdAtMs)按 wire 在场性投影:缺席=键缺席,绝不
+ *  `?? 0` / `?? ''` —— 端渲的是「不知道」,不是「0 秒前创建的无名任务」。 */
 export function assistantTaskToBackgroundRow(t) {
+    const wire = t;
     const updatedAtMs = isoToEpochMs(t.updatedAt);
+    const createdAtMs = isoToEpochMs(t.createdAt);
+    const name = nonEmptyString(wire.name);
+    const sessionId = nonEmptyString(t.sessionId);
     return {
         key: { source: 'assistant', taskId: t.taskId },
         status: backgroundStatusFromAssistant(t.status),
         ...(updatedAtMs !== undefined ? { updatedAtMs } : {}),
+        ...(createdAtMs !== undefined ? { createdAtMs } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
         needsAttention: t.needsAttention,
+        ...(name !== undefined ? { name } : {}),
         ...(t.gate !== null ? { gate: t.gate } : {}),
     };
 }
@@ -81,9 +94,14 @@ export function fleetTaskToBackgroundRow(r) {
             ? `${r.currentTool.toolName}${r.currentTool.target !== undefined ? ` ${r.currentTool.target}` : ''}`
             : undefined;
     const parked = r.status === 'awaiting approval' || r.status === 'waiting' || r.awaitingPlanApproval === true;
+    // [C33]③.2 / server [C36]:launch 时刻 epoch ms(revive 行=本 revive 周期 wake 时刻),
+    // ADDITIVE / tolerate-absent —— 排队中的行本就没有,缺席即键缺席(0 不是「1970 年启动」)。
+    // 两腿同一个 mapper:`snapshot` 首帧行与 `task` 增量帧行(POST-MERGE FULL row)都过这里。
+    const startedAtMs = typeof r.startedAt === 'number' && r.startedAt > 0 ? r.startedAt : undefined;
     return {
         key: { source: 'fleet', rowId: r.id },
         status: backgroundStatusFromFleet(r.status),
+        ...(startedAtMs !== undefined ? { startedAtMs } : {}),
         ...(parked ? { needsAttention: true } : {}),
         ...(typeof r.name === 'string' && r.name !== '' ? { name: r.name } : {}),
         ...(typeof r.description === 'string' && r.description !== '' ? { description: r.description } : {}),
@@ -132,8 +150,8 @@ export function createBackgroundView(client, opts) {
     let disposed = false;
     let current = null;
     let lastSerialized = null;
-    /** caps 探针结果:null = 还没探到/caps 面不可达(判别缺席);boolean = scheduler 位。 */
-    let capsScheduler = null;
+    /** caps 探针结果:null = 还没探到/caps 面不可达(判别缺席);boolean = approvals 位(见头注件 3)。 */
+    let capsApprovals = null;
     const listeners = new Set();
     const abort = new AbortController();
     function notify() {
@@ -148,26 +166,30 @@ export function createBackgroundView(client, opts) {
             }
         }
     }
-    /** caps 只需探到一次;失败保持 null 下轮重试(caps 面挂 ≠ assistant 面挂,判别缺席不编造)。 */
+    /** caps 只需探到一次;失败保持 null 下轮重试(caps 面挂 ≠ assistant 面挂,判别缺席不编造)。
+     *  🔴 读的是 `approvals` 不是 `scheduler` —— 考据见头注「'not-configured' 判别」节件 3。 */
     async function probeCaps() {
-        if (capsScheduler !== null)
+        if (capsApprovals !== null)
             return;
         try {
             const caps = await client.capabilities({ signal: abort.signal });
-            capsScheduler = caps.scheduler === true;
+            capsApprovals = caps.approvals === true;
         }
         catch (err) {
-            debugLog(`caps probe unavailable (scheduler 判别缺席,保持 ok 口径): ${String(err)}`);
+            debugLog(`caps probe unavailable (approvals 判别缺席,保持 ok 口径): ${String(err)}`);
         }
     }
     async function pullAssistant() {
         try {
             const { tasks } = await client.assistant.tasks({ signal: abort.signal });
-            return { health: capsScheduler === false ? 'not-configured' : 'ok', tasks: tasks ?? [] };
+            return { health: capsApprovals === false ? 'not-configured' : 'ok', tasks: tasks ?? [] };
         }
         catch (err) {
             debugLog(`assistant.tasks degrade: ${String(err)}`);
-            const health = capsScheduler === false || isNotImplemented(err) ? 'not-configured' : 'unavailable';
+            // 🔴 只有 approvals:false(面本就没挂)与 501(路由自报 gated off)算 not-configured。
+            // 「caps 说有(approvals:true)却 404」**留在 unavailable** —— 那是两个真源对不上的报警,
+            // 吞掉它以后真的漏注册/误删路由就再也看不见了(server [C34] 明确否掉的修法 (a))。
+            const health = capsApprovals === false || isNotImplemented(err) ? 'not-configured' : 'unavailable';
             return { health, tasks: [] };
         }
     }

package/dist/agentSession/contract.d.ts

@@ -130,6 +130,33 @@ export interface BackgroundRow {
     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;
     readonly description?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.18",
+  "version": "0.11.19",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",