OpenACP/docs/gitbook/architecture/command-system.md
0xmrpeter 914fc013d6 refactor: rename 'dangerous mode' to 'bypass permissions' across documentation and code
- Updated all references from 'dangerous mode' to 'bypass permissions' in CLI commands, API documentation, and internal logic.
- Adjusted command usage and descriptions to reflect the new terminology for clarity and consistency.
- Removed warmup functionality from session management as part of the refactor.
2026-04-01 13:28:08 +07:00

9.9 KiB

Command System

OpenACP has a centralized command system for chat commands (/new, /cancel, /tts, etc.). Commands are registered by core and plugins, dispatched by adapters, and rendered using platform-specific renderers.

This system covers chat commands only (Telegram, Discord, Slack), not CLI commands (openacp start, openacp plugins install).


How It Works

User types /tts on
      |
      v
Adapter receives text
      |
      v
CommandRegistry.execute('/tts on', { channelId, userId, sessionId })
      |
      v
Find handler for 'tts'
      |
      v
Handler runs, returns CommandResponse
      |
      v
Adapter renders response (inline keyboard, embed, block kit, etc.)

Core Types

CommandDef

interface CommandDef {
  name: string              // 'new', 'tts', 'tunnel'
  description: string       // shown in /help
  usage?: string            // 'on|off', '<agent-name>'
  category: 'system' | 'plugin'
  pluginName?: string       // auto-set by registry
  handler(args: CommandArgs): Promise<CommandResponse | void>
}

CommandArgs

interface CommandArgs {
  raw: string               // text after command name
  options?: Record<string, string>  // Discord slash command options
  sessionId: string | null  // null if no active session
  channelId: string         // 'telegram', 'discord', 'slack'
  userId: string
  reply(content: string | CommandResponse): Promise<void>  // mid-execution feedback
  coreAccess?: CoreAccess   // restricted core access
}

The reply() method is an escape hatch for commands that need mid-execution feedback (e.g., /update sends "Checking..." then "Updating..." then "Done"). Most commands just return a CommandResponse.

CommandResponse

type CommandResponse =
  | { type: 'text'; text: string }
  | { type: 'menu'; title: string; options: MenuOption[] }
  | { type: 'list'; title: string; items: ListItem[] }
  | { type: 'confirm'; question: string; onYes: string; onNo: string }
  | { type: 'error'; message: string }
  | { type: 'silent' }

interface MenuOption {
  label: string
  command: string    // command to dispatch when selected
  hint?: string
}

interface ListItem {
  label: string
  detail?: string
}

CommandRegistry

class CommandRegistry {
  // Registration
  register(def: CommandDef, pluginName?: string): void
  unregister(name: string): void
  unregisterByPlugin(pluginName: string): void

  // Lookup
  get(name: string): CommandDef | undefined
  getAll(): CommandDef[]
  getByCategory(category: 'system' | 'plugin'): CommandDef[]

  // Execution
  async execute(commandString: string, baseArgs: Omit<CommandArgs, 'raw'>): Promise<CommandResponse>

  // Namespace
  getQualifiedName(name: string, pluginName: string): string
  getShortName(qualifiedName: string): string | undefined
}

System Commands vs Plugin Commands

System commands

Registered by core during boot, before plugins load. These handle fundamental operations:

Command Description
/new Create new session
/newchat New chat in same agent
/cancel Cancel current session
/status Show session status
/sessions List all sessions
/resume Resume a session
/agents List available agents
/install Install new agent
/help Show all commands (auto-generated)
/menu Show main menu
/restart Restart OpenACP
/update Update and restart
/doctor System diagnostics
/clear Clear session history

Plugin commands

Registered by plugins in their setup() via ctx.registerCommand():

Command Plugin Description
/tts @openacp/speech Toggle text-to-speech
/tunnel @openacp/tunnel Manage tunnels
/tunnels @openacp/tunnel List active tunnels
/usage @openacp/usage View usage and cost
/bypass @openacp/security Toggle auto-approve mode

Namespace Conflict Resolution

Every plugin command has two names:

  • Qualified: pluginScope:commandName -- always unique (e.g., speech:tts)
  • Short: commandName -- available if no conflict (e.g., tts)

Rules

  1. System commands always win -- plugins cannot override system command short names
  2. First plugin wins -- first plugin to register a short name keeps it
  3. Later conflicts get qualified name only -- the first registrant is not affected
  4. Warning logged on conflict

Example

Register 'tts' by @openacp/speech:
  -> short: /tts (no conflict)
  -> qualified: /speech:tts

Register 'status' by @openacp/tunnel:
  -> short: /status (conflict with system command)
  -> qualified: /tunnel:status
  -> warning: "Plugin command 'status' conflicts with system command"

Register 'check' by @community/plugin-a:
  -> short: /check (no conflict)

Register 'check' by @community/plugin-b:
  -> short: /check (conflict with plugin-a)
  -> plugin-a KEEPS /check
  -> plugin-b only accessible via /plugin-b:check

Adapter Dispatch and Rendering

Generic dispatch

Each adapter adds ONE generic dispatch handler that replaces all hardcoded command handlers:

// Telegram adapter
bot.on('message:text', async (ctx) => {
  const text = ctx.message.text
  if (!text.startsWith('/')) return

  const registry = core.serviceRegistry.get<CommandRegistry>('command-registry')
  if (!registry) return

  const response = await registry.execute(text, {
    sessionId: getSessionIdFromTopic(ctx),
    channelId: 'telegram',
    userId: String(ctx.from.id),
  })

  await this.renderResponse(response, ctx)
})

Response renderers

Adapters provide platform-specific renderers for each response type. Default renderers in the MessagingAdapter base class provide plain text fallback.

Telegram renders menu as inline keyboards, confirm as Yes/No buttons:

// menu -> inline keyboard
this.responseRenderers.set('menu', async (response, ctx) => {
  const keyboard = response.options.map(opt => [{
    text: `${opt.label}${opt.hint ? ' -- ' + opt.hint : ''}`,
    callback_data: toCallbackData(opt.command),
  }])
  await ctx.reply(response.title, {
    reply_markup: { inline_keyboard: keyboard },
  })
})

Discord renders menu as select menus, list as embeds.

Slack renders using Block Kit sections.

Button callback data

Commands triggered by button clicks use the c/ prefix:

c/tts on        -> dispatch /tts on
c/#42           -> lookup cached command (for commands > 64 bytes)

Other callback prefixes remain unchanged: p: for permission buttons, etc.


Two-Layer Architecture for Complex Commands

Some commands need multi-step interactive flows that vary by platform:

  • /new on Telegram: create forum topic, show agent picker keyboard, workspace selection
  • /new on Discord: use slash command options, channel creation
  • /resume: session scanner, session picker UI

How it works

Layer 1 -- Core logic (portable): handler returns a simple CommandResponse. Works on all adapters.

Layer 2 -- Platform orchestration (adapter-specific): adapter registers its own handler for the same command, using reply() for multi-step feedback and platform-specific APIs.

Override priority

  1. Adapter-specific handler (matches current channelId) -> highest priority
  2. Core handler -> fallback

If Telegram registers its own /new handler, Telegram users get the rich wizard. Discord users (without an override) get the simpler core handler with a menu response.


Writing a Plugin Command

Here's a complete example of a plugin that registers a command:

import type { OpenACPPlugin, PluginContext } from '@openacp/cli'

export default {
  name: '@community/weather',
  version: '1.0.0',
  description: 'Check weather in chat',
  permissions: ['commands:register', 'services:use'],

  async setup(ctx: PluginContext) {
    ctx.registerCommand({
      name: 'weather',
      description: 'Check weather for a city',
      usage: '<city>',
      category: 'plugin',

      handler: async (args) => {
        const city = args.raw.trim()
        if (!city) {
          return {
            type: 'text',
            text: 'Usage: /weather <city>',
          }
        }

        try {
          const weather = await fetchWeather(city)
          return {
            type: 'list',
            title: `Weather in ${city}`,
            items: [
              { label: 'Temperature', detail: `${weather.temp}C` },
              { label: 'Conditions', detail: weather.conditions },
              { label: 'Wind', detail: `${weather.wind} km/h` },
            ],
          }
        } catch {
          return {
            type: 'error',
            message: `Could not fetch weather for "${city}"`,
          }
        }
      },
    })
  },
} satisfies OpenACPPlugin

This command will:

  • Be available as /weather on all adapters (short name, no conflict)
  • Also available as /weather:weather (qualified name)
  • Appear in /help under "Plugin" category
  • Render as a list on Telegram (plain text), Discord (embed), and Slack (blocks)

Boot Flow

1. Core creates CommandRegistry, registers as service 'command-registry'
2. Core registers system commands (/new, /cancel, /help, etc.)
3. LifecycleManager boots plugins in dependency order
   -> Each plugin's setup() calls ctx.registerCommand()
4. After all plugins booted:
   -> Emit 'system:commands-ready' with registry.getAll()
5. Adapter plugins receive event -> sync with platform:
   - Telegram: bot.setMyCommands()
   - Discord: registerSlashCommands()
   - Slack: register message listener

Further Reading