@sema-agent/client-core 0.11.14 → 0.11.15

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.11.14
+**Version:** 0.11.15
 
 - **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/workflowClient.d.ts

@@ -15,6 +15,26 @@ export interface LiveWorkflowController {
         runId: string | null;
         lastError: string | null;
     };
+    /**
+     * Subscribe to "the projected snapshot changed" — fired on the FIRST successful `get()` and on every
+     * subsequent re-project. Returns an unsubscribe.
+     *
+     * WHY (clay 2026-07-30 症状②「入场蹲卡」): every host polls `snapshot()` on its own 1s interval, so a
+     * `get()` that answered in 50ms still took up to 1s to reach the screen — a purely self-inflicted delay,
+     * and during that window the panel renders its not-yet-resolved fill. The interval stays (it also drives
+     * the wall-clock cells: idle/duration/waiting), but the FIRST resolve no longer waits for a tick.
+     *
+     * 🔴 SUBSCRIBE-AND-RECONCILE: if a snapshot has ALREADY resolved by the time you subscribe, the callback fires
+     * ONCE synchronously from `subscribe` itself. Without this the notify arm and the subscribe arm do not share a
+     * premise — a host that renders (snapshot null) → subscribes in an effect loses the notify entirely whenever
+     * `get()` won that race, and falls back to waiting a full poll tick. That is exactly the residual outlier the
+     * entry-latency fence caught (2 of 3 runs ≈200-340ms, 1 run ≈1026ms = one whole tick).
+     *
+     * Contract: the callback runs INSIDE the source's own loop (or synchronously from `subscribe`) — hosts must only
+     * schedule a re-render from it, never re-enter the controller synchronously. A throwing callback is swallowed so
+     * one bad subscriber cannot kill the background consumer.
+     */
+    subscribe(onChange: () => void): () => void;
     /** abort the underlying SSE stream + stop the background loop (host unmount). */
     dispose(): void;
 }

package/dist/workflowClient.js

@@ -336,6 +336,24 @@ export function createLiveWorkflowSource(config) {
     let lastError = null;
     let disposed = false;
     let lastGetAt = 0;
+    /** 入场打点用:只有第一发 get 是「入场」,后续都是 ticker 触发的 re-GET。 */
+    let first = true;
+    const listeners = new Set();
+    /** 通知订阅者「快照变了」。一个抛异常的订阅者不许弄死后台消费循环(fail-soft 与本源全篇一致)。 */
+    function notify() {
+        if (disposed)
+            return;
+        for (const l of [...listeners]) {
+            try {
+                l();
+            }
+            catch (err) {
+                if (engineWireDebugEnabled()) {
+                    hostLog('debug', `[sema][workflow] subscriber threw (ignored): ${String(err)}`);
+                }
+            }
+        }
+    }
     // 差分① 见头注:唯一构造点 + 显式 maxRetries: 2(= 收编前吃的 SDK 缺省;工厂缺省 0 是单发探针语义)。
     const client = makeEngineWireClient({
         baseUrl: config.baseUrl,
@@ -360,11 +378,22 @@ export function createLiveWorkflowSource(config) {
             hostLog('debug', `[sema][workflow] degrade/err (host falls back to mock/empty): ${lastError}`);
         }
     }
-    /** resolve the run id to monitor: explicit config → the first RUNNING run → the first run → null (empty). */
+    /**
+     * resolve the run id to monitor: explicit config → the first RUNNING run → the first run → null (empty).
+     *
+     * ⚠️ 入场热路径记账(#79 串行普查):`config.workflowId` 在场时**直接返回,不打 list()** —— 三个
+     * 面板宿主(FleetView 内联 / `/workflows` / footer 内联)都是从 fleet 行拿到 id 才开的,所以入场
+     * 只有 **get 一跳**;list→get 的两跳串行只发生在 `SEMA_SCENARIO=workflow` 独立宿主且未给
+     * SEMA_WORKFLOW_ID 的路径上(那条路没有行可依,list 是唯一的 id 来源 —— 必须串行)。
+     */
     async function resolveRunId(signal) {
         if (config.workflowId)
             return config.workflowId;
+        const t0 = Date.now();
         const { workflows } = await client.workflows.list({ signal, ...engineSessionParamSpread() });
+        if (engineWireDebugEnabled()) {
+            hostLog('debug', `[sema][workflow][perf] list ${Date.now() - t0}ms rows=${workflows?.length ?? 0}`);
+        }
         if (!workflows?.length)
             return null;
         const running = workflows.find(w => w.status === 'running');
@@ -372,6 +401,7 @@ export function createLiveWorkflowSource(config) {
     }
     /** take the authoritative snapshot + project it; records degrade on failure (never throws). */
     async function refresh(id, signal) {
+        const t0 = Date.now();
         try {
             const run = await client.workflows.get(id, { signal, ...engineSessionParamSpread() });
             lastGetAt = Date.now();
@@ -381,6 +411,13 @@ export function createLiveWorkflowSource(config) {
             degraded = false;
             code = null;
             lastError = null;
+            if (engineWireDebugEnabled()) {
+                // 入场打点(#79):first=true 的那一行就是「壳拿到第一份权威快照」的耗时。
+                hostLog('debug', `[sema][workflow][perf] get ${Date.now() - t0}ms first=${first} agents=${current.agentCount} phases=${current.phases.length}`);
+            }
+            first = false;
+            // 解析即通知(首帧不等宿主的 1s tick;后续每次 re-project 同样通知,SSE ticker 的 re-GET 也走这里)。
+            notify();
         }
         catch (err) {
             if (disposed || signal.aborted)
@@ -459,9 +496,26 @@ export function createLiveWorkflowSource(config) {
         status() {
             return { connected, degraded, code, runId, lastError };
         },
+        subscribe(onChange) {
+            listeners.add(onChange);
+            // 订阅即对账:订阅前就已经解析完的话,notify() 那一发已经打空了(当时还没有订阅者)——
+            // 不在这里补一发,宿主就要白等一整个轮询 tick(配对机制必须共享前提)。
+            if (current !== null && !disposed) {
+                try {
+                    onChange();
+                }
+                catch {
+                    /* 订阅者自己的问题,不许弄坏本源 */
+                }
+            }
+            return () => {
+                listeners.delete(onChange);
+            };
+        },
         dispose() {
             disposed = true;
             abort.abort();
+            listeners.clear();
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.11.14",
+  "version": "0.11.15",
   "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",