keryx 0.19.1 → 0.20.0

package/README.md

@@ -88,6 +88,10 @@ That's it. The agent can now discover all your actions as tools, authenticate vi
 - **Strongly-typed frontend integration** — `ActionResponse<MyAction>` gives the frontend type-safe API responses, no code generation needed
 - **Drizzle ORM** with auto-migrations (replacing the old `ah-sequelize-plugin`)
 - **Companion Vite + React frontend** as a separate application (replacing `ah-next-plugin`)
+- **Streaming responses** — SSE and chunked binary streaming via `StreamingResponse`, with per-transport behavior (HTTP, WebSocket, MCP)
+- **Pagination helpers** — `paginationInputs()` Zod mixin + `paginate()` utility for standardized paginated responses
+- **Database transactions** — `withTransaction()` and `TransactionMiddleware` for automatic commit/rollback across action execution
+- **Redis caching patterns** — cache-aside and response-level cache middleware using the built-in ioredis connection
 
 ### Why Bun?
 
@@ -213,6 +217,31 @@ OAuth 2.1 with PKCE is used for authentication — MCP clients go through a brow
 
 A parent task can distribute work across many child jobs using `api.actions.fanOut()` for parallel processing. Results are collected automatically in Redis. See the [Tasks guide](https://keryxjs.com/guide/tasks) for full API and examples.
 
+### Streaming Responses
+
+Actions can stream data by returning a `StreamingResponse`. The framework handles SSE, chunked binary, and cross-transport behavior automatically:
+
+```ts
+async run(params: { prompt: string }) {
+  const sse = StreamingResponse.sse();
+
+  (async () => {
+    try {
+      for await (const token of callLLM(params.prompt)) {
+        sse.send(token, { event: "token" });
+      }
+      sse.close();
+    } catch (e) {
+      sse.sendError(String(e));
+    }
+  })();
+
+  return sse;
+}
+```
+
+Over HTTP this is native SSE; over WebSocket each chunk becomes an incremental message; over MCP chunks are forwarded as logging messages. See the [Streaming guide](https://keryxjs.com/guide/streaming) for full details.
+
 ## Coming from ActionHero?
 
 Keryx keeps the core ideas but rewrites everything on Bun with first-class MCP support. The biggest changes: unified controllers (actions = tasks = CLI commands = MCP tools), separate frontend/backend applications, Drizzle ORM, and MCP as a first-class transport.
@@ -228,6 +257,8 @@ Each application has its own `Dockerfile`, and a `docker-compose.yml` runs them
 Full docs at [keryxjs.com](https://keryxjs.com), including:
 - [Getting Started](https://keryxjs.com/guide/)
 - [Actions Guide](https://keryxjs.com/guide/actions)
+- [Streaming](https://keryxjs.com/guide/streaming)
+- [Caching](https://keryxjs.com/guide/caching)
 - [API Reference](https://keryxjs.com/reference/actions)
 
 <p align="center">

package/classes/API.ts

@@ -2,7 +2,11 @@ import { Glob } from "bun";
 import fs from "fs";
 import path from "path";
 import { config } from "../config";
-import { deepMerge } from "../util/config";
+import {
+  deepMerge,
+  deepMergeDefaults,
+  formatLoadedMessage,
+} from "../util/config";
 import { globLoader } from "../util/glob";
 import type { Initializer, InitializerSortKeys } from "./Initializer";
 import { Logger } from "./Logger";
@@ -69,6 +73,7 @@ export class API {
     this.initialized = false;
 
     await this.loadLocalConfig();
+    this.loadPluginConfig();
     await this.findInitializers();
     this.sortInitializers("loadPriority");
 
@@ -205,6 +210,19 @@ export class API {
     }
   }
 
+  /**
+   * Apply plugin config defaults using deepMergeDefaults so that
+   * user-set config values are never overwritten by plugin defaults.
+   */
+  private loadPluginConfig() {
+    for (const plugin of config.plugins) {
+      if (plugin.configDefaults) {
+        deepMergeDefaults(config, plugin.configDefaults);
+        this.logger.debug(`Merged config defaults from plugin ${plugin.name}`);
+      }
+    }
+  }
+
   private async findInitializers() {
     // Load framework initializers from the package directory
     const frameworkInitializers = await globLoader<Initializer>(
@@ -214,6 +232,17 @@ export class API {
       this.initializers.push(i);
     }
 
+    // Load plugin initializers
+    let pluginInitializerCount = 0;
+    for (const plugin of config.plugins) {
+      if (plugin.initializers) {
+        for (const InitializerClass of plugin.initializers) {
+          this.initializers.push(new InitializerClass());
+          pluginInitializerCount++;
+        }
+      }
+    }
+
     // Load user project initializers (if rootDir differs from packageDir)
     if (this.rootDir !== this.packageDir) {
       try {
@@ -227,6 +256,17 @@ export class API {
         // user project may not have initializers, that's fine
       }
     }
+
+    this.logger.info(
+      formatLoadedMessage("initializers", {
+        core: frameworkInitializers.length,
+        plugin: pluginInitializerCount,
+        user:
+          this.initializers.length -
+          frameworkInitializers.length -
+          pluginInitializerCount,
+      }),
+    );
   }
 
   private sortInitializers(key: InitializerSortKeys) {

package/classes/Plugin.ts

@@ -0,0 +1,54 @@
+import type { Action } from "./Action";
+import type { Channel } from "./Channel";
+import type { Initializer } from "./Initializer";
+import type { Server } from "./Server";
+
+/**
+ * A Keryx plugin manifest. Plugins provide class constructors that the framework
+ * instantiates during discovery, alongside any config defaults and generator extensions.
+ *
+ * First-party plugins use the `@keryxjs/*` npm scope (e.g., `@keryxjs/resque-admin`).
+ * Third-party plugins follow the `keryx-plugin-*` naming convention.
+ *
+ * Register plugins via config:
+ * ```typescript
+ * // config/plugins.ts
+ * import { myPlugin } from "@keryxjs/my-plugin";
+ * export default { plugins: [myPlugin] };
+ * ```
+ */
+export interface KeryxPlugin {
+  /** Unique plugin name (e.g., `"resque-admin"`). */
+  name: string;
+  /** SemVer version string for the plugin. */
+  version: string;
+
+  /** Initializer class constructors. Instantiated and merged into the lifecycle alongside framework and user initializers. */
+  initializers?: Array<new () => Initializer>;
+  /** Action class constructors. Instantiated and registered alongside user actions. */
+  actions?: Array<new () => Action>;
+  /** Channel class constructors. Instantiated and registered alongside user channels. */
+  channels?: Array<new () => Channel>;
+  /** Server class constructors. Instantiated and registered alongside framework and user servers. */
+  servers?: Array<new () => Server<unknown>>;
+
+  /** Config defaults merged before user config, so user overrides take precedence. */
+  configDefaults?: Record<string, unknown>;
+
+  /** Custom generator types for the `keryx generate` CLI command. */
+  generators?: PluginGenerator[];
+}
+
+/**
+ * A custom generator type that a plugin registers with the `keryx generate` CLI command.
+ */
+export interface PluginGenerator {
+  /** The generator type name (e.g., `"graphql-resolver"`). Used as `keryx generate <type> <name>`. */
+  type: string;
+  /** The output subdirectory name relative to the project root (e.g., `"resolvers"`). */
+  directory: string;
+  /** Absolute path to the Mustache template file for the generated component. */
+  templatePath: string;
+  /** Absolute path to the Mustache template file for the generated test. If omitted, the default test template is used. */
+  testTemplatePath?: string;
+}

package/config/index.ts

@@ -1,8 +1,10 @@
+import type { KeryxPlugin } from "../classes/Plugin";
 import { configActions } from "./actions";
 import { configChannels } from "./channels";
 import { configDatabase } from "./database";
 import { configLogger } from "./logger";
 import { configObservability } from "./observability";
+import { configPlugins } from "./plugins";
 import { configProcess } from "./process";
 import { configRateLimit } from "./rateLimit";
 import { configRedis } from "./redis";
@@ -13,6 +15,7 @@ import { configSession } from "./session";
 import { configTasks } from "./tasks";
 
 export const config = {
+  plugins: configPlugins,
   actions: configActions,
   channels: configChannels,
   process: configProcess,
@@ -39,6 +42,7 @@ export const config = {
  * ```
  */
 export interface KeryxConfig {
+  plugins: KeryxPlugin[];
   actions: typeof configActions;
   channels: typeof configChannels;
   process: typeof configProcess;

package/config/plugins.ts

@@ -0,0 +1,3 @@
+import type { KeryxPlugin } from "../classes/Plugin";
+
+export const configPlugins: KeryxPlugin[] = [];

package/index.ts

@@ -24,6 +24,7 @@ export type { ChannelMiddleware } from "./classes/Channel";
 export { CHANNEL_NAME_PATTERN } from "./classes/Channel";
 export { Connection } from "./classes/Connection";
 export { LogLevel } from "./classes/Logger";
+export type { KeryxPlugin, PluginGenerator } from "./classes/Plugin";
 export { SSEResponse, StreamingResponse } from "./classes/StreamingResponse";
 export { ErrorStatusCodes, ErrorType, TypedError } from "./classes/TypedError";
 export type { KeryxConfig } from "./config";
@@ -32,7 +33,8 @@ export { checkRateLimit, RateLimitMiddleware } from "./middleware/rateLimit";
 export { TransactionMiddleware } from "./middleware/transaction";
 export type { WebServer } from "./servers/web";
 export { buildProgram } from "./util/cli";
-export { deepMerge, loadFromEnvIfSet } from "./util/config";
+export { deepMerge, deepMergeDefaults, loadFromEnvIfSet } from "./util/config";
+export { getValidTypes } from "./util/generate";
 export { globLoader } from "./util/glob";
 export { type PaginatedResult, paginate } from "./util/pagination";
 export { toMarkdown } from "./util/toMarkdown";

package/initializers/actionts.ts

@@ -6,6 +6,7 @@ import { type Action, DEFAULT_QUEUE } from "../classes/Action";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
+import { formatLoadedMessage } from "../util/config";
 import { globLoader } from "../util/glob";
 
 const namespace = "actions";
@@ -85,7 +86,9 @@ export class Actions extends Initializer {
     inputs: TaskInputs = {},
     queue?: string,
   ) => {
-    const action = api.actions.actions.find((a) => a.name === actionName);
+    const action = api.actions.actions.find(
+      (a: Action) => a.name === actionName,
+    );
     if (!action) {
       throw new TypedError({
         message: `action ${actionName} not found`,
@@ -140,7 +143,9 @@ export class Actions extends Initializer {
     // Validate all action names up front
     const actionNames = new Set<string>();
     for (const job of jobs) {
-      const action = api.actions.actions.find((a) => a.name === job.action);
+      const action = api.actions.actions.find(
+        (a: Action) => a.name === job.action,
+      );
       if (!action) {
         throw new TypedError({
           message: `action ${job.action} not found`,
@@ -152,7 +157,9 @@ export class Actions extends Initializer {
 
     // Resolve queue per job: explicit job.queue > action's task.queue > DEFAULT_QUEUE
     const resolvedJobs = jobs.map((job) => {
-      const action = api.actions.actions.find((a) => a.name === job.action)!;
+      const action = api.actions.actions.find(
+        (a: Action) => a.name === job.action,
+      )!;
       const resolvedQueue = job.queue ?? action?.task?.queue ?? DEFAULT_QUEUE;
       return { ...job, queue: resolvedQueue, inputs: job.inputs ?? {} };
     });
@@ -250,8 +257,8 @@ export class Actions extends Initializer {
       total: parseInt(meta.total, 10) || 0,
       completed: parseInt(meta.completed, 10) || 0,
       failed: parseInt(meta.failed, 10) || 0,
-      results: rawResults.map((r) => JSON.parse(r)),
-      errors: rawErrors.map((e) => JSON.parse(e)),
+      results: rawResults.map((r: string) => JSON.parse(r)),
+      errors: rawErrors.map((e: string) => JSON.parse(e)),
     };
   };
 
@@ -565,7 +572,9 @@ export class Actions extends Initializer {
    * Will throw an error if redis cannot be reached.
    */
   stopRecurrentAction = async (actionName: string): Promise<number> => {
-    const action = api.actions.actions.find((a) => a.name === actionName);
+    const action = api.actions.actions.find(
+      (a: Action) => a.name === actionName,
+    );
     if (!action) {
       throw new TypedError({
         message: `action ${actionName} not found`,
@@ -634,14 +643,34 @@ export class Actions extends Initializer {
   };
 
   async initialize() {
-    const actions = await globLoader<Action>(path.join(api.rootDir, "actions"));
+    // Load plugin actions
+    const pluginActions: Action[] = [];
+    for (const plugin of config.plugins) {
+      if (plugin.actions) {
+        for (const ActionClass of plugin.actions) {
+          pluginActions.push(new ActionClass());
+        }
+      }
+    }
+
+    // Load user actions
+    const userActions = await globLoader<Action>(
+      path.join(api.rootDir, "actions"),
+    );
+
+    const actions = [...pluginActions, ...userActions];
 
     for (const a of actions) {
       if (!a.description) a.description = `An Action: ${a.name}`;
       a.mcp = { tool: true, ...a.mcp };
     }
 
-    logger.info(`loaded ${Object.keys(actions).length} actions`);
+    logger.info(
+      formatLoadedMessage("actions", {
+        plugin: pluginActions.length,
+        user: userActions.length,
+      }),
+    );
 
     return {
       actions,

package/initializers/channels.ts

@@ -5,6 +5,7 @@ import type { Connection } from "../classes/Connection";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
+import { formatLoadedMessage } from "../util/config";
 import { globLoader } from "../util/glob";
 
 const namespace = "channels";
@@ -35,7 +36,7 @@ export class Channels extends Initializer {
    * Returns undefined if no matching channel is found.
    */
   findChannel = (channelName: string): Channel | undefined => {
-    return api.channels.channels.find((c) => c.matches(channelName));
+    return api.channels.channels.find((c: Channel) => c.matches(channelName));
   };
 
   /**
@@ -229,11 +230,22 @@ export class Channels extends Initializer {
       join(LUA_DIR, "refresh-presence.lua"),
     ).text();
 
-    let channels: Channel[] = [];
+    // Load plugin channels
+    const pluginChannels: Channel[] = [];
+    for (const plugin of config.plugins) {
+      if (plugin.channels) {
+        for (const ChannelClass of plugin.channels) {
+          pluginChannels.push(new ChannelClass());
+        }
+      }
+    }
 
-    // Channels are always user-defined, load from rootDir only
+    // Load user channels
+    let userChannels: Channel[] = [];
     try {
-      channels = await globLoader<Channel>(path.join(api.rootDir, "channels"));
+      userChannels = await globLoader<Channel>(
+        path.join(api.rootDir, "channels"),
+      );
     } catch (e) {
       // channels directory may not exist, which is fine
       logger.debug(
@@ -241,11 +253,18 @@ export class Channels extends Initializer {
       );
     }
 
+    const channels = [...pluginChannels, ...userChannels];
+
     for (const c of channels) {
       if (!c.description) c.description = `A Channel: ${c.name}`;
     }
 
-    logger.info(`loaded ${channels.length} channels`);
+    logger.info(
+      formatLoadedMessage("channels", {
+        plugin: pluginChannels.length,
+        user: userChannels.length,
+      }),
+    );
 
     return {
       channels,

package/initializers/mcp.ts

@@ -7,6 +7,7 @@ import colors from "colors";
 import { randomUUID } from "crypto";
 import * as z4mini from "zod/v4-mini";
 import { api, logger } from "../api";
+import type { Action } from "../classes/Action";
 import { MCP_RESPONSE_FORMAT } from "../classes/Action";
 import { Connection } from "../classes/Connection";
 import { Initializer } from "../classes/Initializer";
@@ -46,7 +47,7 @@ function formatToolName(actionName: string): string {
 function parseToolName(toolName: string): string {
   // Reverse lookup against registered actions
   const action = api.actions.actions.find(
-    (a) => formatToolName(a.name) === toolName,
+    (a: Action) => formatToolName(a.name) === toolName,
   );
   return action ? action.name : toolName;
 }

package/initializers/resque.ts

@@ -1,4 +1,5 @@
 import {
+  type ErrorPayload,
   type Job,
   type ParsedJob,
   Queue,
@@ -61,7 +62,7 @@ export class Resque extends Initializer {
       api.resque.jobs,
     );
 
-    api.resque.queue.on("error", (error) => {
+    api.resque.queue.on("error", (error: Error) => {
       logger.error(`[resque:queue] ${error}`);
     });
 
@@ -85,7 +86,7 @@ export class Resque extends Initializer {
         retryStuckJobs: config.tasks.retryStuckJobs,
       });
 
-      api.resque.scheduler.on("error", (error) => {
+      api.resque.scheduler.on("error", (error: Error) => {
         logger.error(`[resque:scheduler] ${error}`);
       });
 
@@ -105,7 +106,7 @@ export class Resque extends Initializer {
       });
       api.resque.scheduler.on(
         "cleanStuckWorker",
-        (workerName, errorPayload, delta) => {
+        (workerName: string, errorPayload: ErrorPayload, delta: number) => {
           logger.warn(
             `[resque:scheduler] cleaning stuck worker: ${workerName}, ${errorPayload}, ${delta}`,
           );

package/initializers/servers.ts

@@ -1,7 +1,9 @@
 import path from "path";
-import { api, RUN_MODE } from "../api";
+import { api, logger, RUN_MODE } from "../api";
 import { Initializer } from "../classes/Initializer";
 import type { Server } from "../classes/Server";
+import { config } from "../config";
+import { formatLoadedMessage } from "../util/config";
 import { globLoader } from "../util/glob";
 
 const namespace = "servers";
@@ -27,6 +29,16 @@ export class Servers extends Initializer {
       path.join(api.packageDir, "servers"),
     );
 
+    // Load plugin servers
+    const pluginServers: Server<any>[] = [];
+    for (const plugin of config.plugins) {
+      if (plugin.servers) {
+        for (const ServerClass of plugin.servers) {
+          pluginServers.push(new ServerClass());
+        }
+      }
+    }
+
     // Load user project servers (if rootDir differs from packageDir)
     let userServers: Server<any>[] = [];
     if (api.rootDir !== api.packageDir) {
@@ -39,12 +51,20 @@ export class Servers extends Initializer {
       }
     }
 
-    const servers = [...frameworkServers, ...userServers];
+    const servers = [...frameworkServers, ...pluginServers, ...userServers];
 
     for (const server of servers) {
       await server.initialize();
     }
 
+    logger.info(
+      formatLoadedMessage("servers", {
+        core: frameworkServers.length,
+        plugin: pluginServers.length,
+        user: userServers.length,
+      }),
+    );
+
     return { servers };
   }
 

package/initializers/swagger.ts

@@ -202,8 +202,8 @@ export class SwaggerInitializer extends Initializer {
       try {
         const cached = await cacheFileHandle.json();
         if (cached.hash === hash) {
-          logger.info(
-            `Loaded ${Object.keys(cached.responseSchemas).length} response schemas from cache`,
+          logger.debug(
+            `Loaded ${Object.keys(cached.responseSchemas).length} OpenAPI response schemas from cache`,
           );
           return { responseSchemas: cached.responseSchemas };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/util/cli.ts

@@ -5,7 +5,7 @@ import { Action, api, Connection, RUN_MODE } from "../api";
 import { ExitCode } from "./../classes/ExitCode";
 import { TypedError } from "./../classes/TypedError";
 import { config } from "../config";
-import { generateComponent } from "./generate";
+import { generateComponent, getValidTypes } from "./generate";
 import { globLoader } from "./glob";
 import {
   interactiveScaffold,
@@ -100,7 +100,7 @@ export async function buildProgram(opts: {
     .alias("g")
     .summary("Generate a new component")
     .description(
-      "Scaffold a new action, initializer, middleware, channel, or ops file.\n\n" +
+      `Scaffold a new component file.\n\nValid types: ${getValidTypes().join(", ")}\n\n` +
         "Examples:\n" +
         "  keryx generate action user:delete\n" +
         "  keryx generate initializer cache\n" +
@@ -232,7 +232,7 @@ async function runActionViaCLI(options: Record<string, string>, command: any) {
 
   await api.initialize();
 
-  const action = api.actions.actions.find((a) => a.name === actionName);
+  const action = api.actions.actions.find((a: Action) => a.name === actionName);
   if (!action) {
     exitWithError(`Action "${actionName}" not found`);
   }

package/util/config.ts

@@ -27,6 +27,61 @@ export function deepMerge<T extends Record<string, any>>(
   return target;
 }
 
+/**
+ * Like `deepMerge`, but only sets values that don't already exist in target.
+ * Useful for applying plugin config defaults without overwriting user-set values.
+ */
+export function deepMergeDefaults<T extends Record<string, any>>(
+  target: T,
+  source: Record<string, any>,
+): T {
+  for (const key of Object.keys(source)) {
+    if (!(key in target)) {
+      (target as any)[key] = source[key];
+    } else {
+      const targetVal = target[key];
+      const sourceVal = source[key];
+
+      if (
+        targetVal &&
+        sourceVal &&
+        typeof targetVal === "object" &&
+        typeof sourceVal === "object" &&
+        !Array.isArray(targetVal) &&
+        !Array.isArray(sourceVal)
+      ) {
+        deepMergeDefaults(targetVal, sourceVal);
+      }
+      // If key exists in target and isn't a nested object, keep the target value
+    }
+  }
+
+  return target;
+}
+
+/**
+ * Build a human-readable summary of how many components were loaded and where
+ * they came from. Example: `"loaded 12 initializers (10 core, 1 from plugins, 1 user-defined)"`
+ *
+ * @param label - Plural noun for the component type (e.g. "actions", "servers").
+ * @param counts - Breakdown by source. All fields are optional; zero-value
+ *   categories are omitted from the output.
+ */
+export function formatLoadedMessage(
+  label: string,
+  counts: { core?: number; plugin?: number; user?: number },
+): string {
+  const total = (counts.core ?? 0) + (counts.plugin ?? 0) + (counts.user ?? 0);
+  const parts: string[] = [];
+  if (counts.core) parts.push(`${counts.core} core`);
+  if (counts.plugin) parts.push(`${counts.plugin} from plugins`);
+  if (counts.user) parts.push(`${counts.user} user-defined`);
+  if (parts.length > 0) {
+    return `loaded ${total} ${label} (${parts.join(", ")})`;
+  }
+  return `loaded ${total} ${label}`;
+}
+
 /**
 Loads a value from the environment, if it's set, otherwise returns the default value.
 */

package/util/generate.ts

@@ -1,6 +1,8 @@
 import fs from "fs";
 import Mustache from "mustache";
 import path from "path";
+import type { PluginGenerator } from "../classes/Plugin";
+import { config } from "../config";
 
 const VALID_TYPES = [
   "action",
@@ -11,6 +13,35 @@ const VALID_TYPES = [
 ] as const;
 type GeneratorType = (typeof VALID_TYPES)[number];
 
+/**
+ * Returns all valid generator types, including built-in types and
+ * any custom types registered by plugins.
+ */
+export function getValidTypes(): string[] {
+  const types = [...VALID_TYPES] as string[];
+  for (const plugin of config.plugins) {
+    if (plugin.generators) {
+      for (const gen of plugin.generators) {
+        if (!types.includes(gen.type)) types.push(gen.type);
+      }
+    }
+  }
+  return types;
+}
+
+/**
+ * Find a plugin generator definition for a given type.
+ */
+function findPluginGenerator(type: string): PluginGenerator | undefined {
+  for (const plugin of config.plugins) {
+    if (plugin.generators) {
+      const gen = plugin.generators.find((g) => g.type === type);
+      if (gen) return gen;
+    }
+  }
+  return undefined;
+}
+
 export interface GenerateOptions {
   dryRun?: boolean;
   force?: boolean;
@@ -60,6 +91,27 @@ function resolveFilePath(type: GeneratorType, name: string): string {
   return path.join(baseDir, `${name}.ts`);
 }
 
+/**
+ * Determine the directory and filename for a plugin generator type + name.
+ */
+function resolvePluginFilePath(gen: PluginGenerator, name: string): string {
+  const segments = name.split(":");
+  if (segments.length > 1) {
+    const fileName = segments.pop()!;
+    return path.join(gen.directory, ...segments, `${fileName}.ts`);
+  }
+  return path.join(gen.directory, `${name}.ts`);
+}
+
+/**
+ * Determine the test file path for a plugin generator component.
+ */
+function resolvePluginTestPath(gen: PluginGenerator, name: string): string {
+  const componentPath = resolvePluginFilePath(gen, name);
+  const parsed = path.parse(componentPath);
+  return path.join("__tests__", parsed.dir, `${parsed.name}.test.ts`);
+}
+
 /**
  * Determine the test file path for a component.
  * "user:delete" action → "__tests__/actions/user/delete.test.ts"
@@ -92,14 +144,21 @@ export async function generateComponent(
   rootDir: string,
   options: GenerateOptions = {},
 ): Promise<string[]> {
-  if (!VALID_TYPES.includes(type as GeneratorType)) {
+  const allValidTypes = getValidTypes();
+  if (!allValidTypes.includes(type)) {
     throw new Error(
-      `Unknown generator type "${type}". Valid types: ${VALID_TYPES.join(", ")}`,
+      `Unknown generator type "${type}". Valid types: ${allValidTypes.join(", ")}`,
     );
   }
 
-  const generatorType = type as GeneratorType;
-  const filePath = resolveFilePath(generatorType, name);
+  // Check if this is a plugin-provided generator type
+  const pluginGen = VALID_TYPES.includes(type as GeneratorType)
+    ? undefined
+    : findPluginGenerator(type);
+
+  const filePath = pluginGen
+    ? resolvePluginFilePath(pluginGen, name)
+    : resolveFilePath(type as GeneratorType, name);
   const fullPath = path.join(rootDir, filePath);
   const createdFiles: string[] = [];
 
@@ -112,25 +171,30 @@ export async function generateComponent(
 
   // Build template view
   let className = toClassName(name);
-  if (generatorType === "middleware") className += "Middleware";
-  if (generatorType === "channel") className += "Channel";
+  if (type === "middleware") className += "Middleware";
+  if (type === "channel") className += "Channel";
 
   const view: Record<string, string> = { name, className };
-  if (generatorType === "action") {
+  if (type === "action") {
     view.route = toRoute(name);
   }
 
-  // Determine template
-  const templateMap: Record<GeneratorType, string> = {
-    action: "action.ts.mustache",
-    initializer: "initializer.ts.mustache",
-    middleware: "action-middleware.ts.mustache",
-    channel: "channel.ts.mustache",
-    ops: "ops.ts.mustache",
-  };
-
-  const template = await loadTemplate(templateMap[generatorType]);
-  const content = Mustache.render(template, view);
+  // Load and render template
+  let content: string;
+  if (pluginGen) {
+    const templateStr = await Bun.file(pluginGen.templatePath).text();
+    content = Mustache.render(templateStr, view);
+  } else {
+    const templateMap: Record<GeneratorType, string> = {
+      action: "action.ts.mustache",
+      initializer: "initializer.ts.mustache",
+      middleware: "action-middleware.ts.mustache",
+      channel: "channel.ts.mustache",
+      ops: "ops.ts.mustache",
+    };
+    const template = await loadTemplate(templateMap[type as GeneratorType]);
+    content = Mustache.render(template, view);
+  }
 
   if (options.dryRun) {
     console.log(`Would create: ${filePath}`);
@@ -145,14 +209,24 @@ export async function generateComponent(
 
   // Generate test file
   if (!options.noTest) {
-    const testPath = resolveTestPath(generatorType, name);
+    const testPath = pluginGen
+      ? resolvePluginTestPath(pluginGen, name)
+      : resolveTestPath(type as GeneratorType, name);
     const testFullPath = path.join(rootDir, testPath);
 
     if (!options.force && fs.existsSync(testFullPath)) {
       // Silently skip test file if it already exists
     } else {
-      const testTemplate = await loadTemplate("test.ts.mustache");
-      const testContent = Mustache.render(testTemplate, view);
+      let testContent: string;
+      if (pluginGen?.testTemplatePath) {
+        const testTemplateStr = await Bun.file(
+          pluginGen.testTemplatePath,
+        ).text();
+        testContent = Mustache.render(testTemplateStr, view);
+      } else {
+        const testTemplate = await loadTemplate("test.ts.mustache");
+        testContent = Mustache.render(testTemplate, view);
+      }
 
       if (options.dryRun) {
         console.log(`Would create: ${testPath}`);

package/util/oauthHandlers.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "crypto";
 import { api } from "../api";
-import type { OAuthActionResponse } from "../classes/Action";
+import type { Action, OAuthActionResponse } from "../classes/Action";
 import { Connection } from "../classes/Connection";
 import { config } from "../config";
 import {
@@ -180,8 +180,10 @@ export function handleAuthorizeGet(
   };
 
   return renderAuthPage(params, templates, {
-    loginAction: api.actions.actions.find((a) => a.mcp?.isLoginAction),
-    signupAction: api.actions.actions.find((a) => a.mcp?.isSignupAction),
+    loginAction: api.actions.actions.find((a: Action) => a.mcp?.isLoginAction),
+    signupAction: api.actions.actions.find(
+      (a: Action) => a.mcp?.isSignupAction,
+    ),
   });
 }
 
@@ -227,8 +229,10 @@ export async function handleAuthorizePost(
   };
 
   const authActions = {
-    loginAction: api.actions.actions.find((a) => a.mcp?.isLoginAction),
-    signupAction: api.actions.actions.find((a) => a.mcp?.isSignupAction),
+    loginAction: api.actions.actions.find((a: Action) => a.mcp?.isLoginAction),
+    signupAction: api.actions.actions.find(
+      (a: Action) => a.mcp?.isSignupAction,
+    ),
   };
 
   // Validate client
@@ -263,7 +267,9 @@ export async function handleAuthorizePost(
   let userId: number;
 
   if (mode === "signup") {
-    const signupAction = api.actions.actions.find((a) => a.mcp?.isSignupAction);
+    const signupAction = api.actions.actions.find(
+      (a: Action) => a.mcp?.isSignupAction,
+    );
     if (!signupAction) {
       oauthParams.error = "No signup action configured";
       return renderAuthPage(oauthParams, templates, authActions);
@@ -283,7 +289,9 @@ export async function handleAuthorizePost(
       connection.destroy();
     }
   } else {
-    const loginAction = api.actions.actions.find((a) => a.mcp?.isLoginAction);
+    const loginAction = api.actions.actions.find(
+      (a: Action) => a.mcp?.isLoginAction,
+    );
     if (!loginAction) {
       oauthParams.error = "No login action configured";
       return renderAuthPage(oauthParams, templates, authActions);

package/util/scaffold.ts

@@ -103,6 +103,10 @@ export async function generateConfigFileContents(): Promise<
       /from ["']\.\.\/classes\/Logger["']/g,
       'from "keryx"',
     );
+    content = content.replace(
+      /from ["']\.\.\/classes\/Plugin["']/g,
+      'from "keryx"',
+    );
 
     // In index.ts, change `export const config` to `export default`
     // and remove the KeryxConfig interface export (it comes from the package)
@@ -112,6 +116,11 @@ export async function generateConfigFileContents(): Promise<
         /\nexport interface KeryxConfig \{[\s\S]*?\}\n/,
         "\n",
       );
+      // Remove the KeryxPlugin import (only used by the stripped KeryxConfig interface)
+      content = content.replace(
+        /import type \{ KeryxPlugin \} from ["']keryx["'];\n/,
+        "",
+      );
     }
 
     result.set(`config/${file}`, content);