104 lines
7.7 KiB
Markdown
104 lines
7.7 KiB
Markdown
# 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.
|
||
|
||
```python
|
||
@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.
|