@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/workflows.js

@@ -3,35 +3,21 @@ import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from ".
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
-const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/; // S8 self-orchestration runs: list / detail / live SSE
-// SVC-5 (design/97 CORE-5 #6): steer a STILL-RUNNING workflow agent (ctx.agentStream) by runId + label. POST-only,
-// so it never collides with the GET WORKFLOWS_RE above. The label is a non-slash segment (core mints `agent-N`
-// for an unlabelled agent, else the caller's opts.label) — URL-decoded by the handler.
+const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/;
 const WORKFLOW_AGENT_STEER_RE = /^\/v1\/workflows\/([^/]+)\/agents\/([^/]+)\/steer$/;
 export async function handleWorkflows(req, res, url, ctx) {
     const miss = { fell: false };
     await handleWorkflowsReadBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** SVC-5 的 steer 路——`handle()` 里位置在 tasks/runs 之后(鉴权门之后),故是**独立**的域入口。 */
 export async function handleWorkflowAgentSteer(req, res, url, ctx) {
     const miss = { fell: false };
     await handleWorkflowAgentSteerBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
- *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { runSessionAcceptOk } = ctx.helpers;
-    // S8 self-orchestration runs (design/97/98): GET /v1/workflows (list) · /v1/workflows/:id (detail) ·
-    // /v1/workflows/:id/stream (live SSE). OWNER-GATED by scope (= the creating principal, prepare-task.js
-    // scope: spec.principal). list/detail need the run store; live stream is in-process (subscribeWorkflow).
-    // 🔐 Identity from gatedPrincipal (direct-door-secure single point — crypto-verified principal JWT when
-    // directDoorActive, transparently `principalFrom` otherwise), NEVER the spoofable x-agent-principal header:
-    // a direct-door worker MUST NOT trust the raw header for a per-tenant owner gate (same bypass class —
-    // parity with the trace owner-gate, the workflow steer POST, and the elicit route). This block returns BEFORE
-    // the service-credential gate below, so the per-tenant gate here is the sole tenant boundary for these reads.
     const wfMatch = req.method === "GET" ? WORKFLOWS_RE.exec(url) : null;
     if (wfMatch) {
         const principal = gatedPrincipal(req, deps.config);
@@ -43,29 +29,19 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
             return;
         }
-        const scope = principal ?? "default"; // matches core's run_workflow scope = spec.principal ?? "default"
+        const scope = principal ?? "default";
         const wfId = wfMatch[1];
         const isStream = wfMatch[2] === "/stream";
         if (!wfId) {
             const q = new URL(req.url ?? "", "http://x").searchParams;
             const statusFilter = q.get("status");
             const limit = Math.min(100, Math.max(1, Number(q.get("limit") ?? 50) || 50));
-            // [1512]§二 交付件接线(1.247 留的 list 缺口):`?session=` 过滤臂 —— present 即按
-            // `originatingSessionId` 严格等值筛。语义是**筛选**非 per-id 的接受拍:无字段行(pre-core-1.210)
-            // 不属于任何会话,筛选下剔除(per-id 面的 absent 放行是访问控制防误伤,两面语义刻意不同);
-            // 空串=无行可匹配=空列表;absent = 全量,字节不变。1.250:筛下推 store 侧(core 1.368 [1516]②
-            // `listByScope.opts.session`,limit **前**应用)——1.249 的「页内筛」升「全量筛」,忙 scope 下
-            // 比 newest-limit 窗口更老的会话行不再漏。直调 store(listWorkflowRuns 是纯透传,其 opts 类型
-            // 未收录 session)。
             const sessionFilter = q.get("session");
             const sessionRuns = await deps.workflowRunStore.listByScope(scope, {
                 ...(statusFilter ? { status: statusFilter } : {}),
                 limit,
                 ...(sessionFilter !== null ? { session: sessionFilter } : {}),
             });
-            // K-2c LIST side (core 1.155 `WorkflowRunSummary` now carries name?/description?/currentPhase? from the
-            // script `meta` — flows via the pin bump): redact the LLM-authored label surfaces for parity with the DETAIL
-            // route (summarizeWorkflowDetail) + the fleet rows. The rest of the summary (status/counts/stats) rides as-is.
             const redacted = sessionRuns.map((r) => ({
                 ...r,
                 ...(r.name !== undefined ? { name: redactSecrets(r.name) } : {}),
@@ -75,48 +51,24 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { workflows: redacted });
             return;
         }
-        // per-id: owner-gate via the persisted run's scope (no existence oracle for non-owners → 404). 1.146:
-        // getWorkflowRun is scope-filtered IN CORE (returns null unless run.scope === scope) — defense-in-depth on
-        // top of our route gate; the `run.scope !== scope` below is now redundant but kept (belt-and-suspenders).
-        // The SSE branch streams ONLY after this gate, so the live stream is owner-gated too (core's subscribeWorkflow
-        // does not self-filter — this gate is its tenant boundary).
         const run = await getWorkflowRun(deps.workflowRunStore, wfId, scope);
         if (!run || run.scope !== scope) {
             sendError(res, 404, "not_found.workflow", "workflow not found");
             return;
         }
-        // [1508] 1.247 — session ACCEPT phase on the workflow per-id faces ([1493]-class sibling: these deliver
-        // conversation-derived content — step prompts/outputs/live events — but were principal-gated only, while
-        // the durable WorkflowRun carries `originatingSessionId` since core 1.210). Same soft phase + helper as
-        // the run faces (present-mismatch → 404; absent → warn-once). The LIST face is NOT gated this拍:
-        // WorkflowRunSummary lacks the field (core ask, γ-batch alignment) — its rows stay redacted summaries.
         if (!runSessionAcceptOk(req, res, { sessionId: run.originatingSessionId ?? null }, wfMatch[2] === "/journal" ? "workflow.journal" : isStream ? "workflow.stream" : "workflow.detail", "workflow not found"))
             return;
         if (wfMatch[2] === "/journal") {
-            // [1402]/[1400]④:per-agent journal 读面(云本地同构——三后端店同契约)。owner 门已过(上方 run
-            // scope 校验);投影=bounded+redact(result 是 LLM 产物,注入面纪律同 fleet 行),ordinal 序稳定。
             if (!deps.workflowJournalStore) {
                 sendError(res, 501, "capability.workflow_store_required", "workflow journal requires the journal store (SELF_ORCHESTRATION_ENABLED + a store backend)");
                 return;
             }
-            // codex R1-H2:hard bounds——limit 默认 20 cap 50(?limit=)、?offset= 游标;SQL 店走 loadPage
-            // (行数 LIMIT/OFFSET + 单行 64KiB LENGTH 门在库端,峰值 ≤50×64KiB);file/in-memory 店(单机形)
-            // 回落全量 load 后同界投影(内存峰值=店内容,记档取舍)。
             const jq = new URL(req.url ?? "", "http://x").searchParams;
             const jLimit = Math.min(50, Math.max(1, Number(jq.get("limit") ?? 20) || 20));
             const jOffset = Math.max(0, Number(jq.get("offset") ?? 0) || 0);
             const MAX_ROW_BYTES = 64 * 1024;
             const firstLine = (t) => (t ? redactSecrets(t.split("\n")[0].slice(0, 300)) : undefined);
             const MAX_RESULT_CHARS = 2000;
-            // A-002.6(披露双标,P1):>64KiB 的行诚实标 `truncated`/`resultBytes`(下方两臂),而 2000 字符~
-            // 64KiB 之间的行此前被 `slice(0, 2000)` **静默**截断 —— 同一个响应数组里一行说得出「我被截了」、
-            // 另一行说不出,消费者也无从区分「结果正好 2000 字」与「结果被截到 2000 字」。
-            // 🔴 键刻意**不复用** `truncated`:兄弟臂的 `truncated:true` 语义是「整行没内容,只有尺寸存根」,
-            //    盖到一行有内容的行上就是把兄弟臂的判别位改义(按它分支的消费者会把有内容的行当空存根)。
-            //    `resultTruncated`/`resultChars` 描述的是 `result` **这个字段**,无歧义。原始长度量的是
-            //    redact 之前的字符数(与兄弟臂 `resultBytes` 同精神,基准不同故不同名)。
-            // ⚠️ wire 记账:SDK spec 的 `WorkflowJournalEntry` 是 `additionalProperties: false`,两枚 additive
-            //    键需要 sema-sdk spec/openapi.yaml 同源补声明(SDK 件另走)。
             const projectResult = (callKey, r) => ({
                 callKey,
                 ordinal: callKeyOrdinal(callKey),
@@ -129,8 +81,6 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
                     }
                     : {}),
                 ...(r.stats ? { tokens: r.stats.tokens, turns: r.stats.turns } : {}),
-                // core 5.51 #210:status:"completed" 但停在人拒的唯一判别位——白名单不投它,journal 消费者
-                // 会把「用户拒了、在等指示」读成「自然跑完」(契约明写的误读形)。additive:自然结束不挂键。
                 ...(r.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}),
             });
             const js = deps.workflowJournalStore;
@@ -139,7 +89,6 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
                 const page = await js.loadPage(wfId, scope, { offset: jOffset, limit: jLimit, maxResultBytes: MAX_ROW_BYTES });
                 projected = page.map((row) => {
                     if (row.resultJson === null) {
-                        // 超单行门的条目:诚实标 truncated,不把 64KiB+ 的 TaskResult 拉进进程
                         return { callKey: row.callKey, ordinal: callKeyOrdinal(row.callKey), truncated: true, resultBytes: row.resultBytes };
                     }
                     try {
@@ -151,9 +100,6 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
                 });
             }
             else {
-                // fallback(file/in-memory,单机 TOC 形——多租户 durable 恒 SQL 店=loadPage 覆盖):load 全量的
-                // 内存/事件环成本=用户读自己盘的单机取舍(ARCHITECTURE.md 记档);投影侧与 SQL 店**同一诚实
-                // 语义**——超 64KiB 的行标 truncated/resultBytes,不做静默 2000 字投影(跨后端 API 形一致)。
                 const entries = await deps.workflowJournalStore.load(wfId, scope);
                 projected = entries
                     .sort((a, b) => callKeyOrdinal(a.callKey) - callKeyOrdinal(b.callKey))
@@ -169,57 +115,35 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
             return;
         }
         if (isStream)
-            await streamWorkflowRun(req, res, wfId, scope); // core 1.366 B-3: scope-doored live stream(异 scope=空流,与不存在同形)
+            await streamWorkflowRun(req, res, wfId, scope);
         else
-            sendJson(res, 200, summarizeWorkflowDetail(run)); // SVC-4: structured drill-down (Phases panel + agent list + groups tree)
+            sendJson(res, 200, summarizeWorkflowDetail(run));
         return;
     }
     miss.fell = true;
 }
-/** 同上纪律(SVC-5 steer 段)。 */
 async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, rateLimited, quotaExceeded, leaseDenied, safeDecode, runSessionAcceptOk } = ctx.helpers;
-    // SVC-5 (design/97 CORE-5 #6): POST /v1/workflows/:id/agents/:label/steer — STEER a still-running workflow
-    // agent (`ctx.agentStream`) mid-flight. Unlike RUN steer (a whole task run), this targets ONE running agent
-    // inside a workflow, addressed by runId + label. Delivery is replica-local (the steerable handle is an
-    // in-memory bridge to the running TaskStream, like `steerableRuns`):
-    //   • the handle is live on THIS replica → `handle.steer(redacted)` injects + returns the marker → 200.
-    //   • not here but the workflow run is `running` (another replica) → 409 steering.not_running (cross-replica
-    //     live-steer is the same fast-follow seam as RUN steer — single-replica-per-worker today; honest, never
-    //     a silent drop). • terminal / no handle → 409 steering.not_running.
-    // 🔴 HANDLE-VISIBILITY SEAM: core returns a WorkflowAgentHandle ONLY from `WorkflowRunContext.agentStream`,
-    // and that host ctx structurally never enters the script runner (the LLM workflow sees the sterile
-    // `WorkflowPrimitives`, which has `agent` but not `agentStream`). The service runs workflows ONLY via core's
-    // `run_workflow` tool → primitives, so it never holds a handle to register. The registry/redaction/auth here
-    // are production-real (the populated path uses them unchanged); until core hands the deployment the handle
-    // (e.g. an onAgentStream lifecycle sink on run_workflow), the registry is genuinely empty and the route
-    // returns steering.not_running. See workflow-agent-steer.ts. Raised to core (SVC-5).
     const wfSteerMatch = req.method === "POST" ? WORKFLOW_AGENT_STEER_RE.exec(url) : null;
     if (wfSteerMatch) {
         if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
-            return; // mutating + steers a running model agent
+            return;
         if (!deps.workflowRunStore) {
             sendError(res, 501, "capability.self_orchestration_required", "workflow runs require self-orchestration (SELF_ORCHESTRATION_ENABLED)");
             return;
         }
-        // Identity from gatedPrincipal (direct-door-secure single point), NEVER the spoofable header — `trusted`
-        // carries operator authority (a supervisor steering any tenant's agent), so deriving it from a header would
-        // be a privilege escalation (parity with RUN steer / preempt; HANDOFF 铁律 + core §3 inv #1).
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
-        // safeDecode (not bare decodeURIComponent): a malformed %-sequence is the CALLER's error → 400, not a 500
-        // (parity with the approvals + session-sync routes' established handling).
         const wfRunId = safeDecode(wfSteerMatch[1]);
         const label = safeDecode(wfSteerMatch[2]);
         if (wfRunId === null || label === null) {
             sendError(res, 400, "request.path_malformed", "malformed workflow path (invalid percent-encoding)");
             return;
         }
-        // Parse + validate the body BEFORE the run lookup (a bad body is the caller's error regardless of state).
         let body;
         try {
             body = (await readJson(req));
@@ -232,43 +156,21 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
             sendError(res, 400, "request.body_shape", "body must be { content: string (non-empty) }");
             return;
         }
-        // 入参上限(见 `STEER_IN_MAX_REQUEST_CHARS` 旁注):脱敏门是**同步**的,烧的是事件循环 ⇒
-        // 一次超大 steer 卡住的是**整个副本**。**拒**而不是服务端先截 —— 先截会让引擎的
-        // `[+N chars]` 披露低报,而"诚实标记不得低报"是本仓另一条钉守着的性质。
         if (body.content.length > STEER_IN_MAX_REQUEST_CHARS) {
             sendError(res, 413, "steer.content_too_large", `content exceeds ${STEER_IN_MAX_REQUEST_CHARS} characters (got ${body.content.length}); note only the first ${STEER_IN_MAX_CHARS} are delivered anyway`);
             return;
         }
-        // trusted = explicit operator (NOT bare isOperator — its empty-list "true-for-all" would let any caller
-        // steer any tenant's agent). A normal owner steers only their own workflow.
         const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
-        const ownerScope = principal ?? "default"; // matches run_workflow scope = spec.principal ?? "default"
-        // Owner-gate via the persisted run, now scope-filtered IN CORE (1.146 getWorkflowRun(store, id, scope) →
-        // null unless run.scope === scope). For a NON-operator: a missing/other-tenant run is null → 404 (no
-        // existence oracle). An explicit OPERATOR (supervisor) may steer ANY tenant's workflow — but core's
-        // scope-filtered read can't fetch another tenant's run by the operator's own scope (→ null), so the operator
-        // is NOT gated on `wfRun` existence: its authority is the operator allowlist, and the steer target's
-        // existence+liveness is proven by the registry handle below (no handle → 409, never a wrong-tenant steer).
+        const ownerScope = principal ?? "default";
         const wfRun = await getWorkflowRun(deps.workflowRunStore, wfRunId, ownerScope);
         if (!trusted && !wfRun) {
             sendError(res, 404, "not_found.workflow", "workflow not found");
             return;
         }
-        // [1508] 1.247 — same session accept-phase as the read faces (a steer ACTS on the conversation's
-        // workflow). Gated on the fetched run only: the operator leg (wfRun null by scope-filtered read) keeps
-        // its registry-handle-proven authority below, and runSessionAcceptOk's operator branch covers a
-        // same-scope operator anyway.
         if (wfRun && !runSessionAcceptOk(req, res, { sessionId: wfRun.originatingSessionId ?? null }, "workflow.agent-steer", "workflow not found"))
             return;
         const sendNotRunningWf = (error) => sendError(res, 409, "steering.not_running", error);
-        // STEER-IN REDACTION GATE (SVC-5 信任门): treat the human/leader content as UNTRUSTED — redact host leaks +
-        // size-bound + fence — BEFORE it reaches the worker. core's `handle.steer` fences AGAIN inside its trusted
-        // marker framing (defense in depth). Applied regardless of `trusted`: an operator's copy-pasted steer can
-        // still leak a host path/token, and an authoritative-looking steer must not pose as system instructions.
         const redacted = redactSteerIn(body.content, label);
-        // Same-replica live path: the steerable handle is registered here → inject now, return the marker.
-        // core does not enforce label uniqueness within a run, so resolve() reports the count: >1 = two live agents
-        // share this label → the target is ambiguous, refuse (409) rather than steer an arbitrary one.
         const resolution = deps.workflowAgentRegistry?.resolve(wfRunId, label);
         if (resolution && resolution.count > 1) {
             sendError(res, 409, "steering.ambiguous_label", `${resolution.count} live agents share label '${label}' in this run — steer target is ambiguous`);
@@ -283,18 +185,13 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
             }
             catch (e) {
                 const code = e.code;
-                // The agent settled between the registry lookup and steer() → core rejects steering.not_running.
                 if (code === "steering.not_running") {
                     sendNotRunningWf("agent just finished — no longer accepting steers");
                     return;
                 }
-                throw e; // unexpected → outer handler 500
+                throw e;
             }
         }
-        // No live handle here. The workflow run is either terminal, or `running` on another replica (cross-replica
-        // live-steer = the same fast-follow seam as RUN steer; a workflow agent is in-memory steerable only on its
-        // running replica). Either way: honest 409, never a silent drop. `wfRun` may be null for an OPERATOR steering
-        // a cross-tenant run (core's scope-filtered read returned null) → a generic message (status unknowable here).
         sendNotRunningWf(!wfRun
             ? "workflow agent is not running on this replica (no live handle)"
             : wfRun.status === "running"
@@ -304,37 +201,14 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
-/** SVC-4 v1 — the STRUCTURED drill-down view of one persisted {@link WorkflowRun} (the historical detail the
- *  Phases panel + agent list + groups tree render, parity with CC's Workflow tool). Pure projection over the
- *  persisted run — no new source of truth, no gate input (the route already owner-gated by scope before this).
- *  Three derived shapes:
- *   - `phases`: each `run.phases` entry + a done/total of the agents that ran under that `phase` title (done =
- *     terminal status). Plus an `unphased` bucket counting agents with no phase.
- *   - `agents`: each agent flattened to `{ label, status, callKey, groupId, phase, tokens, turns, durationMs,
- *     replayed, prompt, output }`. `prompt`/`output` are core-redacted + size-bounded; this is a HUMAN view so
- *     they are surfaced AT REST WITHOUT a fence (a consumer that re-feeds them to an LLM must fence itself —
- *     core's `WorkflowAgentRun` doc). `tokens`/`turns`/`costMicroUsd` come from the agent's own `stats`.
- *   - `groups`: the nested tree rebuilt from `run.groups` (parentGroupId) — each node carries its direct agent
- *     callKeys so a UI can hang the agent list off the tree. Empty when the script used no `ctx.workflow` nesting.
- *  `stats` (own + nested, kept separate per core R-5) and the run-level fields pass through unchanged. */
 function summarizeWorkflowDetail(run) {
     const isDone = (s) => s === "completed" || s === "failed";
-    // MF-W queued (core 1.150): a WorkflowAgentRun's `startedAt` is now OPTIONAL — ABSENT while an agent is QUEUED
-    // (waiting on a concurrency slot) or if it was aborted/finalized before it ran. So duration is undefined unless
-    // BOTH ends are present (a queued agent has no running duration — the DoR fix). Phases still always carry startedAt.
     const durationOf = (a) => a.startedAt === undefined || a.endedAt === undefined ? undefined : a.endedAt - a.startedAt;
-    // A real persisted run always carries these arrays; default defensively so a malformed/partial stored row
-    // projects cleanly instead of 500-ing the detail route (the view is read-only — never a gate input).
     const runPhases = run.phases ?? [];
     const runAgents = run.agents ?? [];
     const runGroups = run.groups ?? [];
-    // [review] label-parity: an LLM-authored run_workflow script controls phase titles + agent labels + the per-agent
-    // phase tag (core stores them raw, unbounded), so redact them on EMISSION for the same reason as name/description
-    // (a secret the agent read could land in a label). Filter/bucket on the RAW values (below) so grouping is unchanged;
-    // redactSecrets is deterministic → a secret-bearing title and the matching agent.phase scrub to the SAME string,
-    // so the shell's phase grouping still lines up. (prompt/output are already core-redacted; model is catalog-sourced.)
     const phases = runPhases.map((p) => {
-        const inPhase = runAgents.filter((a) => a.phase === p.title); // RAW compare — bucketing key, not emitted
+        const inPhase = runAgents.filter((a) => a.phase === p.title);
         return {
             title: redactSecrets(p.title),
             status: p.status,
@@ -345,50 +219,31 @@ function summarizeWorkflowDetail(run) {
             total: inPhase.length,
         };
     });
-    // Agents with no phase title, OR a phase title that matches no registered `run.phases` entry (a stray
-    // `opts.phase` with no enclosing `phase()` block) — surfaced so the panel's counts are EXHAUSTIVE (an agent is
-    // in exactly one bucket: its registered phase, or `unphased`). Without the `titleSet` guard a stray-phase agent
-    // would fall into NO bucket (under-count). Empty-string phase is also unphased.
     const phaseTitleSet = new Set(runPhases.map((p) => p.title));
     const unphased = runAgents.filter((a) => a.phase === undefined || a.phase === "" || !phaseTitleSet.has(a.phase));
     const unphasedView = unphased.length > 0
         ? { done: unphased.filter((a) => isDone(a.status)).length, total: unphased.length }
         : undefined;
     const agents = runAgents.map((a) => ({
-        label: redactSecrets(a.label), // [review] label-parity (LLM-authored, see phases comment)
+        label: redactSecrets(a.label),
         status: a.status,
-        // MF-W (1.149 CORE-shared): the canonical display status (running|queued|done|failed|interrupted) via core's
-        // deriveAgentDisplayStatus — the SAME pure fn the shell renders, so the agent-state glyph can't drift between
-        // shells (one source of truth in core). `interrupted` = a non-terminal agent under a terminal run. The live
-        // `idle` overlay (a running agent with no recent activity) stays a SHELL wall-clock concern — since core 1.295
-        // ToolActivity carries `at`, this view exposes the raw timestamps (activity[].at + lastActivityAt below) and
-        // the shell derives idleness against its own clock (a served idleMs would drift on a historical view).
         displayStatus: deriveAgentDisplayStatus(a, run.status),
         taskStatus: a.taskStatus,
         callKey: a.callKey,
         groupId: a.groupId,
-        phase: a.phase !== undefined ? redactSecrets(a.phase) : undefined, // [review] label-parity; undefined = unphased (kept)
-        model: a.model, // SVC-4 v2 / CORE-8 ①: per-agent model display label ("Opus 4.8 (1M context)" row)
+        phase: a.phase !== undefined ? redactSecrets(a.phase) : undefined,
+        model: a.model,
         tokens: a.stats?.tokens,
         turns: a.stats?.turns,
-        toolCalls: a.toolCalls, // SVC-4 v2 / CORE-8 ②: total tool calls ("M" in "last N of M tool calls")
-        // SVC-4 v2 / CORE-8 ③: the LAST-N tool-call beats (structural — phase/toolName/ids, no args/output). The live
-        // detail SSE (subscribeWorkflow → streamWorkflowRun) already forwards the per-callKey `agent_activity` events
-        // verbatim for a running drill-down; this is the persisted tail a historical view renders.
-        // [843]④a (core 1.295): each beat now carries `at` (epoch ms, stamped on BOTH start and end) — verbatim
-        // passthrough here, so idle derives shell-side as the FRAME GAP (end.at → next start.at), the [879] ruling.
+        toolCalls: a.toolCalls,
         activity: a.activity,
-        // [843]④a convenience: the tail beat's timestamp, so a shell can grey a stale agent without walking the
-        // array. TIMESTAMP not a duration on purpose — this detail is a HISTORICAL view, so a served `idleMs`
-        // (Date.now()-derived) would drift on every re-read; the shell owns the clock. Absent for pre-1.295 runs
-        // whose beats carry no `at` (undefined → key omitted by JSON, same back-compat shape as agentFailures).
         lastActivityAt: a.activity && a.activity.length > 0 ? a.activity[a.activity.length - 1].at : undefined,
         durationMs: durationOf(a),
-        queuedAt: a.queuedAt, // MF-W queued (1.150): when the agent was ENQUEUED (always set) — a queued agent has queuedAt but no startedAt
-        startedAt: a.startedAt, // now optional (absent while queued / aborted-before-run) — displayStatus already reflects "queued"
+        queuedAt: a.queuedAt,
+        startedAt: a.startedAt,
         endedAt: a.endedAt,
         replayed: a.replayed,
-        prompt: a.prompt, // core-redacted + bounded; human view → no fence at rest
+        prompt: a.prompt,
         output: a.output,
     }));
     const byId = new Map();
@@ -404,9 +259,6 @@ function summarizeWorkflowDetail(run) {
             children: [],
         });
     }
-    // Walk up `parentGroupId` from `node`; true if the chain LOOPS (self-parent, or a multi-node cycle A→B→A)
-    // rather than terminating at a top-level (`undefined`) or dangling (absent) parent. Bounded by the seen-set, so
-    // a malformed run can neither hang nor build a circular object that `JSON.stringify` would throw 500 on.
     const inCycle = (start) => {
         const seen = new Set();
         let cur = start;
@@ -421,27 +273,18 @@ function summarizeWorkflowDetail(run) {
     const roots = [];
     for (const node of byId.values()) {
         const parent = node.parentGroupId !== undefined ? byId.get(node.parentGroupId) : undefined;
-        // Link to parent ONLY when that can't form a cycle — a self/multi-node cycle member grafts onto root, so the
-        // tree is always acyclic (JSON-safe) and no node is ever dropped.
         if (parent && parent !== node && !inCycle(node))
             parent.children.push(node);
         else
-            roots.push(node); // top-level, dangling parent, or cycle member → graft onto root (never dropped)
+            roots.push(node);
     }
     return {
         id: run.id,
         scope: run.scope,
         status: run.status,
-        // K-2c (shell §K): the workflow header label + subtitle the MF-W detail view needs — from the script's
-        // `export const meta = {name, description}` (core WorkflowRun.name/description). REDACTED for label parity with
-        // the fleet run/subagent names (an LLM-authored meta is task-controlled → could carry a secret shape). Per-phase
-        // title is already on each `phases[].title`. Omitted when absent (back-compat: older runs have neither).
         ...(run.name !== undefined ? { name: redactSecrets(run.name) } : {}),
         ...(run.description !== undefined ? { description: redactSecrets(run.description) } : {}),
         stats: run.stats,
-        // core 1.293: run-level failed-agent count (agents whose status ended "failed"), stamped at run end only
-        // when > 0. A plain number (not task-controlled text) → no redaction. Omitted when absent (back-compat:
-        // pre-1.293 runs / zero failures) — [843]④a: the detail view had no failure count to render.
         ...(run.agentFailures !== undefined ? { agentFailures: run.agentFailures } : {}),
         startedAt: run.startedAt,
         endedAt: run.endedAt,
@@ -449,10 +292,6 @@ function summarizeWorkflowDetail(run) {
         durationMs: durationOf(run),
         rev: run.rev,
         error: run.error,
-        // core 1.234: the script's RETURN VALUE — bounded + redacted AT THE SOURCE (completion-time,
-        // same egress discipline as the notifier), but re-redacted here for defence-in-depth parity with
-        // name/description (this projection's whitelist predates the field — live-dig T8 caught the omission:
-        // TaskOutput carried the result while this detail view silently dropped it). Absent on failed/pre-1.234 runs.
         ...(run.result !== undefined ? { result: redactSecrets(run.result) } : {}),
         phases,
         ...(unphasedView ? { unphased: unphasedView } : {}),
@@ -460,27 +299,14 @@ function summarizeWorkflowDetail(run) {
         groups: roots,
     };
 }
-/** SSE the live progress of a RUNNING workflow (S8). subscribeWorkflow is IN-PROCESS (replica-local): the
- *  iterable ends when the run's channel closes at run_end, or when the client disconnects. A run with no live
- *  channel (already finished, or on another replica) yields nothing → the stream ends immediately (the
- *  historical view is GET /v1/workflows/:id). Owner-gating (run.scope === principal) is done by the caller;
- *  core 1.366 (B-3) additionally doors the subscription itself on scope — a mismatched scope yields an empty
- *  stream (same shape as not-found), so the caller passes the SAME scope it owner-gated with. */
 async function streamWorkflowRun(req, res, runId, scope) {
     sseHeaders(res);
-    // `type: "meta"` 与 `event: meta` 同名双发(tasks/trace-usage/approvals 三流同款):部分代理只转发
-    // `data:` 行,按 data.type 分派的消费端否则认不出首帧。additive,老消费端忽略未知键。
     res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", version: 1, runId })}\n\n`);
     let closed = false;
-    // subscribeWorkflow is a PUSH iterator: a parked `next()` on an idle-but-alive workflow does NOT observe a
-    // `closed` flag, so a disconnected client would leave the subscriber queue registered in core's channels and
-    // publishWorkflowEvent would buffer events for the dead peer forever (a leak). Drive the iterator explicitly so
-    // disconnect can call `it.return()` — which unwinds the parked next() AND runs core's finally to prune the queue.
     const it = subscribeWorkflow(runId, scope)[Symbol.asyncIterator]();
-    // Heartbeat so an idle proxy/mesh doesn't drop the connection (and a dead TCP peer is detected → "close").
     const hb = setInterval(() => {
         if (!res.writableEnded)
-            res.write(`event: heartbeat\ndata: {}\n\n`); // real frame (not an SSE comment) — a per-frame-parsing BFF drops comments, so downstream saw a zero-frame window; EventSource clients without a heartbeat listener ignore it (zero break)
+            res.write(`event: heartbeat\ndata: {}\n\n`);
     }, 15_000);
     if (typeof hb.unref === "function")
         hb.unref();
@@ -489,12 +315,12 @@ async function streamWorkflowRun(req, res, runId, scope) {
             return;
         closed = true;
         clearInterval(hb);
-        void it.return?.(undefined); // prune core's subscriber queue (workflow-observe finally) — stop buffering for a dead peer
+        void it.return?.(undefined);
         if (!res.writableEnded)
             res.end();
     };
     req.on("close", shutdown);
-    res.on("close", shutdown); // res close (peer gone) too, not just req — either side ending must prune the queue
+    res.on("close", shutdown);
     try {
         for (let next = await it.next(); !next.done; next = await it.next()) {
             if (closed || res.writableEnded)
@@ -504,8 +330,6 @@ async function streamWorkflowRun(req, res, runId, scope) {
         }
     }
     catch {
-        // A1/A6/B:归一 error 帧形(`type` + 机器码)。此前只发人话 message ⇒ 消费端要么锚文案、要么把
-        // "流断了"和"流正常结束"混为一谈;`workflow.stream_error` 是本帧的铸码(附录 A `*.stream_error` 族)。
         if (!closed && !res.writableEnded)
             res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "workflow.stream_error", message: "workflow stream error" })}\n\n`);
     }

package/dist/http/run-meta.js

@@ -1,18 +1,12 @@
 import { redactSecrets } from "../trace/redact.js";
-/** The denormalized run-row metadata captured at submit: correlation (jobId), credential-derived source,
- *  and a redacted objective glance for lists. One place so the three submit paths can't drift. */
 export function runMeta(prepared, source) {
     const obj = prepared.spec.objective ?? "";
     return {
         jobId: prepared.jobId ?? null,
         source,
-        // redactSecrets is best-effort (known key/token shapes only — NOT exhaustive; see redact.ts). Acceptable
-        // here: the preview rides the fleet-token-gated trace surface, not an end-user-readable channel (council #1).
         objectivePreview: obj ? redactSecrets(obj).slice(0, 120) : null,
     };
 }
-/** Build the cascade config from the operator ladder. Default gate = `status==="completed"` (escalate
- *  on a cheap-rung failure); cost-ceiling from the task's budget bounds the cold-rerun tax. */
 export function cascadeConfig(ladder, maxCostUsd) {
     return {
         ladder: ladder.map((model) => ({ model })),

package/dist/http/send.js

@@ -6,47 +6,15 @@ export function sseHeaders(res, extra) {
         ...extra,
     });
 }
-/**
- * 一条 SSE 连接的墙钟上限。到点发一帧 `error`/`STREAM_MAX_DURATION`(**不是**静默关闭 —— 客户端分不出
- * 「到帽了请重连」和「跑完了」)然后收流。
- *
- * 🔴 为什么共享(2026-08-08,#176 二轮扫描 finding):这个数与下面的心跳间隔此前在**三处**各手抄一份
- * —— `http/sse-log.ts`(task_run + image_bake 共用的那台泵)、`http/routes/trace-usage.ts`、
- * `http/routes/approvals-assistant.ts`(它的顶注还自称「parity with streamTaskTrace」)。三处各自有测试
- * 钉着**自己那一份**,没有任何跨副本的一致性钉 ⇒ 单边调帽后「parity」只剩注释里那句话。
- *
- * ⚠️ 改这个数请连**文案**一起改:三处的 `STREAM_MAX_DURATION` 消息里把「15-minute」写死在散文里
- * (文案面另有 freeze 门,故此处不做插值——散文与常量的同步靠这行告诫,不靠机器)。
- */
 export const SSE_MAX_STREAM_MS = 15 * 60 * 1000;
-/**
- * 长时间无事件时的心跳间隔(防中继的 idle timeout 掐流)。与 {@link SSE_MAX_STREAM_MS} 同批收口。
- *
- * ⚠️ 收口的只有**间隔**,**不含帧形**:`sse-log` / `trace-usage` 发 `data: {}`,`approvals-assistant`
- * 发 `data: {"type":"heartbeat"}`。这是真分歧不是笔误 —— trace-usage 自己的 meta 帧还引着 [2373]C-12
- * 「每个 data payload 都带 type」的约定,而它的心跳帧没有 type(probe-sse-1 的注释把这条记成「按
- * data.type 分派的客户端会拿到 undefined」)。统一帧形是**行为面**改动(要么给两处加 type=多发一个键,
- * 要么给 approvals 减 type=消费端破坏),属候裁,不在本批的零行为码范围内。
- */
 export const SSE_HEARTBEAT_IDLE_MS = 15_000;
 export function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify(body));
 }
-/** A6(design/158 lens1 §C3/lens3 §C3a): canonical error-response sender for sites that already carry a
- *  machine `errorCode` — `errorCode` is a required positional arg (not optional-bag) so a call site
- *  cannot regress to the "code but no errorCode" shape the error-code-key-gate forbids. Body shape is
- *  `{ error: message, errorCode, ...extra }`; a site that used to ALSO emit a legacy `code` key keeps it
- *  by passing `{ code: ... }` inside `extra` — this is a pure call-site migration (zero wire-contract
- *  change), not a new response shape. Sites where the two machine-code channels genuinely disagree, or
- *  where `error`/`errorCode` aren't cleanly separable from the rest of the body, are left on raw
- *  `sendJson` (see the A6 migration notes for the callers still doing that on purpose). */
 export function sendError(res, status, errorCode, message, extra) {
     sendJson(res, status, { error: message, errorCode, ...extra });
 }
-/** B7(design/158 lens1 §C3):`HttpError` 的兜底 catch-all 站点没有自己的语义分支——`err.code` 在 42 个
- *  throw 点里只有 3 个带。为了让「errorCode 恒在」在这些站点也成立(而不是靠豁免表放行),按**状态码**
- *  给一个诚实的粗码:它只声明「这类拒绝」,不冒充比 throw 点更细的语义。带 `code` 的 throw 点原样优先。 */
 export function httpErrorCode(status, code) {
     if (code)
         return code;