feat: add plugin HTTP hooks + Zalo plugin

src/gateway/server-http.ts

@@ -190,6 +190,7 @@ export function createGatewayHttpServer(opts: {
   controlUiBasePath: string;
   openAiChatCompletionsEnabled: boolean;
   handleHooksRequest: HooksRequestHandler;
+  handlePluginRequest?: HooksRequestHandler;
   resolvedAuth: import("./auth.js").ResolvedGatewayAuth;
 }): HttpServer {
   const {
@@ -198,6 +199,7 @@ export function createGatewayHttpServer(opts: {
     controlUiBasePath,
     openAiChatCompletionsEnabled,
     handleHooksRequest,
+    handlePluginRequest,
     resolvedAuth,
   } = opts;
   const httpServer: HttpServer = createHttpServer((req, res) => {
@@ -206,6 +208,7 @@ export function createGatewayHttpServer(opts: {
 
     void (async () => {
       if (await handleHooksRequest(req, res)) return;
+      if (handlePluginRequest && (await handlePluginRequest(req, res))) return;
       if (openAiChatCompletionsEnabled) {
         if (await handleOpenAiHttpRequest(req, res, { auth: resolvedAuth })) return;
       }

src/gateway/server-runtime-state.ts

@@ -10,12 +10,14 @@ import type { ChatAbortControllerEntry } from "./chat-abort.js";
 import type { HooksConfigResolved } from "./hooks.js";
 import { createGatewayHooksRequestHandler } from "./server/hooks.js";
 import { listenGatewayHttpServer } from "./server/http-listen.js";
+import { createGatewayPluginRequestHandler } from "./server/plugins-http.js";
 import type { GatewayWsClient } from "./server/ws-types.js";
 import { createGatewayBroadcaster } from "./server-broadcast.js";
 import { type ChatRunEntry, createChatRunState } from "./server-chat.js";
 import { MAX_PAYLOAD_BYTES } from "./server-constants.js";
 import { attachGatewayUpgradeHandler, createGatewayHttpServer } from "./server-http.js";
 import type { DedupeEntry } from "./server-shared.js";
+import type { PluginRegistry } from "../plugins/registry.js";
 
 export async function createGatewayRuntimeState(params: {
   cfg: {
@@ -28,12 +30,14 @@ export async function createGatewayRuntimeState(params: {
   openAiChatCompletionsEnabled: boolean;
   resolvedAuth: ResolvedGatewayAuth;
   hooksConfig: () => HooksConfigResolved | null;
+  pluginRegistry: PluginRegistry;
   deps: CliDeps;
   canvasRuntime: RuntimeEnv;
   canvasHostEnabled: boolean;
   allowCanvasHostInTests?: boolean;
   logCanvas: { info: (msg: string) => void; warn: (msg: string) => void };
   logHooks: ReturnType<typeof createSubsystemLogger>;
+  logPlugins: ReturnType<typeof createSubsystemLogger>;
 }): Promise<{
   canvasHost: CanvasHostHandler | null;
   httpServer: HttpServer;
@@ -89,12 +93,18 @@ export async function createGatewayRuntimeState(params: {
     logHooks: params.logHooks,
   });
 
+  const handlePluginRequest = createGatewayPluginRequestHandler({
+    registry: params.pluginRegistry,
+    log: params.logPlugins,
+  });
+
   const httpServer = createGatewayHttpServer({
     canvasHost,
     controlUiEnabled: params.controlUiEnabled,
     controlUiBasePath: params.controlUiBasePath,
     openAiChatCompletionsEnabled: params.openAiChatCompletionsEnabled,
     handleHooksRequest,
+    handlePluginRequest,
     resolvedAuth: params.resolvedAuth,
   });
 

src/gateway/server.impl.ts

@@ -67,6 +67,7 @@ const logHealth = log.child("health");
 const logCron = log.child("cron");
 const logReload = log.child("reload");
 const logHooks = log.child("hooks");
+const logPlugins = log.child("plugins");
 const logWsControl = log.child("ws");
 const canvasRuntime = runtimeForLogger(logCanvas);
 
@@ -222,12 +223,14 @@ export async function startGatewayServer(
     openAiChatCompletionsEnabled,
     resolvedAuth,
     hooksConfig: () => hooksConfig,
+    pluginRegistry,
     deps,
     canvasRuntime,
     canvasHostEnabled,
     allowCanvasHostInTests: opts.allowCanvasHostInTests,
     logCanvas,
     logHooks,
+    logPlugins,
   });
   let bonjourStop: (() => Promise<void>) | null = null;
   let bridge: import("../infra/bridge/server.js").NodeBridgeServer | null = null;

src/gateway/server/__tests__/test-utils.ts

@@ -0,0 +1,22 @@
+import type { PluginRegistry } from "../../../plugins/registry.js";
+
+export const createTestRegistry = (
+  overrides: Partial<PluginRegistry> = {},
+): PluginRegistry => {
+  const base: PluginRegistry = {
+    plugins: [],
+    tools: [],
+    channels: [],
+    gatewayHandlers: {},
+    httpHandlers: [],
+    cliRegistrars: [],
+    services: [],
+    diagnostics: [],
+  };
+  const merged = { ...base, ...overrides };
+  return {
+    ...merged,
+    gatewayHandlers: merged.gatewayHandlers ?? {},
+    httpHandlers: merged.httpHandlers ?? [],
+  };
+};

src/gateway/server/plugins-http.test.ts

@@ -0,0 +1,77 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { describe, expect, it, vi } from "vitest";
+
+import { createGatewayPluginRequestHandler } from "./plugins-http.js";
+import { createTestRegistry } from "./__tests__/test-utils.js";
+
+const makeResponse = () =>
+  ({
+    headersSent: false,
+    statusCode: 200,
+    setHeader: vi.fn(),
+    end: vi.fn(),
+  }) as unknown as ServerResponse;
+
+describe("createGatewayPluginRequestHandler", () => {
+  it("returns false when no handlers are registered", async () => {
+    const log = { warn: vi.fn() } as unknown as Parameters<
+      typeof createGatewayPluginRequestHandler
+    >[0]["log"];
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry(),
+      log,
+    });
+    const handled = await handler({} as IncomingMessage, makeResponse());
+    expect(handled).toBe(false);
+  });
+
+  it("continues until a handler reports it handled the request", async () => {
+    const first = vi.fn(async () => false);
+    const second = vi.fn(async () => true);
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry({
+        httpHandlers: [
+          { pluginId: "first", handler: first, source: "first" },
+          { pluginId: "second", handler: second, source: "second" },
+        ],
+      }),
+      log: { warn: vi.fn() } as unknown as Parameters<typeof createGatewayPluginRequestHandler>[0]["log"],
+    });
+
+    const handled = await handler({} as IncomingMessage, makeResponse());
+    expect(handled).toBe(true);
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("logs and responds with 500 when a handler throws", async () => {
+    const log = { warn: vi.fn() } as unknown as Parameters<
+      typeof createGatewayPluginRequestHandler
+    >[0]["log"];
+    const handler = createGatewayPluginRequestHandler({
+      registry: createTestRegistry({
+        httpHandlers: [
+          {
+            pluginId: "boom",
+            handler: async () => {
+              throw new Error("boom");
+            },
+            source: "boom",
+          },
+        ],
+      }),
+      log,
+    });
+
+    const res = makeResponse();
+    const handled = await handler({} as IncomingMessage, res);
+    expect(handled).toBe(true);
+    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("boom"));
+    expect(res.statusCode).toBe(500);
+    expect(res.setHeader).toHaveBeenCalledWith(
+      "Content-Type",
+      "text/plain; charset=utf-8",
+    );
+    expect(res.end).toHaveBeenCalledWith("Internal Server Error");
+  });
+});

src/gateway/server/plugins-http.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { createSubsystemLogger } from "../../logging.js";
+import type { PluginRegistry } from "../../plugins/registry.js";
+
+type SubsystemLogger = ReturnType<typeof createSubsystemLogger>;
+
+export type PluginHttpRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<boolean>;
+
+export function createGatewayPluginRequestHandler(params: {
+  registry: PluginRegistry;
+  log: SubsystemLogger;
+}): PluginHttpRequestHandler {
+  const { registry, log } = params;
+  return async (req, res) => {
+    if (registry.httpHandlers.length === 0) return false;
+    for (const entry of registry.httpHandlers) {
+      try {
+        const handled = await entry.handler(req, res);
+        if (handled) return true;
+      } catch (err) {
+        log.warn(`plugin http handler failed (${entry.pluginId}): ${String(err)}`);
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end("Internal Server Error");
+        }
+        return true;
+      }
+    }
+    return false;
+  };
+}

src/plugins/loader.test.ts

@@ -142,4 +142,28 @@ describe("loadClawdbotPlugins", () => {
     expect(registry.channels.length).toBe(1);
     expect(registry.channels[0]?.plugin.id).toBe("demo");
   });
+
+  it("registers http handlers", () => {
+    const plugin = writePlugin({
+      id: "http-demo",
+      body: `export default function (api) {
+  api.registerHttpHandler(async () => false);
+};`,
+    });
+
+    const registry = loadClawdbotPlugins({
+      cache: false,
+      workspaceDir: plugin.dir,
+      config: {
+        plugins: {
+          load: { paths: [plugin.file] },
+          allow: ["http-demo"],
+        },
+      },
+    });
+
+    expect(registry.httpHandlers.length).toBe(1);
+    expect(registry.httpHandlers[0]?.pluginId).toBe("http-demo");
+    expect(registry.plugins[0]?.httpHandlers).toBe(1);
+  });
 });

src/plugins/loader.ts

@@ -193,6 +193,7 @@ function createPluginRecord(params: {
     gatewayMethods: [],
     cliCommands: [],
     services: [],
+    httpHandlers: 0,
     configSchema: params.configSchema,
     configUiHints: undefined,
   };

src/plugins/registry.ts

@@ -10,6 +10,7 @@ import type {
   ClawdbotPluginApi,
   ClawdbotPluginChannelRegistration,
   ClawdbotPluginCliRegistrar,
+  ClawdbotPluginHttpHandler,
   ClawdbotPluginService,
   ClawdbotPluginToolContext,
   ClawdbotPluginToolFactory,
@@ -33,6 +34,12 @@ export type PluginCliRegistration = {
   source: string;
 };
 
+export type PluginHttpRegistration = {
+  pluginId: string;
+  handler: ClawdbotPluginHttpHandler;
+  source: string;
+};
+
 export type PluginChannelRegistration = {
   pluginId: string;
   plugin: ChannelPlugin;
@@ -62,6 +69,7 @@ export type PluginRecord = {
   gatewayMethods: string[];
   cliCommands: string[];
   services: string[];
+  httpHandlers: number;
   configSchema: boolean;
   configUiHints?: Record<string, PluginConfigUiHint>;
 };
@@ -71,6 +79,7 @@ export type PluginRegistry = {
   tools: PluginToolRegistration[];
   channels: PluginChannelRegistration[];
   gatewayHandlers: GatewayRequestHandlers;
+  httpHandlers: PluginHttpRegistration[];
   cliRegistrars: PluginCliRegistration[];
   services: PluginServiceRegistration[];
   diagnostics: PluginDiagnostic[];
@@ -87,6 +96,7 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
     tools: [],
     channels: [],
     gatewayHandlers: {},
+    httpHandlers: [],
     cliRegistrars: [],
     services: [],
     diagnostics: [],
@@ -142,6 +152,18 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
     record.gatewayMethods.push(trimmed);
   };
 
+  const registerHttpHandler = (
+    record: PluginRecord,
+    handler: ClawdbotPluginHttpHandler,
+  ) => {
+    record.httpHandlers += 1;
+    registry.httpHandlers.push({
+      pluginId: record.id,
+      handler,
+      source: record.source,
+    });
+  };
+
   const registerChannel = (
     record: PluginRecord,
     registration: ClawdbotPluginChannelRegistration | ChannelPlugin,
@@ -220,6 +242,7 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
       pluginConfig: params.pluginConfig,
       logger: normalizeLogger(registryParams.logger),
       registerTool: (tool, opts) => registerTool(record, tool, opts),
+      registerHttpHandler: (handler) => registerHttpHandler(record, handler),
       registerChannel: (registration) => registerChannel(record, registration),
       registerGatewayMethod: (method, handler) => registerGatewayMethod(record, method, handler),
       registerCli: (registrar, opts) => registerCli(record, registrar, opts),

src/plugins/types.ts

@@ -1,3 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Command } from "commander";
 
 import type { AnyAgentTool } from "../agents/tools/common.js";
@@ -58,6 +59,11 @@ export type ClawdbotPluginGatewayMethod = {
   handler: GatewayRequestHandler;
 };
 
+export type ClawdbotPluginHttpHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<boolean> | boolean;
+
 export type ClawdbotPluginCliContext = {
   program: Command;
   config: ClawdbotConfig;
@@ -112,6 +118,7 @@ export type ClawdbotPluginApi = {
     tool: AnyAgentTool | ClawdbotPluginToolFactory,
     opts?: { name?: string; names?: string[] },
   ) => void;
+  registerHttpHandler: (handler: ClawdbotPluginHttpHandler) => void;
   registerChannel: (registration: ClawdbotPluginChannelRegistration | ChannelPlugin) => void;
   registerGatewayMethod: (method: string, handler: GatewayRequestHandler) => void;
   registerCli: (registrar: ClawdbotPluginCliRegistrar, opts?: { commands?: string[] }) => void;