feat: add plugin architecture

src/plugins/cli.ts

@@ -0,0 +1,57 @@
+import type { Command } from "commander";
+
+import {
+  resolveAgentWorkspaceDir,
+  resolveDefaultAgentId,
+} from "../agents/agent-scope.js";
+import type { ClawdbotConfig } from "../config/config.js";
+import { loadConfig } from "../config/config.js";
+import { createSubsystemLogger } from "../logging.js";
+import { loadClawdbotPlugins } from "./loader.js";
+import type { PluginLogger } from "./types.js";
+
+const log = createSubsystemLogger("plugins");
+
+export function registerPluginCliCommands(
+  program: Command,
+  cfg?: ClawdbotConfig,
+) {
+  const config = cfg ?? loadConfig();
+  const workspaceDir = resolveAgentWorkspaceDir(
+    config,
+    resolveDefaultAgentId(config),
+  );
+  const logger: PluginLogger = {
+    info: (msg: string) => log.info(msg),
+    warn: (msg: string) => log.warn(msg),
+    error: (msg: string) => log.error(msg),
+    debug: (msg: string) => log.debug(msg),
+  };
+  const registry = loadClawdbotPlugins({
+    config,
+    workspaceDir,
+    logger,
+  });
+
+  for (const entry of registry.cliRegistrars) {
+    try {
+      const result = entry.register({
+        program,
+        config,
+        workspaceDir,
+        logger,
+      });
+      if (result && typeof (result as Promise<void>).then === "function") {
+        void (result as Promise<void>).catch((err) => {
+          log.warn(
+            `plugin CLI register failed (${entry.pluginId}): ${String(err)}`,
+          );
+        });
+      }
+    } catch (err) {
+      log.warn(
+        `plugin CLI register failed (${entry.pluginId}): ${String(err)}`,
+      );
+    }
+  }
+}

src/plugins/discovery.test.ts

@@ -0,0 +1,106 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const tempDirs: string[] = [];
+
+function makeTempDir() {
+  const dir = path.join(os.tmpdir(), `clawdbot-plugins-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function withStateDir<T>(stateDir: string, fn: () => Promise<T>) {
+  const prev = process.env.CLAWDBOT_STATE_DIR;
+  process.env.CLAWDBOT_STATE_DIR = stateDir;
+  vi.resetModules();
+  try {
+    return await fn();
+  } finally {
+    if (prev === undefined) {
+      delete process.env.CLAWDBOT_STATE_DIR;
+    } else {
+      process.env.CLAWDBOT_STATE_DIR = prev;
+    }
+    vi.resetModules();
+  }
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup failures
+    }
+  }
+});
+
+describe("discoverClawdbotPlugins", () => {
+  it("discovers global and workspace extensions", async () => {
+    const stateDir = makeTempDir();
+    const workspaceDir = path.join(stateDir, "workspace");
+
+    const globalExt = path.join(stateDir, "extensions");
+    fs.mkdirSync(globalExt, { recursive: true });
+    fs.writeFileSync(
+      path.join(globalExt, "alpha.ts"),
+      "export default function () {}",
+      "utf-8",
+    );
+
+    const workspaceExt = path.join(workspaceDir, ".clawdbot", "extensions");
+    fs.mkdirSync(workspaceExt, { recursive: true });
+    fs.writeFileSync(
+      path.join(workspaceExt, "beta.ts"),
+      "export default function () {}",
+      "utf-8",
+    );
+
+    const { candidates } = await withStateDir(stateDir, async () => {
+      const { discoverClawdbotPlugins } = await import("./discovery.js");
+      return discoverClawdbotPlugins({ workspaceDir });
+    });
+
+    const ids = candidates.map((c) => c.idHint);
+    expect(ids).toContain("alpha");
+    expect(ids).toContain("beta");
+  });
+
+  it("loads package extension packs", async () => {
+    const stateDir = makeTempDir();
+    const globalExt = path.join(stateDir, "extensions", "pack");
+    fs.mkdirSync(path.join(globalExt, "src"), { recursive: true });
+
+    fs.writeFileSync(
+      path.join(globalExt, "package.json"),
+      JSON.stringify({
+        name: "pack",
+        clawdbot: { extensions: ["./src/one.ts", "./src/two.ts"] },
+      }),
+      "utf-8",
+    );
+    fs.writeFileSync(
+      path.join(globalExt, "src", "one.ts"),
+      "export default function () {}",
+      "utf-8",
+    );
+    fs.writeFileSync(
+      path.join(globalExt, "src", "two.ts"),
+      "export default function () {}",
+      "utf-8",
+    );
+
+    const { candidates } = await withStateDir(stateDir, async () => {
+      const { discoverClawdbotPlugins } = await import("./discovery.js");
+      return discoverClawdbotPlugins({});
+    });
+
+    const ids = candidates.map((c) => c.idHint);
+    expect(ids).toContain("pack/one");
+    expect(ids).toContain("pack/two");
+  });
+});

src/plugins/discovery.ts

@@ -0,0 +1,269 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { CONFIG_DIR, resolveUserPath } from "../utils.js";
+import type { PluginDiagnostic, PluginOrigin } from "./types.js";
+
+const EXTENSION_EXTS = new Set([".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"]);
+
+export type PluginCandidate = {
+  idHint: string;
+  source: string;
+  origin: PluginOrigin;
+  workspaceDir?: string;
+  packageName?: string;
+  packageVersion?: string;
+  packageDescription?: string;
+};
+
+export type PluginDiscoveryResult = {
+  candidates: PluginCandidate[];
+  diagnostics: PluginDiagnostic[];
+};
+
+type PackageManifest = {
+  name?: string;
+  version?: string;
+  description?: string;
+  clawdbot?: {
+    extensions?: string[];
+  };
+};
+
+function isExtensionFile(filePath: string): boolean {
+  const ext = path.extname(filePath);
+  if (!EXTENSION_EXTS.has(ext)) return false;
+  return !filePath.endsWith(".d.ts");
+}
+
+function readPackageManifest(dir: string): PackageManifest | null {
+  const manifestPath = path.join(dir, "package.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    return JSON.parse(raw) as PackageManifest;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePackageExtensions(manifest: PackageManifest): string[] {
+  const raw = manifest.clawdbot?.extensions;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter(Boolean);
+}
+
+function deriveIdHint(params: {
+  filePath: string;
+  packageName?: string;
+  hasMultipleExtensions: boolean;
+}): string {
+  const base = path.basename(params.filePath, path.extname(params.filePath));
+  const packageName = params.packageName?.trim();
+  if (!packageName) return base;
+  if (!params.hasMultipleExtensions) return packageName;
+  return `${packageName}/${base}`;
+}
+
+function addCandidate(params: {
+  candidates: PluginCandidate[];
+  seen: Set<string>;
+  idHint: string;
+  source: string;
+  origin: PluginOrigin;
+  workspaceDir?: string;
+  manifest?: PackageManifest | null;
+}) {
+  const resolved = path.resolve(params.source);
+  if (params.seen.has(resolved)) return;
+  params.seen.add(resolved);
+  const manifest = params.manifest ?? null;
+  params.candidates.push({
+    idHint: params.idHint,
+    source: resolved,
+    origin: params.origin,
+    workspaceDir: params.workspaceDir,
+    packageName: manifest?.name?.trim() || undefined,
+    packageVersion: manifest?.version?.trim() || undefined,
+    packageDescription: manifest?.description?.trim() || undefined,
+  });
+}
+
+function discoverInDirectory(params: {
+  dir: string;
+  origin: PluginOrigin;
+  workspaceDir?: string;
+  candidates: PluginCandidate[];
+  diagnostics: PluginDiagnostic[];
+  seen: Set<string>;
+}) {
+  if (!fs.existsSync(params.dir)) return;
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(params.dir, { withFileTypes: true });
+  } catch (err) {
+    params.diagnostics.push({
+      level: "warn",
+      message: `failed to read extensions dir: ${params.dir} (${String(err)})`,
+      source: params.dir,
+    });
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(params.dir, entry.name);
+    if (entry.isFile()) {
+      if (!isExtensionFile(fullPath)) continue;
+      addCandidate({
+        candidates: params.candidates,
+        seen: params.seen,
+        idHint: path.basename(entry.name, path.extname(entry.name)),
+        source: fullPath,
+        origin: params.origin,
+        workspaceDir: params.workspaceDir,
+      });
+    }
+    if (!entry.isDirectory()) continue;
+
+    const manifest = readPackageManifest(fullPath);
+    const extensions = manifest ? resolvePackageExtensions(manifest) : [];
+
+    if (extensions.length > 0) {
+      for (const extPath of extensions) {
+        const resolved = path.resolve(fullPath, extPath);
+        addCandidate({
+          candidates: params.candidates,
+          seen: params.seen,
+          idHint: deriveIdHint({
+            filePath: resolved,
+            packageName: manifest?.name,
+            hasMultipleExtensions: extensions.length > 1,
+          }),
+          source: resolved,
+          origin: params.origin,
+          workspaceDir: params.workspaceDir,
+          manifest,
+        });
+      }
+      continue;
+    }
+
+    const indexCandidates = ["index.ts", "index.js", "index.mjs", "index.cjs"];
+    const indexFile = indexCandidates
+      .map((candidate) => path.join(fullPath, candidate))
+      .find((candidate) => fs.existsSync(candidate));
+    if (indexFile && isExtensionFile(indexFile)) {
+      addCandidate({
+        candidates: params.candidates,
+        seen: params.seen,
+        idHint: entry.name,
+        source: indexFile,
+        origin: params.origin,
+        workspaceDir: params.workspaceDir,
+      });
+    }
+  }
+}
+
+function discoverFromPath(params: {
+  rawPath: string;
+  origin: PluginOrigin;
+  workspaceDir?: string;
+  candidates: PluginCandidate[];
+  diagnostics: PluginDiagnostic[];
+  seen: Set<string>;
+}) {
+  const resolved = resolveUserPath(params.rawPath);
+  if (!fs.existsSync(resolved)) {
+    params.diagnostics.push({
+      level: "warn",
+      message: `plugin path not found: ${resolved}`,
+      source: resolved,
+    });
+    return;
+  }
+
+  const stat = fs.statSync(resolved);
+  if (stat.isFile()) {
+    if (!isExtensionFile(resolved)) {
+      params.diagnostics.push({
+        level: "warn",
+        message: `plugin path is not a supported file: ${resolved}`,
+        source: resolved,
+      });
+      return;
+    }
+    addCandidate({
+      candidates: params.candidates,
+      seen: params.seen,
+      idHint: path.basename(resolved, path.extname(resolved)),
+      source: resolved,
+      origin: params.origin,
+      workspaceDir: params.workspaceDir,
+    });
+    return;
+  }
+
+  if (stat.isDirectory()) {
+    discoverInDirectory({
+      dir: resolved,
+      origin: params.origin,
+      workspaceDir: params.workspaceDir,
+      candidates: params.candidates,
+      diagnostics: params.diagnostics,
+      seen: params.seen,
+    });
+    return;
+  }
+}
+
+export function discoverClawdbotPlugins(params: {
+  workspaceDir?: string;
+  extraPaths?: string[];
+}): PluginDiscoveryResult {
+  const candidates: PluginCandidate[] = [];
+  const diagnostics: PluginDiagnostic[] = [];
+  const seen = new Set<string>();
+
+  const globalDir = path.join(CONFIG_DIR, "extensions");
+  discoverInDirectory({
+    dir: globalDir,
+    origin: "global",
+    candidates,
+    diagnostics,
+    seen,
+  });
+
+  const workspaceDir = params.workspaceDir?.trim();
+  if (workspaceDir) {
+    const workspaceRoot = resolveUserPath(workspaceDir);
+    const workspaceExt = path.join(workspaceRoot, ".clawdbot", "extensions");
+    discoverInDirectory({
+      dir: workspaceExt,
+      origin: "workspace",
+      workspaceDir: workspaceRoot,
+      candidates,
+      diagnostics,
+      seen,
+    });
+  }
+
+  const extra = params.extraPaths ?? [];
+  for (const extraPath of extra) {
+    if (typeof extraPath !== "string") continue;
+    const trimmed = extraPath.trim();
+    if (!trimmed) continue;
+    discoverFromPath({
+      rawPath: trimmed,
+      origin: "config",
+      workspaceDir: workspaceDir?.trim() || undefined,
+      candidates,
+      diagnostics,
+      seen,
+    });
+  }
+
+  return { candidates, diagnostics };
+}

src/plugins/loader.test.ts

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { loadClawdbotPlugins } from "./loader.js";
+
+type TempPlugin = { dir: string; file: string; id: string };
+
+const tempDirs: string[] = [];
+
+function makeTempDir() {
+  const dir = path.join(os.tmpdir(), `clawdbot-plugin-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  tempDirs.push(dir);
+  return dir;
+}
+
+function writePlugin(params: { id: string; body: string }): TempPlugin {
+  const dir = makeTempDir();
+  const file = path.join(dir, `${params.id}.js`);
+  fs.writeFileSync(file, params.body, "utf-8");
+  return { dir, file, id: params.id };
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup failures
+    }
+  }
+});
+
+describe("loadClawdbotPlugins", () => {
+  it("loads plugins from config paths", () => {
+    const plugin = writePlugin({
+      id: "allowed",
+      body: `export default function (api) { api.registerGatewayMethod("allowed.ping", ({ respond }) => respond(true, { ok: true })); }`,
+    });
+
+    const registry = loadClawdbotPlugins({
+      cache: false,
+      workspaceDir: plugin.dir,
+      config: {
+        plugins: {
+          load: { paths: [plugin.file] },
+          allow: ["allowed"],
+        },
+      },
+    });
+
+    expect(registry.plugins.length).toBe(1);
+    expect(registry.plugins[0]?.status).toBe("loaded");
+    expect(Object.keys(registry.gatewayHandlers)).toContain("allowed.ping");
+  });
+
+  it("denylist disables plugins even if allowed", () => {
+    const plugin = writePlugin({
+      id: "blocked",
+      body: `export default function () {}`,
+    });
+
+    const registry = loadClawdbotPlugins({
+      cache: false,
+      workspaceDir: plugin.dir,
+      config: {
+        plugins: {
+          load: { paths: [plugin.file] },
+          allow: ["blocked"],
+          deny: ["blocked"],
+        },
+      },
+    });
+
+    expect(registry.plugins[0]?.status).toBe("disabled");
+  });
+
+  it("fails fast on invalid plugin config", () => {
+    const plugin = writePlugin({
+      id: "configurable",
+      body: `export default {\n  id: "configurable",\n  configSchema: {\n    parse(value) {\n      if (!value || typeof value !== "object" || Array.isArray(value)) {\n        throw new Error("bad config");\n      }\n      return value;\n    }\n  },\n  register() {}\n};`,
+    });
+
+    const registry = loadClawdbotPlugins({
+      cache: false,
+      workspaceDir: plugin.dir,
+      config: {
+        plugins: {
+          load: { paths: [plugin.file] },
+          entries: {
+            configurable: {
+              config: "nope" as unknown as Record<string, unknown>,
+            },
+          },
+        },
+      },
+    });
+
+    expect(registry.plugins[0]?.status).toBe("error");
+    expect(registry.diagnostics.some((d) => d.level === "error")).toBe(true);
+  });
+});

src/plugins/loader.ts

@@ -0,0 +1,376 @@
+import { createJiti } from "jiti";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import type { GatewayRequestHandler } from "../gateway/server-methods/types.js";
+import { createSubsystemLogger } from "../logging.js";
+import { resolveUserPath } from "../utils.js";
+import { discoverClawdbotPlugins } from "./discovery.js";
+import {
+  createPluginRegistry,
+  type PluginRecord,
+  type PluginRegistry,
+} from "./registry.js";
+import type {
+  ClawdbotPluginConfigSchema,
+  ClawdbotPluginDefinition,
+  ClawdbotPluginModule,
+  PluginDiagnostic,
+  PluginLogger,
+} from "./types.js";
+
+export type PluginLoadResult = PluginRegistry;
+
+export type PluginLoadOptions = {
+  config?: ClawdbotConfig;
+  workspaceDir?: string;
+  logger?: PluginLogger;
+  coreGatewayHandlers?: Record<string, GatewayRequestHandler>;
+  cache?: boolean;
+};
+
+type NormalizedPluginsConfig = {
+  enabled: boolean;
+  allow: string[];
+  deny: string[];
+  loadPaths: string[];
+  entries: Record<
+    string,
+    { enabled?: boolean; config?: Record<string, unknown> }
+  >;
+};
+
+const registryCache = new Map<string, PluginRegistry>();
+
+const defaultLogger = () => createSubsystemLogger("plugins");
+
+const normalizeList = (value: unknown): string[] => {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter(Boolean);
+};
+
+const normalizePluginEntries = (
+  entries: unknown,
+): NormalizedPluginsConfig["entries"] => {
+  if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+    return {};
+  }
+  const normalized: NormalizedPluginsConfig["entries"] = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (!key.trim()) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      normalized[key] = {};
+      continue;
+    }
+    const entry = value as Record<string, unknown>;
+    normalized[key] = {
+      enabled: typeof entry.enabled === "boolean" ? entry.enabled : undefined,
+      config:
+        entry.config &&
+        typeof entry.config === "object" &&
+        !Array.isArray(entry.config)
+          ? (entry.config as Record<string, unknown>)
+          : undefined,
+    };
+  }
+  return normalized;
+};
+
+const normalizePluginsConfig = (
+  config?: ClawdbotConfig["plugins"],
+): NormalizedPluginsConfig => {
+  return {
+    enabled: config?.enabled !== false,
+    allow: normalizeList(config?.allow),
+    deny: normalizeList(config?.deny),
+    loadPaths: normalizeList(config?.load?.paths),
+    entries: normalizePluginEntries(config?.entries),
+  };
+};
+
+function buildCacheKey(params: {
+  workspaceDir?: string;
+  plugins: NormalizedPluginsConfig;
+}): string {
+  const workspaceKey = params.workspaceDir
+    ? resolveUserPath(params.workspaceDir)
+    : "";
+  return `${workspaceKey}::${JSON.stringify(params.plugins)}`;
+}
+
+function resolveEnableState(
+  id: string,
+  config: NormalizedPluginsConfig,
+): { enabled: boolean; reason?: string } {
+  if (!config.enabled) {
+    return { enabled: false, reason: "plugins disabled" };
+  }
+  if (config.deny.includes(id)) {
+    return { enabled: false, reason: "blocked by denylist" };
+  }
+  if (config.allow.length > 0 && !config.allow.includes(id)) {
+    return { enabled: false, reason: "not in allowlist" };
+  }
+  const entry = config.entries[id];
+  if (entry?.enabled === false) {
+    return { enabled: false, reason: "disabled in config" };
+  }
+  return { enabled: true };
+}
+
+function validatePluginConfig(params: {
+  schema?: ClawdbotPluginConfigSchema;
+  value?: Record<string, unknown>;
+}): { ok: boolean; value?: Record<string, unknown>; errors?: string[] } {
+  const schema = params.schema;
+  if (!schema) return { ok: true, value: params.value };
+
+  if (typeof schema.validate === "function") {
+    const result = schema.validate(params.value);
+    if (result.ok) {
+      return { ok: true, value: result.value as Record<string, unknown> };
+    }
+    return { ok: false, errors: result.errors };
+  }
+
+  if (typeof schema.safeParse === "function") {
+    const result = schema.safeParse(params.value);
+    if (result.success) {
+      return { ok: true, value: result.data as Record<string, unknown> };
+    }
+    const issues = result.error?.issues ?? [];
+    const errors = issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+      return `${path}: ${issue.message}`;
+    });
+    return { ok: false, errors };
+  }
+
+  if (typeof schema.parse === "function") {
+    try {
+      const parsed = schema.parse(params.value);
+      return { ok: true, value: parsed as Record<string, unknown> };
+    } catch (err) {
+      return { ok: false, errors: [String(err)] };
+    }
+  }
+
+  return { ok: true, value: params.value };
+}
+
+function resolvePluginModuleExport(moduleExport: unknown): {
+  definition?: ClawdbotPluginDefinition;
+  register?: ClawdbotPluginDefinition["register"];
+} {
+  const resolved =
+    moduleExport &&
+    typeof moduleExport === "object" &&
+    "default" in (moduleExport as Record<string, unknown>)
+      ? (moduleExport as { default: unknown }).default
+      : moduleExport;
+  if (typeof resolved === "function") {
+    return {
+      register: resolved as ClawdbotPluginDefinition["register"],
+    };
+  }
+  if (resolved && typeof resolved === "object") {
+    const def = resolved as ClawdbotPluginDefinition;
+    const register = def.register ?? def.activate;
+    return { definition: def, register };
+  }
+  return {};
+}
+
+function createPluginRecord(params: {
+  id: string;
+  name?: string;
+  description?: string;
+  version?: string;
+  source: string;
+  origin: PluginRecord["origin"];
+  workspaceDir?: string;
+  enabled: boolean;
+  configSchema: boolean;
+}): PluginRecord {
+  return {
+    id: params.id,
+    name: params.name ?? params.id,
+    description: params.description,
+    version: params.version,
+    source: params.source,
+    origin: params.origin,
+    workspaceDir: params.workspaceDir,
+    enabled: params.enabled,
+    status: params.enabled ? "loaded" : "disabled",
+    toolNames: [],
+    gatewayMethods: [],
+    cliCommands: [],
+    services: [],
+    configSchema: params.configSchema,
+  };
+}
+
+function pushDiagnostics(
+  diagnostics: PluginDiagnostic[],
+  append: PluginDiagnostic[],
+) {
+  diagnostics.push(...append);
+}
+
+export function loadClawdbotPlugins(
+  options: PluginLoadOptions = {},
+): PluginRegistry {
+  const cfg = options.config ?? {};
+  const logger = options.logger ?? defaultLogger();
+  const normalized = normalizePluginsConfig(cfg.plugins);
+  const cacheKey = buildCacheKey({
+    workspaceDir: options.workspaceDir,
+    plugins: normalized,
+  });
+  const cacheEnabled = options.cache !== false;
+  if (cacheEnabled) {
+    const cached = registryCache.get(cacheKey);
+    if (cached) return cached;
+  }
+
+  const { registry, createApi } = createPluginRegistry({
+    logger,
+    coreGatewayHandlers: options.coreGatewayHandlers as Record<
+      string,
+      GatewayRequestHandler
+    >,
+  });
+
+  const discovery = discoverClawdbotPlugins({
+    workspaceDir: options.workspaceDir,
+    extraPaths: normalized.loadPaths,
+  });
+  pushDiagnostics(registry.diagnostics, discovery.diagnostics);
+
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: true,
+  });
+
+  for (const candidate of discovery.candidates) {
+    const enableState = resolveEnableState(candidate.idHint, normalized);
+    const entry = normalized.entries[candidate.idHint];
+    const record = createPluginRecord({
+      id: candidate.idHint,
+      name: candidate.packageName ?? candidate.idHint,
+      description: candidate.packageDescription,
+      version: candidate.packageVersion,
+      source: candidate.source,
+      origin: candidate.origin,
+      workspaceDir: candidate.workspaceDir,
+      enabled: enableState.enabled,
+      configSchema: false,
+    });
+
+    if (!enableState.enabled) {
+      record.status = "disabled";
+      record.error = enableState.reason;
+      registry.plugins.push(record);
+      continue;
+    }
+
+    let mod: ClawdbotPluginModule | null = null;
+    try {
+      mod = jiti(candidate.source) as ClawdbotPluginModule;
+    } catch (err) {
+      record.status = "error";
+      record.error = String(err);
+      registry.plugins.push(record);
+      registry.diagnostics.push({
+        level: "error",
+        pluginId: record.id,
+        source: record.source,
+        message: `failed to load plugin: ${String(err)}`,
+      });
+      continue;
+    }
+
+    const resolved = resolvePluginModuleExport(mod);
+    const definition = resolved.definition;
+    const register = resolved.register;
+
+    if (definition?.id && definition.id !== record.id) {
+      registry.diagnostics.push({
+        level: "warn",
+        pluginId: record.id,
+        source: record.source,
+        message: `plugin id mismatch (config uses "${record.id}", export uses "${definition.id}")`,
+      });
+    }
+
+    record.name = definition?.name ?? record.name;
+    record.description = definition?.description ?? record.description;
+    record.version = definition?.version ?? record.version;
+    record.configSchema = Boolean(definition?.configSchema);
+
+    const validatedConfig = validatePluginConfig({
+      schema: definition?.configSchema,
+      value: entry?.config,
+    });
+
+    if (!validatedConfig.ok) {
+      record.status = "error";
+      record.error = `invalid config: ${validatedConfig.errors?.join(", ")}`;
+      registry.plugins.push(record);
+      registry.diagnostics.push({
+        level: "error",
+        pluginId: record.id,
+        source: record.source,
+        message: record.error,
+      });
+      continue;
+    }
+
+    if (typeof register !== "function") {
+      record.status = "error";
+      record.error = "plugin export missing register/activate";
+      registry.plugins.push(record);
+      registry.diagnostics.push({
+        level: "error",
+        pluginId: record.id,
+        source: record.source,
+        message: record.error,
+      });
+      continue;
+    }
+
+    const api = createApi(record, {
+      config: cfg,
+      pluginConfig: validatedConfig.value,
+    });
+
+    try {
+      const result = register(api);
+      if (result && typeof (result as Promise<void>).then === "function") {
+        registry.diagnostics.push({
+          level: "warn",
+          pluginId: record.id,
+          source: record.source,
+          message:
+            "plugin register returned a promise; async registration is ignored",
+        });
+      }
+      registry.plugins.push(record);
+    } catch (err) {
+      record.status = "error";
+      record.error = String(err);
+      registry.plugins.push(record);
+      registry.diagnostics.push({
+        level: "error",
+        pluginId: record.id,
+        source: record.source,
+        message: `plugin failed during register: ${String(err)}`,
+      });
+    }
+  }
+
+  if (cacheEnabled) {
+    registryCache.set(cacheKey, registry);
+  }
+  return registry;
+}

src/plugins/registry.ts

@@ -0,0 +1,206 @@
+import type { AnyAgentTool } from "../agents/tools/common.js";
+import type {
+  GatewayRequestHandler,
+  GatewayRequestHandlers,
+} from "../gateway/server-methods/types.js";
+import { resolveUserPath } from "../utils.js";
+import type {
+  ClawdbotPluginApi,
+  ClawdbotPluginCliRegistrar,
+  ClawdbotPluginService,
+  ClawdbotPluginToolContext,
+  ClawdbotPluginToolFactory,
+  PluginDiagnostic,
+  PluginLogger,
+  PluginOrigin,
+} from "./types.js";
+
+export type PluginToolRegistration = {
+  pluginId: string;
+  factory: ClawdbotPluginToolFactory;
+  names: string[];
+  source: string;
+};
+
+export type PluginCliRegistration = {
+  pluginId: string;
+  register: ClawdbotPluginCliRegistrar;
+  commands: string[];
+  source: string;
+};
+
+export type PluginServiceRegistration = {
+  pluginId: string;
+  service: ClawdbotPluginService;
+  source: string;
+};
+
+export type PluginRecord = {
+  id: string;
+  name: string;
+  version?: string;
+  description?: string;
+  source: string;
+  origin: PluginOrigin;
+  workspaceDir?: string;
+  enabled: boolean;
+  status: "loaded" | "disabled" | "error";
+  error?: string;
+  toolNames: string[];
+  gatewayMethods: string[];
+  cliCommands: string[];
+  services: string[];
+  configSchema: boolean;
+};
+
+export type PluginRegistry = {
+  plugins: PluginRecord[];
+  tools: PluginToolRegistration[];
+  gatewayHandlers: GatewayRequestHandlers;
+  cliRegistrars: PluginCliRegistration[];
+  services: PluginServiceRegistration[];
+  diagnostics: PluginDiagnostic[];
+};
+
+export type PluginRegistryParams = {
+  logger: PluginLogger;
+  coreGatewayHandlers?: GatewayRequestHandlers;
+};
+
+export function createPluginRegistry(registryParams: PluginRegistryParams) {
+  const registry: PluginRegistry = {
+    plugins: [],
+    tools: [],
+    gatewayHandlers: {},
+    cliRegistrars: [],
+    services: [],
+    diagnostics: [],
+  };
+  const coreGatewayMethods = new Set(
+    Object.keys(registryParams.coreGatewayHandlers ?? {}),
+  );
+
+  const pushDiagnostic = (diag: PluginDiagnostic) => {
+    registry.diagnostics.push(diag);
+  };
+
+  const registerTool = (
+    record: PluginRecord,
+    tool: AnyAgentTool | ClawdbotPluginToolFactory,
+    opts?: { name?: string; names?: string[] },
+  ) => {
+    const names = opts?.names ?? (opts?.name ? [opts.name] : []);
+    const factory: ClawdbotPluginToolFactory =
+      typeof tool === "function"
+        ? tool
+        : (_ctx: ClawdbotPluginToolContext) => tool;
+
+    if (typeof tool !== "function") {
+      names.push(tool.name);
+    }
+
+    const normalized = names.map((name) => name.trim()).filter(Boolean);
+    if (normalized.length > 0) {
+      record.toolNames.push(...normalized);
+    }
+    registry.tools.push({
+      pluginId: record.id,
+      factory,
+      names: normalized,
+      source: record.source,
+    });
+  };
+
+  const registerGatewayMethod = (
+    record: PluginRecord,
+    method: string,
+    handler: GatewayRequestHandler,
+  ) => {
+    const trimmed = method.trim();
+    if (!trimmed) return;
+    if (coreGatewayMethods.has(trimmed) || registry.gatewayHandlers[trimmed]) {
+      pushDiagnostic({
+        level: "error",
+        pluginId: record.id,
+        source: record.source,
+        message: `gateway method already registered: ${trimmed}`,
+      });
+      return;
+    }
+    registry.gatewayHandlers[trimmed] = handler;
+    record.gatewayMethods.push(trimmed);
+  };
+
+  const registerCli = (
+    record: PluginRecord,
+    registrar: ClawdbotPluginCliRegistrar,
+    opts?: { commands?: string[] },
+  ) => {
+    const commands = (opts?.commands ?? [])
+      .map((cmd) => cmd.trim())
+      .filter(Boolean);
+    record.cliCommands.push(...commands);
+    registry.cliRegistrars.push({
+      pluginId: record.id,
+      register: registrar,
+      commands,
+      source: record.source,
+    });
+  };
+
+  const registerService = (
+    record: PluginRecord,
+    service: ClawdbotPluginService,
+  ) => {
+    const id = service.id.trim();
+    if (!id) return;
+    record.services.push(id);
+    registry.services.push({
+      pluginId: record.id,
+      service,
+      source: record.source,
+    });
+  };
+
+  const normalizeLogger = (logger: PluginLogger): PluginLogger => ({
+    info: logger.info,
+    warn: logger.warn,
+    error: logger.error,
+    debug: logger.debug,
+  });
+
+  const createApi = (
+    record: PluginRecord,
+    params: {
+      config: ClawdbotPluginApi["config"];
+      pluginConfig?: Record<string, unknown>;
+    },
+  ): ClawdbotPluginApi => {
+    return {
+      id: record.id,
+      name: record.name,
+      version: record.version,
+      description: record.description,
+      source: record.source,
+      config: params.config,
+      pluginConfig: params.pluginConfig,
+      logger: normalizeLogger(registryParams.logger),
+      registerTool: (tool, opts) => registerTool(record, tool, opts),
+      registerGatewayMethod: (method, handler) =>
+        registerGatewayMethod(record, method, handler),
+      registerCli: (registrar, opts) => registerCli(record, registrar, opts),
+      registerService: (service) => registerService(record, service),
+      resolvePath: (input: string) => resolveUserPath(input),
+    };
+  };
+
+  return {
+    registry,
+    createApi,
+    pushDiagnostic,
+    registerTool,
+    registerGatewayMethod,
+    registerCli,
+    registerService,
+  };
+}

src/plugins/services.ts

@@ -0,0 +1,70 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import { STATE_DIR_CLAWDBOT } from "../config/paths.js";
+import { createSubsystemLogger } from "../logging.js";
+import type { PluginRegistry } from "./registry.js";
+
+const log = createSubsystemLogger("plugins");
+
+export type PluginServicesHandle = {
+  stop: () => Promise<void>;
+};
+
+export async function startPluginServices(params: {
+  registry: PluginRegistry;
+  config: ClawdbotConfig;
+  workspaceDir?: string;
+}): Promise<PluginServicesHandle> {
+  const running: Array<{
+    id: string;
+    stop?: () => void | Promise<void>;
+  }> = [];
+
+  for (const entry of params.registry.services) {
+    const service = entry.service;
+    try {
+      await service.start({
+        config: params.config,
+        workspaceDir: params.workspaceDir,
+        stateDir: STATE_DIR_CLAWDBOT,
+        logger: {
+          info: (msg) => log.info(msg),
+          warn: (msg) => log.warn(msg),
+          error: (msg) => log.error(msg),
+          debug: (msg) => log.debug(msg),
+        },
+      });
+      running.push({
+        id: service.id,
+        stop: service.stop
+          ? () =>
+              service.stop?.({
+                config: params.config,
+                workspaceDir: params.workspaceDir,
+                stateDir: STATE_DIR_CLAWDBOT,
+                logger: {
+                  info: (msg) => log.info(msg),
+                  warn: (msg) => log.warn(msg),
+                  error: (msg) => log.error(msg),
+                  debug: (msg) => log.debug(msg),
+                },
+              })
+          : undefined,
+      });
+    } catch (err) {
+      log.error(`plugin service failed (${service.id}): ${String(err)}`);
+    }
+  }
+
+  return {
+    stop: async () => {
+      for (const entry of running.reverse()) {
+        if (!entry.stop) continue;
+        try {
+          await entry.stop();
+        } catch (err) {
+          log.warn(`plugin service stop failed (${entry.id}): ${String(err)}`);
+        }
+      }
+    },
+  };
+}

src/plugins/status.ts

@@ -0,0 +1,42 @@
+import {
+  resolveAgentWorkspaceDir,
+  resolveDefaultAgentId,
+} from "../agents/agent-scope.js";
+import { resolveDefaultAgentWorkspaceDir } from "../agents/workspace.js";
+import { loadConfig } from "../config/config.js";
+import { createSubsystemLogger } from "../logging.js";
+import { loadClawdbotPlugins } from "./loader.js";
+import type { PluginRegistry } from "./registry.js";
+
+export type PluginStatusReport = PluginRegistry & {
+  workspaceDir?: string;
+};
+
+const log = createSubsystemLogger("plugins");
+
+export function buildPluginStatusReport(params?: {
+  config?: ReturnType<typeof loadConfig>;
+  workspaceDir?: string;
+}): PluginStatusReport {
+  const config = params?.config ?? loadConfig();
+  const workspaceDir = params?.workspaceDir
+    ? params.workspaceDir
+    : (resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config)) ??
+      resolveDefaultAgentWorkspaceDir());
+
+  const registry = loadClawdbotPlugins({
+    config,
+    workspaceDir,
+    logger: {
+      info: (msg) => log.info(msg),
+      warn: (msg) => log.warn(msg),
+      error: (msg) => log.error(msg),
+      debug: (msg) => log.debug(msg),
+    },
+  });
+
+  return {
+    workspaceDir,
+    ...registry,
+  };
+}

src/plugins/tools.ts

@@ -0,0 +1,47 @@
+import type { AnyAgentTool } from "../agents/tools/common.js";
+import { createSubsystemLogger } from "../logging.js";
+import { loadClawdbotPlugins } from "./loader.js";
+import type { ClawdbotPluginToolContext } from "./types.js";
+
+const log = createSubsystemLogger("plugins");
+
+export function resolvePluginTools(params: {
+  context: ClawdbotPluginToolContext;
+  existingToolNames?: Set<string>;
+}): AnyAgentTool[] {
+  const registry = loadClawdbotPlugins({
+    config: params.context.config,
+    workspaceDir: params.context.workspaceDir,
+    logger: {
+      info: (msg) => log.info(msg),
+      warn: (msg) => log.warn(msg),
+      error: (msg) => log.error(msg),
+      debug: (msg) => log.debug(msg),
+    },
+  });
+
+  const tools: AnyAgentTool[] = [];
+  const existing = params.existingToolNames ?? new Set<string>();
+
+  for (const entry of registry.tools) {
+    let resolved: AnyAgentTool | AnyAgentTool[] | null | undefined = null;
+    try {
+      resolved = entry.factory(params.context);
+    } catch (err) {
+      log.error(`plugin tool failed (${entry.pluginId}): ${String(err)}`);
+      continue;
+    }
+    if (!resolved) continue;
+    const list = Array.isArray(resolved) ? resolved : [resolved];
+    for (const tool of list) {
+      if (existing.has(tool.name)) {
+        log.warn(`plugin tool name conflict (${entry.pluginId}): ${tool.name}`);
+        continue;
+      }
+      existing.add(tool.name);
+      tools.push(tool);
+    }
+  }
+
+  return tools;
+}

src/plugins/types.ts

@@ -0,0 +1,120 @@
+import type { Command } from "commander";
+
+import type { AnyAgentTool } from "../agents/tools/common.js";
+import type { ClawdbotConfig } from "../config/config.js";
+import type { GatewayRequestHandler } from "../gateway/server-methods/types.js";
+
+export type PluginLogger = {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+export type PluginConfigValidation =
+  | { ok: true; value?: unknown }
+  | { ok: false; errors: string[] };
+
+export type ClawdbotPluginConfigSchema = {
+  safeParse?: (value: unknown) => {
+    success: boolean;
+    data?: unknown;
+    error?: {
+      issues?: Array<{ path: Array<string | number>; message: string }>;
+    };
+  };
+  parse?: (value: unknown) => unknown;
+  validate?: (value: unknown) => PluginConfigValidation;
+};
+
+export type ClawdbotPluginToolContext = {
+  config?: ClawdbotConfig;
+  workspaceDir?: string;
+  agentDir?: string;
+  agentId?: string;
+  sessionKey?: string;
+  messageProvider?: string;
+  agentAccountId?: string;
+  sandboxed?: boolean;
+};
+
+export type ClawdbotPluginToolFactory = (
+  ctx: ClawdbotPluginToolContext,
+) => AnyAgentTool | AnyAgentTool[] | null | undefined;
+
+export type ClawdbotPluginGatewayMethod = {
+  method: string;
+  handler: GatewayRequestHandler;
+};
+
+export type ClawdbotPluginCliContext = {
+  program: Command;
+  config: ClawdbotConfig;
+  workspaceDir?: string;
+  logger: PluginLogger;
+};
+
+export type ClawdbotPluginCliRegistrar = (
+  ctx: ClawdbotPluginCliContext,
+) => void | Promise<void>;
+
+export type ClawdbotPluginServiceContext = {
+  config: ClawdbotConfig;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+};
+
+export type ClawdbotPluginService = {
+  id: string;
+  start: (ctx: ClawdbotPluginServiceContext) => void | Promise<void>;
+  stop?: (ctx: ClawdbotPluginServiceContext) => void | Promise<void>;
+};
+
+export type ClawdbotPluginDefinition = {
+  id?: string;
+  name?: string;
+  description?: string;
+  version?: string;
+  configSchema?: ClawdbotPluginConfigSchema;
+  register?: (api: ClawdbotPluginApi) => void | Promise<void>;
+  activate?: (api: ClawdbotPluginApi) => void | Promise<void>;
+};
+
+export type ClawdbotPluginModule =
+  | ClawdbotPluginDefinition
+  | ((api: ClawdbotPluginApi) => void | Promise<void>);
+
+export type ClawdbotPluginApi = {
+  id: string;
+  name: string;
+  version?: string;
+  description?: string;
+  source: string;
+  config: ClawdbotConfig;
+  pluginConfig?: Record<string, unknown>;
+  logger: PluginLogger;
+  registerTool: (
+    tool: AnyAgentTool | ClawdbotPluginToolFactory,
+    opts?: { name?: string; names?: string[] },
+  ) => void;
+  registerGatewayMethod: (
+    method: string,
+    handler: GatewayRequestHandler,
+  ) => void;
+  registerCli: (
+    registrar: ClawdbotPluginCliRegistrar,
+    opts?: { commands?: string[] },
+  ) => void;
+  registerService: (service: ClawdbotPluginService) => void;
+  resolvePath: (input: string) => string;
+};
+
+export type PluginOrigin = "global" | "workspace" | "config";
+
+export type PluginDiagnostic = {
+  level: "warn" | "error";
+  message: string;
+  pluginId?: string;
+  source?: string;
+};