Plugin Configuration

The Agent SDK registers already constructed Runtime Plugins. It does not define the CLI manifest, installer, or a PluginFactory:

await agent.plugins.register(new SkillPlugin());
await agent.plugins.unregister("skill");

SDK hosts

An embedded host passes runtime options directly through Plugin constructors:

import { ChatPlugin, TelegramChannel } from "@downcity/plugins/chat";

const chat = new ChatPlugin({
  queue: {
    max_concurrency: 4,
    merge_debounce_ms: 500,
  },
  channels: [
    new TelegramChannel({
      bot_token: process.env.TELEGRAM_BOT_TOKEN,
    }),
  ],
});

await agent.plugins.register(chat);

The SDK does not read the City database or interpret Agent Plugin Bindings. The host owns credential storage, configuration UI, and Runtime assembly.

CLI / City hosts

The CLI uses a separate control-plane protocol:

Plugin Catalog
  → Plugin Resource (complete Item)
  → Agent Plugin Binding (enabled + config + resource_ids)
  → CLI Runtime Factory
  → Agent Runtime Plugin

Built-in and external Plugins describe Binding configuration and optional Resource Items with standard JSON Schema. City validates and persists them through one path; when an Agent starts, the CLI resolves Resource IDs into complete Items before constructing Runtime Plugins.

Example Chat Binding:

{
  "config": {},
  "resource_ids": ["telegram-a1b2c3"]
}

This Factory belongs to the CLI and is not part of the @downcity/agent public API.

Recommended mental model

• Agent SDK: accepts and runs Plugin objects.
• SDK host: constructs Plugins and owns its configuration source.
• CLI / City: owns the Catalog, installation, Bindings, Schema forms, and Runtime Factory.

Related docs

• Plugin overview
• Plugin availability
• Plugin lifecycle