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 — Export as AdapterFactory

So your adapter can be loaded as a plugin:

import type { AdapterFactory } from 'openacp'
import { MyPlatformAdapter } from './adapter.js'

export const adapterFactory: AdapterFactory = {
  name: 'myplatform',
  createAdapter(core, config) {
    return new MyPlatformAdapter(core, config)
  },
}

---

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