Surface per-iteration / per-region step logs in run observability (ADR-0031 follow-up)

Follow-up to ADR-0031 / #1479 (now complete).

AutomationEngine.runRegion() (the executor for the loop body, parallel branches, and try_catch regions) currently runs each region against a region-local StepLogEntry[] that is not merged into the parent run's step log. There's a TODO(#1479) marking this in packages/services/service-automation/src/engine.ts:

// TODO(#1479): merge region step logs into the parent run log so
// per-iteration body steps surface in run observability.
const regionSteps: StepLogEntry[] = [];

Impact

Run logs (listRuns / getRun) show the container node (loop/parallel/try_catch) as a single step, but not the body/branch/handler steps that executed inside it, nor per-iteration detail for loops. This is a gap for debugging and audit.

Scope

Thread the parent steps array (or a child grouping) into runRegion so body steps are recorded.
Decide on representation: flat append vs nested/grouped (e.g. parentNodeId + iteration index on each entry) so a loop's N iterations are distinguishable.
Extend StepLogEntry if grouping metadata is needed; update engine.test.ts accordingly.
Mind concurrency for parallel branches (single-threaded JS, but interleaved at await points — appends must stay consistent).

Executors don't currently receive the steps array, so this is a deliberate engine-level change.

docs(adr): mark ADR-0031 Accepted (implemented) (#1506)

feat(automation): surface structured-region body steps in run observa…

Both halves of this are now landed:

Engine (this repo, already on main): AutomationEngine.runRegion() returns each region's body steps and the container executor folds them into the run log via NodeExecutionResult.childSteps, tagged with parentNodeId / iteration / regionKind (ExecutionStepLogSchema). The loop / parallel / try_catch executors populate childSteps, and getRun / listRuns pass the fields through untouched. (ADR-0031 already records this as done.)
Observability UI: feat(studio): nest per-iteration / per-region step logs in the flow Runs panel (#1505) objectui#2667 (merged) — FlowRunsPanel reconstructs the execution tree from the flat, pre-order step log (buildStepTree) and nests per-iteration / per-branch / handler body steps under their container node (Iteration N / Branch N / Try / Catch), robust to repeated node ids and nested regions.

Every item in the original scope is covered: parent steps threaded into runRegion; parentNodeId + iteration-index representation; StepLogEntry extended with grouping metadata + tests; parallel-branch append consistency (each branch collects its own region-local array, joined in order via Promise.all).

One durable-history edge case spun out to #3234 (a long loop's compactStepsForHistory tail-slice can drop the container + early iterations from persisted history). Closing this as completed.

Generated by Claude Code

docs(automation): correct run-history durability + region-step nestin…

fix(automation): region-aware run-history compaction keeps loop conta…

Navigation Menu

Repository navigation

Surface per-iteration / per-region step logs in run observability (ADR-0031 follow-up) #1505

Impact

Scope

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Surface per-iteration / per-region step logs in run observability (ADR-0031 follow-up) #1505

Description

Impact

Scope

Activity

os-zhuang commented on Jul 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions