@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/workflowClient.js

@@ -57,6 +57,7 @@
  * state once one resolves. `dispose()` aborts the stream + stops the background loop on host unmount.
  */
 import { APIError } from '@sema-agent/sdk';
+import { abortableSleep } from './abortableSleep.js';
 import { engineSessionParamSpread } from './engineSessionParam.js';
 import { makeEngineWireClient } from './engineWireSdk.js';
 import { engineWireDebugEnabled } from './engineWireTarget.js';
@@ -246,13 +247,14 @@ function stripPhase(a) {
  *  one phase per distinct tag; (3) neither → a single synthetic 'Workflow' phase holding every agent. */
 function projectPhases(run, agents) {
     const raw = readPhases(run);
-    if (raw.length > 0) {
+    const firstRaw = raw[0];
+    if (raw.length > 0 && firstRaw !== undefined) {
         const known = new Set(raw.map(p => p.title));
         const buckets = new Map();
         for (const p of raw)
             buckets.set(p.title, []);
         for (const a of agents) {
-            const t = a._phase && known.has(a._phase) ? a._phase : raw[0].title;
+            const t = a._phase && known.has(a._phase) ? a._phase : firstRaw.title;
             buckets.get(t).push(a);
         }
         return raw.map(p => {
@@ -318,6 +320,23 @@ export function projectWorkflowRun(run) {
         state.description = run.description;
     return state;
 }
+// ── 轮询/退避节拍(REF-CC-131,域词表-15):三个 3000ms 常量语义各不相同,拆开命名——合并成一个
+// 会把三条独立的退避策略绑死在一起(其中任一策略调优都会误伤另外两条)。──────────────────────
+/** owner 名下暂无任何 run(`resolveRunId` 回 null)时的重试间隔:不是错误,只是「还没有可监的
+ *  run」——退避到下一次 list() 重试,给一个正在被启动的 run 留出出现的时间。 */
+const NO_RUN_BACKOFF_MS = 3000;
+/** `refresh()` 判定 degraded(501 S8-off / 404 gone)后的重试间隔:不再尝试 stream(),直接退避
+ *  重跑外层循环——与 NO_RUN_BACKOFF_MS 数值巧合相同但触发条件不同(有 run id 但拿不到快照)。 */
+const DEGRADED_BACKOFF_MS = 3000;
+/** consume() 外层 catch 兜到的未归类异常(list/refresh 之外的意外)后的退避间隔——保守值,
+ *  与前两个 3000 又是同一个数字、不同的触发路径,故各自具名而非合一常量。 */
+const UNEXPECTED_ERROR_BACKOFF_MS = 3000;
+/** stream() 以「无终帧」收场(丢连,非可续传)之后、重新 re-`get()` 快照前的退避间隔——比另外
+ *  三个短,因为这是「已知在连接一个存在的 run」而不是「不确定还有没有事可做」。 */
+const STREAM_DROP_BACKOFF_MS = 1000;
+/** stream() ticker 帧触达时,距上一次 `refresh()` 的最小间隔——节流 re-GET 频率,不是退避:
+ *  帧到来表示「有变化」,但没必要每一帧都打一次权威快照。 */
+const REFRESH_THROTTLE_MS = 400;
 /**
  * createLiveWorkflowSource({ baseUrl, authToken, principal, workflowId? }) — the LIVE workflow-monitor source.
  *
@@ -360,10 +379,17 @@ export function createLiveWorkflowSource(config) {
         ...(config.authToken ? { token: config.authToken } : {}),
         principal: config.principal,
         maxRetries: 2,
+        ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
     });
     const abort = new AbortController();
     /** record a degrade/error WITHOUT throwing: 501 (S8 off) / 404 (non-owner|absent) are EXPECTED degrades;
-     *  anything else (connection refused, parse) is a soft error — either way the host keeps the mock/empty. */
+     *  anything else (connection refused, parse) is a soft error — either way the host keeps the mock/empty.
+     *
+     * REF-CC-153(midband-01,fix-outright):the non-APIError branch must explicitly clear `code`/`degraded`
+     * rather than leave a prior call's values sitting there — `status().code` is documented as "the HTTP
+     * status behind a degrade (501/404), else null", so a stale 404 surviving into a later connection-refused
+     * error would misreport an unrelated failure as "still a 404 (run gone)".
+     */
     function noteDegrade(err) {
         connected = false;
         if (err instanceof APIError) {
@@ -372,6 +398,8 @@ export function createLiveWorkflowSource(config) {
             lastError = `${err.status} ${err.message}`;
         }
         else {
+            code = null;
+            degraded = false;
             lastError = err instanceof Error ? err.message : String(err);
         }
         if (engineWireDebugEnabled()) {
@@ -397,7 +425,12 @@ export function createLiveWorkflowSource(config) {
         if (!workflows?.length)
             return null;
         const running = workflows.find(w => w.status === 'running');
-        return (running ?? workflows[0]).id;
+        const firstWorkflow = workflows[0];
+        // `workflows.length > 0` above guarantees index 0 exists; noUncheckedIndexedAccess can't see that,
+        // so re-check explicitly rather than reach for a non-null assertion.
+        if (firstWorkflow === undefined)
+            return null;
+        return (running ?? firstWorkflow).id;
     }
     /** take the authoritative snapshot + project it; records degrade on failure (never throws). */
     async function refresh(id, signal) {
@@ -435,13 +468,13 @@ export function createLiveWorkflowSource(config) {
                     degraded = true;
                     code = null;
                     connected = false;
-                    await sleep(3000);
+                    await abortableSleep(NO_RUN_BACKOFF_MS, abort.signal);
                     continue;
                 }
                 await refresh(id, abort.signal);
                 // snapshot degraded (501 S8-off / 404 gone) → don't attempt the stream; back off and retry.
                 if (degraded) {
-                    await sleep(3000);
+                    await abortableSleep(DEGRADED_BACKOFF_MS, abort.signal);
                     continue;
                 }
                 try {
@@ -453,7 +486,7 @@ export function createLiveWorkflowSource(config) {
                         if (disposed)
                             return;
                         connected = true;
-                        if (Date.now() - lastGetAt >= 400)
+                        if (Date.now() - lastGetAt >= REFRESH_THROTTLE_MS)
                             await refresh(id, abort.signal);
                         if (degraded)
                             break;
@@ -466,19 +499,21 @@ export function createLiveWorkflowSource(config) {
                 }
                 // stream ended (drop, not resumable) → re-snapshot on the next loop after a small backoff.
                 if (!disposed && !abort.signal.aborted)
-                    await sleep(1000);
+                    await abortableSleep(STREAM_DROP_BACKOFF_MS, abort.signal);
             }
             catch (err) {
                 if (disposed || abort.signal.aborted)
                     return;
                 noteDegrade(err);
-                await sleep(3000);
+                await abortableSleep(UNEXPECTED_ERROR_BACKOFF_MS, abort.signal);
             }
         }
     }
-    function sleep(ms) {
-        return new Promise(r => setTimeout(r, ms));
-    }
+    // REF-CC-147(域词表-17):此前这里有一个私有 `sleep()`,裸 Promise+定时器形
+    // ——不感知 abort:dispose() 唤不醒正在等待的那一轮,循环最多多跑一轮,且未清的 setTimeout 在
+    // Node 上继续维持事件循环存活(拖慢 headless `-p` 车道的进程退出)。已改用共享叶 abortableSleep
+    // (与 agentSession/backgroundView.ts 同一实现,详见 ./abortableSleep.ts 头注),消费点全改传
+    // `abort.signal` ——dispose() 一旦 `abort.abort()`,四处退避里在飞的那一个立即唤醒。
     // 差分① 的 fail-soft 半场:工厂造不出 client(SDK 拒绝构造)⇒ 不起循环、恒 degraded,
     // `snapshot()` 恒 null ⇒ 宿主走它既有的 mock/空态回落。**绝不抛进宿主**(与 501/404/空列表同路)。
     if (client === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "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",
@@ -28,11 +28,11 @@
   },
   "peerDependencies": {
     "@sema-agent/agent-types": ">=0.2.0",
-    "@sema-agent/sdk": ">=3.0.0"
+    "@sema-agent/sdk": ">=4.1.0"
   },
   "devDependencies": {
     "@sema-agent/agent-types": "^0.2.0",
-    "@sema-agent/sdk": "^3.0.0",
+    "@sema-agent/sdk": "^4.1.0",
     "esbuild": "^0.27.4",
     "typescript": "^6.0.2"
   }