## Key Actors
MCP servers act as secure gateways between AI agents and IXO services:
```
## Parameters
### Resizing
agent-callable tools?"] A -->|No — middleware / transport only| Silent[silent] A -->|Yes| B["Should the agent use it
on most turns?"] B -->|Yes| Always[always] B -->|No — discover on demand| OnDemand[on-demand] ``` Promoting to `'always'` costs ~80 tokens per plugin in the Tier-1 prompt plus the tool schemas on every turn. `'silent'` simply stops advertising the plugin to the agent — it does not hide or disable any tools the plugin returns.
(browser, mobile, server)"] subgraph Runtime["@ixo/oracle-runtime"] Boot["createOracleApp"] Agent["LangChain agent
per request"] Plugins["Bundled + your plugins"] Boot --> Agent Plugins --> Agent end Matrix[("Matrix
(encrypted per-user rooms)")] Chain[("IXO chain
(DIDs + UCAN)")] Client -->|"HTTP + UCAN"| Agent Agent -.encrypted.-> Matrix Agent -.identity + auth.-> Chain ``` You write the green box (and any custom plugins). Everything else is shipped in the framework. ## Plugin vs skill — the most important distinction | | **Plugin** | **Skill** | | --- | --- | --- | | **What it is** | TypeScript extension to the runtime | Executable capsule from the IXO skills registry | | **Where it lives** | Inside your oracle's bundle | Remote, fetched at request time | | **When it loads** | At boot, via `createOracleApp` | Per request, when the agent decides to use one | | **Who authors it** | Oracle developer (you, or the framework team for bundled) | Anyone — published to the public registry | | **How the agent uses it** | Tools bound directly to the LLM | The agent calls `search_skills` + `sandbox_run` (plugin tools) to find and execute one | Use a plugin when only your team needs to extend the oracle and you want type safety + full host access. Use a skill when the community should be able to publish capabilities without touching your code. [Read the full Plugin vs Skill comparison](/build-an-oracle/understand/plugins-vs-skills) ## What you can build - **Domain agents** — climate, MRV, carbon DAO assistants. - **Workflow copilots** — drive an AG-UI portal, fill forms, navigate browsers. - **Integration hubs** — Gmail, GitHub, Linear, Slack, Notion via the bundled `composio` plugin. - **Skill runners** — discover and run community-authored capsules in a per-user Linux sandbox. ## Where to go next
Sessions · Messages · WS · Secrets · UCAN · Auth · Subscription · Throttler · Checkpointer"] Bundled["16 bundled plugins
memory · skills · sandbox · editor · agui · portal · firecrawl · domain-indexer · composio · slack · credits · user-preferences · matrix-group-chats · tasks · calls · vfs"] Agent["LangChain agent
built per request"] end Matrix[("Matrix homeserver")] Chain[("IXO chain")] LLM[("LLM provider")] Your --> Runtime Core --> Agent Bundled --> Agent Agent -.encrypted.-> Matrix Agent -.UCAN.-> Chain Agent -.invoke.-> LLM User["User"] -->|"HTTP + UCAN"| Agent ``` ### Layer 1 — Your oracle Typically `apps/your-oracle/src/main.ts` (a `createOracleApp(...)` call), a `config.ts` for identity, and any custom plugins or Nest modules. **You own:** the entry point, your oracle's identity, custom plugins, custom Nest modules. **You don't own:** the agent loop, the graph state shape, the checkpointer, the auth flow, the meta-tools, the bundled plugins' internals. ### Layer 2 — `@ixo/oracle-runtime` The framework. Owns the bootstrap (`createOracleApp`), the always-on Nest modules (Sessions, Messages, WebSocket, Secrets, UCAN, Auth, Subscription, Throttler, Health), the per-request agent builder, the four always-on agent middleware (capability gate, tool validation, tool-repetition guard, tool retry — plus page-context and safety-guardrail when their hooks are set), the Matrix-backed SQLite checkpointer, and the plugin API. You never edit this layer. Updates come via `pnpm update @ixo/oracle-runtime`. ### Layer 3 — Bundled plugins 16 plugins shipped inside the runtime package, each independently toggleable via `features`. See the [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) for what each one does. ## Bootstrap, in one picture ```mermaid graph LR A["resolve plugins
(features + autoDetect)"] --> B["topo sort
by dependsOn"] B --> C["validate manifests"] C --> D["compose env schema
base + plugin configSchemas"] D --> E["populate 6 registries"] E --> F["build RuntimeAppModule"] F --> G["NestFactory.create"] G --> H["schedule Matrix init
(background)"] G --> I["listen on PORT"] ``` The HTTP server accepts requests immediately; auth-requiring routes 401 until Matrix init finishes and the UCAN signing mnemonic loads. Defined in [`create-oracle-app.ts`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/bootstrap/create-oracle-app.ts). ## The six registries Plugins don't talk to the runtime directly. They push contributions into one of six registries at boot; the agent builder reads from them per request. | Registry | Holds | Collision rule | | --- | --- | --- | | ToolRegistry | All plugin tools | Flat namespace — collision is a boot error | | SubAgentRegistry | All plugin sub-agents | Flat namespace — collision is a boot error | | MiddlewareRegistry | All plugin middleware | Ordered topologically; no names | | ManifestRegistry | All plugin manifests | Title collision = soft warn | | ConfigSchemaRegistry | All plugin Zod schemas | Merged; later wins with warning | | SharedStateRegistry | Plugin shared-state accessors | Flat namespace — collision is a boot error | Source: [`packages/oracle-runtime/src/registries/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/registries/). ## What's pluggable vs fixed | Pluggable | Fixed | | --- | --- | | Plugin set (bundled toggles + your plugins) | Agent loop (LangChain `createAgent`) | | `nestModules` (your Nest modules) | Graph state shape (except one new `loadedPlugins` field) | | `authExcludedRoutes` (host + plugin) | Checkpointer (Matrix-backed SQLite) | | LLM provider (env-driven) | Auth flow (UCAN delegation) | | `hooks.checkpointerForUser` (advanced) | The four always-on middleware | | System prompt (via `OracleConfig.prompt`) | The Tier-1 block format | | Anything inside a custom plugin | The six registries | If you find yourself wanting to swap something on the "Fixed" side, you're probably trying to do something the framework explicitly doesn't allow — and you should either work within the model (e.g. write a plugin) or fork the runtime. ## Model resolution and hooks How does the agent pick which LLM to call, and how do you change it? **Provider is env-driven.** `LLM_PROVIDER` selects the whole per-role model map: `openrouter` (default) or `nebius`, each with its matching API key (`OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`). The actual model id for each role (`main`, `subagent`, `utility`, `vision`, `guard`, …) is baked into the provider's model map — there is no env var to change a single role's model id on its own. **Resolution is per-role.** Different jobs use different models. The main agent resolves the `main` role; sub-agents and utility calls resolve `subagent` / `utility` through `ctx.llm.get(role)`. The runtime resolves the main model as `resolveModel('main')`, defaulting to the provider map. **To change the main agent's model, pass `hooks.resolveModel`** to `createOracleApp`. Spreading `params` keeps the provider's fallback models and latency sorting: ```ts import { createOracleApp, getProviderChatModel } from '@ixo/oracle-runtime'; const app = await createOracleApp({ config, plugins, hooks: { // role is 'main' | 'subagent' | 'utility'. Spreading params preserves // the provider's fallback models + latency sort. resolveModel: (role, params) => getProviderChatModel(role, { ...params, ...(role === 'main' && { model: 'google/gemini-3.1-flash-lite' }), }), }, }); ``` The runtime only calls `resolveModel('main')` itself, so a hook that special-cases `'main'` swaps **only the main agent's model**; sub-agents and utility calls keep the provider defaults unless your own code routes them through the hook too. `resolveModel` is one of several `hooks` — the framework's advanced extension surface. Others include `checkpointerForUser` (swap the per-user checkpointer), `safetyModel` (enable the safety-guardrail middleware), `getRoomTitle` (enable the page-context middleware), and prompt-block overrides like `operationalMode`. See the [`createOracleApp` reference](/build-an-oracle/reference/createoracleapp) for the full list. ## Read next
(if credits loaded) participant Throttle as ThrottlerGuard participant Ctrl as MessagesController participant Agent as createMainAgent participant Ckpt as Checkpointer participant LLM participant Tools as Plugin tools Client->>Auth: POST /messages (UCAN + DID) Auth->>Sub: validated Sub->>Throttle: credits OK Throttle->>Ctrl: rate OK Ctrl->>Agent: build per-request agent Agent->>Ckpt: load thread state Ckpt-->>Agent: { messages, loadedPlugins, ... } Agent->>LLM: invoke LLM-->>Agent: text + tool calls Agent->>Tools: execute calls Tools-->>Agent: results Agent->>LLM: re-invoke LLM-->>Agent: final text Agent->>Ckpt: save state Agent-->>Client: stream SSE ``` ## 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. | | **ThrottlerGuard** | Per-user rate limit, registered as a global Nest guard (`APP_GUARD`), not an HTTP middleware. Nest runs middleware before guards, so it still gates after auth and subscription. 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 resolved for the `main` role (provider from `LLM_PROVIDER`, or a `hooks.resolveModel` override). Plugin middleware fires (`beforeModel`, `wrapModelCall`, `afterModel`). | | **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` / `wrapModelCall` / `afterModel` | Around each LLM invocation | | `middlewares[].wrapToolCall` | Around each tool call | | 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 | Propagates to the client by default. A middleware can catch it by wrapping the call in `wrapModelCall` with `try`/`catch`. | | 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
(if visibility=always)"] Manifest --> ListCaps["list_capabilities()"] Manifest --> LoadCap["load_capability({ names })"] Tier1 --> System["System prompt
every turn"] ListCaps --> Agent["Agent"] LoadCap --> Agent ``` Tier-1 plugins pay token cost on every turn forever — and not just the summary: each entry also renders `whenToUse`, `whenNotToUse`, and the first `example` as sub-bullets, so manifest length is prompt length. `on-demand` plugins cost nothing in the prompt until the agent loads them. `silent` plugins are never listed in Tier-1 and can't be loaded through the meta-tools (note: a silent plugin's tools, if it ships any, are still bound and callable — `silent` is not a security boundary). ## Writing a good manifest - **Be specific in `whenToUse`.** "Weather questions" is too vague. "User asks about current weather, temperature, precipitation, or wind in any city" is precise. - **Use `whenNotToUse` to disambiguate** when your plugin conceptually overlaps with another (Firecrawl vs Sandbox vs Domain Indexer is the canonical case). - **Examples should cover the typical patterns**, not just the obvious one. - **Keep `tags` lowercase.** They're for search ranking, not display. - **Pick `visibility` deliberately.** Default to `on-demand`; promote to `always` only when the agent needs the plugin on nearly every turn.
call this plugin's tools?"] A -->|"No — it's middleware/HTTP only"| Silent["silent"] A -->|Yes| B["Will the LLM use it
on most turns?"] B -->|Yes| Always["always"] B -->|No| OnDemand["on-demand"] ``` Promoting to `always` is a deliberate budget choice — it pays Tier-1 tokens on every turn. `silent` is for plugins that don't need to be advertised or discovered (they work through middleware or HTTP). Most plugins should stay on the default — `on-demand`.
getSharedState()"] Reg["SharedStateRegistry
(boot)"] RtCtx["RuntimeContext.shared
(per request)"] Cons["Plugin B
tool handler"] Prod --> Reg --> RtCtx --> Cons ``` ## When to use it | Good fit | Bad fit | | --- | --- | | A derived value other plugins might want (e.g. `userProfile`, `lastWeatherQuery`, `activePageId`) | Mutable state with multiple writers | | Cheap reads that abstract graph-state field names | Large blobs consumers might read but ignore | | Stable shape worth declaring on `SharedAccessors` for typed reads | Plugin internals other plugins shouldn't see | If only your plugin reads it, keep it private. ## The contract - **Read-only.** Consumers never mutate the value. Producers update their own internal state via tool handlers or middleware; the accessor just exposes a view. - **Flat namespace.** Keys live in a single global record. Two plugins registering the same key fail boot — no quiet overrides. - **Lazy.** Each accessor is a function `(state, runCtx) => value`. It runs every time a consumer reads. Cheap reads only; cache in the producer if derivation is expensive. - **Optional.** A consumer must assume the producer may not be installed. `rtCtx.shared.someKey` can be `undefined`. Pair shared state with `softDependsOn` so the soft dependency is explicit in the `app.plugins.status()` report. ## Typed reads `SharedAccessors` is an open interface. Producer plugins extend it via TypeScript declaration merging so consumers see the right type on `rtCtx.shared.someKey`. Without merging, the key types as `unknown` and consumers cast. Use declaration merging when the shape is stable; skip it for ad-hoc keys. ## Read next
getSubAgents
getMiddlewares
getNestModules"] Req["Per request"] --> RCtx["RuntimeContext"] RCtx --> Hooks2["getRequestTools
getRequestSubAgents
tool/sub-agent handlers
middleware hooks"] ``` ## What each context carries ### `PluginContext` — boot-time, no user - `config` — the merged, Zod-validated env (base + every plugin's `configSchema`). - `identity` — your oracle's identity (`name`, `org`, `description`, `entityDid`, `prompt`). - `availablePlugins` — set of names of all loaded plugins; useful for soft-dependency branching. - `logger` — a plugin-scoped logger. ### `RuntimeContext` — per request, authenticated user Everything in `PluginContext`, plus: | Field | Purpose | | --- | --- | | `user` | DID, Matrix user ID, UCAN delegation, timezone | | `session` | Thread ID (= `session.id`), client (`portal` / `matrix` / `slack`), request ID, room ID | | `history` | `messages`, `recent(n)`, `userContext`, typed `state` view | | `secrets` | `getIndex()`, `getValues(keys)` for per-user secrets | | `blobStore` | Short-TTL keyed store for values the model must never echo verbatim (UCAN invocation CARs, JWTs): `put()` returns an opaque `blob_
{messages.map((m) => (
);
}
```
Options (`IChatOptions`):
{renderMessageContent(m.content)}
))}