2.5 KiB

Raw Permalink Blame History

AO Plugin Spec

This document defines the runtime contract and packaging requirements for Agent Orchestrator plugins.

Runtime Contract

Plugins are standard Node.js modules that export a PluginModule:

export interface PluginModule<T = unknown> {
  manifest: PluginManifest;
  create(config?: Record<string, unknown>): T;
  detect?(): boolean;
}

Minimum manifest shape:

export interface PluginManifest {
  name: string;
  slot: PluginSlot;
  description: string;
  version: string;
}

AO accepts either a direct named export or a default export that satisfies this shape.

Supported Slots

Current core slot types:

runtime
agent
workspace
tracker
scm
notifier
terminal

The manifest slot determines where AO registers the plugin and which config surface can reference it.

Packaging Requirements

Published plugins should:

ship built JavaScript, not raw TypeScript-only entrypoints
export an ESM entrypoint through exports or main
declare a semver dependency on @aoagents/ao-core
keep side effects out of module top-level code where possible

Recommended package shape:

{
  "name": "@aoagents/ao-plugin-example",
  "version": "0.1.0",
  "type": "module",
  "main": "dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"]
}

Config Descriptors

Project config enables plugins through plugins: entries:

plugins:
  - name: openclaw
    source: registry
    package: "@aoagents/ao-plugin-notifier-openclaw"
    version: "0.1.1"

Descriptor fields:

name: logical plugin name shown in CLI UX
source: one of registry, npm, or local
package: package name for registry/npm-backed plugins
version: requested or installed version for store-backed plugins
path: local filesystem path for source: local
enabled: optional flag, defaults to true

Marketplace Registry

AO’s bundled marketplace catalog lives at:

packages/cli/src/assets/plugin-registry.json

Registry entries provide AO-specific metadata on top of the runtime contract:

id
package
slot
description
source
latestVersion
setupAction when post-install guidance is needed

Installation Model

Registry and npm plugins install into the AO-managed store:

~/.agent-orchestrator/plugins/

That store is shared across projects. agent-orchestrator.yaml remains the source of truth for whether a plugin is enabled in a given repo.

2.5 KiB Raw Permalink Blame History Unescape Escape