refactor(agent): add wait_for_agent tool and simplify prompt sending API

This commit is contained in:
Mohamed Boudra
2025-11-03 11:47:15 +01:00
parent 1d22fe46e7
commit a118fd3315
12 changed files with 592 additions and 146 deletions

View File

@@ -1,48 +0,0 @@
# 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.