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>
347 lines
12 KiB
Markdown
347 lines
12 KiB
Markdown
# 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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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:
|
|
```typescript
|
|
// @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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```typescript
|
|
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](../api-reference/rest-api.md) 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
|
|
|
|
- [Architecture Overview](README.md) -- high-level picture
|
|
- [Plugin System](plugin-system.md) -- how plugins work
|
|
- [Writing Plugins](writing-plugins.md) -- build your own
|
|
- [Command System](command-system.md) -- how commands are registered and dispatched
|