OpenACP/docs/gitbook/extending/building-adapters.md
0xmrpeter 63bee61daa fix: update outdated docs + add system command tests
- Fix adapter-reference.md and building-adapters.md (AdapterFactory → plugin pattern)
- Fix contributing.md (src/adapters/ → src/plugins/)
- Fix for-contributors.md (plugin-manager → PluginRegistry)
- Update configuration.md for per-plugin settings
- Update environment-variables.md for plugin-level env vars
- Add system command handler tests

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 22:14:52 +07:00

295 lines
8.3 KiB
Markdown

# Building Adapters
This guide walks through building a complete custom channel adapter from scratch.
---
## What Is a ChannelAdapter?
A `ChannelAdapter` is the bridge between OpenACP's core and a specific messaging platform. It has two responsibilities:
- **Inbound**: receive messages from the platform and call `core.handleIncomingMessage()`.
- **Outbound**: implement methods that core calls to deliver agent output back to the platform.
OpenACP provides an abstract base class `ChannelAdapter<TCore>` with default no-op implementations for optional methods. You extend it and implement the required abstracts.
---
## Message Flow
```
Platform user sends message
↓
YourAdapter (platform SDK listener)
↓
core.handleIncomingMessage(IncomingMessage)
↓
OpenACPCore → Session → AgentInstance (ACP subprocess)
↓
AgentEvents emitted
↓
core calls adapter.sendMessage() / sendPermissionRequest() / sendNotification()
↓
YourAdapter delivers to platform
```
The adapter is always the outermost layer. Core never talks to the platform directly.
---
## Step 1 — Extend ChannelAdapter
```typescript
import { ChannelAdapter, type ChannelConfig } from 'openacp'
import type {
OutgoingMessage,
PermissionRequest,
NotificationMessage,
} from 'openacp'
import type { OpenACPCore } from 'openacp'
export class MyPlatformAdapter extends ChannelAdapter<OpenACPCore> {
constructor(core: OpenACPCore, config: ChannelConfig) {
super(core, config)
}
// ...
}
```
The generic parameter `TCore` types `this.core`. Use `OpenACPCore` for full type safety.
---
## Step 2 — Implement start() and stop()
`start()` initializes your platform SDK, registers listeners, and begins receiving messages. `stop()` tears everything down cleanly.
```typescript
async start(): Promise<void> {
// Initialize platform client
this.client = new MyPlatformClient(this.config.token as string)
// Register inbound listener
this.client.on('message', (msg) => this.handlePlatformMessage(msg))
await this.client.connect()
}
async stop(): Promise<void> {
await this.client?.disconnect()
}
```
---
## Step 3 — Handle Inbound Messages
When the platform delivers a user message, convert it to `IncomingMessage` and call `core.handleIncomingMessage()`:
```typescript
private async handlePlatformMessage(msg: PlatformMessage): Promise<void> {
await this.core.handleIncomingMessage({
channelId: 'myplatform',
threadId: msg.threadId,
userId: msg.authorId,
text: msg.content,
// attachments: [...] — optional
})
}
```
`handleIncomingMessage` looks up or creates a session for the `(channelId, threadId, userId)` combination and enqueues the prompt.
---
## Step 4 — Implement sendMessage()
Core calls `sendMessage()` for every agent output event (text chunks, tool calls, usage summaries, errors, etc.).
```typescript
async sendMessage(sessionId: string, content: OutgoingMessage): Promise<void> {
const threadId = this.getThreadId(sessionId)
switch (content.type) {
case 'text':
await this.client.sendText(threadId, content.text)
break
case 'thought':
// Display or suppress agent reasoning — platform-specific choice
await this.client.sendText(threadId, `_${content.text}_`)
break
case 'tool_call':
await this.client.sendText(threadId, `Using tool: ${content.text}`)
break
case 'error':
await this.client.sendText(threadId, `Error: ${content.text}`)
break
case 'session_end':
// Agent finished — optionally close/archive the thread
break
}
}
```
`OutgoingMessage.type` can be: `text`, `thought`, `tool_call`, `tool_update`, `plan`, `usage`, `session_end`, `error`, `attachment`, `system_message`. You decide which types to surface in your UI.
---
## Step 5 — Implement sendPermissionRequest()
When an agent needs user approval before taking an action, core calls `sendPermissionRequest()`. You must render the options and eventually call `core.resolvePermission()`.
```typescript
async sendPermissionRequest(
sessionId: string,
request: PermissionRequest
): Promise<void> {
const threadId = this.getThreadId(sessionId)
// Build a list of buttons/options and send to platform
const optionLabels = request.options.map((o) => o.label)
const userChoice = await this.client.promptWithButtons(
threadId,
request.description,
optionLabels,
)
const chosen = request.options.find((o) => o.label === userChoice)
if (chosen) {
await this.core.resolvePermission(sessionId, request.id, chosen.id)
}
}
```
---
## Step 6 — Implement sendNotification()
Notifications are summary alerts (session completed, error, budget warning). They are typically sent to a dedicated notification channel or thread.
```typescript
async sendNotification(notification: NotificationMessage): Promise<void> {
const text = `[${notification.type}] ${notification.summary}`
await this.client.sendToNotificationsChannel(text)
}
```
---
## Step 7 — Implement Session Thread Lifecycle
Core manages sessions and expects the adapter to maintain corresponding UI threads (channels, topics, threads):
```typescript
async createSessionThread(sessionId: string, name: string): Promise<string> {
// Create a thread or channel for this session
const thread = await this.client.createThread(name)
this.sessionThreads.set(sessionId, thread.id)
return thread.id // return the platform thread ID
}
async renameSessionThread(sessionId: string, newName: string): Promise<void> {
const threadId = this.sessionThreads.get(sessionId)
if (threadId) await this.client.renameThread(threadId, newName)
}
```
`deleteSessionThread` and `archiveSessionTopic` are optional — the base class provides no-op defaults.
---
## Step 8 — Register With Core
Before calling `core.start()`, register your adapter:
```typescript
import { OpenACPCore } from 'openacp'
import { MyPlatformAdapter } from './adapter.js'
const core = new OpenACPCore(config)
const adapter = new MyPlatformAdapter(core, config.adapters.myplatform)
core.registerAdapter('myplatform', adapter)
await core.start()
```
---
## Step 9 — Package as a Plugin
Adapter plugins implement `OpenACPPlugin` and register themselves in `setup()`:
```typescript
import type { OpenACPPlugin, PluginContext } from '@openacp/plugin-sdk'
import { MyPlatformAdapter } from './adapter.js'
const plugin: OpenACPPlugin = {
name: '@openacp/adapter-myplatform',
version: '1.0.0',
description: 'MyPlatform adapter for OpenACP',
async setup(ctx: PluginContext) {
const settings = await ctx.settings.getAll()
const adapter = new MyPlatformAdapter(ctx, settings)
ctx.registerAdapter('myplatform', adapter)
},
}
export default plugin
```
Adapter implementations can extend `MessagingAdapter` (for platforms with threads/topics) or `StreamAdapter` (for simpler integrations) from `@openacp/plugin-sdk`, instead of extending `ChannelAdapter` directly.
> **Note:** The previous `AdapterFactory` pattern is no longer used. All adapter registration now goes through the plugin system.
---
## Complete Minimal Adapter
```typescript
import { ChannelAdapter } from 'openacp'
import type {
ChannelConfig,
OutgoingMessage,
PermissionRequest,
NotificationMessage,
} from 'openacp'
import type { OpenACPCore } from 'openacp'
export class MinimalAdapter extends ChannelAdapter<OpenACPCore> {
private sessionThreads = new Map<string, string>()
async start(): Promise<void> {
// connect platform SDK, register listeners
}
async stop(): Promise<void> {
// disconnect
}
async sendMessage(sessionId: string, content: OutgoingMessage): Promise<void> {
if (content.type === 'text') {
console.log(`[${sessionId}] ${content.text}`)
}
}
async sendPermissionRequest(
sessionId: string,
request: PermissionRequest,
): Promise<void> {
// Render request.options, collect user input, call core.resolvePermission()
}
async sendNotification(notification: NotificationMessage): Promise<void> {
console.log(`[notification] ${notification.summary}`)
}
async createSessionThread(sessionId: string, name: string): Promise<string> {
this.sessionThreads.set(sessionId, sessionId)
return sessionId
}
async renameSessionThread(sessionId: string, newName: string): Promise<void> {
// update thread name in platform
}
}
```