Request Lifecycle

Trace a user prompt from the TUI through the server to the LLM provider and back.

Flow

Key Stages

1. Prompt submission

The TUI sends a POST /api/session/prompt to the server with the session ID and text. The server handler delegates to the Session core service.

2. Context assembly

The session runner assembles the system prompt, message history, and available tools. Plugin context hooks fire here, allowing plugins to modify system, messages, or tools before dispatch.

3. LLM request

The assembled request goes to the LLM provider. For native models, http.request hooks fire before dispatch. The response streams back through http.response hooks.

4. Tool execution loop

If the LLM returns tool calls, the runner checks permissions, fires execute.before hooks, dispatches each tool, collects results, fires execute.after hooks, and sends results back to the LLM. This loop continues until the LLM responds with text only or the step limit is reached.

5. Event streaming

The server streams events to the TUI via Server-Sent Events (SSE). The TUI renders deltas, tool calls, and results in real time.

6. Persistence

Each message and tool result is persisted to SQLite via Drizzle ORM. The session projection updates so the conversation survives restarts.