82f3140847
Complete architecture document set with multi-model review remediation: - Frozen interface contracts, runtime semantics, DB schemas - Event/tool/error/provider registries - Scheduler and main agent state machines - C4 module/code views, solution architecture, baseline V1 - Multi-model review reports and joint assessment - Phase-gate remediation complete (P0/P1/P2/UX resolved) - Implementation plan with T-000A through T-045 - Reference folders kept as placeholders only
149 lines
9.5 KiB
Markdown
149 lines
9.5 KiB
Markdown
# Main Agent State Machine
|
|
|
|
Date: 2026-05-28
|
|
Status: V1.0.0 Alpha canonical state machine
|
|
|
|
This document defines the Main Agent lifecycle for V1.0.0 Alpha. Event names align with `event-registry-v1.md`. Permission model aligns with `interface-contracts-v1.md` `permission_template`.
|
|
|
|
## States
|
|
|
|
```text
|
|
┌──────────────────────────────────────────────┐
|
|
│ IDLE │
|
|
│ Waiting for user input │
|
|
└──────┬───────────────────────────────────────┘
|
|
│ user.message.created
|
|
▼
|
|
┌──────────────────────────────────────────────┐
|
|
│ CLASSIFYING │
|
|
│ LLM classifies intent │
|
|
└──┬──────────────────┬───────────────────────┘
|
|
│ │
|
|
Chat/Q&A │ Task request │ /direct command
|
|
▼ ▼ ▼
|
|
┌──────────┐ ┌──────────────────┐ ┌──────────────┐
|
|
│ANSWERING │ │ DELEGATING │ │ DIRECT_MODE │
|
|
│ Direct │ │ Needs arch check?│ │ Main Agent │
|
|
│ reply │ └──┬───────────┬───┘ │ with executor│
|
|
│ → IDLE │ │ │ │ permissions │
|
|
└──────────┘ Simple│ Needs│ │ /done → IDLE │
|
|
skip │ plan │ └──────────────┘
|
|
plan │ │
|
|
→ ▼ ▼
|
|
Scheduler┌──────────┐ ┌──────────────────────┐
|
|
│SCHEDULING│ │ARCHITECTURE_DESIGNING│
|
|
│Create │ │ Architecture │
|
|
│tasks │ │ Designer assesses │
|
|
│→ AWAITING│ │ impact │
|
|
└──────────┘ └──────┬───────────────┘
|
|
│ architecture.plan.updated
|
|
▼
|
|
┌──────────────────┐
|
|
│ CONFIRMING │
|
|
│ Present plan to │
|
|
│ user, await │
|
|
│ confirm/modify/ │
|
|
│ reject │
|
|
└──┬───┬───┬──────┘
|
|
│ │ │
|
|
Confirm │ │Mod│ Reject
|
|
▼ │ │ → IDLE
|
|
┌──────────┐│
|
|
│EXECUTING ││
|
|
│ Scheduler││
|
|
│ monitors ││
|
|
│ progress ││
|
|
└──┬───┬───┘│
|
|
│ │ │
|
|
task.progress event │ │ │
|
|
→ summarize to user │ │ │
|
|
│ │ │
|
|
┌────────────────────┘ │ │
|
|
│ User requirement change │ │
|
|
▼ │ │
|
|
┌──────────────┐ │ │
|
|
│ INTERRUPTING │ │ │
|
|
│ Classify │ │ │
|
|
│ change level:│ │ │
|
|
│ execution │ │ │
|
|
│ → notify │ │ │
|
|
│ Scheduler │ │ │
|
|
│ design/ │ │ │
|
|
│ interface │ │ │
|
|
│ → Arch │ │ │
|
|
│ Designer │ │ │
|
|
│ full │ │ │
|
|
│ assessment │ │ │
|
|
└──┬───────┬───┘ │
|
|
│ │ │
|
|
Execution│ Design level │
|
|
→ resume │ ▼ │
|
|
EXECUTING│ ┌──────────────┐ │
|
|
│ │ARCHITECTURE │ │
|
|
│ │ REVISING │ │
|
|
│ │ Update plan │ │
|
|
│ │ → CONFIRMING │ │
|
|
│ └──────────────┘ │
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────────────────────────┐
|
|
│ SUMMARIZING │
|
|
│ All tasks complete, summarize to user│
|
|
│ Trigger ExperienceMiner │
|
|
│ → IDLE │
|
|
└──────────────────────────────────────┘
|
|
```
|
|
|
|
## Events (from event-registry-v1.md)
|
|
|
|
| Event | Emitter | Consumer | Notes |
|
|
|---|---|---|---|
|
|
| `user.message.created` | TUI/CLI | Main Agent | User input |
|
|
| `requirement.changed` | Main Agent | Scheduler, Architecture Designer | When user changes scope mid-execution |
|
|
| `architecture.plan.updated` | Architecture Designer | Main Agent | Plan produced or revised |
|
|
| `architecture.impact.completed` | Architecture Designer | Main Agent | Impact assessment done |
|
|
| `task.created` | Scheduler | Main Agent | Tasks created from plan |
|
|
| `task.progress` | Scheduler/workers | Main Agent | Progress update |
|
|
| `task.completed` | Scheduler | Main Agent | Task done |
|
|
| `task.failed` | Scheduler | Main Agent | Task failed |
|
|
| `task.blocked` | Scheduler | Main Agent | Task blocked |
|
|
| `permission.prompt.requested` | PermissionEngine | Main Agent/TUI | Needs user decision |
|
|
| `permission.prompt.resolved` | TUI | PermissionEngine | User decided |
|
|
|
|
## Key Internal Events
|
|
|
|
| Event | Meaning |
|
|
|---|---|
|
|
| `IntentClassified` | Main Agent internal: chat vs task vs direct |
|
|
| `DirectModeEntered` | Main Agent entered `/direct` mode |
|
|
| `DirectModeExited` | Main Agent exited `/done` mode |
|
|
|
|
## Confirmation Gating
|
|
|
|
| Change Level | Action |
|
|
|---|---|
|
|
| Implementation (no interface/architecture impact) | Silent → EXECUTING |
|
|
| Architecture (interface/constraint/design change) | Architecture Designer assessment → low-permission: user confirm; high-permission: auto-proceed, results displayed |
|
|
|
|
## Main Agent Idle Principle
|
|
|
|
Main Agent must remain idle and responsive. Background tasks (ExperienceMiner, DebugKnowledge indexing) are dispatched to sub-agents via Scheduler, never run on Main Agent's thread/loop.
|
|
|
|
## Direct Mode Rules
|
|
|
|
1. `/direct` enters DIRECT_MODE with `permission_template: "main_direct"`.
|
|
2. In DIRECT_MODE, Main Agent executes directly without Scheduler dispatch.
|
|
3. Main Agent uses Executor-level permissions but remains user-facing.
|
|
4. `/done` exits DIRECT_MODE, triggers evidence collection, returns to IDLE.
|
|
5. DIRECT_MODE does not block Scheduler-owned background tasks.
|
|
6. All DIRECT_MODE actions are logged with `source.kind = "main"`.
|
|
|
|
## State-to-AgentRuntimeContext Mapping
|
|
|
|
| State | permission_template |
|
|
|---|---|
|
|
| IDLE, CLASSIFYING, ANSWERING, CONFIRMING, SUMMARIZING | N/A (no task execution) |
|
|
| DIRECT_MODE | `main_direct` |
|
|
| EXECUTING | Determined by Scheduler per task |
|
|
| INTERRUPTING, ARCHITECTURE_REVISING | N/A (delegation only) |
|