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
built-in plugin exports
the local Agent plugins: [...] assembly entry point

Minimal skeleton

import type { Plugin } from "@downcity/agent";

export const notesPlugin: Plugin = {
  name: "notes",
  title: "Notes Helper",
  description: "Adds note-related actions and prompt guidance.",
  actions: {
    status: {
      execute: async ({ context }) => {
        return {
          success: true,
          data: {
            rootPath: context.rootPath,
          },
        };
      },
    },
  },
};

Attach the custom plugin to a local Agent

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

const notesPlugin: Plugin = {
  name: "notes",
  title: "Notes Helper",
  description: "Adds note-related actions and runtime guidance.",
  actions: {
    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: [notesPlugin],
});