@acpus/runtime 0.5.1 → 0.6.1

package/dist/interpreter.js

@@ -1,4 +1,4 @@
-import { parseDurationMs, compileWorkflow, hashIrNode } from "@acpus/core";
+import { parseDurationMs, compileWorkflow, hashIrNode, realPathOrUndefined } from "@acpus/core";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { ExpressionEvaluator } from "./evaluator.js";
@@ -15,6 +15,11 @@ import { randomBytes } from "node:crypto";
 import pLimit from "p-limit";
 import { AgentTelemetryAccumulator, upsertAgentAttemptTelemetry } from "./agent-telemetry.js";
 import { buildWorkflowExpressionContext } from "./workflow-context.js";
+import { HookFailureError } from "./hooks/runner.js";
+import { HookJournal } from "./hooks/journal.js";
+import { basePayload, runScope, withNodeFields } from "./hooks/payload.js";
+import { isRunTerminal } from "./types.js";
+import { join } from "node:path";
 /**
  * The core IR interpreter that drives state transitions, orchestrates
  * execution, and persists state.
@@ -28,8 +33,18 @@ export class WorkflowInterpreter {
     attemptArtifacts;
     runControl;
     maxConcurrency;
-    allowedSourceRoots;
     sleep;
+    /** Frozen hook runner for this Run; undefined disables all hook machinery. */
+    hookRunner;
+    /** Lazily-created per-Run injector journal (only when injectors fire). */
+    hookJournal;
+    /**
+     * Per-node leaf execution metadata for hook onNodeComplete/Error payloads,
+     * keyed by node key. Populated by executeProgram/executeAgent and deleted by
+     * executeNode once the node's terminal lifecycle events have fired, so the map
+     * never accumulates across a long-lived Run.
+     */
+    leafMeta = new Map();
     /** Pending external-decision resolvers for Signal Nodes awaiting a payload,
      *  keyed by "runId:nodeKey". An entry exists only while a node is `awaiting`.
      *  The resolver validates the payload against the node's output schema and
@@ -46,8 +61,8 @@ export class WorkflowInterpreter {
         this.attemptArtifacts = new AttemptArtifactRecorder(this.artifactStore);
         this.runControl = new RunControl(store);
         this.maxConcurrency = options?.maxConcurrency ?? 10;
-        this.allowedSourceRoots = options?.allowedSourceRoots?.map((root) => resolve(root)) ?? [];
         this.sleep = options?.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.hookRunner = options?.hookRunner;
     }
     /**
      * Start a new workflow run to completion (init + execute). Convenience for
@@ -68,7 +83,8 @@ export class WorkflowInterpreter {
             workflowRef: opts.workflowRef,
             workflowSourcePath: opts.workflowSourcePath,
             agentOverrides: opts.agentOverrides,
-            submissionWarnings: opts.submissionWarnings
+            submissionWarnings: opts.submissionWarnings,
+            skipHooks: opts.skipHooks
         });
     }
     /**
@@ -76,6 +92,18 @@ export class WorkflowInterpreter {
      */
     async runToCompletion(ir, opts, runId) {
         const meta = this.store.readRunMeta(runId);
+        const scope = this.hookRunner ? runScope(ir, meta) : undefined;
+        // `beforeRun` fires only at the first execution entry (no node states yet),
+        // never on retry/resume where the Run is already underway.
+        const isFirstExecution = this.store.listNodeStates(runId).length === 0;
+        if (scope && isFirstExecution) {
+            await this.emitRunEvent("beforeRun", scope, (p) => {
+                p.input = opts.input;
+                p.run_attempt = meta.runAttempt;
+                p.ir_digest = meta.irDigest;
+            });
+        }
+        const runStartedAt = Date.now();
         try {
             const ctx = this.buildContext(ir, opts.input, runId);
             await this.executeNode(ir.root, ctx, runId, {});
@@ -110,6 +138,19 @@ export class WorkflowInterpreter {
         }
         meta.updatedAt = new Date().toISOString();
         this.store.writeRunMeta(runId, meta);
+        // `afterRun` fires once the Run reaches a terminal status.
+        if (scope && isRunTerminal(meta.status)) {
+            await this.emitRunEvent("afterRun", scope, (p) => {
+                p.run_status = meta.status;
+                p.run_attempt = meta.runAttempt;
+                p.ir_digest = meta.irDigest;
+                p.duration_ms = Date.now() - runStartedAt;
+                if (meta.output !== undefined)
+                    p.output = meta.output;
+                if (meta.error !== undefined)
+                    p.error = meta.error;
+            });
+        }
         return meta;
     }
     /**
@@ -366,6 +407,7 @@ export class WorkflowInterpreter {
         const controller = new AbortController();
         this.runControl.registerAbortController(runId, nodeKey, controller);
         // Transition to running
+        const fromState = state.state;
         if (canTransition(state.state, "running")) {
             state.state = transition(state.state, "running");
         }
@@ -381,6 +423,9 @@ export class WorkflowInterpreter {
                 state.dynamicContext = snapshot;
         }
         this.store.writeNodeState(runId, state);
+        if (fromState !== "running") {
+            await this.emitNodeLifecycle(runId, "onNodeStart", node, nodeKey, state, dynamic, ctx, fromState);
+        }
         try {
             let output;
             let completeScope = false;
@@ -450,7 +495,10 @@ export class WorkflowInterpreter {
             if (artifactRefs)
                 state.artifactRefs = artifactRefs;
             state.completedAt = new Date().toISOString();
+            // A Signal Node completes from `awaiting`, every other leaf from `running`.
+            const completeFrom = node.kind === "run.signal" ? "awaiting" : "running";
             this.store.writeNodeState(runId, state);
+            await this.emitNodeLifecycle(runId, "onNodeComplete", node, nodeKey, state, dynamic, ctx, completeFrom);
             // Add output to step context
             ctx.steps[node.id] = output;
             if (completeScope) {
@@ -477,6 +525,7 @@ export class WorkflowInterpreter {
                     state.artifactRefs = error.artifactRefs;
                 this.syncAgentTelemetryFromDisk(runId, nodeKey, state);
                 this.store.writeNodeState(runId, state);
+                await this.emitNodeLifecycle(runId, error.state === "paused" ? "onNodePaused" : "onNodeCancelled", node, nodeKey, state, dynamic, ctx, "running");
                 throw error;
             }
             // Don't clobber an external pause/cancel that landed while this node's
@@ -504,10 +553,13 @@ export class WorkflowInterpreter {
             this.syncAgentTelemetryFromDisk(runId, nodeKey, state);
             state.completedAt = new Date().toISOString();
             this.store.writeNodeState(runId, state);
+            await this.emitNodeLifecycle(runId, "onNodeError", node, nodeKey, state, dynamic, ctx, "running", error);
             throw error;
         }
         finally {
             this.runControl.clearInFlightNode(runId, nodeKey);
+            // Drop per-node leaf hook metadata so the map never grows across a Run.
+            this.clearLeafMeta(nodeKey);
         }
     }
     // ─── Kind-specific execution ───────────────────────────────────
@@ -532,6 +584,13 @@ export class WorkflowInterpreter {
         const maxRetries = typeof retry?.max === "number" ? retry.max : hasOutputSchema ? 2 : 0;
         const backoffMs = retry?.backoff ? parseDurationMs(retry.backoff) : 5e3;
         const allArtifactRefs = [...(this.store.readNodeState(runId, nodeKey)?.artifactRefs ?? [])];
+        // Run `beforeAgentExec` once per Agent Step execution (per persisted attempt),
+        // not per internal parse/schema auto-retry iteration. The returned prompt
+        // prefix is prepended to every rendered prompt below.
+        const injectedPrompt = await this.runInjector("beforeAgentExec", node, ctx, runId, nodeKey, (p) => {
+            p.agent_use = node.metadata.agent?.use;
+            p.is_continuation = Boolean(continuation);
+        });
         // `attempt` is local to this executor call and controls parse/schema
         // auto-retry. The persisted `state.attempt` is the durable attempt sequence
         // used for node state and artifact filenames across pause/resume/manual retry.
@@ -547,6 +606,9 @@ export class WorkflowInterpreter {
                 const use = node.metadata.agent?.use ?? "?";
                 throw new LeafExecutionError(`Agent step '${node.id}' (use: ${use}) failed (config): Failed to evaluate agent configuration template: ${error instanceof Error ? error.message : String(error)}`);
             }
+            if (injectedPrompt?.prependPrompt) {
+                preparedPrompt = `${injectedPrompt.prependPrompt}\n\n${preparedPrompt}`;
+            }
             const rawAcpDebug = process.env.ACPUS_AGENT_RAW_ACP_DEBUG === "1";
             const liveArtifacts = this.attemptArtifacts.startAgentAttempt(runId, nodeKey, attemptNo, preparedPrompt, { rawAcpDebug });
             this.attemptArtifacts.mergeAttemptRefs(allArtifactRefs, liveArtifacts.artifactRefs);
@@ -649,6 +711,19 @@ export class WorkflowInterpreter {
                     await this.sleep(backoffMs);
                 continue;
             }
+            // Stash agent detail for hook onNodeComplete/Error payloads (terminal attempt).
+            if (this.hookRunner) {
+                const agent = node.metadata.agent;
+                this.leafMeta.set(nodeKey, {
+                    failureKind: result.failureKind,
+                    agentModel: agent?.model,
+                    agentType: agent?.type,
+                    agentPolicy: node.metadata.policy ?? agent?.policy,
+                    sessionKey: renderedSessionKey,
+                    agentExitCode: result.exitCode,
+                    agentResponseText: result.responseText
+                });
+            }
             if (result.failureKind || (result.error && !result.partial)) {
                 const use = node.metadata.agent?.use ?? "?";
                 throw new LeafExecutionError(`Agent step '${node.id}' (use: ${use}) failed${result.failureKind ? ` (${result.failureKind})` : ""}: ${result.error ?? "unknown"}`, allArtifactRefs.length > 0 ? allArtifactRefs : artifactRefs, result.output);
@@ -661,7 +736,29 @@ export class WorkflowInterpreter {
         }
     }
     async executeProgram(node, ctx, runId, signal, nodeKey) {
-        const result = await this.programExecutor.execute({ node, context: ctx, signal, nodeKey });
+        // Run `beforeProgramExec` before the executor call. cmd/env render inside
+        // the executor, so injected env is passed through ExecutionRequest and the
+        // executor merges it into the subprocess environment.
+        const injected = await this.runInjector("beforeProgramExec", node, ctx, runId, nodeKey);
+        const result = await this.programExecutor.execute({
+            node,
+            context: ctx,
+            signal,
+            nodeKey,
+            injectedEnv: injected?.env
+        });
+        // Stash rendered command/env/output for hook onNodeComplete/Error payloads.
+        if (this.hookRunner) {
+            this.leafMeta.set(nodeKey, {
+                failureKind: result.failureKind,
+                command: result.command,
+                shell: result.shell,
+                subprocessEnv: result.subprocessEnv,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr
+            });
+        }
         // Operator abort → paused/cancelled (carry output on the abort error).
         if (result.partial) {
             throw new NodeAbortedError(nodeKey, this.runControl.abortIntent(runId, nodeKey), undefined, result.output);
@@ -1026,8 +1123,11 @@ export class WorkflowInterpreter {
         // machine); a signal payload resolves it, a cancel aborts it.
         const enterState = this.store.readNodeState(runId, nodeKey);
         if (enterState && canTransition(enterState.state, "awaiting")) {
+            const from = enterState.state;
             enterState.state = transition(enterState.state, "awaiting");
             this.store.writeNodeState(runId, enterState);
+            // Surface the running → awaiting transition to onStateChange observers.
+            await this.emitNodeLifecycle(runId, "onStateChange", node, nodeKey, enterState, this.dynamicFromCtx(ctx), ctx, from);
         }
         return new Promise((resolve, reject) => {
             const onAbort = () => {
@@ -1094,20 +1194,20 @@ export class WorkflowInterpreter {
         const parentIr = this.store.readIr(runId);
         const baseDir = parentIr?.source.path ? dirname(parentIr.source.path) : process.cwd();
         const childAbs = resolve(baseDir, specPath);
-        this.assertAllowedSourcePath(childAbs, `Subworkflow path '${specPath}' resolves outside allowed Workflow Spec roots`);
-        // Cycle guard across nested subworkflows.
-        if (this.subworkflowStack.has(childAbs)) {
-            throw new Error(`Subworkflow cycle detected for '${childAbs}'`);
+        const childReal = this.resolveExistingSourcePath(childAbs, `Subworkflow path '${specPath}' does not exist or is not readable`);
+        // Cycle guard across nested subworkflows (uses real path).
+        if (this.subworkflowStack.has(childReal)) {
+            throw new Error(`Subworkflow cycle detected for '${specPath}'`);
         }
         // Compile the child spec at runtime (file I/O lives in the runtime layer).
-        const source = readFileSync(childAbs, "utf8");
+        const source = readFileSync(childReal, "utf8");
         const compiled = compileWorkflow(source, {
-            sourcePath: childAbs,
+            sourcePath: childReal,
             includeResolver: (includePath, fromPath) => {
                 const dir = fromPath ? dirname(resolve(fromPath)) : process.cwd();
                 const includeAbs = resolve(dir, includePath);
-                this.assertAllowedSourcePath(includeAbs, `Include path '${includePath}' resolves outside allowed Workflow Spec roots`);
-                return readFileSync(includeAbs, "utf8");
+                const includeReal = this.resolveExistingSourcePath(includeAbs, `Include path '${includePath}' does not exist or is not readable`);
+                return readFileSync(includeReal, "utf8");
             }
         });
         if (!compiled.ok || !compiled.ir) {
@@ -1124,22 +1224,22 @@ export class WorkflowInterpreter {
         const validatedChildInput = validateInput(compiled.ir.input, childInput);
         // Execute the child root as a nested pipeline. Child node keys are nested
         // under this subworkflow's node key to stay unique within the run.
-        this.subworkflowStack.add(childAbs);
+        this.subworkflowStack.add(childReal);
         try {
             const childCtx = this.buildContext(compiled.ir, validatedChildInput, runId);
             await this.executeNode(compiled.ir.root, childCtx, runId, dynamic, nodeKey);
             return { output: evaluateWorkflowOutputs(compiled.ir, childCtx, this.evaluator) };
         }
         finally {
-            this.subworkflowStack.delete(childAbs);
+            this.subworkflowStack.delete(childReal);
         }
     }
-    assertAllowedSourcePath(path, message) {
-        if (this.allowedSourceRoots.length === 0)
-            return;
-        if (this.allowedSourceRoots.some((root) => path === root || path.startsWith(root + "/")))
-            return;
-        throw new Error(message);
+    resolveExistingSourcePath(path, message) {
+        const realPath = realPathOrUndefined(path);
+        if (realPath === undefined) {
+            throw new Error(message);
+        }
+        return realPath;
     }
     // ─── Helpers ────────────────────────────────────────────────────
     buildContext(ir, input, runId) {
@@ -1226,6 +1326,230 @@ export class WorkflowInterpreter {
         }
         return String(index ?? 0);
     }
+    // ─── Hook integration ───────────────────────────────────────────
+    /** Run scope for the active Run, derived from the frozen IR + metadata. */
+    resolveRunScope(runId) {
+        if (!this.hookRunner)
+            return undefined;
+        const ir = this.store.readIr(runId);
+        const meta = this.store.readRunMeta(runId);
+        if (!ir || !meta)
+            return undefined;
+        return runScope(ir, meta);
+    }
+    /** Lazily create the per-Run injector journal. */
+    journalFor(runId) {
+        if (!this.hookJournal) {
+            this.hookJournal = new HookJournal(join(this.store.getBaseDir(), runId));
+        }
+        return this.hookJournal;
+    }
+    /**
+     * Run an injector for a node, journaling each handler invocation. Returns the
+     * merged InjectorResult, or undefined when no hook runner / no handlers.
+     * An injector failure under `fail` policy propagates as HookFailureError,
+     * which executeNode maps to a node failure with failureKind hook_failure.
+     */
+    async runInjector(name, node, ctx, runId, nodeKey, enrich) {
+        if (!this.hookRunner || !this.hookRunner.hasInjector(name))
+            return undefined;
+        const scope = this.resolveRunScope(runId);
+        if (!scope)
+            return undefined;
+        const state = this.store.readNodeState(runId, nodeKey);
+        const nodeAttempt = state?.attempt ?? 1;
+        const isRetry = nodeAttempt > 1;
+        const payload = withNodeFields(basePayload(scope, name), node, nodeKey, state, this.dynamicFromCtx(ctx), ctx);
+        payload.is_retry = isRetry;
+        // Note: `beforeAgentExec` runs before the prompt is rendered, so we do NOT
+        // surface state.renderedPrompt here — it would be absent on first execution
+        // and stale on retry. The rendered prompt is carried by lifecycle events.
+        enrich?.(payload);
+        const journal = this.journalFor(runId);
+        return this.hookRunner.runInjector(name, payload, (handlerIndex, result, durationMs) => {
+            journal.append({
+                node_key: nodeKey,
+                injector: name,
+                handler_index: handlerIndex,
+                node_attempt: nodeAttempt,
+                is_retry: isRetry,
+                prepend_prompt: name === "beforeAgentExec" ? (result.prependPrompt ?? null) : null,
+                env: result.env ?? null,
+                timestamp: new Date().toISOString(),
+                duration_ms: durationMs
+            });
+        });
+    }
+    /** Fire a node lifecycle event plus onStateChange for an actual transition. */
+    async emitNodeLifecycle(runId, name, node, nodeKey, state, dynamic, ctx, fromState, error) {
+        if (!this.hookRunner)
+            return;
+        const firesSpecific = this.hookRunner.hasEvent(name);
+        const firesStateChange = this.hookRunner.hasEvent("onStateChange");
+        if (!firesSpecific && !firesStateChange)
+            return;
+        const scope = this.resolveRunScope(runId);
+        if (!scope)
+            return;
+        const hookFailure = error instanceof HookFailureError;
+        const build = (eventName) => {
+            const p = withNodeFields(basePayload(scope, eventName), node, nodeKey, state, dynamic, ctx);
+            if (state.output !== undefined)
+                p.output = state.output;
+            if (state.startedAt && state.completedAt) {
+                p.duration_ms = Date.parse(state.completedAt) - Date.parse(state.startedAt);
+            }
+            // beforeAgentExec aside, lifecycle events carry the rendered prompt.
+            if (state.renderedPrompt)
+                p.prompt = state.renderedPrompt;
+            if (state.renderedSessionKey)
+                p.session_key = state.renderedSessionKey;
+            if (node.kind === "run.agent") {
+                const telemetry = hookAgentTelemetry(state);
+                if (telemetry)
+                    p.agent_telemetry = telemetry;
+            }
+            if (error !== undefined)
+                p.error = error instanceof Error ? error.message : String(error);
+            this.fillParentFields(runId, node, nodeKey, p);
+            fillCompositeFields(node, p);
+            const leaf = this.leafMeta.get(nodeKey);
+            if (leaf) {
+                if (leaf.failureKind !== undefined)
+                    p.failure_kind = leaf.failureKind;
+                // Program detail.
+                if (leaf.command !== undefined)
+                    p.command = leaf.command;
+                if (leaf.shell !== undefined)
+                    p.shell = leaf.shell;
+                if (leaf.subprocessEnv !== undefined)
+                    p.subprocess_env = leaf.subprocessEnv;
+                if (leaf.exitCode !== undefined)
+                    p.exit_code = leaf.exitCode;
+                if (leaf.stdout !== undefined)
+                    p.stdout = leaf.stdout;
+                if (leaf.stderr !== undefined)
+                    p.stderr = leaf.stderr;
+                // Agent detail.
+                if (leaf.agentModel !== undefined)
+                    p.agent_model = leaf.agentModel;
+                if (leaf.agentType !== undefined)
+                    p.agent_type = leaf.agentType;
+                if (leaf.agentPolicy !== undefined)
+                    p.agent_policy = leaf.agentPolicy;
+                if (leaf.sessionKey !== undefined)
+                    p.session_key = leaf.sessionKey;
+                if (leaf.agentExitCode !== undefined)
+                    p.agent_exit_code = leaf.agentExitCode;
+                if (leaf.agentResponseText !== undefined)
+                    p.agent_response_text = leaf.agentResponseText;
+            }
+            else if (hookFailure) {
+                // A node that failed because an injector failed under `fail` policy.
+                p.failure_kind = "hook_failure";
+            }
+            return p;
+        };
+        // The specific lifecycle event (onNodeStart/Complete/... ); onStateChange is
+        // never emitted via this branch — it always carries from/to below.
+        if (firesSpecific && name !== "onStateChange")
+            await this.hookRunner.emitEvent(name, build(name));
+        // onStateChange only fires when the state field actually changed.
+        if (firesStateChange && fromState !== state.state) {
+            const p = build("onStateChange");
+            p.from_state = fromState;
+            p.to_state = state.state;
+            await this.hookRunner.emitEvent("onStateChange", p);
+        }
+    }
+    /** Fire a run-level event (beforeRun / afterRun). */
+    async emitRunEvent(name, scope, enrich) {
+        if (!this.hookRunner || !this.hookRunner.hasEvent(name))
+            return;
+        const payload = basePayload(scope, name);
+        enrich(payload);
+        await this.hookRunner.emitEvent(name, payload);
+    }
+    /** Recover the dynamic key dimensions from an expression context. */
+    dynamicFromCtx(ctx) {
+        const dynamic = {};
+        if (ctx.loop?.iter !== undefined)
+            dynamic.loopRound = ctx.loop.iter;
+        if (ctx.item_id !== undefined)
+            dynamic.fanoutItemId = ctx.item_id;
+        return dynamic;
+    }
+    /**
+     * Populate parent_node_key/parent_node_kind from the Run's frozen IR. The
+     * parent's resolved key shares this node's dynamic prefix, so we map the
+     * static parent path onto the dynamic portion of the child key.
+     */
+    fillParentFields(runId, node, nodeKey, payload) {
+        const ir = this.store.readIr(runId);
+        if (!ir)
+            return;
+        const parent = findParentNode(ir.root, node.id);
+        if (!parent || parent.id === ir.root.id && parent.kind === "pipeline") {
+            // The workflow root is an implicit container; only surface real parents.
+            if (!parent || parent.nodePath.length === 0)
+                return;
+        }
+        if (!parent)
+            return;
+        payload.parent_node_kind = parent.kind;
+        // The child static path is parent path + child id; the parent's resolved key
+        // is the child key with the trailing static `/childId` segment removed.
+        const childStatic = staticNodePathFromKey(nodeKey);
+        const childIdSeg = `/${node.id}`;
+        if (childStatic.endsWith(childIdSeg)) {
+            const idx = nodeKey.lastIndexOf(childIdSeg);
+            if (idx > 0)
+                payload.parent_node_key = nodeKey.slice(0, idx);
+        }
+    }
+    /** Drop per-node leaf metadata once its terminal events have fired. */
+    clearLeafMeta(nodeKey) {
+        this.leafMeta.delete(nodeKey);
+    }
+}
+function hookAgentTelemetry(state) {
+    const telemetry = state.agentTelemetry;
+    const attempt = telemetry?.attempts.find((item) => item.attempt === telemetry.currentAttempt)
+        ?? telemetry?.attempts[telemetry.attempts.length - 1];
+    if (!attempt)
+        return undefined;
+    const result = {
+        attempt: attempt.attempt,
+        state: attempt.state,
+        updated_at: attempt.updatedAt
+    };
+    if (attempt.completedAt)
+        result.completed_at = attempt.completedAt;
+    if (attempt.context) {
+        result.context = {
+            used: attempt.context.used,
+            size: attempt.context.size,
+            updated_at: attempt.context.updatedAt
+        };
+    }
+    if (attempt.tokenUsage) {
+        result.token_usage = {
+            source: attempt.tokenUsage.source
+        };
+        if (attempt.tokenUsage.inputTokens !== undefined)
+            result.token_usage.input_tokens = attempt.tokenUsage.inputTokens;
+        if (attempt.tokenUsage.outputTokens !== undefined)
+            result.token_usage.output_tokens = attempt.tokenUsage.outputTokens;
+        if (attempt.tokenUsage.cachedReadTokens !== undefined)
+            result.token_usage.cached_read_tokens = attempt.tokenUsage.cachedReadTokens;
+        if (attempt.tokenUsage.cachedWriteTokens !== undefined)
+            result.token_usage.cached_write_tokens = attempt.tokenUsage.cachedWriteTokens;
+        if (attempt.tokenUsage.thoughtTokens !== undefined)
+            result.token_usage.thought_tokens = attempt.tokenUsage.thoughtTokens;
+        if (attempt.tokenUsage.totalTokens !== undefined)
+            result.token_usage.total_tokens = attempt.tokenUsage.totalTokens;
+    }
+    return result;
 }
 /** Generate a locally sortable run ID: yyyyMMddHHmmss + 20 uppercase hex chars. */
 export function generateRunId(now = new Date()) {
@@ -1247,6 +1571,60 @@ function nestedParallelBranchDynamic(dynamic, branchIndex) {
         parallelBranchId: dynamic.parallelBranchId === undefined ? branchId : `${dynamic.parallelBranchId}.${branchId}`
     };
 }
+/** Find the immediate parent IR node of `childId`, or undefined for the root. */
+function findParentNode(node, childId) {
+    for (const child of node.children ?? []) {
+        if (child.id === childId)
+            return node;
+        const found = findParentNode(child, childId);
+        if (found)
+            return found;
+    }
+    for (const branch of node.branches ?? []) {
+        for (const child of branch.children) {
+            if (child.id === childId)
+                return node;
+            const found = findParentNode(child, childId);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Populate composite-container-specific payload fields from node metadata. */
+function fillCompositeFields(node, p) {
+    const m = node.metadata;
+    switch (node.kind) {
+        case "parallel":
+            if (typeof m.join === "string")
+                p.join_strategy = m.join;
+            if (typeof m.max_concurrency === "number")
+                p.max_concurrency = m.max_concurrency;
+            break;
+        case "fanout":
+            if (typeof m.join === "string")
+                p.join_strategy = m.join;
+            if (typeof m.max_concurrency === "number")
+                p.max_concurrency = m.max_concurrency;
+            break;
+        case "loop":
+            if (typeof m.max_iterations === "number")
+                p.max_iterations = m.max_iterations;
+            break;
+        case "subworkflow":
+            if (typeof m.subworkflow === "string")
+                p.subworkflow_spec_path = m.subworkflow;
+            break;
+        case "run.signal":
+            if (typeof m.timeout === "string")
+                p.signal_timeout = m.timeout;
+            if (typeof m.on_timeout === "string")
+                p.signal_on_timeout = m.on_timeout;
+            break;
+        default:
+            break;
+    }
+}
 class NodeAbortedError extends Error {
     nodeKey;
     state;