40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
# Architecture
|
|
|
|
```text
|
|
interactive Pi AgentSession (Supervisor)
|
|
├─ Hypothesis Machine extension commands/tools
|
|
├─ explicit ResearchLoop state machine
|
|
└─ AgentTree
|
|
├─ child AgentSession + SessionManager + recursive tools
|
|
│ └─ grandchild AgentSession + ...
|
|
└─ child AgentSession + ... (parallel)
|
|
|
|
subject results ──> Markdown memory ──> rebuildable SQLite FTS5 index
|
|
web tools ──> SearXNG / Firecrawl / Browser adapter ──> sources
|
|
test plans ──> Docker-only ExperimentRunner ──> artifacts
|
|
└────> independent review verdict
|
|
```
|
|
|
|
The root conversational session is never replaced. A generated child spec is
|
|
validated before the tree manifest is changed. The child receives its own Pi
|
|
session file and custom tool set. Calling its `spawn_agent` repeats the same
|
|
factory path, which makes recursion a capability rather than a special role.
|
|
|
|
`AgentTree` is model-independent and depends on `AgentRuntimeFactory`. Production
|
|
uses `PiAgentRuntimeFactory`; tests use deterministic fake runtimes without paid
|
|
API calls. Results are captured from the child's final observable assistant text
|
|
and returned by foreground spawn or `agent_control wait/collect`.
|
|
|
|
The run manifest is small and atomic. On restore, previously running/waiting
|
|
agents become `interrupted`; their Pi session path and parent/child relationships
|
|
remain intact, and `start()` resumes through `SessionManager.open()`.
|
|
|
|
The research loop is not an auto-prompt recursion. Each model-driven iteration
|
|
must call `record_iteration` with measurable deltas. Code applies termination for
|
|
goal completion, methodological failure, external-only questions, user decision,
|
|
no information gain, or the absolute iteration cap.
|
|
|
|
Markdown/source bytes are authoritative. SQLite contains only derived search and
|
|
relation data and can be dropped/rebuilt. Pi JSONL remains authoritative for each
|
|
agent conversation.
|