7.7 KiB
The Execution engine
Status: needs-triage
The design for iteration 1. Vocabulary is in CONTEXT.md; the decisions are ADR-0001 and ADR-0002. The plan across both repositories is ../tom_analysis/IMPLEMENTATION_PLAN.md.
What it is
A package, execution_engine, that holds one Execution of any Workflow. It is the Reference's engine with everything about cloud solution architecture taken out and passed in.
It keeps the Reference's decisions unchanged:
- A LangGraph state graph holds the Execution, checkpoints after every step and interrupts when the user must answer or approve.
- Every agent runs behind one agent-runtime interface; the ADK runtime is the first implementation and the only module that imports
google.adk. - The Orchestrator is a router: readings, a disposition by threshold, a playbook in code, with Jev for the judgements and a fallback for each.
- The Ledger refuses what Dependencies, Approvals and the Revision limit do not allow, whatever was decided.
- Behaviour lives in Skills, assigned to roles by a provider bundle.
The Workflow
One value, given to the engine when an agent is assembled.
Built on 2026-10-13. execution_engine/workflows/workflow.py is now the definition; the sketch below is the design it was built from, and differs from it in names and in a few parts added while building. .agents/plans/iter-01-execution-engine/steps/step-3.md lists the parts as built.
@dataclass(frozen=True)
class Workflow:
name: str
about: str # what intake says this agent does
phases: tuple[str, ...] # in order
deliverables: Mapping[
str, DeliverableSpec
] # kind -> phase, specialist, depends_on,
# sections, attachments, reads_in_full,
# not_shown, working_copy, written_from
final: str # the Deliverable handed over as the result
data_checks: Mapping[
str, DataCheck
] = {} # kind -> (data file, check on submission)
for_readers: Mapping[str, str] = {} # sections code adds for a person
on_submit: Mapping[str, SubmitHook] = {} # what code adds to a submission
validation: ValidationPolicy | None = None
approval_facts: ApprovalFacts | None = None # (phase, deliverables) -> facts
fan_out: Mapping[str, FanOut] = {} # kind -> the further agents it consults
roles: tuple[str, ...] = () # required beyond one per Deliverable
local_tools: LocalTools | None = None # (bundle, settings) -> tools by tier
reviews: Mapping[str, SubmissionReview] = {} # kind -> a review before acceptance
options: Mapping[str, OptionSpec] = {} # per-Execution options a caller may set
manifest: ManifestEntries | None = None # state -> entries for execution.json
response: Response | None = None # state -> the one-shot reply
card: CardText | None = None
spec: SpecSupport | None = None # catalogue, digest adapters, its name
samples: Mapping[
str, Sample
] = {} # a passing submission per kind, for the fake runtime
Deliverable kinds and Phase ids are strings. A Workflow may write them as a StrEnum of its own; the engine sees strings, which is what state and storage already hold.
What each part replaces in the Reference
| Part | In the Reference | Notes |
|---|---|---|
phases, deliverables, data_checks, for_readers |
workflows/deliverables.py |
Data. inputs_of, dependencies_for, shown and check_submission stay in the engine and take the Workflow |
on_submit |
tools/execution.py 320–413 |
A hook receives the submission and what it builds on, and returns added content, added attachments and working memory. The Reference's are: tables and a diagram for the graph, the checklist review, the rendered plan, the scope's files |
validation |
router.py 161, 313–344, 631–652 |
Names the validation Deliverable and gives two functions: its data to failed Check ids, and a failure to the Deliverable to reopen. Without one, the playbook's validation group never applies |
approval_facts |
router.py 747–826 |
Facts only. The reply writer still writes the summary, and the assembled fallback still exists |
fan_out |
execution_nodes.py 1016, toolkit.py 81, tools/pillars.py |
The Reference's pillar advisors. Declares the consulting role, the list of parts with a Skill each, and how advice is kept between attempts |
final, manifest, response |
execution_nodes.py 1145, 1376–1449; a2a_server.py 178; presentation.py |
|
roles, local_tools, reviews |
adk/roles.py, agent.py |
The engine always requires the Orchestrator and the reply writer |
options |
terraform_modules in state, in the manifest and in baseline.py |
A named per-Execution option with a default, carried into a Change request from its Baseline |
spec |
scope.py, tools/scoping.py, the bundle's scope section |
Step 6 |
samples |
adk/fake_runtime.py |
The fake runtime's sample submissions are the Reference's Deliverables today |
Settings and paths
Settingsholds the engine's settings only. A Workflow brings a settings class of its own for the rest; in the Reference these are the Terraform settings and the coverage and requirements reviews.- The Reference resolves its bundle, Skills and role files from the package's own location. An agent gives its root; an installed engine has no files of its own there.
- The provider bundle keeps what every Workflow needs: Skills, models, tools by tier, MCP servers, role Skills, the lessons Skill. Sections only one Workflow reads, such as
terraformandpillar_skills, are read by that Workflow from the bundle's remaining keys.
The steps
| Step | Brings or builds |
|---|---|
| 2 | The modules that import nothing about a subject. Done |
| 3 | states/ledger, recorder, adk/fake_runtime, adk/roles, states/lessons, nodes/intake, nodes/router, nodes/execution_nodes, tools/execution, tools/toolkit, tools/scoping, tools/meaning, workflows/execution_graph, the generic half of workflows/deliverables, the scheduler from workflows/work_breakdown, learning/curator, learning/evidence, agent, a2a_server, card, main. Each is brought, then changed to take the Workflow. config and providers lose what belongs to a Workflow |
| 4 | Built with four Deliverables in three Phases; see steps/step-4.md. As designed: a toy Workflow under tests/: three Deliverables in two Phases, one with a data check, one with a submit hook, a validation policy. The Reference's engine tests (test_engine, test_ledger, test_router, test_intake, test_change_requests, test_working_copy, a2a/test_server) are brought and re-pointed at it |
| 5 | The Reference's workflow under tests/reference_workflow/: its deliverables, chain, target_architecture, changes, the Element rule of work_breakdown, and its hooks, written as a Workflow. Its tests (test_deliverables, test_requirements_chain, test_work_breakdown, test_pillars) are brought |
| 6 | The digest step |
| 7 | The container build |
Steps 3 and 4 are one piece of work: a module is not finished being changed until the toy Workflow runs through it.
Not in this iteration
- The Orchestration engine. It is iteration 2 and shares only the Jev client and the A2A plumbing with this package.
- The Reference's Skills, role files, provider bundle and evaluation cases. Step 5 runs its workflow on the fake runtime only.
- The evaluation harness. It is brought when the first agent on this engine needs it.
Open
- How an agent's container build obtains this package (step 7). A dependency on this repository at a pinned commit, with a build secret for access; a package registry; or a submodule. The owner's choice.
- Where the shared role files and the Specialist protocol live. They are text, not code. Either package data here, or copied into each agent.