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.
Where each hook plugs in
The runtime never reaches inside your plugin. Every contribution flows through one of these channels.The nine hooks at a glance
| Hook | What it contributes | When called |
|---|---|---|
manifest | The agent-facing interface — title, summary, whenToUse, examples, visibility | Boot (validation + Tier-1 composition) |
configSchema | A Zod object merged into the global env schema | Boot (env validation) |
dependsOn / softDependsOn | Plugin ordering constraints | Boot (topo sort) |
autoDetect(env) | Decide whether to load based on env | Boot (resolution) |
getTools(ctx) / getRequestTools(rtCtx) | LLM-callable tools | Boot cache + per-request |
getSubAgents(ctx) / getRequestSubAgents(rtCtx) | Focused inner agents (auto-wrapped as tools) | Boot cache + per-request |
getMiddlewares(ctx) | beforeModel / afterModel / onError hooks | Boot cache |
getNestModules(ctx?) | Nest modules (HTTP routes, services) | Boot, once |
getAuthExcludedRoutes() | Routes that skip UCAN auth | Boot, once |
getSharedState() | Read-only accessors other plugins can consume | Boot, once |
getTools, getSubAgents, getMiddlewares) are called once and the results are cached for every request. The per-request variants run on every agent build — use them only when the contribution depends on live state (e.g. loadedPlugins, current user, rtCtx.shared.*).
Two contexts
| Context | Holds | Hooks that receive it |
|---|---|---|
PluginContext | config, identity, availablePlugins, logger | getTools, getSubAgents, getMiddlewares, getNestModules |
RuntimeContext | Everything in PluginContext plus user, session, history, secrets, matrix, ucan, llm, emit, shared, abortSignal, loadedPlugins | getRequestTools, getRequestSubAgents, all handlers, all middleware hooks |
getTools still gets a fresh RuntimeContext when its handler fires. “Boot-time” refers to registration, not execution. See Contexts for the field list.
Error semantics
| Hook throws… | Effect |
|---|---|
autoDetect, manifest validation, configSchema, getNestModules, getAuthExcludedRoutes, getSharedState | Boot fails. Loud failures because misconfiguration in production is worse than no plugin. |
getTools / getSubAgents / getMiddlewares (boot warm or per-request) | Logged with plugin name; plugin’s contribution skipped for that build. Other plugins continue. |
Tool / sub-agent handler | Becomes an error ToolMessage the agent sees; one retry on validation errors. |
| Middleware hook | Propagates as a turn error. |
Read next
Write a plugin
Scaffold and ship one.
Manifest
The agent-facing interface.
packages/oracle-runtime/src/plugin-api/oracle-plugin.ts.