Repository navigation
Surface per-iteration / per-region step logs in run observability (ADR-0031 follow-up) #1505
Description
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
stepsarray (or a child grouping) intorunRegionso 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
StepLogEntryif grouping metadata is needed; updateengine.test.tsaccordingly. - Mind concurrency for
parallelbranches (single-threaded JS, but interleaved atawaitpoints — appends must stay consistent).
Executors don't currently receive the steps array, so this is a deliberate engine-level change.
Metadata
Metadata
Assignees
Labels
No labels
Activity
docs(adr): mark ADR-0031 Accepted (implemented) (#1506)
feat(automation): surface structured-region body steps in run observa…
os-zhuang commentedon Jul 18, 2026
Both halves of this are now landed:
main):AutomationEngine.runRegion()returns each region's body steps and the container executor folds them into the run log viaNodeExecutionResult.childSteps, tagged withparentNodeId/iteration/regionKind(ExecutionStepLogSchema). Theloop/parallel/try_catchexecutors populatechildSteps, andgetRun/listRunspass the fields through untouched. (ADR-0031 already records this as done.)FlowRunsPanelreconstructs 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
stepsthreaded intorunRegion;parentNodeId+ iteration-index representation;StepLogEntryextended with grouping metadata + tests;parallel-branch append consistency (each branch collects its own region-local array, joined in order viaPromise.all).One durable-history edge case spun out to #3234 (a long loop's
compactStepsForHistorytail-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…