Documentation Index
Fetch the complete documentation index at: https://docs.ixo.world/llms.txt
Use this file to discover all available pages before exploring further.
The full path
What each stop does
| Stop | Responsibility |
|---|---|
| AuthHeaderMiddleware | Validates the UCAN delegation (signature, expiry, audience, capability). Resolves the user’s DID and attaches RuntimeUserContext. Failure → 401, agent never runs. |
| SubscriptionMiddleware | Only when the credits plugin is loaded. Checks user balance. Empty + DISABLE_CREDITS !== 'true' → 402. |
| ThrottlerMiddleware | Per-user rate limit. Breach → 429. |
| MessagesController | Reads the inbound message, looks up the session (creates on first contact), hands off to the agent builder. Returns SSE. |
| createMainAgent | Builds the per-request RuntimeContext, reads cached registries, runs getRequestTools / getRequestSubAgents, composes the prompt, returns a LangChain agent compiled against the per-user checkpointer. |
| Checkpointer | Loads { messages, loadedPlugins, userContext, ... } for this thread_id (= session id) from per-user SQLite (synced to Matrix in the background). |
| LLM invocation | Composed prompt + bound tools + state messages go to the model selected by LLM_PROVIDER. Plugin middleware fires (beforeModel, afterModel, onError). |
| Tool calls | The agent loop dispatches plugin tools, sub-agent tools, meta-tools, and browser tools. Each emits a typed event so the client can render “Agent called X”. |
| Save state + stream | The final state is checkpointed; the assistant message streams over SSE. WS events for intermediate steps have already shipped. |
Where each plugin hook fires
| Hook | Fires during |
|---|---|
getTools, getSubAgents, getMiddlewares, getSharedState | Read from boot cache during agent build |
getRequestTools, getRequestSubAgents | Per-request agent build |
middlewares[].beforeModel / afterModel / onError | Around each LLM invocation |
Tool / sub-agent handler | When the LLM calls the tool |
getNestModules controllers | Any HTTP request to a plugin route |
Failure modes
| What fails | Effect |
|---|---|
| UCAN validation | 401. Agent never runs. |
| Credit check | 402. Agent never runs. |
| Rate limit | 429. Agent never runs. |
| Checkpointer load | Error logged; falls back to empty state. Turn proceeds. |
| LLM | onError middleware fires. Default: propagate to client. |
| Tool handler | One retry on validation error; otherwise the error becomes a ToolMessage the agent sees. |
| Sub-agent init | Promise.allSettled — log and skip; rest of turn continues. |
Read next
Contexts
What
RuntimeContext carries.Meta-tools
How
load_capability mutates loadedPlugins mid-turn.packages/oracle-runtime/src/graph/ and packages/oracle-runtime/src/modules/messages/.