Skip to main content

​
Overview

PluginContext is the boot-time context. It’s the input to the boot-time hooks — getTools, getSubAgents, getMiddlewares, and getNestModules. (The request-time hooks getRequestTools / getRequestSubAgents receive the richer RuntimeContext instead.) 
export interface PluginContext<TConfig = MergedConfig> {
  config: TConfig;
  identity: OracleIdentity;
  availablePlugins: ReadonlySet<string>;
  logger: Logger;
}
No authenticated user, no session, no live socket, no request data. If your code needs those, use RuntimeContext instead — available in request-time hooks (getRequestTools, getRequestSubAgents) and in every tool handler / sub-agent handler / middleware hook.

​
Fields

  • Type: TConfig (defaults to MergedConfig = Record<string, unknown>)
Merged Zod-validated env vars: the base Tier-0 schema combined with every loaded plugin’s configSchema. Already validated by the time you receive it — parse it through your plugin’s own schema for typed access.
const units = configSchema.parse(ctx.config).WEATHER_DEFAULT_UNITS;
  • Type: OracleIdentity
interface OracleIdentity {
  name: string;
  org: string;
  description: string;
  entityDid: string;
  prompt?: OraclePromptConfig;
}
The oracle’s own identity. name, org, description, and prompt come from the config argument to createOracleApp. entityDid is sourced from the ORACLE_ENTITY_DID env var. Read-only.
  • Type: ReadonlySet<string>
The names of every plugin that survived boot resolution. Use it for soft-dep branching:
if (ctx.availablePlugins.has('memory')) {
  tools.push(rememberSomethingTool);
}
Fixed at boot, identical across all PluginContext and RuntimeContext instances during the lifetime of the app.
  • Type: Logger
Plugin-scoped logger, auto-prefixed with the plugin’s name in output. The Logger interface:
interface Logger {
  log(message: unknown, ...optional: unknown[]): void;
  error(message: unknown, ...optional: unknown[]): void;
  warn(message: unknown, ...optional: unknown[]): void;
  debug?(message: unknown, ...optional: unknown[]): void;
  verbose?(message: unknown, ...optional: unknown[]): void;
  child?(bindings: Record<string, unknown>): Logger;
}
debug, verbose, and child are optional. The runtime ships NestJS’s Logger as the default; you can override via createOracleApp({ logger }).

​
Lifetime

Boot-time hooks (getTools, getSubAgents, getMiddlewares) fire once at boot, against a boot-warm PluginContext, and their output is cached. The per-request agent build reuses that cache and only re-runs the request-time hooks (getRequestTools, getRequestSubAgents) — so anything that varies per request must come from RuntimeContext, not PluginContext. PluginContext only ever carries boot-fixed data (config, identity, availablePlugins, logger).