@acpus/runtime 0.6.0 → 0.6.1

package/dist/interpreter.d.ts

@@ -17,6 +17,17 @@ export declare class WorkflowInterpreter {
     private readonly runControl;
     private readonly maxConcurrency;
     private readonly sleep;
+    /** Frozen hook runner for this Run; undefined disables all hook machinery. */
+    private readonly hookRunner?;
+    /** Lazily-created per-Run injector journal (only when injectors fire). */
+    private 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.
+     */
+    private readonly leafMeta;
     /** 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
@@ -108,11 +119,6 @@ export declare class WorkflowInterpreter {
     private syncAgentTelemetryFromDisk;
     private executeParallel;
     private executeFanout;
-    /**
-     * Resolve fanout lanes per the wait strategy. Lanes never reject on normal
-     * failure (captured as LaneResult); only NodeAbortedError rejects, which we
-     * let propagate. Losing/excess lanes are silently consumed.
-     */
     private waitForFanout;
     private materializePendingNode;
     private executeSwitch;
@@ -141,6 +147,23 @@ export declare class WorkflowInterpreter {
     private extractNodeIdFromKey;
     private findNodeById;
     private extractItemId;
+    /** Run scope for the active Run, derived from the frozen IR + metadata. */
+    private resolveRunScope;
+    /** Lazily create the per-Run injector journal. */
+    private journalFor;
+    private runInjector;
+    private emitNodeLifecycle;
+    private emitRunEvent;
+    /** Recover the dynamic key dimensions from an expression context. */
+    private dynamicFromCtx;
+    /**
+     * 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.
+     */
+    private fillParentFields;
+    /** Drop per-node leaf metadata once its terminal events have fired. */
+    private clearLeafMeta;
 }
 /** Generate a locally sortable run ID: yyyyMMddHHmmss + 20 uppercase hex chars. */
 export declare function generateRunId(now?: Date): string;

package/dist/interpreter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../src/interpreter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../src/interpreter.ts"],"names":[],"mappings":"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"}

package/dist/interpreter.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.
@@ -29,6 +34,17 @@ export class WorkflowInterpreter {
     runControl;
     maxConcurrency;
     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,6 +62,7 @@ export class WorkflowInterpreter {
         this.runControl = new RunControl(store);
         this.maxConcurrency = options?.maxConcurrency ?? 10;
         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
@@ -66,7 +83,8 @@ export class WorkflowInterpreter {
             workflowRef: opts.workflowRef,
             workflowSourcePath: opts.workflowSourcePath,
             agentOverrides: opts.agentOverrides,
-            submissionWarnings: opts.submissionWarnings
+            submissionWarnings: opts.submissionWarnings,
+            skipHooks: opts.skipHooks
         });
     }
     /**
@@ -74,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, {});
@@ -108,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;
     }
     /**
@@ -364,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");
         }
@@ -379,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;
@@ -448,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) {
@@ -475,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
@@ -502,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 ───────────────────────────────────
@@ -530,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.
@@ -545,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);
@@ -647,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);
@@ -659,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);
@@ -1024,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 = () => {
@@ -1224,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()) {
@@ -1245,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;