Plugin Overview

In current Downcity, plugin is the extension unit.

That means:

• capability is exposed through plugins
• runtime participation is exposed through plugins
• long-lived managed runtime modules are also modeled as plugins

If you want concrete built-in plugin manuals, continue with Plugins Docs.

One-sentence mental model

A plugin is the unit that owns one capability boundary in Downcity.

That plugin may be:

• action-first
• hook-oriented
• system-oriented
• lifecycle-owned
• HTTP-exposing

Two important families

Local plugins

These are usually attached directly inside one local SDK Agent.

Typical examples:

• skill
• web
• asr
• tts
• auth

Managed plugins

These are runtime-owned plugins that participate in one target agent lifecycle.

Typical examples:

• chat
• task
• memory
• contact
• shell

ActionSchedule is managed by Agent itself, so it is not listed as a plugin.

Managed plugins are the reason the old split runtime language is no longer the right model.

How plugins attach in the local SDK

import { Agent } from "@downcity/agent";
import { SkillPlugin, WebPlugin } from "@downcity/plugins";

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  tools: {},
  plugins: [new SkillPlugin(), new WebPlugin()],
});

const plugins = agent.plugins.list();

Important points:

• plugins is a registry owned by this specific Agent
• the SDK does not auto-register every built-in plugin
• you can use agent.plugins.list(), availability(), and runAction() directly
• prompt-time plugin system text comes only from plugins registered on that SDK Agent

What a plugin may contain

A full plugin may include:

• config
• actions
• setup
• usage
• hooks
• resolves
• system
• availability
• http
• lifecycle

Not every plugin needs all of them.

What “plugin enabled” means now

There are multiple layers:

• agent-level: did this local SDK Agent register the plugin
• runtime-level: is this managed plugin currently started or stopped
• plugin-level: does availability() currently say it is usable
• project-level: what runtime options exist under downcity.json.plugins.*

Do not collapse these into one idea.

Recommended reading order

1. Plugin Design Patterns
2. Plugin Lifecycle
3. Plugin Configuration
4. Plugin Actions
5. Plugin Hooks
6. Plugins Docs
7. Custom Plugin