@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/workflowClient.d.ts

@@ -0,0 +1,42 @@
+import type { WorkflowRun } from '@sema-agent/sdk';
+import type { WorkflowRunState } from './workflowMonitor.js';
+/** The live controller the host drives — a projected-snapshot reader + diagnostics + teardown. */
+export interface LiveWorkflowController {
+    /** the latest projected run state, or null (not yet resolved / degraded 501-404 / empty). */
+    snapshot(): WorkflowRunState | null;
+    /** connection + degrade diagnostics for the empty/degraded render + verify cross-check. */
+    status(): {
+        connected: boolean;
+        /** true when the endpoint is unavailable (501 = S8 flag off) / the run is absent (404) / the list is empty. */
+        degraded: boolean;
+        /** the HTTP status behind a degrade (501 / 404), else null. */
+        code: number | null;
+        /** the resolved workflow run id (null until list()/config resolves one). */
+        runId: string | null;
+        lastError: string | null;
+    };
+    /** abort the underlying SSE stream + stop the background loop (host unmount). */
+    dispose(): void;
+}
+export interface LiveWorkflowConfig {
+    baseUrl: string;
+    authToken: string;
+    /** SDK Principal — e.g. 'anon:sema' (workflows are owner-scoped by principal). */
+    principal: string;
+    /** explicit workflow run id; when absent the source picks the first RUNNING run from list() (else the first). */
+    workflowId?: string;
+}
+/** THE projector: SDK `WorkflowRun` (client.workflows.get) → the monitor's `WorkflowRunState`. Pure/total —
+ *  tolerates absent/permissive fields and never throws (the graceful-degrade contract lives above, in the
+ *  source loop; this just maps a well-formed run). Exported for the mock-parity unit cross-check. */
+export declare function projectWorkflowRun(run: WorkflowRun): WorkflowRunState;
+/**
+ * createLiveWorkflowSource({ baseUrl, authToken, principal, workflowId? }) — the LIVE workflow-monitor source.
+ *
+ * Constructs the AgentClient and kicks off a background loop that (1) resolves a run id (explicit config, else
+ * the first running run from `list()`), (2) snapshots it via `get()` → project → store, and (3) follows
+ * `stream()` as a change-ticker (re-`get()` throttled on each frame). Every step is degrade-safe: a 501 (S8
+ * off) / 404 (non-owner/absent) / empty list / connection error is RECORDED (status().degraded/code) and
+ * leaves `snapshot()` null so the host falls back to the mock/empty state — the source never throws into it.
+ */
+export declare function createLiveWorkflowSource(config: LiveWorkflowConfig): LiveWorkflowController;

package/dist/workflowClient.js

@@ -0,0 +1,467 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/workflowClient.ts` 整搬(依赖面 = SDK + env,
+ *    §3 表登记 472 行)。
+ *
+ * 🔴 搬迁四处差分(端资产上移 / 单一构造点,行为面逐条记账):
+ *   ① `new AgentClient({…})` 直造 → `makeEngineWireClient()`(§8-2 定谳的唯一构造点;凭证过
+ *      `resolveWireAuth` 三态)。**`maxRetries: 2` 显式传** —— 工厂缺省是 0(raw fetch 单发语义),
+ *      而这里原本吃的是 SDK 缺省 2;不显式传就等于**偷偷改了这条观测环路的重试次数**。
+ *      唯一残余差分:`authToken` 为**空串**时,原版原样交给 SDK,收编后走三态(loopback ⇒ 零
+ *      Authorization 头 / 非 loopback ⇒ 'anon')—— 与另外 11 处构造点同一处置,记在 §8-2。
+ *      工厂 fail-soft 返回 null(SDK 拒绝构造)⇒ 本源恒 degraded、`snapshot()` 恒 null,宿主回落
+ *      mock/空态 —— 与「501/404/空列表」同一条不抛的路。
+ *   ② `process.env.SEMA_DEBUG` → `engineWireDebugEnabled()`;`console.error` → `hostLog('debug', …)`
+ *      (本包零 `process`、零 console —— portability 门盯着)。
+ *   ③ 投影产物的类型契约(`WorkflowRunState` 族)改 import 本包 `workflowMonitor.ts`(同批搬入),
+ *      不再从 TUI 的 `overrides/workflow-detail-dialog.js` 反向依赖渲染件。
+ *   ④ `export default createLiveWorkflowSource` **不带过来**:本包是具名导出面(index 做 `export *`,
+ *      default 不在其中)。壳侧那一行 default import 若存在,shim 里改具名。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * workflowClient — MF-W LIVE WIRE source (the workflow-monitor TWIN of fleetClient.ts).
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * mock/workflow/workflowRun.ts synthesizes ONE representative WorkflowRunState from a scripted run (offline/
+ * demo). This file is its LIVE TWIN: it constructs the @sema-ai/sdk `AgentClient`, consumes the §workflow
+ * observability surface shipped in @sema-ai/sdk 0.0.40 (`client.workflows.list/get/stream`, resources/
+ * workflows.ts — GET /v1/workflows*, the S8 self-orchestration-observability endpoints), and PROJECTS the
+ * SDK's `WorkflowRun` (phases / agents / stats) to the SAME `WorkflowRunState` the reconstructed monitor
+ * (src/sema/overrides/workflow-detail-dialog.tsx) already consumes. ZERO renderer change — exactly the
+ * fleetClient.ts pattern (a projector, not a port).
+ *
+ * SDK CONTRACT (resources/workflows.ts + types.ts):
+ *   - `list({status?,limit?})` → `{ workflows: WorkflowRunSummary[] }` (OWNER-scoped: only the caller's runs).
+ *   - `get(id)`               → full `WorkflowRun` (phases: unknown[] structured {title,status,done,total};
+ *                                agents: WorkflowAgentRow[] with activity[].arg; stats.tokens own+nested).
+ *   - `stream(id)`            → SSE of `WorkflowStreamEvent` (first frame `meta`, then core WorkflowEvent
+ *                                frames). REPLICA-LOCAL + in-process, NOT resumable — a drop is a FULL restart
+ *                                (re-`get()` for the snapshot), never a resume.
+ *
+ * 🔴 GRACEFUL DEGRADE (the load-bearing half — see the mount seam's verification-debt note): the LIVE
+ *    endpoints are gated behind the server's S8 (self-orchestration-observability) flag. With S8 OFF the
+ *    routes answer **501** (typed APIError) BEFORE any frame; a non-owner / absent run answers **404**; an
+ *    owner with no runs yields an **empty** list. ALL THREE are EXPECTED, NOT crashes: this source records
+ *    them (status().degraded/code) and keeps `snapshot()` null so the host can fall back to the mock/empty
+ *    state. A raw connection error (server down) is treated the same way — the stream/loop just backs off and
+ *    retries; the source NEVER throws into the host.
+ *
+ * 🔴 THE SDK PRODUCES FRAMES, IT DOES NOT MAINTAIN STATE. We take the AUTHORITATIVE snapshot from `get()` and
+ *    treat `stream()` as a "something changed" TICKER: on each frame we re-`get()` the owner-scoped detail
+ *    (throttled) and re-project, rather than reduce the permissive/core-internal WorkflowEvent shapes on the
+ *    client. On stream drop we re-`get()` for a fresh snapshot (not resumable) with a small backoff.
+ *
+ * DROP-IN SHAPE: `snapshot()` returns the latest projected `WorkflowRunState | null` (null until the first
+ * successful `get()`, or while degraded) — the host polls it on an interval and swaps the mock for the live
+ * state once one resolves. `dispose()` aborts the stream + stops the background loop on host unmount.
+ */
+import { APIError } from '@sema-agent/sdk';
+import { engineSessionParamSpread } from './engineSessionParam.js';
+import { makeEngineWireClient } from './engineWireSdk.js';
+import { engineWireDebugEnabled } from './engineWireTarget.js';
+import { hostLog } from './host.js';
+// ── SDK WorkflowRun → monitor WorkflowRunState projectors ────────────────────────────────────────────────
+// The SDK shapes (types.ts) are PERMISSIVE (open index sigs). The monitor's WorkflowRunState/Phase/Agent
+// (workflowMonitor.ts) is the 187-faithful consumed set. We read the known fields, coerce
+// the vocabularies, and fill the shell-local render defaults the wire does not carry — same discipline as
+// projectTasks/projectWorkflows in fleet/fleetProjection.ts.
+/** run status → the monitor's run-level vocabulary. SDK: queued|running|completed|failed|(open). The monitor
+ *  run status is running|done|failed|stopped|paused — there is no run-level 'queued', so a queued run reads as
+ *  'running' (the header shows the raw status text anyway; the box treats non-done/failed as active). */
+function coerceRunStatus(s) {
+    switch (s) {
+        case 'completed':
+            return 'done';
+        case 'failed':
+            return 'failed';
+        case 'running':
+            return 'running';
+        default:
+            return 'running'; // queued / unknown-future → render as an active run (open-set fallback)
+    }
+}
+/** detail phase status (service projects {title,status,done,total}) → the monitor's phase vocabulary. */
+function coercePhaseStatus(s) {
+    switch (s) {
+        case 'done':
+        case 'completed':
+            return 'done';
+        case 'failed':
+            return 'failed';
+        case 'not-started':
+        case 'queued':
+        case 'pending':
+            return 'not-started';
+        default:
+            return 'running';
+    }
+}
+/** SDK WorkflowAgentRow.status ("the input vocab the display derivation reads", types.ts:352) → the monitor's
+ *  AgentState input set (start|progress|queued|done|error|inactive — the WPe INPUT vocabulary the monitor
+ *  derives DisplayStatus from). We pass the atlas vocab through and tolerate service display-synonyms. */
+function coerceAgentState(s) {
+    switch (s) {
+        case 'start':
+        case 'progress':
+        case 'queued':
+        case 'done':
+        case 'error':
+        case 'inactive':
+            return s;
+        // service display-vocab synonyms (should the wire emit them) → the monitor's input state.
+        case 'running':
+        case 'active':
+            return 'progress';
+        case 'completed':
+            return 'done';
+        case 'failed':
+            return 'error';
+        // service detail `displayStatus` (core deriveAgentDisplayStatus): `interrupted` = a non-terminal agent
+        // under a terminated run → the monitor's `inactive` input (WPe lands it on 'interrupted' display via
+        // !workflowActive — the run IS terminal whenever core emits this).
+        case 'interrupted':
+            return 'inactive';
+        default:
+            return 'progress'; // unknown-future live status → render as an active agent (open-set fallback)
+    }
+}
+/** Project the bounded activity beats (WorkflowActivityBeat, start/end PAIRS) → the monitor's per-call
+ *  WorkflowToolCall[]. The 'start' beat carries the SHORT secret-scrubbed primary-arg summary (types.ts:339);
+ *  we fold each tool CALL (keyed by toolCallId) to one row {name, summary?}, keeping the first non-empty arg
+ *  as the summary. Beats without a toolName are dropped (heartbeat/partial). Order preserved. */
+/** clay ⑤ 案(2026-07-22 截图定谳):beat.arg 契约上是 SHORT 摘要,但 StructuredOutput 等工具的
+ *  主参数=整段多行内容(server 侧 scrub 不折行)——Activity 行渲染用 truncateToWidth 只截宽度
+ *  不清换行,首个换行之后的行顶格渲出面板(样式逃框)。数据层单点单行化:取首行,有后续行缀 …;
+ *  两个消费点(Activity 行 + lastToolSummary)一并被护。 */
+function oneLineSummary(s) {
+    const nl = s.search(/\r?\n/);
+    if (nl < 0)
+        return s;
+    const head = s.slice(0, nl).trimEnd();
+    return head ? `${head}…` : '…';
+}
+function projectActivity(beats) {
+    if (!beats?.length)
+        return [];
+    const byCall = new Map();
+    const order = [];
+    let anon = 0;
+    for (const b of beats) {
+        const name = typeof b.toolName === 'string' ? b.toolName.trim() : '';
+        if (!name)
+            continue;
+        const key = typeof b.toolCallId === 'string' && b.toolCallId ? b.toolCallId : `#${anon++}`;
+        if (!byCall.has(key))
+            order.push(key);
+        const prev = byCall.get(key);
+        const arg = typeof b.arg === 'string' && b.arg.trim() ? oneLineSummary(b.arg.trim()) : prev?.summary;
+        const call = { name };
+        if (arg)
+            call.summary = arg;
+        byCall.set(key, { ...prev, ...call });
+    }
+    return order.map(k => byCall.get(k)).filter((c) => !!c);
+}
+/** one WorkflowAgentRow → the monitor's WorkflowAgent (+ a private `_phase` carrier for phase bucketing). */
+function projectAgent(row, index) {
+    // WorkflowAgentRow carries no TYPED id — read a stable id from the permissive fields, else index-derive.
+    const rec = row;
+    const id = String(rec.id ?? rec.agentId ?? `agent-${index}`);
+    const agentId = typeof rec.agentId === 'string' && rec.agentId ? rec.agentId : id;
+    // Prefer the service detail's `displayStatus` (core's shared deriveAgentDisplayStatus:
+    // queued|running|done|failed|interrupted) over the RAW record `status` (running|completed|failed): the raw
+    // vocabulary carries no queued/interrupted arm — a queued agent's record status is literally 'running', so
+    // coercing `row.status` alone rendered every queued agent as "Running" (the [840] parity gap).
+    const displayStatus = typeof rec.displayStatus === 'string' ? rec.displayStatus : undefined;
+    const state = coerceAgentState(displayStatus ?? row.status);
+    const activity = projectActivity(row.activity);
+    const last = activity.length ? activity[activity.length - 1] : undefined;
+    const label = typeof row.label === 'string' && row.label.trim() ? row.label.trim() : id || 'agent';
+    const agent = { id, agentId, label, state };
+    if (typeof row.model === 'string')
+        agent.model = row.model;
+    if (typeof row.tokens === 'number')
+        agent.tokens = row.tokens;
+    if (typeof row.toolCalls === 'number')
+        agent.toolCalls = row.toolCalls;
+    if (activity.length)
+        agent.activity = activity;
+    if (last) {
+        agent.lastToolName = last.name;
+        if (last.summary)
+            agent.lastToolSummary = last.summary;
+    }
+    if (typeof row.prompt === 'string')
+        agent.promptPreview = row.prompt;
+    if (typeof row.output === 'string')
+        agent.resultPreview = row.output;
+    // WPe (agentDisplayStatus) derives queued-vs-running from queuedAt/startedAt on the active path. The service
+    // detail ALWAYS sends `queuedAt` (MF-W 1.150: enqueue time) and sends `startedAt` only once the agent acquired
+    // a concurrency slot — so PASS BOTH THROUGH unconditionally and WPe derives faithfully (queuedAt set +
+    // startedAt absent → 'queued'; both set → 'running'). The old projection dropped queuedAt unless the coerced
+    // state was literally 'queued' (which the raw record vocabulary never produces) — every queued agent lost its
+    // timestamps and rendered 'running'. Synthesize queuedAt only for a wire that says 'queued' without one.
+    const startedAt = typeof rec.startedAt === 'number' ? rec.startedAt : undefined;
+    const queuedAt = typeof rec.queuedAt === 'number' ? rec.queuedAt : undefined;
+    const durationMs = typeof rec.durationMs === 'number' ? rec.durationMs : undefined;
+    const lastProgressAt = typeof rec.lastProgressAt === 'number' ? rec.lastProgressAt : undefined;
+    if (durationMs != null)
+        agent.durationMs = durationMs;
+    if (lastProgressAt != null)
+        agent.lastProgressAt = lastProgressAt;
+    if (queuedAt != null)
+        agent.queuedAt = queuedAt;
+    if (startedAt != null)
+        agent.startedAt = startedAt;
+    if (state === 'queued' && agent.queuedAt == null)
+        agent.queuedAt = Date.now();
+    const phase = typeof row.phase === 'string' && row.phase.trim() ? row.phase.trim() : undefined;
+    return Object.assign(agent, phase ? { _phase: phase } : {});
+}
+/** read the (permissive) structured phase rows the service detail projects (`{title,status,done,total,…}`). */
+function readPhases(run) {
+    const out = [];
+    for (const p of run.phases ?? []) {
+        if (p && typeof p === 'object') {
+            const rec = p;
+            out.push({
+                title: typeof rec.title === 'string' && rec.title.trim() ? rec.title.trim() : '',
+                status: rec.status,
+                done: typeof rec.done === 'number' ? rec.done : undefined,
+                total: typeof rec.total === 'number' ? rec.total : undefined,
+            });
+        }
+    }
+    return out;
+}
+function stripPhase(a) {
+    const { _phase: _ignored, ...rest } = a;
+    void _ignored;
+    return rest;
+}
+/** Build the monitor's WorkflowPhase[] from the run's structured phases + the agents' `_phase` tags. Three
+ *  paths, all degrade-safe: (1) structured phases on the wire → bucket agents by their phase title (an agent
+ *  whose phase matches none lands in the first phase); (2) no structured phases but agents carry phase tags →
+ *  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 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;
+            buckets.get(t).push(a);
+        }
+        return raw.map(p => {
+            const bucket = buckets.get(p.title) ?? [];
+            return {
+                title: p.title || 'Phase',
+                status: coercePhaseStatus(p.status),
+                doneCount: p.done ?? bucket.filter(a => a.state === 'done').length,
+                totalCount: p.total ?? bucket.length,
+                agents: bucket.map(stripPhase),
+            };
+        });
+    }
+    const distinct = [...new Set(agents.map(a => a._phase).filter((t) => !!t))];
+    if (distinct.length > 0) {
+        return distinct.map(title => {
+            const bucket = agents.filter(a => a._phase === title);
+            const allDone = bucket.every(a => a.state === 'done');
+            return {
+                title,
+                status: bucket.some(a => a.state === 'error') ? 'failed' : allDone ? 'done' : 'running',
+                doneCount: bucket.filter(a => a.state === 'done').length,
+                totalCount: bucket.length,
+                agents: bucket.map(stripPhase),
+            };
+        });
+    }
+    return [
+        {
+            title: 'Workflow',
+            status: run.status === 'completed' ? 'done' : run.status === 'failed' ? 'failed' : 'running',
+            doneCount: agents.filter(a => a.state === 'done').length,
+            totalCount: agents.length,
+            agents: agents.map(stripPhase),
+        },
+    ];
+}
+/** THE projector: SDK `WorkflowRun` (client.workflows.get) → the monitor's `WorkflowRunState`. Pure/total —
+ *  tolerates absent/permissive fields and never throws (the graceful-degrade contract lives above, in the
+ *  source loop; this just maps a well-formed run). Exported for the mock-parity unit cross-check. */
+export function projectWorkflowRun(run) {
+    const agents = (run.agents ?? []).map((r, i) => projectAgent(r, i));
+    const phases = projectPhases(run, agents);
+    const ownTokens = run.stats?.tokens ?? 0;
+    const nestedTokens = run.stats?.nested?.tokens ?? 0;
+    const totalTokens = run.stats?.tokens != null || run.stats?.nested?.tokens != null
+        ? ownTokens + nestedTokens
+        : agents.reduce((s, a) => s + (a.tokens ?? 0), 0); // no stats on the wire → sum the agent rows
+    const state = {
+        workflowRunId: run.id,
+        status: coerceRunStatus(run.status),
+        // The authored script TEXT is not projected to the wire (types.ts:375 — service does not emit it), so leave
+        // it empty: the monitor's "save script" affordance stays off (canSave = script.length > 0). Never fabricate
+        // a script we do not have. scriptPath is likewise absent until the service projects it.
+        script: '',
+        agentCount: agents.length,
+        totalTokens,
+        phases,
+    };
+    if (run.name)
+        state.name = run.name;
+    if (run.description)
+        state.description = run.description;
+    return state;
+}
+/**
+ * createLiveWorkflowSource({ baseUrl, authToken, principal, workflowId? }) — the LIVE workflow-monitor source.
+ *
+ * Constructs the AgentClient and kicks off a background loop that (1) resolves a run id (explicit config, else
+ * the first running run from `list()`), (2) snapshots it via `get()` → project → store, and (3) follows
+ * `stream()` as a change-ticker (re-`get()` throttled on each frame). Every step is degrade-safe: a 501 (S8
+ * off) / 404 (non-owner/absent) / empty list / connection error is RECORDED (status().degraded/code) and
+ * leaves `snapshot()` null so the host falls back to the mock/empty state — the source never throws into it.
+ */
+export function createLiveWorkflowSource(config) {
+    let current = null;
+    let connected = false;
+    let degraded = false;
+    let code = null;
+    let runId = config.workflowId ?? null;
+    let lastError = null;
+    let disposed = false;
+    let lastGetAt = 0;
+    // 差分① 见头注:唯一构造点 + 显式 maxRetries: 2(= 收编前吃的 SDK 缺省;工厂缺省 0 是单发探针语义)。
+    const client = makeEngineWireClient({
+        baseUrl: config.baseUrl,
+        ...(config.authToken ? { token: config.authToken } : {}),
+        principal: config.principal,
+        maxRetries: 2,
+    });
+    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. */
+    function noteDegrade(err) {
+        connected = false;
+        if (err instanceof APIError) {
+            code = err.status;
+            degraded = err.status === 501 || err.status === 404;
+            lastError = `${err.status} ${err.message}`;
+        }
+        else {
+            lastError = err instanceof Error ? err.message : String(err);
+        }
+        if (engineWireDebugEnabled()) {
+            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). */
+    async function resolveRunId(signal) {
+        if (config.workflowId)
+            return config.workflowId;
+        const { workflows } = await client.workflows.list({ signal, ...engineSessionParamSpread() });
+        if (!workflows?.length)
+            return null;
+        const running = workflows.find(w => w.status === 'running');
+        return (running ?? workflows[0]).id;
+    }
+    /** take the authoritative snapshot + project it; records degrade on failure (never throws). */
+    async function refresh(id, signal) {
+        try {
+            const run = await client.workflows.get(id, { signal, ...engineSessionParamSpread() });
+            lastGetAt = Date.now();
+            current = projectWorkflowRun(run);
+            runId = run.id;
+            connected = true;
+            degraded = false;
+            code = null;
+            lastError = null;
+        }
+        catch (err) {
+            if (disposed || signal.aborted)
+                return;
+            noteDegrade(err);
+        }
+    }
+    /** background loop: resolve → snapshot → follow the stream (re-get on frames), degrade-safe throughout. */
+    async function consume() {
+        while (!disposed && !abort.signal.aborted) {
+            try {
+                const id = runId ?? (await resolveRunId(abort.signal));
+                if (!id) {
+                    // owner has no runs → empty/degraded (not an error). Back off and re-poll (a run may appear).
+                    degraded = true;
+                    code = null;
+                    connected = false;
+                    await sleep(3000);
+                    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);
+                    continue;
+                }
+                try {
+                    // stream = "something changed" ticker. Re-GET the authoritative owner-scoped detail (throttled to
+                    // ~400ms) rather than reduce the permissive core-internal WorkflowEvent shapes on the client. NOT
+                    // resumable — a drop ends the iterator; the outer loop re-snapshots.
+                    for await (const _frame of client.workflows.stream(id, { signal: abort.signal, ...engineSessionParamSpread() })) {
+                        void _frame;
+                        if (disposed)
+                            return;
+                        connected = true;
+                        if (Date.now() - lastGetAt >= 400)
+                            await refresh(id, abort.signal);
+                        if (degraded)
+                            break;
+                    }
+                }
+                catch (err) {
+                    if (disposed || abort.signal.aborted)
+                        return;
+                    noteDegrade(err); // 501 (S8 off) / 404 (gone) thrown BEFORE any frame, or a mid-stream transport drop
+                }
+                // stream ended (drop, not resumable) → re-snapshot on the next loop after a small backoff.
+                if (!disposed && !abort.signal.aborted)
+                    await sleep(1000);
+            }
+            catch (err) {
+                if (disposed || abort.signal.aborted)
+                    return;
+                noteDegrade(err);
+                await sleep(3000);
+            }
+        }
+    }
+    function sleep(ms) {
+        return new Promise(r => setTimeout(r, ms));
+    }
+    // 差分① 的 fail-soft 半场:工厂造不出 client(SDK 拒绝构造)⇒ 不起循环、恒 degraded,
+    // `snapshot()` 恒 null ⇒ 宿主走它既有的 mock/空态回落。**绝不抛进宿主**(与 501/404/空列表同路)。
+    if (client === null) {
+        degraded = true;
+        lastError = 'client construction failed (invalid baseUrl/credentials)';
+    }
+    else {
+        // kick off the background consumer (fire-and-forget; all failures captured into status()).
+        void consume();
+    }
+    return {
+        snapshot() {
+            return current;
+        },
+        status() {
+            return { connected, degraded, code, runId, lastError };
+        },
+        dispose() {
+            disposed = true;
+            abort.abort();
+        },
+    };
+}

package/dist/workflowMonitor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):workflow 监视器的**状态契约**(MF-W ·
+ *    contract/MF-W-workflow-monitor.md)从 cli `src/sema/overrides/workflow-detail-dialog.tsx:118-200`
+ *    搬入 —— 逐字,一个字段都没动。
+ *
+ * 🔴 **为什么类型必须先过来**:`workflowClient.projectWorkflowRun()`(同批搬入)的**产物**就是这套
+ *    形状。类型留在一个 `.tsx` 渲染文件里,等于「库产出的东西,它的契约住在 TUI 里」——
+ *    web/桌面要消费同一份投影就得手抄一遍 shape,而手抄的那份**没有任何东西**会在它漂移时报红。
+ *    定位公理([1832])说的「CC 皮肤形状全收本包」,指的正是这种东西。
+ *
+ * 🔴 **拆缝**:`workflow-detail-dialog.tsx` 本身是 Ink 渲染件(设计稿 §2 分类表「Ink 渲染」),
+ *    **留 TUI**;搬过来的只有 ① 六个契约类型 ② `agentDisplayStatus`(WPe —— 从 wire 输入词表
+ *    派生显示态的那条**纯**规则,是本契约的消费侧半场,端端都要用)。
+ *    留在 TUI 的:`computeVisibleWindow`(滚动窗口数学 = 视口概念,端专属)、glyph/color 映射、
+ *    以及整棵 JSX。壳侧 shim = 那个 tsx 改成从本包 re-export 这两样,自己不再定义。
+ */
+export type AgentState = 'start' | 'progress' | 'queued' | 'done' | 'error' | 'inactive';
+export type DisplayStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped' | 'interrupted';
+export interface WorkflowToolCall {
+    name: string;
+    summary?: string;
+}
+export interface WorkflowAgent {
+    id: string;
+    label: string;
+    model?: string;
+    fallbackModel?: string;
+    agentType?: string;
+    isolation?: string;
+    remoteSessionId?: string;
+    cached?: boolean;
+    state: AgentState;
+    /** WPe maps state→display; `skipped` distinguishes an error that was a user-skip. */
+    skipped?: boolean;
+    tokens?: number;
+    toolCalls?: number;
+    durationMs?: number;
+    queuedAt?: number;
+    startedAt?: number;
+    /** ofm/C0l: `idle <t>` when running and lastProgressAt is ≥30s ago. (contract: idleSince) */
+    lastProgressAt?: number;
+    attempt?: number;
+    lastAttemptReason?: 'throttled' | 'user-retry' | 'stalled';
+    error?: string;
+    agentId?: string;
+    /** detail "Prompt" body; promptPreview is the fallback when no transcript is loaded. */
+    promptPreview?: string;
+    /** detail "Activity" rows. */
+    activity?: WorkflowToolCall[];
+    lastToolName?: string;
+    lastToolSummary?: string;
+    /** detail "Outcome" body for done agents (the StructuredOutput JSON / final text). */
+    resultPreview?: string;
+}
+export interface WorkflowPhase {
+    title: string;
+    status: 'not-started' | 'running' | 'done' | 'failed';
+    doneCount: number;
+    totalCount: number;
+    agents: WorkflowAgent[];
+}
+export interface WorkflowRunState {
+    workflowRunId?: string;
+    name?: string;
+    description?: string;
+    summary?: string;
+    script: string;
+    scriptPath?: string;
+    status: 'running' | 'done' | 'failed' | 'stopped' | 'paused';
+    cloud?: boolean;
+    agentCount: number;
+    totalTokens: number;
+    /** phases as authored; the component derives the active/clamped windows itself. */
+    phases: WorkflowPhase[];
+    /** the 187 reads e.workflowProgress to recompute phases; the mock pre-builds them. */
+    workflowProgress?: unknown;
+}
+/**
+ * WPe — agentDisplayStatus: agent.state (+ workflowActive) → display status.
+ *
+ * FAITHFUL to the atlas state SET (atlas 0476_076:30-34). The atlas `WPe` reads ONLY these inputs:
+ *   if(state==="done") → "done"
+ *   if(state==="error") → skipped?"skipped":"failed"
+ *   if(!workflowActive) → "interrupted"          // the inactive/non-active fallback
+ *   else → (queuedAt!=null && startedAt==null) ? "queued" : "running"
+ * The atlas runner's agent-state enum the monitor sees is {start, progress, queued, done, error,
+ * inactive} — there is NO `failed`/`skipped`/`interrupted`/`stopped`/`running` INPUT state; those are
+ * DISPLAY statuses derived here: `failed`/`skipped` from `error` (+ the `skipped` flag), `interrupted` from
+ * `!workflowActive` (the `inactive`/non-active fallback), and `queued`/`running` from the queuedAt/startedAt
+ * fields on the active path. The AgentState type carries exactly this input set, so the type contract now
+ * matches the atlas vocabulary 1:1 — the branches below consume only atlas input states and the output
+ * DisplayStatus set + glyph/color mapping ($jn) is identical.
+ */
+export declare function agentDisplayStatus(a: WorkflowAgent, workflowActive: boolean): DisplayStatus;

package/dist/workflowMonitor.js

@@ -0,0 +1,43 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):workflow 监视器的**状态契约**(MF-W ·
+ *    contract/MF-W-workflow-monitor.md)从 cli `src/sema/overrides/workflow-detail-dialog.tsx:118-200`
+ *    搬入 —— 逐字,一个字段都没动。
+ *
+ * 🔴 **为什么类型必须先过来**:`workflowClient.projectWorkflowRun()`(同批搬入)的**产物**就是这套
+ *    形状。类型留在一个 `.tsx` 渲染文件里,等于「库产出的东西,它的契约住在 TUI 里」——
+ *    web/桌面要消费同一份投影就得手抄一遍 shape,而手抄的那份**没有任何东西**会在它漂移时报红。
+ *    定位公理([1832])说的「CC 皮肤形状全收本包」,指的正是这种东西。
+ *
+ * 🔴 **拆缝**:`workflow-detail-dialog.tsx` 本身是 Ink 渲染件(设计稿 §2 分类表「Ink 渲染」),
+ *    **留 TUI**;搬过来的只有 ① 六个契约类型 ② `agentDisplayStatus`(WPe —— 从 wire 输入词表
+ *    派生显示态的那条**纯**规则,是本契约的消费侧半场,端端都要用)。
+ *    留在 TUI 的:`computeVisibleWindow`(滚动窗口数学 = 视口概念,端专属)、glyph/color 映射、
+ *    以及整棵 JSX。壳侧 shim = 那个 tsx 改成从本包 re-export 这两样,自己不再定义。
+ */
+/**
+ * WPe — agentDisplayStatus: agent.state (+ workflowActive) → display status.
+ *
+ * FAITHFUL to the atlas state SET (atlas 0476_076:30-34). The atlas `WPe` reads ONLY these inputs:
+ *   if(state==="done") → "done"
+ *   if(state==="error") → skipped?"skipped":"failed"
+ *   if(!workflowActive) → "interrupted"          // the inactive/non-active fallback
+ *   else → (queuedAt!=null && startedAt==null) ? "queued" : "running"
+ * The atlas runner's agent-state enum the monitor sees is {start, progress, queued, done, error,
+ * inactive} — there is NO `failed`/`skipped`/`interrupted`/`stopped`/`running` INPUT state; those are
+ * DISPLAY statuses derived here: `failed`/`skipped` from `error` (+ the `skipped` flag), `interrupted` from
+ * `!workflowActive` (the `inactive`/non-active fallback), and `queued`/`running` from the queuedAt/startedAt
+ * fields on the active path. The AgentState type carries exactly this input set, so the type contract now
+ * matches the atlas vocabulary 1:1 — the branches below consume only atlas input states and the output
+ * DisplayStatus set + glyph/color mapping ($jn) is identical.
+ */
+export function agentDisplayStatus(a, workflowActive) {
+    if (a.state === 'done')
+        return 'done';
+    // atlas: `state==="error"` → skipped?"skipped":"failed".
+    if (a.state === 'error')
+        return a.skipped ? 'skipped' : 'failed';
+    // atlas `!t` (workflow not active) → interrupted (also the `inactive`-state landing).
+    if (!workflowActive)
+        return 'interrupted';
+    return a.queuedAt != null && a.startedAt == null ? 'queued' : 'running';
+}