Build a custom plugin with config, actions, hooks, system text, availability checks, lifecycle, and optional runtime HTTP routes

Custom Plugin

If the thing you want to add is mainly:

a set of actions
a set of hooks
one system text layer
one lifecycle-owned runtime boundary
one set of runtime HTTP routes

then a custom plugin is usually the right extension point.

Current public entry points

@downcity/agent exposes:

plugin types and contracts
the BasePlugin base class
the local Agent plugins: [...] assembly entry point

Built-in plugin classes are exported from @downcity/plugins.

Minimal skeleton

import { BasePlugin, type PluginActions } from "@downcity/agent";

export class NotesPlugin extends BasePlugin {
  readonly name = "notes";
  readonly title = "Notes Helper";
  readonly description = "Adds note-related actions and prompt guidance.";

  readonly actions: PluginActions = {
    status: {
      execute: async ({ context }) => {
        return {
          success: true,
          data: {
            rootPath: context.rootPath,
          },
        };
      },
    },
  };
}

Attach the custom plugin to a local Agent

import { Agent, BasePlugin, type PluginActions } from "@downcity/agent";

class NotesPlugin extends BasePlugin {
  readonly name = "notes";
  readonly title = "Notes Helper";
  readonly description = "Adds note-related actions and runtime guidance.";

  readonly actions: PluginActions = {
    status: {
      allowWhenDisabled: true,
      execute: async ({ context }) => ({
        success: true,
        data: {
          rootPath: context.rootPath,
        },
      }),
    },
  };
}

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