- 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>
8.3 KiB
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
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.
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():
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.).
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().
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.
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):
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:
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():
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
AdapterFactorypattern is no longer used. All adapter registration now goes through the plugin system.
Complete Minimal Adapter
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
}
}