OpenACP/docs/gitbook/extending/plugin-sdk-reference.md
0xmrpeter 4121840b84 docs: add plugin dev tooling guides (getting started, SDK reference, dev mode)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 21:07:56 +07:00

393 lines
12 KiB
Markdown

# Plugin SDK Reference
The `@openacp/plugin-sdk` package provides types, base classes, adapter primitives, and testing utilities for building OpenACP plugins.
---
## Installation
```bash
npm install --save-dev @openacp/plugin-sdk
```
---
## Type Exports
All types are re-exported from the main entry point:
```typescript
import type { OpenACPPlugin, PluginContext } from '@openacp/plugin-sdk'
```
### Plugin Interfaces
| Type | Description |
|---|---|
| `OpenACPPlugin` | Main plugin interface. All plugins must default-export an object matching this shape. |
| `PluginContext` | Context passed to `setup()`. Provides services, events, commands, middleware, storage, and logging. |
| `PluginPermission` | Union type of all permission strings (e.g., `'events:read'`, `'services:register'`). |
| `PluginStorage` | Key-value storage interface available via `ctx.storage`. |
| `InstallContext` | Context passed to `install()`, `configure()`, and `uninstall()`. Provides terminal I/O and settings. |
| `MigrateContext` | Context passed to `migrate()`. Provides logging. |
| `TerminalIO` | Interactive terminal interface wrapping `@clack/prompts`. |
| `SettingsAPI` | Read/write interface for plugin settings. |
### Command Types
| Type | Description |
|---|---|
| `CommandDef` | Command definition including name, description, usage, category, and handler. |
| `CommandArgs` | Arguments passed to a command handler (raw text, sessionId, channelId, userId, reply function). |
| `CommandResponse` | Response from a command handler (text, error, menu, list, etc.). |
| `MenuOption` | A selectable option in a menu-type command response. |
| `ListItem` | An item in a list-type command response. |
### Service Interfaces
| Type | Description |
|---|---|
| `SecurityService` | Access control and session limit checking. |
| `FileServiceInterface` | File saving, resolving, and format conversion. |
| `NotificationService` | Send notifications to users. |
| `UsageService` | Token/cost tracking and budget checking. |
| `SpeechServiceInterface` | Text-to-speech and speech-to-text. |
| `TunnelServiceInterface` | Port tunneling and public URL management. |
| `ContextService` | Context building and provider registration for agent sessions. |
### Adapter Types
| Type | Description |
|---|---|
| `IChannelAdapter` | Interface that all channel adapters must implement. |
| `OutgoingMessage` | Message sent from OpenACP to a channel. |
| `PermissionRequest` | Permission prompt sent to the user. |
| `PermissionOption` | A selectable option in a permission request. |
| `NotificationMessage` | Notification sent to the notification channel. |
| `AgentCommand` | Command received from a channel adapter. |
---
## Base Classes
Exported from the main entry point:
```typescript
import { MessagingAdapter, StreamAdapter, BaseRenderer } from '@openacp/plugin-sdk'
```
### MessagingAdapter
Abstract base class for channel adapters (Telegram, Discord, Slack, etc.). Implements `IChannelAdapter` with common patterns for session threading and message routing.
Use this when building a new platform adapter.
### StreamAdapter
Extends `MessagingAdapter` with streaming support. Handles chunked message updates, buffering, and periodic batch sends.
Use this when your platform supports message editing (e.g., Telegram, Discord).
### BaseRenderer
Base class for rendering agent output into platform-specific formats. Handles markdown conversion, code block formatting, and tool call display.
Use this to customize how agent responses appear on your platform.
---
## Adapter Primitives
Reusable building blocks for adapter implementations:
```typescript
import { SendQueue, DraftManager, ToolCallTracker, ActivityTracker } from '@openacp/plugin-sdk'
```
| Class | Description |
|---|---|
| `SendQueue` | Serial message queue that ensures messages are sent one at a time. Prevents race conditions when multiple messages arrive simultaneously. |
| `DraftManager` | Manages streaming message drafts. Buffers text chunks and sends periodic batch updates to the platform. |
| `ToolCallTracker` | Tracks active tool calls (file edits, shell commands, etc.) and generates status displays. |
| `ActivityTracker` | Monitors agent activity and manages typing indicators. |
---
## Testing Utilities
Import from the `/testing` subpath:
```typescript
import { createTestContext, createTestInstallContext, mockServices } from '@openacp/plugin-sdk/testing'
```
---
### createTestContext(opts)
Creates a test-friendly `PluginContext` for unit-testing plugin `setup()` and runtime behavior. All state is in-memory, the logger is silent, and services can be pre-populated.
**Options:**
```typescript
interface TestContextOpts {
pluginName: string
pluginConfig?: Record<string, unknown>
permissions?: string[]
services?: Record<string, unknown>
}
```
| Option | Type | Description |
|---|---|---|
| `pluginName` | `string` | Required. The plugin name. |
| `pluginConfig` | `Record<string, unknown>` | Plugin settings available as `ctx.pluginConfig`. Default: `{}`. |
| `permissions` | `string[]` | Simulated permissions. Default: all permitted. |
| `services` | `Record<string, unknown>` | Pre-registered services available via `ctx.getService()`. |
**Returns: `TestPluginContext`**
Extends `PluginContext` with inspection properties:
| Property / Method | Type | Description |
|---|---|---|
| `registeredServices` | `Map<string, unknown>` | Services registered via `registerService()`. |
| `registeredCommands` | `Map<string, CommandDef>` | Commands registered via `registerCommand()`. |
| `registeredMiddleware` | `Array<{ hook, opts }>` | Middleware registered via `registerMiddleware()`. |
| `emittedEvents` | `Array<{ event, payload }>` | Events emitted via `emit()`. |
| `sentMessages` | `Array<{ sessionId, content }>` | Messages sent via `sendMessage()`. |
| `executeCommand(name, args?)` | `Promise<CommandResponse>` | Dispatch a registered command by name for testing. |
**Example:**
```typescript
import { describe, it, expect } from 'vitest'
import { createTestContext } from '@openacp/plugin-sdk/testing'
import plugin from '../index.js'
describe('my-plugin', () => {
it('registers a service on setup', async () => {
const ctx = createTestContext({
pluginName: '@myorg/my-plugin',
pluginConfig: { apiKey: 'test-key' },
})
await plugin.setup(ctx)
expect(ctx.registeredServices.has('my-service')).toBe(true)
})
it('registers a command and handles it', async () => {
const ctx = createTestContext({ pluginName: '@myorg/my-plugin' })
await plugin.setup(ctx)
const response = await ctx.executeCommand('mycommand', { raw: 'test input' })
expect(response).toEqual({ type: 'text', text: expect.any(String) })
})
it('sends messages on events', async () => {
const ctx = createTestContext({ pluginName: '@myorg/my-plugin' })
await plugin.setup(ctx)
ctx.emit('session:created', { sessionId: 'sess-1' })
expect(ctx.sentMessages).toHaveLength(1)
expect(ctx.sentMessages[0].sessionId).toBe('sess-1')
})
it('uses pre-populated services', async () => {
const ctx = createTestContext({
pluginName: '@myorg/my-plugin',
services: { security: mockServices.security() },
})
await plugin.setup(ctx)
// Plugin can call ctx.getService('security') and get the mock
})
})
```
---
### createTestInstallContext(opts)
Creates a test-friendly `InstallContext` for unit-testing `install()`, `configure()`, and `uninstall()` hooks. Terminal prompts are automatically answered from a response map.
**Options:**
```typescript
interface TestInstallContextOpts {
pluginName: string
legacyConfig?: Record<string, unknown>
terminalResponses?: Record<string, unknown[]>
}
```
| Option | Type | Description |
|---|---|---|
| `pluginName` | `string` | Required. The plugin name. |
| `legacyConfig` | `Record<string, unknown>` | Simulated legacy config data (for migration testing). |
| `terminalResponses` | `Record<string, unknown[]>` | Auto-answers for terminal prompts, keyed by method name. |
**Terminal auto-answering:**
The `terminalResponses` map provides answers for each prompt method. Responses are consumed in order (queue). If the queue is empty, sensible defaults are returned:
- `text` -> `''`
- `password` -> `''`
- `confirm` -> `false`
- `select` -> `undefined`
- `multiselect` -> `[]`
**Returns: `InstallContext` with extra properties:**
| Property | Type | Description |
|---|---|---|
| `terminalCalls` | `Array<{ method, args }>` | Log of all terminal prompt calls made. |
| `settingsData` | `Map<string, unknown>` | In-memory settings store. |
**Example:**
```typescript
import { describe, it, expect } from 'vitest'
import { createTestInstallContext } from '@openacp/plugin-sdk/testing'
import plugin from '../index.js'
describe('install flow', () => {
it('saves API key from prompt', async () => {
const ctx = createTestInstallContext({
pluginName: '@myorg/my-plugin',
terminalResponses: {
password: ['sk-test-123456789'],
select: ['en'],
},
})
await plugin.install!(ctx)
// Verify settings were saved
expect(ctx.settingsData.get('apiKey')).toBe('sk-test-123456789')
expect(ctx.settingsData.get('targetLanguage')).toBe('en')
})
it('records terminal interactions', async () => {
const ctx = createTestInstallContext({
pluginName: '@myorg/my-plugin',
terminalResponses: {
password: ['sk-test-123456789'],
select: ['en'],
},
})
await plugin.install!(ctx)
expect(ctx.terminalCalls).toEqual([
{ method: 'password', args: expect.objectContaining({ message: expect.any(String) }) },
{ method: 'select', args: expect.objectContaining({ message: expect.any(String) }) },
])
})
it('handles legacy config migration', async () => {
const ctx = createTestInstallContext({
pluginName: '@myorg/my-plugin',
legacyConfig: {
oldApiKey: 'legacy-key',
},
})
await plugin.install!(ctx)
// Plugin should read legacyConfig and migrate to new settings format
expect(ctx.settingsData.has('apiKey')).toBe(true)
})
})
```
---
### mockServices
Factory functions that create mock implementations of OpenACP service interfaces. Each function returns a fully-typed object with sensible defaults. Pass `overrides` to customize specific methods.
```typescript
import { mockServices } from '@openacp/plugin-sdk/testing'
```
#### mockServices.security(overrides?)
```typescript
const security = mockServices.security()
// { checkAccess() -> { allowed: true }, checkSessionLimit() -> { allowed: true }, getUserRole() -> 'user' }
const restricted = mockServices.security({
async checkAccess() { return { allowed: false, reason: 'blocked' } },
})
```
#### mockServices.fileService(overrides?)
```typescript
const files = mockServices.fileService()
// { saveFile(), resolveFile() -> null, readTextFileWithRange() -> '', extensionFromMime() -> '.bin', convertOggToWav() }
```
#### mockServices.notifications(overrides?)
```typescript
const notifs = mockServices.notifications()
// { notify(), notifyAll() }
```
#### mockServices.usage(overrides?)
```typescript
const usage = mockServices.usage()
// { trackUsage(), checkBudget() -> { ok: true }, getSummary() -> { totalTokens: 0, ... } }
```
#### mockServices.speech(overrides?)
```typescript
const speech = mockServices.speech()
// { textToSpeech(), speechToText(), registerTTSProvider(), registerSTTProvider() }
```
#### mockServices.tunnel(overrides?)
```typescript
const tunnel = mockServices.tunnel()
// { getPublicUrl(), start(), stop(), getStore(), fileUrl(), diffUrl() }
```
#### mockServices.context(overrides?)
```typescript
const context = mockServices.context()
// { buildContext() -> '', registerProvider() }
```
**Using mockServices with createTestContext:**
```typescript
const ctx = createTestContext({
pluginName: '@myorg/my-plugin',
services: {
security: mockServices.security(),
usage: mockServices.usage({
async checkBudget() { return { ok: false, percent: 100 } },
}),
},
})
await plugin.setup(ctx)
// Plugin can now call ctx.getService('security') and ctx.getService('usage')
```
---
## Further Reading
- [Getting Started: Your First Plugin](getting-started-plugin.md) -- step-by-step tutorial
- [Writing Plugins](../architecture/writing-plugins.md) -- full guide to services, middleware, events, and storage
- [Dev Mode](dev-mode.md) -- development workflow with hot-reload