872b0adb48
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and dev/ (ADRs, architecture, extension guides, proposals). Updated docs/README.md index to reflect new paths.
34 lines
2.5 KiB
Markdown
34 lines
2.5 KiB
Markdown
# Architecture & Mental Model
|
|
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Pi Runtime │
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
|
│ │ Session │ │ Agent │ │ Tool Executor │ │
|
|
│ │ Manager │ │ Loop │ │ │ │
|
|
│ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
|
|
│ │ │ │ │
|
|
│ └──────────────┼─────────────────┘ │
|
|
│ │ │
|
|
│ ┌───────▼────────┐ │
|
|
│ │ Event System │ ◄── All events flow │
|
|
│ └───────┬────────┘ through here │
|
|
│ │ │
|
|
│ ┌────────────┼────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ Extension A Extension B Extension C │
|
|
│ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Key concepts:**
|
|
|
|
- **Extensions are loaded once** when pi starts (or on `/reload`). Your default export function runs, and you subscribe to events and register tools/commands during that function call.
|
|
- **Events are the communication mechanism.** Pi emits events at every stage of its lifecycle. Your extension listens and reacts.
|
|
- **Tools are the LLM's interface to your extension.** The LLM sees tool descriptions in its system prompt and calls them when appropriate.
|
|
- **Commands are the user's interface.** Users type `/mycommand` to invoke your extension directly.
|
|
- **State lives in tool result `details`** for proper branching/forking support, or in `pi.appendEntry()` for extension-private state.
|
|
|
|
---
|