49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# Agent Lifecycle
|
|
|
|
This project uses client-driven lazy initialization for Claude Code agents. Sessions start without spinning up agent runtimes; the client opts in when needed.
|
|
|
|
## Connection Bootstrapping
|
|
- The session emits `session_state` after connection with an array of agents. Each entry matches the server `AgentInfo` structure (`id`, `status`, `createdAt`, `type`, `sessionId`, `error`, `currentModeId`, `availableModes`, `title`, `cwd`).
|
|
- No history or runtime is loaded at this point. Every agent starts in `uninitialized` and only streams live status updates once subscribed.
|
|
|
|
## Opting In To An Agent
|
|
1. When the UI needs an agent, send an inbound session message:
|
|
|
|
```json
|
|
{
|
|
"type": "initialize_agent_request",
|
|
"agentId": "<agent-id>",
|
|
"requestId": "<optional-correlation-id>"
|
|
}
|
|
```
|
|
|
|
2. The session subscribes to the agent, calls `AgentManager.initializeAgentAndGetHistory`, and lazily starts the runtime if required.
|
|
3. The server responds with:
|
|
|
|
```json
|
|
{
|
|
"type": "agent_initialized",
|
|
"payload": {
|
|
"agentId": "<agent-id>",
|
|
"info": { /* same shape as session_state agents */ },
|
|
"updates": [
|
|
{
|
|
"agentId": "<agent-id>",
|
|
"timestamp": "2024-01-01T00:00:00.000Z",
|
|
"notification": { /* AgentNotification */ }
|
|
}
|
|
],
|
|
"requestId": "<optional-correlation-id>"
|
|
}
|
|
}
|
|
```
|
|
|
|
4. After the response, all ongoing traffic uses the existing channels:
|
|
- `agent_status` continues to broadcast status changes.
|
|
- `agent_update` streams real-time session notifications, permission prompts, etc.
|
|
|
|
## Notes
|
|
- `initialize_agent_request` is idempotent. The manager short-circuits if the agent is already ready and returns the cached history.
|
|
- Session state no longer replays history when clients reconnect; clients must explicitly reinitialize agents they care about.
|
|
- `requestId` lets the caller correlate UI state but remains optional throughout the flow.
|