OpenACP/docs/gitbook/architecture/built-in-plugins.md
0xmrpeter e8af143c87 docs: update gitbook for recent specs (03-29 to 04-01)
Add new pages: output modes, workspaces (multi-instance), app connectivity.
Update 16 existing pages to reflect: tunnel auto-start/keepalive, JWT auth
system, SSE streaming, session config options, one-liner install, startup UX,
lazy session resume, new CLI commands (attach, remote), and new chat commands
(/mode, /model, /thought, /dangerous).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 21:24:26 +07:00

12 KiB

Built-in Plugins Reference

OpenACP ships with 11 built-in plugins. They live in src/plugins/ and are loaded automatically on boot. Built-in plugins cannot be uninstalled, but they can be disabled.


Adapter Plugins

@openacp/telegram

Telegram messaging adapter using the grammY framework.

  • Service: adapter:telegram
  • Dependencies: @openacp/security, @openacp/file-service
  • Permissions: services:register, kernel:access, events:read, events:emit, commands:register

What it does: Connects OpenACP to Telegram. Creates forum topics for sessions, renders agent output as HTML messages with inline keyboards, handles permission buttons, and supports voice messages.

Settings (settings.json):

Key Type Description
botToken string Telegram Bot Token from @BotFather
chatId string Supergroup Chat ID
outputMode 'low' | 'medium' | 'high' How much agent output to show. The legacy key displayVerbosity is accepted for backward compatibility.

Commands: /outputmode, /verbosity (deprecated alias for /outputmode), /archive (adapter-specific), plus overrides for /new, /resume, /settings with multi-step wizards.


@openacp/discord

Discord messaging adapter using discord.js.

  • Service: adapter:discord
  • Dependencies: @openacp/security, @openacp/file-service
  • Permissions: services:register, kernel:access, events:read, events:emit, commands:register

What it does: Connects OpenACP to Discord. Creates threads for sessions, renders output with embeds and markdown, registers slash commands, and supports file uploads.

Settings:

Key Type Description
botToken string Discord Bot Token
guildId string Discord Server ID
outputMode 'low' | 'medium' | 'high' How much agent output to show. The legacy key displayVerbosity is accepted for backward compatibility.

Commands: /outputmode, /verbosity (deprecated alias).


@openacp/slack

Slack messaging adapter using @slack/bolt.

  • Service: adapter:slack
  • Dependencies: @openacp/security, @openacp/file-service
  • Permissions: services:register, kernel:access, events:read, events:emit, commands:register

What it does: Connects OpenACP to Slack via Socket Mode. Creates channels/threads for sessions, renders output with Block Kit, and handles interactive components.

Settings:

Key Type Description
botToken string Slack Bot Token
appToken string Slack App-Level Token (for Socket Mode)
signingSecret string Slack Signing Secret

Service Plugins

@openacp/security

Access control and rate limiting.

  • Service: security (implements SecurityService)
  • Dependencies: none
  • Permissions: services:register, events:read, middleware:register

What it does: Checks if users are allowed to interact with OpenACP (allowedUserIds), enforces session limits (maxConcurrentSessions), and provides user role management.

Service interface:

interface SecurityService {
  checkAccess(userId: string): Promise<{ allowed: boolean; reason?: string }>
  checkSessionLimit(userId: string): Promise<{ allowed: boolean; reason?: string }>
  getUserRole(userId: string): Promise<'admin' | 'user' | 'blocked'>
}

Commands: /bypass on|off -- toggle auto-approve mode for all permissions.

Config: Uses core config.json security section (allowedUserIds, maxConcurrentSessions).


@openacp/file-service

File I/O for agent operations.

  • Service: file-service (implements FileServiceInterface)
  • Dependencies: none
  • Permissions: services:register, middleware:register

What it does: Handles file operations that agents request -- saving attachments, resolving file paths, reading file contents with line ranges, and audio format conversion (OGG to WAV for speech).

Service interface:

interface FileServiceInterface {
  saveFile(sessionId: string, fileName: string, data: Buffer, mimeType: string): Promise<Attachment>
  resolveFile(filePath: string): Promise<Attachment | null>
  readTextFileWithRange(path: string, opts?: { line?: number; limit?: number }): Promise<string>
  convertOggToWav(oggData: Buffer): Promise<Buffer>
}

@openacp/speech

Text-to-speech and speech-to-text with pluggable providers.

  • Service: speech (implements SpeechServiceInterface)
  • Dependencies: @openacp/file-service
  • Optional dependencies: none
  • Permissions: services:register, services:use, commands:register

What it does: Provides TTS (text-to-speech) and STT (speech-to-text) capabilities. Ships with two built-in providers: Edge TTS and Groq STT. Community plugins can add more providers via registerTTSProvider() / registerSTTProvider().

Service interface:

interface SpeechServiceInterface {
  textToSpeech(text: string, opts?: { language?: string; voice?: string }): Promise<Buffer>
  speechToText(audio: Buffer, opts?: { language?: string }): Promise<string>
  registerTTSProvider(name: string, provider: TTSProvider): void
  registerSTTProvider(name: string, provider: STTProvider): void
}

Settings:

Key Type Description
stt.provider string STT provider name (default: 'groq')
tts.provider string TTS provider name (default: 'edge-tts')

Commands: /tts on|off -- toggle text-to-speech for the current session.

Extension point: Community plugins can add providers:

// @community/speech-elevenlabs setup()
const speech = ctx.getService<SpeechServiceInterface>('speech')
speech.registerTTSProvider('elevenlabs', new ElevenLabsTTS())

@openacp/tunnel

Expose local ports publicly via tunnel providers.

  • Service: tunnel (implements TunnelServiceInterface)
  • Dependencies: none
  • Permissions: services:register, commands:register

What it does: Creates public URLs for local development servers. Useful when agents need to preview web applications they're building. Ships with providers: Cloudflare Tunnel, ngrok, bore, tailscale.

Service interface:

interface TunnelServiceInterface {
  getPublicUrl(): string | undefined
  isConnected(): boolean
  start(): Promise<string>   // returns public URL
  stop(): Promise<void>
}

Settings:

Key Type Description
enabled boolean Enable tunnel on startup
provider string Tunnel provider ('cloudflare', 'ngrok', 'bore', 'tailscale')

Commands: /tunnel start|stop|status, /tunnels -- manage and list tunnels.


@openacp/usage

Cost tracking and budget management.

  • Service: usage (implements UsageService)
  • Dependencies: none
  • Permissions: services:register, events:read, commands:register, storage:read, storage:write

What it does: Tracks API usage costs per session and month. Enforces monthly budgets and sends warnings when approaching limits.

Service interface:

interface UsageService {
  trackUsage(record: UsageRecord): Promise<void>
  checkBudget(sessionId: string): Promise<{ ok: boolean; percent: number; warning?: string }>
  getSummary(period: string): Promise<UsageSummary>
}

Settings:

Key Type Description
enabled boolean Enable usage tracking
monthlyBudget number Monthly budget in USD

Commands: /usage -- view usage summary and budget status.


@openacp/notifications

Cross-session notification delivery.

  • Service: notifications (implements NotificationService)
  • Dependencies: none
  • Permissions: services:register, events:read

What it does: Delivers notifications across sessions. When a session completes, errors, or hits a budget warning, notifications are sent to dedicated notification channels/topics on all active adapters.

Service interface:

interface NotificationService {
  notify(channelId: string, notification: NotificationMessage): Promise<void>
  notifyAll(notification: NotificationMessage): Promise<void>
}

@openacp/context

Conversation history and session resume.

  • Service: context (implements ContextService)
  • Dependencies: none
  • Permissions: services:register, events:read, storage:read, storage:write

What it does: Stores conversation context and enables session resume. When resuming a session, builds a context summary that can be injected into the new agent's initial prompt. Supports pluggable context providers.

Service interface:

interface ContextService {
  buildContext(sessionId: string, opts?: { maxTokens?: number }): Promise<string>
  registerProvider(provider: ContextProvider): void
}

@openacp/api-server

REST API, Server-Sent Events, and authentication for external integrations.

  • Service: api-server (implements ApiServerService)
  • Dependencies: @openacp/security
  • Permissions: services:register, kernel:access, events:read

What it does: Exposes a Fastify-based REST API with schema validation (Zod), Swagger/OpenAPI documentation, CORS, and rate limiting. Provides session management, prompt delivery, agent events via SSE, JWT authentication, and file viewer routes. Plugins can register additional routes via ApiServerService.registerPlugin().

Settings:

Key Type Description
port number HTTP port (default: 21420)

Key capabilities:

  • Structured routes — /api/v1/* endpoints for sessions, agents, config, system, commands, and auth
  • JWT authentication — two-tier auth with secret token (master key) and scoped JWT access tokens
  • SSE streaming — real-time session events, agent output, and health pings via GET /api/v1/sse/sessions/:id/stream
  • File viewer — serves file, diff, and output viewer routes (merged from the former standalone viewer server)
  • Plugin extensibility — plugins register additional Fastify routes via the ApiServerService
  • Swagger UI — auto-generated API documentation at /docs

See the REST API reference for the full endpoint list.


SSE Manager (part of @openacp/api-server)

The SSE (Server-Sent Events) manager is integrated into the API server plugin rather than being a separate plugin. It provides real-time event streaming for app clients.

What it does: Broadcasts session lifecycle events, agent output, and health pings over SSE connections. Supports per-session filtering and automatic cleanup on disconnect.

Event types:

Event Description
session:created A new session was created
session:updated Session state changed (status, name, etc.)
session:deleted A session was destroyed
agent:event Agent output (text, tool calls, errors)
permission:request A permission request is pending
health Periodic health ping (every 30s) with memory and uptime stats

Connection: GET /api/v1/sse/sessions/:id/stream?token=<jwt> for per-session streams, or GET /api/events?token=<api-secret> for all events.

Reconnect support: A 100-event circular buffer per session enables replay on reconnect — if the client missed fewer than 100 events, they are replayed on reconnection.


Plugin Dependency Graph

@openacp/security          (no deps)
@openacp/file-service      (no deps)
@openacp/notifications     (no deps)
@openacp/context           (no deps)
@openacp/usage             (no deps)
@openacp/tunnel            (no deps)
@openacp/speech            -> @openacp/file-service
@openacp/api-server        -> @openacp/security
@openacp/telegram          -> @openacp/security, @openacp/file-service
@openacp/discord           -> @openacp/security, @openacp/file-service
@openacp/slack             -> @openacp/security, @openacp/file-service

Plugins at the top (no deps) load first. Adapter plugins load last since they depend on services being available.


Further Reading