Files

7.7 KiB
Raw Permalink Blame History

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

  • Settings holds 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 terraform and pillar_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.