Manifest schema

Overview

PluginManifest is the structured metadata every plugin must declare. The runtime composes it into the Tier-1 prompt block, feeds it to the meta-tools, and validates it at boot.

import type { PluginManifest, ManifestExample } from '@ixo/oracle-runtime';

Type

export interface PluginManifest {
  title: string;
  summary: string;
  whenToUse: string[];
  whenNotToUse?: string[];
  examples?: ManifestExample[];
  tags?: string[];
  category?:
    | 'data' | 'communication' | 'automation' | 'memory'
    | 'integration' | 'ui' | 'auth' | 'observability' | 'core';
  visibility?: 'always' | 'on-demand' | 'silent';
  stability?: 'stable' | 'beta' | 'experimental';
}

export interface ManifestExample {
  user: string;
  thought?: string;
  tool: string;
  args?: Record<string, unknown>;
}

Fields

title

Type: string
Required: yes

Human-readable name. Used to prefix every tool description ([Climate Data] Fetch emissions…) and appears in the app.plugins.status() report. Distinct from name — name is kebab-case unique identifier, title is prose.

summary

Type: string
Required: yes

One-line description. Rendered in the Tier-1 prompt block for always plugins as - {name}: {summary}. Keep it short — every Tier-1 plugin costs ~80 tokens on every turn.

Validation:

Hard: must be non-empty.
Soft warn: > 120 chars.

whenToUse

Type: string[]
Required: when visibility !== 'silent'

Trigger phrases — each entry teaches the agent a situation in which this plugin is the right call.

Validation:

Hard: at least 1 entry when visibility !== 'silent'.
Soft warn: > 8 entries, or any entry > 100 chars.

whenNotToUse

Type: string[]
Required: no

Anti-patterns. Use to disambiguate from other plugins.

Validation:

Soft warn: > 4 entries, or any entry > 80 chars.

examples

Type: ManifestExample[]
Required: no

Few-shot examples. Each example binds a user message to a tool call.

Validation:

Hard: every example.tool must reference a tool the plugin actually registers — but only when the plugin registers boot-time tools. Plugins whose tools arrive at request time (MCP-sourced: sandbox, memory, firecrawl) register zero boot-time tools, so the cross-check is skipped for them. A sub-agent's wrapped name (call_<name>) is a valid example tool too.
Soft warn: > 3 examples.

examples: [
  {
    user: "What's the weather in Berlin?",
    thought: 'Direct lookup — call get_current_weather.',
    tool: 'get_current_weather',
    args: { city: 'Berlin' },
  },
]

ManifestExample

interface ManifestExample {
  user: string;                       // representative user message
  thought?: string;                   // optional reasoning
  tool: string;                       // tool the agent should call (must exist)
  args?: Record<string, unknown>;     // tool args
}

thought is optional but useful — agents pick up the reasoning pattern alongside the example.

Validation behaviour

At boot the runtime calls validateManifest(manifest, pluginName) from @ixo/oracle-runtime/manifest. The result:

interface ManifestValidationResult {
  valid: boolean;
  errors: string[];        // hard violations — boot fails
  warnings: string[];      // soft violations — logged, boot continues
}

Hard violations abort boot with the full error list printed.

Soft violations log warnings. The plugin still loads.

Manifest validation runs before env validation, so manifest errors surface even when env vars are missing.

Cross-checking examples against tools

Each example.tool is checked against the names the plugin registers — the union of its boot-time tool names and its sub-agent wrapped names (call_<name>). If a manifest references tool: 'foo' but the plugin registers no such tool, boot fails:

[boot-error] [weather] examples[0].tool: references unknown tool "foo".

This catches typos and stale manifests during refactors.

The check is lenient for MCP-sourced plugins: when a plugin registers no boot-time tools (its tools come from getRequestTools fetched per-request from an upstream MCP server — sandbox, memory, firecrawl), the runtime can't see those names at boot, so it skips the cross-check rather than false-flag every example.

Worked example

const manifest: PluginManifest = {
  title: 'Weather',
  summary: 'Weather lookups via Open-Meteo (no API key required).',
  whenToUse: [
    'Whenever asked about current weather, temperature, precipitation, or wind in any city.',
    'Any question related to forecasts (today, tomorrow, next week) for any location.',
    'When the user asks "what should I wear", "do I need an umbrella", or similar outfit guidance.',
  ],
  whenNotToUse: [
    'Questions about historical or long-term climate data.',
    'Locations smaller than city-level precision.',
  ],
  examples: [
    {
      user: "What's the weather in Berlin?",
      tool: 'get_current_weather',
      args: { city: 'Berlin' },
    },
    {
      user: 'Forecast for Tokyo this week.',
      tool: 'get_weather_forecast',
      args: { city: 'Tokyo', days: 7 },
    },
  ],
  tags: ['weather', 'forecast', 'outfit'],
  category: 'data',
  visibility: 'on-demand',
  stability: 'experimental',
};

Retuning a bundled plugin's manifest

You don't have to fork a bundled plugin to change its manifest. createOracleApp accepts a manifestOverrides option that shallow-merges fork-supplied fields onto each loaded plugin's manifest before validation and registration — so the override is what the Tier-1 prompt, the meta-tools, and the visibility index all see. This is the supported way to flip a bundled plugin's visibility (e.g. drop a noisy always plugin to on-demand) or relabel its summary / tags / whenToUse without touching the plugin source.

Manifest schema

Overview

Type

Fields

ManifestExample

Validation behaviour

Cross-checking examples against tools

Worked example

Retuning a bundled plugin's manifest

Related references