This commit is contained in:
@@ -67,7 +67,7 @@ These are carried from the decision log. The numbers refer to it.
|
||||
|
||||
### Module layout
|
||||
|
||||
New code only. The current modules stay untouched until [increment 9](#build-increments).
|
||||
The engine sits in the KAB workflow-agent layout since 2026-10-06 (`.agents/plans/iter-03-kab-layout/`). The original pipeline was deleted the same day.
|
||||
|
||||
```
|
||||
agents/ # framework-neutral role files (one per role)
|
||||
@@ -75,6 +75,7 @@ agents/ # framework-neutral role files (one per rol
|
||||
requirements-analyst.md decomposer.md product-selector.md diagrammer.md
|
||||
describer.md design-advisor.md pillar-advisor.md iac-author.md
|
||||
validator.md packager.md
|
||||
partials/specialist-protocol.md
|
||||
providers/
|
||||
gcp.yaml # Cloud provider bundle
|
||||
skills/
|
||||
@@ -84,32 +85,41 @@ skills/
|
||||
cloud-discovery/SKILL.md # our tooling Skills (Agent Skills spec compliant)
|
||||
iac-validation/SKILL.md
|
||||
app/
|
||||
execution/
|
||||
deliverables.py # DeliverableKind, PhaseId, DEPENDENCY_GRAPH, contracts
|
||||
main.py # A2A server on A2A_PORT: /a2a, agent card, /health, /generate
|
||||
a2a_server.py # maps A2A tasks <-> Executions and interrupts
|
||||
agent.py # ExecutionEngine (start, resume, interaction) and open_assembly
|
||||
card.py # A2A agent card, derived from the dependency graph
|
||||
states/
|
||||
execution_state.py # ExecutionState TypedDict
|
||||
ledger.py # Ledger: Deliverable/Phase states, acceptance, Revision (pure, no I/O)
|
||||
graph.py # LangGraph StateGraph: orchestrator turn, Specialist fan-out, interrupts
|
||||
tools.py # Orchestrator and Specialist execution tools bound to the Ledger
|
||||
state.py # ExecutionState TypedDict
|
||||
recorder.py # records submissions, Approvals, Revisions, final files
|
||||
agents/
|
||||
nodes/
|
||||
execution_nodes.py # orchestrator turn, Specialist task, await user, finalize
|
||||
workflows/
|
||||
deliverables.py # DeliverableKind, PhaseId, DEPENDENCY_GRAPH, contracts
|
||||
execution_graph.py # LangGraph StateGraph wiring of the nodes
|
||||
adk/
|
||||
runtime.py # AgentRuntime protocol, RoleSpec, AgentTask, Outcome types
|
||||
roles.py # loads agents/*.md into RoleSpec
|
||||
adk_runtime.py # ADK LlmAgent + SkillToolset + LiteLlm implementation
|
||||
fake_runtime.py # scripted implementation for tests (under app/ so eval can reuse it)
|
||||
skills/
|
||||
agent_skills.py # Agent Skills discovery and frontmatter validation
|
||||
tools/
|
||||
general/ # mermaid check, terraform fmt/validate (local)
|
||||
cloud_read/ # terraform plan (local CLI, reads live state)
|
||||
execution.py # Orchestrator and Specialist execution tools bound to the Ledger
|
||||
toolkit.py # which tools each role gets
|
||||
pillars.py # the design advisor's fan-out to pillar advisors
|
||||
local.py # mermaid check, terraform fmt/validate/plan (local, tiered)
|
||||
mcp.py # McpServerSpec, read-only allowlist, tier + permission metadata
|
||||
providers.py # loads providers/<name>.yaml
|
||||
a2a/
|
||||
server.py # aiohttp A2A server on :8000, agent_card.json
|
||||
executor.py # maps A2A tasks <-> Executions and interrupts
|
||||
recorder.py # records submissions, Approvals, Revisions, status
|
||||
checkpointing.py # memory | sqlite | postgres checkpointer
|
||||
presentation.py # prompts and the /generate response
|
||||
scripts/sync-vendored-skills.sh
|
||||
```
|
||||
|
||||
### Deliverables and the dependency graph <a id="dependency-graph"></a>
|
||||
|
||||
`app/execution/deliverables.py` declares the graph as data. It is the only place Phases, Deliverables and Dependencies are listed.
|
||||
`app/workflows/deliverables.py` declares the graph as data. It is the only place Phases, Deliverables and Dependencies are listed.
|
||||
|
||||
| Phase | Deliverable kind | Specialist role | Depends on | Tools (tier) |
|
||||
|---|---|---|---|---|
|
||||
@@ -131,7 +141,7 @@ scripts/sync-vendored-skills.sh
|
||||
|
||||
### The Ledger: acceptance and Revision rules
|
||||
|
||||
`app/execution/ledger.py` is a pure module. It holds every rule code owns, and the tests exercise it heavily.
|
||||
`app/states/ledger.py` is a pure module. It holds every rule code owns, and the tests exercise it heavily.
|
||||
|
||||
- **Deliverable states:** `pending → in_progress → submitted`. Only a Revision goes backwards.
|
||||
- **Phase states:** `open → awaiting_approval → approved`. A Phase becomes `awaiting_approval` when the Orchestrator calls `request_approval` with all its Deliverables `submitted`.
|
||||
@@ -149,7 +159,7 @@ scripts/sync-vendored-skills.sh
|
||||
|
||||
### Execution graph (LangGraph)
|
||||
|
||||
`app/execution/graph.py` compiles once at startup with the configured checkpointer: `SqliteSaver` locally and in tests, `PostgresSaver` in production. The Execution id is the LangGraph `thread_id`.
|
||||
`app/workflows/execution_graph.py` wires the nodes in `app/nodes/execution_nodes.py`, and the graph compiles once at startup with the configured checkpointer: `SqliteSaver` locally and in tests, `PostgresSaver` in production. The Execution id is the LangGraph `thread_id`.
|
||||
|
||||
**State (`ExecutionState`):**
|
||||
- `execution_id`, `session_id`, `workflow_request`, `mode: "interactive" | "pre_approved"`, `allow_cloud_read: bool | None`
|
||||
@@ -182,7 +192,7 @@ await_user ───────────────────────
|
||||
- **Escalations:** end the Execution as `completed_with_warnings`.
|
||||
- **`finalize`:** runs after Phase 4 is `approved`. It writes files to `deliverables/executions/{execution_id}/`: the Solution guide, every Deliverable as markdown, and attachments under `terraform/`. It then records completion.
|
||||
|
||||
**Orchestrator tools** (`app/execution/tools.py`):
|
||||
**Orchestrator tools** (`app/tools/execution.py`):
|
||||
|
||||
| Tool | Effect |
|
||||
|---|---|
|
||||
@@ -200,7 +210,7 @@ await_user ───────────────────────
|
||||
|
||||
### Agent runtime interface
|
||||
|
||||
`app/agents/runtime.py`:
|
||||
`app/adk/runtime.py`:
|
||||
|
||||
```python
|
||||
class AgentRuntime(Protocol):
|
||||
@@ -299,10 +309,10 @@ role_mcp_servers:
|
||||
|
||||
### Tools
|
||||
|
||||
- **General, local** (`app/tools/general/`):
|
||||
- **General, local** (`app/tools/local.py`):
|
||||
- `mermaid_check`: moved from `validation_tools.validate_mermaid_diagram`.
|
||||
- `terraform_fmt` and `terraform_validate`: run the `terraform` CLI in a temp dir with `-backend=false`. There are no credentials, and the tool fails clearly if `terraform` is missing.
|
||||
- **Cloud read, local** (`app/tools/cloud_read/`): `terraform_plan` needs ADC and `-lock=false`, and never runs `apply`.
|
||||
- **Cloud read, local** (`app/tools/local.py`): `terraform_plan` needs ADC and `-lock=false`, and never runs `apply`.
|
||||
- **Remote MCP servers** (`app/tools/mcp.py`): the Cloud provider's own hosted servers, declared in the provider bundle and used for both discovery and grounding. They replace `GCPEnvironmentScanner` (hand-written REST calls) and the hand-rolled JSON-RPC `DeveloperKnowledgeMCPClient`, including its offline fallback knowledge base and the `data`/`documents` bug from review candidate 02. Both are deleted in increment 9.
|
||||
- `McpServerSpec(id, url, tier, allow, preview)` is framework-neutral. The ADK runtime maps each one to `McpToolset(StreamableHTTPConnectionParams(url, headers=auth), tool_filter=allow)`.
|
||||
- **Read-only in depth.** Tools outside `allow` are never offered to any agent. At startup, a server whose `tools/list` reports an allowed tool with `readOnlyHint` not true fails to load, loudly. Operators should also run the agent's identity with only viewer roles, plus Google Cloud's control that blocks read-write MCP tool use and an IAM deny policy (`docs/operations/mcp-access.md`, written in increment 6).
|
||||
@@ -314,7 +324,7 @@ role_mcp_servers:
|
||||
|
||||
### Interaction
|
||||
|
||||
**A2A** (`app/a2a/`), using `a2a-sdk>=0.3` on `aiohttp` :8000, with `agent_card.json` and `/.well-known/agent.json`:
|
||||
**A2A** (`app/main.py`, `app/a2a_server.py`, `app/card.py`), using `a2a-sdk>=0.3` on `aiohttp` :8000, with `agent_card.json` and `/.well-known/agent.json`:
|
||||
- **Task ↔ Execution:** an A2A task is an Execution (`task.id` = `execution_id`), and `context_id` is the Session.
|
||||
- **Status updates:** `working` while nodes run.
|
||||
- **`input-required`** at every `interrupt()`. The interrupt payload goes out as a `DataPart`, with a text rendering for plain clients.
|
||||
@@ -332,7 +342,7 @@ The route switches to the new graph in increment 7, behind `AGENT_ENGINE=hierarc
|
||||
|
||||
### Recording
|
||||
|
||||
`app/execution/recorder.py` reuses `DatabaseManager` tables until candidate 03:
|
||||
`app/recorder.py` reuses `DatabaseManager` tables until candidate 03:
|
||||
- `workflow_executions`: one row per Execution, updated at each interrupt and at completion.
|
||||
- `adk_artifacts`: one row per Deliverable submission. Rows for earlier Revisions stay as history.
|
||||
- `orchestrator_review_logs`: one row per Ledger event. `review_status` holds the event type, `reviewer_agent` holds the role or `user`, and `feedback` holds the reason or feedback.
|
||||
@@ -430,7 +440,7 @@ These are ordered, and each leaves the suite green. They are called *increments*
|
||||
- The A2A server and executor, `agent_card.json`, `test_executor.py`.
|
||||
- `/generate` behind `AGENT_ENGINE`, and the Dockerfile exposing :8000 and :8080.
|
||||
8. **Evaluation:** scripted answers, template-heading scoring, and a real-model eval run with results recorded under `## Comments`. Proceed to 9 only when the pass rate meets the current harness threshold (≥ 80% per case).
|
||||
9. **Cleanup** (carried over from the superseded spec):
|
||||
9. **Cleanup** (carried over from the superseded spec). **Done differently on 2026-10-06:** the engine moved into the KAB layout and the original pipeline was then deleted. See `.agents/plans/iter-03-kab-layout/`. The list below is the plan as first written:
|
||||
- **Delete:** `app/tools/gcp_scanner.py`, `app/tools/mcp_developer_knowledge.py` (replaced by remote MCP servers), `app/adk/`, `app/nodes/`, `app/states/`, `app/workflows/gcp_architecture_graph.py`, `app/skills/` (the loader and the 5 non-compliant Skills), `tests/test_graph_workflow.py`, the ADK and orchestrator tests in `tests/test_adk_architecture.py` (keeping the DB test as `tests/test_database.py`), and `test_adk_mcp_function_tools`.
|
||||
- **Fix:** remove the unreachable duplicate `return` in `routes.py`. Rename `ADK_MAX_LOOP_ITERATIONS` → removed, and delete `ADK_ENABLE_ARTIFACT_STORE`.
|
||||
- **Update:**
|
||||
@@ -444,8 +454,8 @@ These are ordered, and each leaves the suite green. They are called *increments*
|
||||
## Acceptance
|
||||
|
||||
- [ ] **Upstream parity:** a pre-approved evaluation run produces a Solution guide containing every heading of the upstream `output-template.md`, and all benchmark cases pass the threshold.
|
||||
- [ ] **Single source for the workflow:** Phases, Deliverables and Dependencies are listed only in `app/execution/deliverables.py`, and card and manifest data is derived from it.
|
||||
- [ ] **No framework types outside `app/agents/adk_runtime.py`:** `rg -n "google\.adk" app | grep -v adk_runtime.py` is empty. After increment 9, `rg -n "app\.adk|OrchestratorLoopAgent|compat" app eval tests` is empty.
|
||||
- [ ] **Single source for the workflow:** Phases, Deliverables and Dependencies are listed only in `app/workflows/deliverables.py`, and card and manifest data is derived from it (`tests/test_workflow_manifest.py` checks `workflow.yaml`).
|
||||
- [ ] **No framework types outside `app/adk/adk_runtime.py`:** `rg -n "google\.adk" app | grep -v adk_runtime.py` is empty. Nothing of the original pipeline remains: `rg -n "OrchestratorLoopAgent|compat|app\.legacy" app eval tests` is empty.
|
||||
- [ ] **Vendored Skills unchanged:** they match the `81a31a6` checksums, and every Skill under `skills/` passes the frontmatter rules.
|
||||
- [ ] **Approvals only by structured decision:** no path grants an Approval from free text (covered by tests).
|
||||
- [ ] **Nothing changes cloud resources:** no tool can run `terraform apply`, a deploy or a script (`run_skill_script` absent from the tool lists). Cloud-read tools, MCP included, are unreachable without permission.
|
||||
@@ -457,7 +467,7 @@ These are ordered, and each leaves the suite green. They are called *increments*
|
||||
|
||||
- **Specialists submitting without asking (D32).** A Specialist might submit without getting the user's conversational OK. Mitigation: role files require confirmation through `needs_input` before `submit_deliverable`, and the evaluation checks that submissions follow a question. If it's still observed, fall back to Approval per Deliverable (the Q31 alternative).
|
||||
- **ADK Skills are Experimental.** The `SkillToolset` API may change. It's confined to `adk_runtime.py`, and Deep Agents is the planned second implementation.
|
||||
- **Parallel Specialists and rate limits.** Fan-out multiplies concurrent model calls. Cap concurrency per Execution (default 4) in `graph.py`.
|
||||
- **Parallel Specialists and rate limits.** Fan-out multiplies concurrent model calls. Cap concurrency per Execution (default 4) in `app/nodes/execution_nodes.py` (not built; `.agents/plans/iter-04-learning-and-skills/` step 5).
|
||||
- **Upstream Skill drift.** Upstream edits may assume a different workflow. Re-sync only through the script, and review the diff against `agents/*.md` and `deliverables.py`.
|
||||
- **Two frameworks in one process.** LangGraph and ADK both manage async state. Keep ADK sessions in memory per run, and never put ADK objects in graph state.
|
||||
- **Remote MCP server availability and drift.** Several servers are Preview (Asset Inventory, Network Intelligence, Billing), each needs its product API enabled in the user's project, and tool sets can change. Mitigations:
|
||||
@@ -469,6 +479,8 @@ These are ordered, and each leaves the suite green. They are called *increments*
|
||||
|
||||
## Comments
|
||||
|
||||
The dated entries below are history and keep the module paths of their day. Translate them with the table in `.agents/plans/README.md`.
|
||||
|
||||
### 2026-09-15 · Increment 1: environment and baseline
|
||||
|
||||
**Environment**
|
||||
|
||||
Reference in New Issue
Block a user