Plugin Overview

A Plugin is Downcity's unified extension product. It may provide Actions, Hooks, Resolves, System content, Availability, HTTP routes, lifecycle, and optional Mainview or Config surfaces.

Plugins do not belong to Agents. City owns the catalog, main modules, one instance per Plugin ID, and the complete lifecycle. Every registered Plugin is exposed to every Agent. A Session captures a stable Hook view at execution checkpoints.

SDK assembly

import { Agent } from "@downcity/agent";
import { City } from "@downcity/city";
import { create_builtin_plugin_registrations } from "@downcity/plugins";

const registrations = create_builtin_plugin_registrations();
const city = new City({ workspaces: [workspace], plugins: registrations });
const agent = new Agent({ id: "repo-helper", model });

city.agents.add(agent);

CityOptions.plugins or city.plugins.add() registers Plugins. city.agents.add() only registers the Agent.

PluginContext

Actions, Hooks, System providers, and Availability checks use a scope-specific PluginContext. It provides restricted handles for:

• city: Embassy and cross-Plugin collaboration ports.
• agent: identity, instructions, and Sessions.
• workspace: files, Shell, environment, and stable ID.
• session / turn: direct communication handles when the call belongs to a Session or Turn.
• config: a read-only snapshot of the current Plugin's City-level configuration.
• storage: private storage for the current Agent/Plugin scope.

Object handles support direct in-process communication; IDs provide stable identity and serialization. A Plugin does not need to receive only a session_id and resolve it through the host.

Unique instances and configuration

One City creates one instance per Plugin ID with one initialize/dispose lifecycle. Agent and Workspace belong only to each call Context. Each Plugin ID also has one City-level configuration, and every Agent receives the same context.config snapshot.

Recommended reading

1. Plugin Lifecycle
2. Plugin Actions
3. Plugin Hooks
4. Plugin Configuration
5. Plugin Development
6. Built-in Plugin manuals