13 KiB
Writing Your Own Plugin — Full API Reference
This is the complete API reference for building OpenACP plugins. It covers every API surface: services, commands, middleware, events, settings, storage, overrides, and publishing.
New to plugin development? Start with Getting Started: Your First Plugin — a hands-on tutorial that walks you through scaffolding, developing, testing, and publishing your first plugin. Come back here when you need the full API details.
Plugin SDK: For type exports, base classes, and testing utilities, see the Plugin SDK Reference.
Dev Mode: For hot-reload development workflow, see the Dev Mode guide.
Plugin Structure
A plugin is a module that exports an OpenACPPlugin object. At minimum:
my-plugin/
src/
index.ts <- exports OpenACPPlugin
package.json
tsconfig.json
Minimal Plugin
// src/index.ts
import type { OpenACPPlugin, PluginContext } from '@openacp/cli'
export default {
name: '@community/my-plugin',
version: '1.0.0',
description: 'My first OpenACP plugin',
permissions: [],
async setup(ctx: PluginContext) {
ctx.log.info('My plugin loaded!')
},
} satisfies OpenACPPlugin
This plugin does nothing useful, but it's valid. It loads on boot, logs a message, and that's it.
Declaring Dependencies
If your plugin needs services from other plugins, declare them as dependencies:
export default {
name: '@community/my-plugin',
version: '1.0.0',
// Required: must be loaded before your plugin
pluginDependencies: {
'@openacp/speech': '>=1.0.0',
},
// Optional: used if available, graceful degrade if not
optionalPluginDependencies: {
'@openacp/tunnel': '>=1.0.0',
},
permissions: ['services:use'],
async setup(ctx) {
// Guaranteed to exist (required dependency)
const speech = ctx.getService<SpeechServiceInterface>('speech')!
// May be undefined (optional dependency)
const tunnel = ctx.getService<TunnelServiceInterface>('tunnel')
if (tunnel) {
ctx.log.info('Tunnel available')
}
},
} satisfies OpenACPPlugin
Overriding a built-in
To replace a built-in plugin entirely:
export default {
name: '@community/better-security',
version: '1.0.0',
overrides: '@openacp/security', // replaces the built-in security plugin
permissions: ['services:register', 'events:read', 'middleware:register'],
async setup(ctx) {
// Register the same service name the built-in would
ctx.registerService('security', new MyBetterSecurityGuard())
},
} satisfies OpenACPPlugin
When overrides is set, the overridden plugin's setup() never runs. Your plugin takes its place in the dependency graph.
Declaring Permissions
Permissions control what your plugin can do. Only request what you need:
permissions: [
'events:read', // subscribe to events with ctx.on()
'events:emit', // emit events with ctx.emit()
'services:register', // provide services with ctx.registerService()
'services:use', // consume services with ctx.getService()
'middleware:register', // intercept flows with ctx.registerMiddleware()
'commands:register', // add chat commands with ctx.registerCommand()
'storage:read', // read plugin storage
'storage:write', // write plugin storage
'kernel:access', // access ctx.sessions, ctx.config, ctx.eventBus
]
Calling a method without the required permission throws PluginPermissionError, which counts against your error budget.
Using the PluginContext API
Registering a service
async setup(ctx) {
const myService = new TranslationService()
ctx.registerService('translation', myService)
}
Other plugins can then access your service:
const translator = ctx.getService<TranslationService>('translation')
Subscribing to events
async setup(ctx) {
ctx.on('session:afterDestroy', (data) => {
ctx.log.info(`Session ${data.sessionId} destroyed after ${data.durationMs}ms`)
})
ctx.on('system:ready', () => {
ctx.log.info('System is ready!')
})
}
Event listeners are automatically cleaned up on teardown.
Emitting events
Community plugins must prefix event names with their plugin name:
ctx.emit('@community/my-plugin:translation-complete', {
sessionId: '123',
language: 'es',
})
Built-in plugins can use short names (e.g., security:blocked).
Sending messages to sessions
ctx.sendMessage(sessionId, {
type: 'system_message',
text: 'Translation complete!',
})
Messages go through the message:outgoing middleware chain, so other plugins can modify them before delivery.
Registering Commands
async setup(ctx) {
ctx.registerCommand({
name: 'translate',
description: 'Translate last message',
usage: '<language>',
category: 'plugin',
handler: async (args) => {
const lang = args.raw.trim()
if (!lang) {
return { type: 'error', message: 'Usage: /translate <language>' }
}
const translated = await translateLastMessage(args.sessionId, lang)
return { type: 'text', text: translated }
},
})
}
Your command will be available as /translate (if no conflict) and /my-plugin:translate (qualified name, always available).
Return a CommandResponse object -- adapters handle rendering automatically. See Command System for all response types.
Registering Middleware
Middleware lets you intercept and modify the message flow:
async setup(ctx) {
// Translate outgoing messages
ctx.registerMiddleware('message:outgoing', {
priority: 50, // lower = earlier execution within same dependency level
handler: async (payload, next) => {
// Modify before downstream handlers
payload.message.text = await translate(payload.message.text, 'es')
// Continue the chain
const result = await next()
// Observe after downstream (optional)
return result
},
})
}
Blocking a flow
Return null to stop the chain:
ctx.registerMiddleware('message:incoming', {
handler: async (payload, next) => {
if (containsSpam(payload.text)) {
ctx.log.warn(`Blocked spam from user ${payload.userId}`)
return null // message is dropped
}
return next()
},
})
Available hooks
See Core Design > MiddlewareChain for the full list of 18 hook points and their payload types.
Settings Schema and Install Flow
If your plugin needs configuration, define a settings schema and install hook:
import { z } from 'zod'
const settingsSchema = z.object({
apiKey: z.string(),
targetLanguage: z.string().default('en'),
autoTranslate: z.boolean().default(false),
})
export default {
name: '@community/translator',
version: '1.0.0',
essential: true, // requires setup before system can run
settingsSchema,
permissions: ['services:register', 'middleware:register'],
async install(ctx) {
// Interactive setup -- runs once on install
const apiKey = await ctx.terminal.password({
message: 'Enter your translation API key:',
validate: (v) => v.length > 10 ? undefined : 'Key too short',
})
const lang = await ctx.terminal.select({
message: 'Default target language:',
options: [
{ value: 'en', label: 'English' },
{ value: 'es', label: 'Spanish' },
{ value: 'fr', label: 'French' },
],
})
await ctx.settings.setAll({
apiKey,
targetLanguage: lang,
autoTranslate: false,
})
ctx.terminal.log.success('Translator configured!')
},
async configure(ctx) {
// Reconfiguration -- runs on `openacp plugins configure`
const current = await ctx.settings.getAll()
// Show menu to change settings...
},
async migrate(ctx, oldSettings, oldVersion) {
// Handle version upgrades
if (oldVersion === '1.0.0') {
return { ...oldSettings, autoTranslate: false } // new field
}
return oldSettings
},
async setup(ctx) {
const config = ctx.pluginConfig
if (!config.apiKey) {
ctx.log.warn('Translator not configured')
return
}
// Normal startup with validated settings...
},
} satisfies OpenACPPlugin
InstallContext
The install(), configure(), and uninstall() hooks receive an InstallContext:
interface InstallContext {
pluginName: string
terminal: TerminalIO // interactive I/O (text, select, confirm, password)
settings: SettingsAPI // read/write plugin settings
legacyConfig?: Record<string, unknown> // old config.json data for migration
dataDir: string // ~/.openacp/plugins/@scope/name/data/
log: Logger
}
TerminalIO
Wraps @clack/prompts for interactive flows:
interface TerminalIO {
text(opts: { message: string; placeholder?: string; validate?: (v: string) => string | undefined }): Promise<string>
select<T>(opts: { message: string; options: { value: T; label: string }[] }): Promise<T>
confirm(opts: { message: string }): Promise<boolean>
password(opts: { message: string; validate?: (v: string) => string | undefined }): Promise<string>
multiselect<T>(opts: { message: string; options: { value: T; label: string }[] }): Promise<T[]>
log: { info, success, warning, error, step }
spinner(): { start, stop, fail }
note(message: string, title?: string): void
}
Using Plugin Storage
For persistent data beyond settings (caches, state, databases):
async setup(ctx) {
// Key-value store
await ctx.storage.set('lastRun', Date.now())
const lastRun = await ctx.storage.get<number>('lastRun')
// Data directory for files
const dataDir = ctx.storage.getDataDir()
// dataDir = ~/.openacp/plugins/data/@community/my-plugin/
// Store SQLite databases, large files, etc.
}
Testing Your Plugin
Create a test file alongside your plugin:
// src/__tests__/my-plugin.test.ts
import { describe, it, expect, vi } from 'vitest'
import plugin from '../index.js'
function mockPluginContext() {
return {
pluginName: '@community/my-plugin',
pluginConfig: { apiKey: 'test-key' },
log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
on: vi.fn(),
off: vi.fn(),
emit: vi.fn(),
registerService: vi.fn(),
getService: vi.fn(),
registerMiddleware: vi.fn(),
registerCommand: vi.fn(),
sendMessage: vi.fn(),
storage: {
get: vi.fn(),
set: vi.fn(),
delete: vi.fn(),
list: vi.fn(),
getDataDir: vi.fn().mockReturnValue('/tmp/test-data'),
},
} as any
}
describe('my-plugin', () => {
it('registers service on setup', async () => {
const ctx = mockPluginContext()
await plugin.setup(ctx)
expect(ctx.registerService).toHaveBeenCalledWith('translation', expect.anything())
})
it('registers commands on setup', async () => {
const ctx = mockPluginContext()
await plugin.setup(ctx)
expect(ctx.registerCommand).toHaveBeenCalledWith(
expect.objectContaining({ name: 'translate' })
)
})
})
Publishing to npm
package.json
{
"name": "@community/openacp-translator",
"version": "1.0.0",
"type": "module",
"main": "dist/index.js",
"exports": {
".": "./dist/index.js"
},
"peerDependencies": {
"@openacp/cli": ">=2026.0326.0"
},
"keywords": ["openacp", "openacp-plugin"]
}
Build and publish
# Build
tsc
# Test
vitest run
# Publish
npm publish --access public
Users install your plugin
openacp plugins install @community/openacp-translator
This runs npm install into ~/.openacp/plugins/, validates the plugin interface, and calls install() if the plugin has essential: true.
Checklist
Before publishing:
- Plugin exports an
OpenACPPluginobject (default export) namefollows@scope/nameconventionversionis valid semverpermissionsonly includes what's neededpluginDependenciesdeclares all required pluginssettingsSchemavalidates all settings (if applicable)install()handles both fresh install and legacy migrationmigrate()handles version upgradesteardown()cleans up resources (timers, connections)- Tests cover setup, commands, and error cases
package.jsonhas@openacp/clias peer dependency
Further Reading
- Getting Started: Your First Plugin -- scaffold, develop, test, and publish
- Plugin SDK Reference -- types, base classes, and testing utilities
- Dev Mode -- hot-reload development workflow
- Plugin System -- complete plugin infrastructure
- Command System -- command registration and rendering
- Built-in Plugins -- examples of real plugins
- Core Design -- core modules your plugin interacts with