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

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 AdapterFactory pattern 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
  }
}