Plugin API Reference

Complete reference for the CortexPrism plugin system APIs, covering the lifecycle hooks, capability interface, permission model, and runtime APIs.

Plugin Lifecycle Hooks

Plugins can hook into lifecycle events to perform initialization and cleanup:

export default definePlugin({
  name: "lifecycle-demo",
  version: "1.0.0",

  onInstall(ctx: LifecycleContext): void | Promise<void> {
    // Called when the plugin is first installed
    // Use for one-time setup: create directories, initialize state
  },

  onActivate(ctx: LifecycleContext): void | Promise<void> {
    // Called when the plugin is activated (enabled)
    // Use for per-session setup: connect to services, allocate resources
  },

  onDeactivate(ctx: LifecycleContext): void | Promise<void> {
    // Called when the plugin is deactivated (disabled)
    // Use for cleanup: close connections, release resources
  },

  onUninstall(ctx: LifecycleContext): void | Promise<void> {
    // Called right before the plugin is removed
    // Use for final cleanup: remove data, revoke permissions
  },

  onConfigChange(ctx: LifecycleContext, prev: Record<string, unknown>): void | Promise<void> {
    // Called when plugin configuration changes at runtime
    // Use to hot-reload settings without restart
  },
});

LifecycleContext

Property	Type	Description
`pluginDir`	`string`	Plugin installation directory path
`dataDir`	`string`	Plugin-scoped data directory for persistent storage
`config`	`Record<string, unknown>`	Current plugin configuration
`log`	`Logger`	Structured logger
`db`	`KVStore`	Simple key-value store backed by plugins.db

Capability Definition

ESM Capabilities

type CapabilityFunction<TInput = unknown, TOutput = unknown> = (
  input: TInput,
  context: CapabilityContext
) => TOutput | Promise<TOutput>;

CapabilityContext

Property	Type	Description
`sandbox`	`SandboxAPI`	Restricted file/network access
`log`	`Logger`	Structured logger
`memory`	`MemoryAPI`	Read-only memory access
`config`	`Record<string, unknown>`	Plugin config scoped to this call
`abortSignal`	`AbortSignal`	Signals timeout/cancellation
`requestId`	`string`	Unique ID for this capability invocation

SandboxAPI

interface SandboxAPI {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  readDir(path: string): Promise<string[]>;
  fetch(url: string, options?: RequestInit): Promise<Response>;
  exec(command: string, args?: string[]): Promise<ExecResult>;
  tempDir(): Promise<string>;
}

Each SandboxAPI method is gated by the Parallax policy engine. Access is denied unless the plugin manifest declares the required permission.

MemoryAPI

interface MemoryAPI {
  search(query: string, options?: { limit?: number; tier?: MemoryTier }): Promise<MemoryEntry[]>;
  get(id: string): Promise<MemoryEntry | null>;
}

type MemoryTier = "ephemeral" | "working" | "episodic" | "semantic" | "reflection";

interface MemoryEntry {
  id: string;
  content: string;
  score: number;
  tier: MemoryTier;
  timestamp: number;
}

Plugin Manifest Schema

Full schema for manifest.json:

Required Fields

Field	Type	Description
`name`	`string`	Unique plugin identifier (kebab-case). Primary key in the plugin database.
`version`	`string`	Semantic version (e.g. `1.0.0`).
`description`	`string`	Short description shown in marketplace and plugin list.
`kind`	`"esm"	"mcp"
`entryPoint`	`string`	Path to module, URL, or WASM binary (relative to manifest).
`runtime`	`"deno"	"wasm"`
`capabilities`	`string[]`	Declared extension points and permissions.

Optional Fields

Field	Type	Description
`author`	`string`	Author name or organization.
`homepage`	`string` (url)	Plugin homepage URL.
`license`	`string`	SPDX license identifier (e.g. `MIT`).
`repository`	`string` (url)	Source repository URL.
`hash`	`string`	SHA-256 hash of entry point for integrity verification.
`signature`	`string`	Optional GPG/JWT signature for trust verification.
`icon`	`string`	Path to icon file.
`dependencies`	`Record<string, string>`	Other plugins required, keyed by name with semver constraints.
`peerDependencies`	`Record<string, string>`	Host CortexPrism version constraint.
`tools`	`ToolDeclaration[]`	Tool definitions (names, params). ESM plugins provide the implementation.
`cliCommands`	`CliCommandDeclaration[]`	CLI subcommand specifications.
`ui`	`UiContribution`	UI panels, widgets, and settings forms.
`config`	`ConfigContribution`	Config schema extensions and defaults.
`events`	`string[]`	Event types the plugin subscribes to.
`permissions`	`object`	Granular sandbox permissions.
`mcp`	`object`	MCP-specific transport and timeout settings.
`wasm`	`object`	WASM-specific memory and allocator settings.

Capabilities

Capabilities serve dual purpose: they declare what extension points the plugin uses AND what permissions it needs.

Extension Point Capabilities:

Value	Description
`tools`	Plugin provides `Tool[]`
`cli:commands`	Plugin provides CLI subcommands
`ui:panel`	Plugin provides a Web UI panel/tab
`ui:widget`	Plugin provides a dashboard widget
`config:schema`	Plugin extends config schema
`config:provider`	Plugin provides an LLM provider
`memory:store`	Plugin provides a custom memory backend
`memory:embedder`	Plugin provides an embedding provider
`events:listener`	Plugin subscribes to event bus
`middleware:pre`	Plugin provides pre-execution middleware
`middleware:post`	Plugin provides post-execution middleware

Permission Capabilities:

Value	Description
`fs:read`	Read filesystem access
`fs:write`	Write filesystem access
`fs:list`	Directory listing
`fs:edit`	File editing
`fs:delete`	File deletion
`fs:search`	File searching
`shell:run`	Shell command execution
`network:fetch`	Outbound HTTP requests
`net:outbound`	General outbound network access
`net:inbound`	Inbound network (listening)
`db:read`	Database read access
`db:write`	Database write access

ToolDeclaration

{
  "tools": [
    {
      "name": "my_tool",
      "description": "What this tool does",
      "params": [
        { "name": "input", "type": "string", "description": "Input value", "required": true }
      ]
    }
  ]
}

CliCommandDeclaration

{
  "cliCommands": [
    {
      "name": "my-cmd",
      "description": "My custom command",
      "args": [
        { "name": "target", "type": "string", "description": "Target to operate on", "required": true }
      ],
      "options": [
        { "name": "verbose", "type": "boolean", "description": "Verbose output", "flag": "-v" }
      ]
    }
  ]
}

UiContribution

{
  "ui": {
    "panels": [
      { "id": "my-panel", "title": "My Panel", "icon": "star", "htmlPath": "./ui/panel.html" }
    ],
    "widgets": [
      { "id": "my-widget", "title": "My Widget", "type": "html", "config": {} }
    ],
    "settings": [
      {
        "section": "General",
        "fields": [
          { "key": "apiKey", "label": "API Key", "type": "secret", "defaultValue": "" },
          { "key": "maxRetries", "label": "Max Retries", "type": "number", "defaultValue": 3 },
          { "key": "enabled", "label": "Enabled", "type": "boolean", "defaultValue": true },
          {
            "key": "mode", "label": "Mode", "type": "select",
            "defaultValue": "auto",
            "options": [
              { "label": "Automatic", "value": "auto" },
              { "label": "Manual", "value": "manual" }
            ]
          }
        ]
      }
    ]
  }
}

UiSettingField Types:

Type	Description
`text`	Single-line text input
`number`	Numeric input
`boolean`	Checkbox toggle
`select`	Dropdown with `options` array
`secret`	Password field (masked input)

ConfigContribution

{
  "config": {
    "providers": [
      { "kind": "my-provider", "label": "My Provider", "defaultModel": "my-model-v1" }
    ],
    "settings": {
      "defaultEndpoint": "https://api.example.com"
    }
  }
}

Trust Levels

Level	Sandbox	Permissions
`untrusted`	Worker sandbox	Limited to declared permissions
`signed`	Worker sandbox	Broader permissions based on signature
`trusted`	In-process	Full declared permissions

Trust level is set at install time and can be changed via cortex plugins permissions <name>.

Full Manifest Example

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "An example plugin with tools, UI panel, and settings",
  "kind": "esm",
  "entryPoint": "./mod.ts",
  "runtime": "deno",
  "capabilities": ["tools", "ui:panel", "network:fetch"],
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/you/my-plugin",
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a city",
      "params": [
        { "name": "city", "type": "string", "description": "City name", "required": true }
      ]
    }
  ],
  "cliCommands": [
    {
      "name": "my-command",
      "description": "My custom CLI command",
      "options": [
        { "name": "verbose", "type": "boolean", "flag": "-v" }
      ]
    }
  ],
  "ui": {
    "panels": [
      { "id": "weather", "title": "Weather", "icon": "cloud", "htmlPath": "./ui/panel.html" }
    ],
    "settings": [
      {
        "section": "API",
        "fields": [
          { "key": "apiKey", "label": "API Key", "type": "secret", "defaultValue": "" }
        ]
      }
    ]
  }
}

Runtime API (Available to ESM Plugins)

Global Objects

Object	Description
`CortexPrism`	Version info and build metadata
`fetch`	Global fetch (limited by policy)
`console`	Scoped console (prefixed with plugin name)

Importable SDK

import {
  definePlugin,        // Type-safe plugin definition
  z,                   // Zod validation
  HttpError,           // 400-level errors
  PermissionError,     // Policy denial errors
  PluginError,         // Generic plugin errors
  TimeoutError,        // Capability timeout errors
} from "@cortexprism/plugin-sdk";

Error Types

Error Class	HTTP Status	When to Use
`PluginError`	500	Unexpected internal errors
`HttpError`	400-599	Client errors, service unavailable
`PermissionError`	403	Policy denial
`TimeoutError`	408	Operation exceeded time limit

Registry DB Schema (plugins.db)

The plugin registry is stored in plugins.db with this schema:

CREATE TABLE plugins (
  id          TEXT PRIMARY KEY,
  name        TEXT NOT NULL UNIQUE,
  version     TEXT NOT NULL,
  type        TEXT NOT NULL CHECK(type IN ('esm','mcp','wasm')),
  entry_point TEXT NOT NULL,
  manifest    TEXT NOT NULL,       -- Full manifest as JSON
  enabled     INTEGER DEFAULT 1,
  installed_at TEXT NOT NULL,
  updated_at  TEXT NOT NULL,
  download_count INTEGER DEFAULT 0
);

CREATE TABLE plugin_permissions (
  id          TEXT PRIMARY KEY,
  plugin_id   TEXT NOT NULL REFERENCES plugins(id),
  permission  TEXT NOT NULL,
  granted     INTEGER DEFAULT 0
);

CREATE TABLE plugin_config (
  plugin_id TEXT PRIMARY KEY REFERENCES plugins(id),
  config    TEXT NOT NULL DEFAULT '{}'
);

CLI Commands

cortex plugin install <source>     # Install from marketplace, path, npm, jsr, or URL
cortex plugin uninstall <name>     # Remove a plugin
cortex plugin list                  # List installed plugins with status
cortex plugin enable <name>        # Activate a plugin
cortex plugin disable <name>       # Deactivate without removing
cortex plugin config <name>        # View or set plugin configuration
cortex plugin info <name>          # Show plugin details and capabilities
cortex plugin call <name> <cap>    # Invoke a capability directly (for testing)