Files

104 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.