paseo/AGENTS.md

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:

   {
     "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:

   {
     "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.