@united-workforce/cli 0.6.1 → 0.8.1

package/dist/commands/broker-step.js

@@ -0,0 +1,654 @@
+/**
+ * Broker-driven step execution. Replaces the legacy `spawnAgent` /
+ * `executeAgentCommand` / last-stdout-line JSON parsing path with
+ * `broker.send()` over the Sumeru HTTP API.
+ *
+ * Phase 3 (#380) — `cmdThreadStepOnce`, `cmdThreadResume`, and `cmdThreadPoke`
+ * use this module instead of spawning per-role CLI binaries.
+ */
+import { join } from "node:path";
+import { putSchema, validate } from "@ocas/core";
+import { createBroker, createSessionStore, } from "@united-workforce/broker";
+import { SUSPEND_STATUS, } from "@united-workforce/protocol";
+import { createLogger } from "@united-workforce/util";
+import { buildContinuationPrompt, buildFrontmatterRetryPrompt, buildOutputFormatInstruction, buildRolePrompt, buildThreadProgress, mergeUsage, tryFrontmatterFastPath, trySuspendFastPath, } from "@united-workforce/util-agent";
+import { clearActiveStep, clearActiveTurns, getActiveTurnHead, setActiveStep, setActiveTurnHead, writeStepStart, writeTurnNode, } from "../store.js";
+import { expandOutput, fail } from "./shared.js";
+const log = createLogger({ sink: { kind: "stderr" } });
+/** Tag for broker.send call site. */
+const PL_BROKER_SEND = "BR0KR5ND";
+/** Tag for frontmatter retry call sites. */
+const PL_FRONTMATTER_RETRY = "F4RTM4RT";
+/** Tag for frontmatter extraction failure. */
+const PL_FRONTMATTER_FAIL = "F4FA117Z";
+const MAX_FRONTMATTER_RETRIES = 2;
+const DETAIL_SCHEMA = {
+    title: "broker-detail",
+    type: "object",
+    required: ["sessionId", "duration", "turnCount"],
+    properties: {
+        sessionId: { type: "string" },
+        duration: { type: "integer" },
+        turnCount: { type: "integer" },
+        // Suspend diagnostics (issue #435) — present only on a timeout-suspended
+        // step. Optional, so the completed-path detail node is byte-for-byte
+        // unchanged (same content hash).
+        nativeId: { type: "string" },
+        elapsedMs: { type: "integer" },
+        reason: { type: "string" },
+    },
+    additionalProperties: false,
+};
+/**
+ * Parse `--agent` overrides under the new `{host, gateway}` shape.
+ *
+ * Accepts:
+ *   - alias    e.g. `hermes`             → `config.agents.hermes`
+ *   - inline   e.g. `http://h:7900 gw`   → `{host: "http://h:7900", gateway: "gw"}`
+ *
+ * Single-token forms that don't match an alias fail with the documented
+ * message; this fully replaces the legacy "treat anything as a binary path"
+ * behaviour.
+ */
+export function parseAgentOverride(override) {
+    const trimmed = override.trim();
+    if (trimmed === "") {
+        fail("agent override must not be empty");
+    }
+    const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+    if (parts.length !== 2) {
+        fail(`agent override must be an alias or "<host> <gateway>"`);
+    }
+    const host = parts[0];
+    const gateway = parts[1];
+    if (host === undefined || gateway === undefined) {
+        fail(`agent override must be an alias or "<host> <gateway>"`);
+    }
+    return { host, gateway };
+}
+/**
+ * Resolve the agent route for a (workflow, role, override) triple.
+ * Mirrors the legacy `resolveAgentConfig` precedence:
+ *   --agent override > agentOverrides[workflow][role] > defaultAgent
+ * Override may be an alias or an inline `"<host> <gateway>"` form.
+ */
+export function resolveAgentRoute(config, workflow, role, agentOverride, cwd) {
+    if (agentOverride !== null) {
+        const fromAlias = config.agents[agentOverride];
+        if (fromAlias !== undefined) {
+            return { host: fromAlias.host, gateway: fromAlias.gateway, cwd };
+        }
+        const parsed = parseAgentOverride(agentOverride);
+        return { host: parsed.host, gateway: parsed.gateway, cwd };
+    }
+    let alias = config.defaultAgent;
+    if (config.agentOverrides !== null) {
+        const roleOverrides = config.agentOverrides[workflow.name];
+        if (roleOverrides !== undefined && roleOverrides[role] !== undefined) {
+            alias = roleOverrides[role];
+        }
+    }
+    const agentConfig = config.agents[alias];
+    if (agentConfig === undefined) {
+        fail(`unknown agent alias in config: ${alias}`);
+    }
+    return { host: agentConfig.host, gateway: agentConfig.gateway, cwd };
+}
+/**
+ * Path to the broker session store DB under the storage root. Mirrors the
+ * default used by `createSessionStore` but anchored at the user's `UWF_HOME`
+ * so multi-process scripts share the same SQLite file.
+ */
+export function brokerSessionStorePath(storageRoot) {
+    return join(storageRoot, "broker", "sessions.db");
+}
+/**
+ * Open (or create) the broker session store under `<storageRoot>/broker/sessions.db`.
+ * The caller is responsible for closing it.
+ */
+export function openBrokerSessionStore(storageRoot) {
+    return createSessionStore({ dbPath: brokerSessionStorePath(storageRoot) });
+}
+/**
+ * Look up the role's frontmatter / output schema in CAS so we can drive
+ * `tryFrontmatterFastPath`.  The workflow payload only carries the schema's
+ * CAS hash; the JSON Schema itself lives in CAS via `WorkflowAdd`.
+ */
+function loadRoleSchemaHash(workflow, role) {
+    const roleDef = workflow.roles[role];
+    if (roleDef === undefined) {
+        fail(`unknown role "${role}" in workflow "${workflow.name}"`);
+    }
+    return roleDef.frontmatter;
+}
+/**
+ * Build the output-format instruction for a role from its frontmatter schema in
+ * CAS. Returns an empty string when the schema node is missing.
+ */
+function loadOutputFormatInstruction(uwf, schemaHash) {
+    const node = uwf.store.cas.get(schemaHash);
+    if (node === null) {
+        return "";
+    }
+    return buildOutputFormatInstruction(node.payload);
+}
+/** Extract the last assistant turn's content from a detail node, or null. */
+function extractStepContent(uwf, detailRef) {
+    const detailNode = uwf.store.cas.get(detailRef);
+    if (detailNode === null) {
+        return null;
+    }
+    const detail = detailNode.payload;
+    const turns = detail.turns;
+    if (!Array.isArray(turns) || turns.length === 0) {
+        return null;
+    }
+    for (let i = turns.length - 1; i >= 0; i--) {
+        const turnRef = turns[i];
+        if (typeof turnRef !== "string") {
+            continue;
+        }
+        const turnNode = uwf.store.cas.get(turnRef);
+        if (turnNode === null) {
+            continue;
+        }
+        const turn = turnNode.payload;
+        if (turn.role === "assistant" &&
+            typeof turn.content === "string" &&
+            turn.content.trim() !== "") {
+            return turn.content;
+        }
+    }
+    return null;
+}
+/**
+ * Walk the CAS step chain from `prevHash` back to the StartNode and return the
+ * steps in chronological order (oldest first) as StepContext records. Honors the
+ * caller-supplied `prev` pointer so poke replace-semantics (prev = old head's
+ * prev) produce the correct history. Mirrors the history assembly in
+ * util-agent's `buildContext`, but reuses the store the CLI already opened.
+ */
+function collectStepContexts(uwf, prevHash) {
+    const newestFirst = [];
+    let hash = prevHash;
+    while (hash !== null) {
+        const node = uwf.store.cas.get(hash);
+        if (node === null || node.type !== uwf.schemas.stepNode) {
+            break;
+        }
+        const payload = node.payload;
+        newestFirst.push(payload);
+        hash = payload.prev;
+    }
+    const chronological = [...newestFirst].reverse();
+    return chronological.map((step) => ({
+        role: step.role,
+        output: expandOutput(uwf, step.output),
+        detail: step.detail,
+        agent: step.agent,
+        edgePrompt: step.edgePrompt ?? "",
+        startedAtMs: step.startedAtMs,
+        completedAtMs: step.completedAtMs,
+        cwd: step.cwd ?? "",
+        assembledPrompt: step.assembledPrompt ?? null,
+        usage: step.usage ?? null,
+        previousAttempts: step.previousAttempts ?? null,
+        content: extractStepContent(uwf, step.detail),
+    }));
+}
+/**
+ * Assemble the full agent prompt for a broker step. Combines the five
+ * components the legacy agent-CLI path produced (output-format instruction,
+ * thread progress, role prompt, task prompt, and continuation/edge context) so
+ * `broker.send()` receives the same context the spawned-agent path did.
+ *
+ * Mirrors `buildClaudeCodePrompt` from the agent-claude-code adapter.
+ */
+export function assembleBrokerPrompt(args) {
+    const roleDef = args.workflow.roles[args.role];
+    const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+    const isFirstVisit = !args.steps.some((s) => s.role === args.role);
+    const parts = [];
+    if (args.outputFormatInstruction !== "") {
+        parts.push(args.outputFormatInstruction, "");
+    }
+    // Inject thread progress so the agent knows step count and role visit count.
+    parts.push(buildThreadProgress(args.steps, args.role, args.threadId), "");
+    parts.push(rolePrompt, "", "## Task", args.startPrompt);
+    if (!isFirstVisit) {
+        // Re-entry (broker resumes the cached session): show only steps since the
+        // last visit, meta only.
+        parts.push("", buildContinuationPrompt(args.steps, args.role, args.edgePrompt));
+    }
+    else if (args.steps.length > 0) {
+        // First visit with prior history: show steps with content for recent ones.
+        parts.push("", buildContinuationPrompt(args.steps, args.role, args.edgePrompt, {
+            includeContent: true,
+            quota: 32000,
+        }));
+    }
+    else {
+        parts.push("", "## Current Instruction", "", args.edgePrompt);
+    }
+    return parts.join("\n");
+}
+/**
+ * Persist the step's detail node. Phase 2 (#419): the detail no longer contains
+ * a `turns` array — turns are self-contained via their `prev`+`owner` chain.
+ * Only metadata (sessionId, duration, turnCount) is stored.
+ */
+async function storeBrokerDetail(uwf, result, threadId, role, startedAtMs, completedAtMs, turnCount) {
+    const detailSchemaHash = await putSchema(uwf.store, DETAIL_SCHEMA);
+    // Phase 2 (#419): clear the deprecated role-keyed active var for backward
+    // compatibility. The turns are already persisted via the turn chain.
+    clearActiveTurns(uwf.store, threadId, role);
+    const detail = {
+        sessionId: result.sessionId,
+        duration: Math.max(0, completedAtMs - startedAtMs),
+        turnCount,
+    };
+    return uwf.store.cas.put(detailSchemaHash, detail);
+}
+/**
+ * Build the realtime `onTurn` callback wired into `broker.send` (Phase 2, #419).
+ * For each arriving assistant turn it writes a TurnNode with:
+ *   - `role: "assistant"`
+ *   - `content: <turn content>`
+ *   - `prev: <previous turn hash or null>`
+ *   - `owner: <current step-start hash>`
+ * Then updates `@uwf/active-turn-head/<threadId>` to point to the new turn.
+ *
+ * The turn chain is self-contained — each turn links to its predecessor via
+ * `prev` and to its owning step via `owner`. No separate array accumulation
+ * is needed.
+ *
+ * Returns the turn count after the step completes (for detail node).
+ */
+function makeOnTurn(uwf, threadId, stepStartHash) {
+    let turnCount = 0;
+    // Get the current turn head before this step starts (could be from previous steps)
+    let prevTurnHash = getActiveTurnHead(uwf.store, threadId);
+    const onTurn = (turn) => {
+        // Write turn node with prev+owner chain
+        const turnHash = writeTurnNode(uwf, {
+            role: "assistant",
+            content: turn.content,
+            prev: prevTurnHash,
+            owner: stepStartHash,
+        });
+        // Update thread-keyed active turn head
+        setActiveTurnHead(uwf.store, threadId, turnHash);
+        // Also maintain deprecated role-keyed var for backward compatibility
+        // during transition period (can be removed in Phase 3)
+        // appendActiveTurn is called but we don't rely on it for turn retrieval
+        prevTurnHash = turnHash;
+        turnCount++;
+    };
+    const getTurnCount = () => turnCount;
+    return { onTurn, getTurnCount };
+}
+/** Persist a StepNode payload and verify it round-trips through schema validation. */
+async function writeBrokerStepNode(args) {
+    const payload = {
+        start: args.startHash,
+        prev: args.prevHash,
+        role: args.role,
+        output: args.outputHash,
+        detail: args.detailHash,
+        agent: args.agentName,
+        edgePrompt: args.edgePrompt,
+        startedAtMs: args.startedAtMs,
+        completedAtMs: args.completedAtMs,
+        cwd: args.cwd,
+        assembledPrompt: args.assembledPromptHash,
+        usage: args.usage,
+        previousAttempts: args.previousAttempts,
+    };
+    const hash = await args.uwf.store.cas.put(args.uwf.schemas.stepNode, payload);
+    const node = args.uwf.store.cas.get(hash);
+    if (node === null || !validate(args.uwf.store, node)) {
+        fail("broker step persisted a StepNode that failed schema validation");
+    }
+    return hash;
+}
+/**
+ * Render the engine-level suspend (coroutine yield) wire format — frontmatter
+ * with `$status: "$SUSPEND"` plus a human-readable `reason`. Round-trips through
+ * the public {@link trySuspendFastPath}, which stores it against the reserved
+ * suspend-output schema.
+ *
+ * NOTE: this mirrors the adapter-side `buildSuspendOutput` in
+ * `@united-workforce/util-agent`, kept private here on purpose — the #381
+ * public-API cleanup deliberately keeps that helper OUT of the util-agent
+ * barrel, and `broker-step.ts` is engine/CLI code (not an adapter). The string
+ * is a one-liner over `SUSPEND_STATUS`, so duplicating it costs nothing and
+ * preserves the package boundary (see public-api-no-llm.test.ts).
+ */
+function buildSuspendOutput(reason) {
+    return `---\n$status: ${SUSPEND_STATUS}\nreason: ${reason}\n---\n`;
+}
+/**
+ * Route a broker `kind:"suspended"` result through the existing engine-level
+ * `$SUSPEND` exit (issue #435, Phase 2). A send timeout is NOT an error and NOT
+ * a frontmatter failure — it is a human gate. We build a suspend output via the
+ * shared {@link buildSuspendOutput} / {@link trySuspendFastPath} helpers (the
+ * same wire format any agent that prints `$status: "$SUSPEND"` produces), store
+ * it against the reserved `suspendOutput` schema, record `nativeId`/`elapsedMs`
+ * on the detail node for diagnostics, and persist a normal StepNode. Downstream
+ * thread-status resolution maps the head step's `$status: "$SUSPEND"` output to
+ * `status: "suspended"`, and `uwf thread resume` continues from `nativeId`.
+ */
+async function writeSuspendedStep(args) {
+    const reason = `sumeru send timed out after ${args.suspend.elapsedMs}ms ` +
+        `(nativeId=${args.suspend.nativeId}); resume to continue`;
+    const suspendRaw = buildSuspendOutput(reason);
+    const extracted = await trySuspendFastPath(suspendRaw, args.uwf.schemas.suspendOutput, args.uwf.store);
+    if (extracted === null) {
+        fail("broker step failed to build a $SUSPEND output node for a timeout-suspended send");
+    }
+    const detailSchemaHash = await putSchema(args.uwf.store, DETAIL_SCHEMA);
+    // Clear the deprecated role-keyed active var (parity with storeBrokerDetail).
+    clearActiveTurns(args.uwf.store, args.threadId, args.role);
+    const detail = {
+        sessionId: args.sessionId,
+        duration: Math.max(0, args.completedAtMs - args.startedAtMs),
+        turnCount: args.turnCount,
+        nativeId: args.suspend.nativeId,
+        elapsedMs: args.suspend.elapsedMs,
+        reason: args.suspend.reason,
+    };
+    const detailHash = await args.uwf.store.cas.put(detailSchemaHash, detail);
+    // Clear the active-step var: the step has reached a terminal (suspended) state.
+    clearActiveStep(args.uwf.store, args.threadId);
+    const stepHash = await writeBrokerStepNode({
+        uwf: args.uwf,
+        startHash: args.startHash,
+        prevHash: args.prevHash,
+        role: args.role,
+        outputHash: extracted.outputHash,
+        detailHash,
+        agentName: args.agentName,
+        edgePrompt: args.edgePrompt,
+        startedAtMs: args.startedAtMs,
+        completedAtMs: args.completedAtMs,
+        cwd: args.cwd,
+        assembledPromptHash: args.assembledPromptHash,
+        usage: null,
+        previousAttempts: args.previousAttempts,
+    });
+    return {
+        stepHash,
+        detailHash,
+        role: args.role,
+        frontmatter: extracted.frontmatter,
+        body: extracted.body,
+        startedAtMs: args.startedAtMs,
+        completedAtMs: args.completedAtMs,
+        usage: null,
+        isError: false,
+        errorMessage: null,
+    };
+}
+async function tryExtract(uwf, rawOutput, outputSchema) {
+    // `$status: "$SUSPEND"` is a reserved coroutine yield — store it against the
+    // suspend schema, bypassing the role's own frontmatter schema.
+    const suspend = await trySuspendFastPath(rawOutput, uwf.schemas.suspendOutput, uwf.store);
+    if (suspend !== null) {
+        return { outputHash: suspend.outputHash, frontmatter: suspend.frontmatter, body: suspend.body };
+    }
+    const fastPath = await tryFrontmatterFastPath(rawOutput, outputSchema, uwf.store);
+    if (fastPath !== null) {
+        return {
+            outputHash: fastPath.outputHash,
+            frontmatter: fastPath.frontmatter,
+            body: fastPath.body,
+        };
+    }
+    return null;
+}
+/**
+ * Drive one moderator-resolved role through `broker.send()`, frontmatter
+ * extraction (with retries on the same Sumeru session), and StepNode
+ * persistence. Returns a `BrokerStepResult` shaped for the existing
+ * `executeAndProcessAgentStep` flow.
+ *
+ * Phase 2 (#419) changes:
+ *   - Writes step-start node at entry, sets `@uwf/active-step/<threadId>`
+ *   - Turns are written with `prev`+`owner` chain via `writeTurnNode`
+ *   - Updates `@uwf/active-turn-head/<threadId>` as turns arrive
+ *   - Clears `@uwf/active-step/<threadId>` at completion
+ *   - Detail node no longer contains `turns` array (turns self-contained)
+ *
+ * Side effects:
+ *   - inserts a row in the broker session store keyed by (threadId, role)
+ *   - writes step-start / turns / detail / StepNode to CAS
+ *   - on extraction failure, persists an error StepNode (isError=true)
+ */
+export async function executeBrokerStep(args) {
+    const sessionStore = openBrokerSessionStore(args.storageRoot);
+    try {
+        const route = resolveAgentRoute(args.config, args.workflow, args.role, args.agentOverride, args.effectiveCwd === "" ? null : args.effectiveCwd);
+        const broker = createBroker({
+            sessionStore,
+            resolveRoute: () => route,
+            clientFactory: null,
+        });
+        args.plog.log(PL_BROKER_SEND, `broker.send role=${args.role} host=${route.host} gateway=${route.gateway}`, null);
+        // Assemble the full agent prompt (output-format instruction + thread
+        // progress + role prompt + task + continuation/edge context) so the broker
+        // path sends the same context the legacy spawned-agent path did, rather than
+        // the bare edge prompt.
+        const outputSchemaHash = loadRoleSchemaHash(args.workflow, args.role);
+        const outputFormatInstruction = loadOutputFormatInstruction(args.uwf, outputSchemaHash);
+        const startNode = args.uwf.store.cas.get(args.startHash);
+        const startPrompt = startNode !== null ? startNode.payload.prompt : "";
+        const steps = collectStepContexts(args.uwf, args.prevHash);
+        const assembledPrompt = assembleBrokerPrompt({
+            workflow: args.workflow,
+            role: args.role,
+            threadId: args.threadId,
+            startPrompt,
+            steps,
+            edgePrompt: args.edgePrompt,
+            outputFormatInstruction,
+        });
+        const assembledPromptHash = (await args.uwf.store.cas.put(args.uwf.schemas.text, assembledPrompt));
+        const startedAtMs = Date.now();
+        // Phase 2 (#419): Write step-start node at entry
+        const stepStartHash = writeStepStart(args.uwf, {
+            role: args.role,
+            edgePrompt: args.edgePrompt,
+            stepIndex: steps.length,
+            prev: args.prevHash,
+            start: args.startHash,
+            startedAtMs,
+            cwd: args.effectiveCwd,
+        });
+        // Set the active-step var so other processes can detect in-flight state
+        setActiveStep(args.uwf.store, args.threadId, stepStartHash);
+        // Start-of-step clear (Phase 2, #398): a crash-rerun is a fresh attempt, so
+        // any residual active var from a failed prior attempt is dropped here —
+        // before any onTurn can fire — rather than appended onto. The clear is
+        // start-of-step only (NOT per-send): frontmatter retries below re-send on
+        // the cached session and must keep appending to the same attempt's var.
+        clearActiveTurns(args.uwf.store, args.threadId, args.role);
+        // Phase 2 (#419): makeOnTurn now writes turns with prev+owner chain
+        const { onTurn, getTurnCount } = makeOnTurn(args.uwf, args.threadId, stepStartHash);
+        const primary = await broker.send({
+            threadId: args.threadId,
+            role: args.role,
+            prompt: assembledPrompt,
+            onTurn,
+        });
+        // Suspend gate (issue #435, Phase 2): a broker `kind:"suspended"` result
+        // means the Sumeru send hit a timeout and emitted RFC #95 `suspend`. Route
+        // it through the existing `$SUSPEND` exit BEFORE any frontmatter work —
+        // suspend is a human gate, never retried, never an error. TypeScript's
+        // discriminated union forces this narrow before any `primary.output` read.
+        if (primary.kind === "suspended") {
+            return writeSuspendedStep({
+                uwf: args.uwf,
+                threadId: args.threadId,
+                suspend: {
+                    reason: primary.reason,
+                    nativeId: primary.nativeId,
+                    elapsedMs: primary.elapsedMs,
+                },
+                sessionId: primary.sessionId,
+                turnCount: getTurnCount(),
+                startHash: args.startHash,
+                prevHash: args.prevHash,
+                role: args.role,
+                agentName: route.gateway,
+                edgePrompt: args.edgePrompt,
+                startedAtMs,
+                completedAtMs: Date.now(),
+                cwd: args.effectiveCwd,
+                assembledPromptHash,
+                previousAttempts: args.previousAttempts,
+            });
+        }
+        let extracted = await tryExtract(args.uwf, primary.output, outputSchemaHash);
+        let accumulatedUsage = brokerUsage(primary);
+        let lastOutput = primary.output;
+        let lastSessionId = primary.sessionId;
+        // Retry on the same (threadId, role) — the broker re-uses the cached
+        // Sumeru session, so the agent gets to "fix its frontmatter" with full
+        // context preserved. Retries carry the same onTurn and keep appending to
+        // the same attempt's active var (no clear between retries).
+        for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && extracted === null; retry++) {
+            const correctionPrompt = buildFrontmatterRetryPrompt(outputFormatInstruction);
+            log(PL_FRONTMATTER_RETRY, `frontmatter retry ${retry + 1}/${MAX_FRONTMATTER_RETRIES} thread=${args.threadId} role=${args.role}`);
+            const retryResult = await broker.send({
+                threadId: args.threadId,
+                role: args.role,
+                prompt: correctionPrompt,
+                onTurn,
+            });
+            // A retry can itself time out — honor the same suspend gate rather than
+            // dereferencing `retryResult.output` on a suspended result.
+            if (retryResult.kind === "suspended") {
+                return writeSuspendedStep({
+                    uwf: args.uwf,
+                    threadId: args.threadId,
+                    suspend: {
+                        reason: retryResult.reason,
+                        nativeId: retryResult.nativeId,
+                        elapsedMs: retryResult.elapsedMs,
+                    },
+                    sessionId: retryResult.sessionId,
+                    turnCount: getTurnCount(),
+                    startHash: args.startHash,
+                    prevHash: args.prevHash,
+                    role: args.role,
+                    agentName: route.gateway,
+                    edgePrompt: args.edgePrompt,
+                    startedAtMs,
+                    completedAtMs: Date.now(),
+                    cwd: args.effectiveCwd,
+                    assembledPromptHash,
+                    previousAttempts: args.previousAttempts,
+                });
+            }
+            lastOutput = retryResult.output;
+            lastSessionId = retryResult.sessionId;
+            accumulatedUsage = mergeUsage(accumulatedUsage, brokerUsage(retryResult));
+            extracted = await tryExtract(args.uwf, lastOutput, outputSchemaHash);
+        }
+        const completedAtMs = Date.now();
+        // Phase 2 (#419): Pass turn count to detail (no longer from active var)
+        const detailHash = await storeBrokerDetail(args.uwf, { ...primary, output: lastOutput, sessionId: lastSessionId }, args.threadId, args.role, startedAtMs, completedAtMs, getTurnCount());
+        // Phase 2 (#419): Clear active-step var on completion
+        clearActiveStep(args.uwf.store, args.threadId);
+        if (extracted === null) {
+            log(PL_FRONTMATTER_FAIL, `frontmatter extraction failed after ${MAX_FRONTMATTER_RETRIES} retries thread=${args.threadId} role=${args.role}`);
+            const errorMessage = "Agent output does not contain valid YAML frontmatter matching the role schema " +
+                `after ${MAX_FRONTMATTER_RETRIES} retries.\n` +
+                `Raw output (first 500 chars): ${lastOutput.slice(0, 500)}`;
+            const errorPayload = {
+                $status: "error",
+                error: errorMessage,
+                phase: "frontmatter_extraction",
+            };
+            const errorOutputHash = await args.uwf.store.cas.put(args.uwf.schemas.errorOutput, errorPayload);
+            const failedStepHash = await writeBrokerStepNode({
+                uwf: args.uwf,
+                startHash: args.startHash,
+                prevHash: args.prevHash,
+                role: args.role,
+                outputHash: errorOutputHash,
+                detailHash,
+                agentName: route.gateway,
+                edgePrompt: args.edgePrompt,
+                startedAtMs,
+                completedAtMs,
+                cwd: args.effectiveCwd,
+                assembledPromptHash,
+                usage: accumulatedUsage,
+                previousAttempts: null,
+            });
+            return {
+                stepHash: failedStepHash,
+                detailHash,
+                role: args.role,
+                frontmatter: { $status: "error" },
+                body: "",
+                startedAtMs,
+                completedAtMs,
+                usage: accumulatedUsage,
+                isError: true,
+                errorMessage,
+            };
+        }
+        const stepHash = await writeBrokerStepNode({
+            uwf: args.uwf,
+            startHash: args.startHash,
+            prevHash: args.prevHash,
+            role: args.role,
+            outputHash: extracted.outputHash,
+            detailHash,
+            agentName: route.gateway,
+            edgePrompt: args.edgePrompt,
+            startedAtMs,
+            completedAtMs,
+            cwd: args.effectiveCwd,
+            assembledPromptHash,
+            usage: accumulatedUsage,
+            previousAttempts: args.previousAttempts,
+        });
+        return {
+            stepHash,
+            detailHash,
+            role: args.role,
+            frontmatter: extracted.frontmatter,
+            body: extracted.body,
+            startedAtMs,
+            completedAtMs,
+            usage: accumulatedUsage,
+            isError: false,
+            errorMessage: null,
+        };
+    }
+    finally {
+        sessionStore.close();
+    }
+}
+function brokerUsage(result) {
+    // Sumeru's `done` event reports per-exchange usage. Normalize into the
+    // engine's Usage shape so `mergeUsage` can sum across retries. A suspended
+    // result has no `done` (the discriminated union enforces this narrow) — a
+    // timeout carries no usage summary.
+    if (result.kind !== "completed") {
+        return null;
+    }
+    const done = result.done;
+    if (done === null || typeof done !== "object") {
+        return null;
+    }
+    const turns = done.turnCount;
+    const inputTokens = done.tokens !== null ? done.tokens.in : 0;
+    const outputTokens = done.tokens !== null ? done.tokens.out : 0;
+    const duration = done.durationMs;
+    return { turns, inputTokens, outputTokens, duration };
+}
+//# sourceMappingURL=broker-step.js.map