For AI agents

import { createOracleApp } from '@ixo/oracle-runtime';
import { MyPlugin } from './plugins/my-plugin/my-plugin.plugin.js';

const app = await createOracleApp({
  config: {
    name: 'My Oracle',
    org: 'Acme',
    description: 'One-line pitch the system prompt will use.',
  },
  plugins: [new MyPlugin()],
  features: {
    composio: false,        // opt out of bundled composio
    firecrawl: 'auto',      // (default) — autoDetect from env
  },
});

await app.listen(Number(process.env.PORT ?? 3000));

interface CreateOracleAppOptions {
  config: OracleConfig;                                           // required
  features?: Partial<Record<BundledFeatureName | string, FeatureToggle>>;
  plugins?: OraclePlugin[];
  nestModules?: Array<Type | DynamicModule>;
  authExcludedRoutes?: AuthExcludedRoute[];
  bundledPlugins?: OraclePlugin[];                                // test override
  env?: NodeJS.ProcessEnv;                                        // test override
  skipMatrixInit?: boolean;                                       // test override
  skipGracefulShutdown?: boolean;                                 // test override
  logger?: PluginLogger;
  hooks?: MainAgentHooks;
}

type FeatureToggle = boolean | 'auto';

interface OracleConfig {
  name: string;
  org?: string;
  description?: string;
  prompt?: {
    opening?: string;            // full replacement of the identity preamble
    communicationStyle?: string; // appended to operating principles (tone/voice)
    capabilities?: string;       // author elevator pitch above the capability list
    customInstructions?: string; // verbatim `## Custom Instructions` block
  };
}

interface AuthExcludedRoute { path: string; method?: RequestMethod }

interface MainAgentHooks {
  checkpointerForUser?: (userDid: string) => Promise<BaseCheckpointSaver>;
  resolveModel?: (role: ModelRole, params?: ChatOpenAIFields) => BaseChatModel;
  getRoomTitle?: (roomId: string) => Promise<string | undefined>;
  safetyModel?: BaseChatModel;
  validationSkipToolNames?: string[];
  operationalMode?: string;
  editorSection?: string;
  composioContext?: string;
  userSecretsContext?: string;
  degradedServicesBlock?: string;
}

interface OracleApp {
  getNestApp(): INestApplication;
  ambient: AmbientServices;
  plugins: { status(): { loaded: string[]; excluded: { plugin: string; reason: string }[]; softDepGaps: { plugin: string; missing: string }[] } };
  beforeListen(fn: (nestApp: INestApplication) => Promise<void> | void): void;
  onError(handler: (err: Error, source: string) => void): void;
  onPluginStatusChange(handler: (event: { plugin: string; from: 'pending'|'loaded'|'failed'; to: 'pending'|'loaded'|'failed'; reason?: string }) => void): void;
  listen(port?: number): Promise<void>;
}

abstract class OraclePlugin {
  abstract readonly name: string;                     // kebab-case
  abstract readonly version: string;
  abstract readonly manifest: PluginManifest;

  readonly dependsOn?: string[];                      // hard deps — boot fails if missing
  readonly softDependsOn?: string[];                  // soft deps — branches on availability
  readonly configSchema?: z.ZodObject<any>;           // merged into runtime env schema

  autoDetect?(env: NodeJS.ProcessEnv): boolean;       // skip plugin when false
  readonly autoDetectHint?: string;                   // surfaced in boot errors

  getTools?(ctx: PluginContext): PluginTool[] | Promise<PluginTool[]>;
  getSubAgents?(ctx: PluginContext): PluginSubAgent[];
  getRequestTools?(rtCtx: RuntimeContext): PluginTool[] | Promise<PluginTool[]>;
  getRequestSubAgents?(rtCtx: RuntimeContext): PluginSubAgent[] | Promise<PluginSubAgent[]>;
  getMiddlewares?(ctx: PluginContext): AgentMiddleware[];
  getSharedState?(): Record<string, (state: any, runCtx: RuntimeContext) => unknown>;
  getNestModules?(ctx?: PluginContext): Array<Type | DynamicModule>;
  getAuthExcludedRoutes?(): AuthExcludedRoute[];
}

interface PluginManifest {
  title: string;                                                       // human name
  summary: string;                                                     // one-line, shown in Tier-1 prompt for `always`
  whenToUse: string[];                                                 // triggers
  whenNotToUse?: string[];                                             // anti-patterns
  examples?: { user: string; thought?: string; tool: string; args?: Record<string, unknown> }[];
  tags?: string[];
  category?: 'data' | 'communication' | 'automation' | 'memory' | 'integration' | 'ui' | 'auth' | 'observability' | 'core';
  visibility?: 'always' | 'on-demand' | 'silent';                      // default: 'on-demand'
  stability?: 'stable' | 'beta' | 'experimental';
}

interface PluginTool {
  name: string;
  description: string;
  schema: z.ZodType;
  handler: (args: unknown, ctx: RuntimeContext) => Promise<unknown>;
  visibility?: 'always' | 'on-demand' | 'silent';                      // override plugin default per tool
}

interface PluginSubAgent {
  name: string;                                                        // e.g. 'call_memory_agent'
  description: string;
  systemPrompt: string | ((ctx: PluginContext) => string);
  tools: PluginTool[] | ((ctx: PluginContext) => PluginTool[]);
  model?: ModelRole;                                                   // default 'subagent'
  middlewares?: AgentMiddleware[];
  forwardTools?: boolean | string[];                                   // forward tool calls to main message stream
  onComplete?: (result: string, ctx: RuntimeContext) => Promise<void>;
}

// src/plugins/example/example.plugin.ts
import { OraclePlugin, type PluginManifest, type PluginTool, type RuntimeContext } from '@ixo/oracle-runtime';
import { z } from 'zod';

const manifest: PluginManifest = {
  title: 'Example',
  summary: 'One-line description shown in the Tier-1 prompt block.',
  whenToUse: ['User asks about example things'],
  whenNotToUse: ['User asks about unrelated things'],
  visibility: 'on-demand',
  stability: 'experimental',
};

export class ExamplePlugin extends OraclePlugin {
  readonly name = 'example';
  readonly version = '0.1.0';
  readonly manifest = manifest;

  readonly configSchema = z.object({
    EXAMPLE_API_KEY: z.string().min(1),
  });

  autoDetect(env: NodeJS.ProcessEnv): boolean {
    return Boolean(env.EXAMPLE_API_KEY);
  }
  readonly autoDetectHint = 'EXAMPLE_API_KEY';

  override getTools(): PluginTool[] {
    return [
      {
        name: 'get_example',
        description: 'Fetch an example.',
        schema: z.object({ query: z.string() }),
        handler: async (args, rtCtx: RuntimeContext) => {
          const { query } = args as { query: string };
          rtCtx.logger.log(`Example tool called with ${query}`);
          return { result: `echo: ${query}` };
        },
      },
    ];
  }
}

import { ExamplePlugin } from './plugins/example/example.plugin.js';

const app = await createOracleApp({
  config: { name: 'My Oracle' },
  plugins: [new ExamplePlugin()],
});
await app.listen(Number(process.env.PORT ?? 3000));