keryx 0.25.5 → 0.29.0

package/classes/Connection.ts

@@ -11,6 +11,54 @@ import { LogFormat } from "./Logger";
 import { StreamingResponse } from "./StreamingResponse";
 import { ErrorType, TypedError } from "./TypedError";
 
+/**
+ * Per-invocation context passed to {@link BeforeActHook} and {@link AfterActHook}.
+ * The same object instance threads from `beforeAct` to `afterAct` for a single
+ * action invocation, so hooks can stash span refs, timing data, etc.
+ */
+export interface ActContext {
+  /** Mutable scratch space shared between `beforeAct` and `afterAct`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Unified outcome passed to {@link AfterActHook}. Discriminate via the `success` field.
+ * Covers both the happy-path and error paths of an action invocation.
+ */
+export type ActOutcome =
+  | { success: true; response: unknown; duration: number }
+  | { success: false; error: unknown; duration: number };
+
+/**
+ * Runs inside `Connection.act()` after params are validated and before the action's
+ * own `runBefore` middleware. Fires for every action invocation regardless of
+ * transport (web, websocket, task, cli, mcp, …) — inspect `connection.type` to
+ * discriminate. Throwing fails the action.
+ *
+ * Register via `api.hooks.actions.beforeAct(...)`.
+ */
+export type BeforeActHook = (
+  actionName: string,
+  params: Record<string, unknown>,
+  connection: Connection,
+  ctx: ActContext,
+) => Promise<void> | void;
+
+/**
+ * Runs inside `Connection.act()` after the action completes (success or failure),
+ * in a `finally` block so it always fires if the corresponding `beforeAct` fired.
+ * Receives the same `ctx` plus an {@link ActOutcome} describing what happened.
+ *
+ * Register via `api.hooks.actions.afterAct(...)`.
+ */
+export type AfterActHook = (
+  actionName: string,
+  params: Record<string, unknown>,
+  connection: Connection,
+  ctx: ActContext,
+  outcome: ActOutcome,
+) => Promise<void> | void;
+
 /**
  * Represents a client connection to the server — HTTP request, WebSocket, or internal caller.
  * Each connection tracks its own session, channel subscriptions, and rate-limit state.
@@ -108,6 +156,11 @@ export class Connection<
 
     let action: Action | undefined;
     let formattedParams: Record<string, unknown> | undefined;
+    // Cross-transport action hooks (api.hooks.actions.beforeAct / afterAct).
+    // beforeActRan guards afterAct so we only fire after-hooks for invocations
+    // where before-hooks also fired (i.e. action found + params validated).
+    const actCtx: ActContext = { metadata: {} };
+    let beforeActRan = false;
     try {
       action = this.findAction(actionName);
       if (!action) {
@@ -122,6 +175,11 @@ export class Connection<
 
       formattedParams = await this.formatParams(params, action);
 
+      for (const hook of api.hooks.actions.beforeActHooks) {
+        await hook(action.name, formattedParams, this, actCtx);
+      }
+      beforeActRan = true;
+
       for (const middleware of action.middleware ?? []) {
         if (middleware.runBefore) {
           const middlewareResponse = await middleware.runBefore(
@@ -184,19 +242,20 @@ export class Connection<
           }
         }
       }
+      if (beforeActRan && action && formattedParams) {
+        const actDuration = new Date().getTime() - reqStartTime;
+        const outcome: ActOutcome = error
+          ? { success: false, error, duration: actDuration }
+          : { success: true, response, duration: actDuration };
+        for (const hook of api.hooks.actions.afterActHooks) {
+          await hook(action.name, formattedParams, this, actCtx, outcome);
+        }
+      }
       this._actDepth--;
     }
 
     const duration = new Date().getTime() - reqStartTime;
 
-    api.observability.action.executionsTotal.add(1, {
-      action: actionName ?? "unknown",
-      status: loggerResponsePrefix === "OK" ? "success" : "error",
-    });
-    api.observability.action.duration.record(duration, {
-      action: actionName ?? "unknown",
-    });
-
     logAction({
       actionName,
       connectionType: this.type,

package/index.ts

@@ -5,6 +5,7 @@ import "./initializers/actionts";
 import "./initializers/channels";
 import "./initializers/connections";
 import "./initializers/db";
+import "./initializers/hooks";
 import "./initializers/mcp";
 import "./initializers/oauth";
 import "./initializers/observability";
@@ -22,16 +23,43 @@ export type { ActionMiddleware } from "./classes/Action";
 export { HTTP_METHOD, MCP_RESPONSE_FORMAT } from "./classes/Action";
 export type { ChannelMiddleware } from "./classes/Channel";
 export { CHANNEL_NAME_PATTERN } from "./classes/Channel";
+export type {
+  ActContext,
+  ActOutcome,
+  AfterActHook,
+  BeforeActHook,
+} from "./classes/Connection";
 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";
+export type { OnEnqueueHook } from "./initializers/actionts";
+export type {
+  OnMcpConnectHook,
+  OnMcpDisconnectHook,
+  OnMcpMessageHook,
+} from "./initializers/mcp";
+export type {
+  AfterJobHook,
+  BeforeJobHook,
+  JobContext,
+  JobOutcome,
+} from "./initializers/resque";
 export type { SessionData } from "./initializers/session";
 export { checkRateLimit, RateLimitMiddleware } from "./middleware/rateLimit";
 export { TransactionMiddleware } from "./middleware/transaction";
-export type { WebServer } from "./servers/web";
+export type {
+  AfterRequestHook,
+  BeforeRequestHook,
+  OnConnectHook,
+  OnDisconnectHook,
+  OnMessageHook,
+  RequestContext,
+  RequestOutcome,
+  WebServer,
+} from "./servers/web";
 export { buildProgram } from "./util/cli";
 export { deepMerge, deepMergeDefaults, loadFromEnvIfSet } from "./util/config";
 export { getValidTypes } from "./util/generate";

package/initializers/actionts.ts

@@ -68,11 +68,44 @@ declare module "keryx" {
 
 export type TaskInputs = Record<string, any>;
 
+/**
+ * Runs when any action is enqueued — via {@link Actions.enqueue}, {@link Actions.enqueueAt},
+ * {@link Actions.enqueueIn}, or the per-job calls inside {@link Actions.fanOut}. Fires after
+ * the queue has been resolved and before the job is placed in Redis.
+ *
+ * Return a new `TaskInputs` object to replace the payload (e.g. to inject trace headers),
+ * or return `void` / `undefined` to leave the payload unchanged. If multiple hooks are
+ * registered they run sequentially in registration order; each receives the output of
+ * the previous one.
+ *
+ * Register via `api.hooks.actions.onEnqueue(...)`.
+ */
+export type OnEnqueueHook = (
+  actionName: string,
+  inputs: TaskInputs,
+  queue: string,
+) => Promise<TaskInputs | void> | TaskInputs | void;
+
 export class Actions extends Initializer {
   constructor() {
     super(namespace);
+    this.dependsOn = ["hooks"];
   }
 
+  /** Run all registered `onEnqueue` hooks, threading inputs through each. */
+  private runOnEnqueueHooks = async (
+    actionName: string,
+    inputs: TaskInputs,
+    queue: string,
+  ): Promise<TaskInputs> => {
+    let current = inputs;
+    for (const hook of api.hooks.actions.onEnqueueHooks) {
+      const next = await hook(actionName, current, queue);
+      if (next !== undefined) current = next;
+    }
+    return current;
+  };
+
   /**
    * Enqueue an action to be performed in the background.
    *
@@ -96,11 +129,8 @@ export class Actions extends Initializer {
       });
     }
     queue = queue ?? action?.task?.queue ?? DEFAULT_QUEUE;
-    api.observability.task.enqueuedTotal.add(1, {
-      action: actionName,
-      queue,
-    });
-    return api.resque.queue.enqueue(queue, actionName, [inputs]);
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
+    return api.resque.queue.enqueue(queue, actionName, [finalInputs]);
   };
 
   /**
@@ -302,11 +332,12 @@ export class Actions extends Initializer {
     queue: string = DEFAULT_QUEUE,
     suppressDuplicateTaskError = false,
   ) => {
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
     return api.resque.queue.enqueueAt(
       timestamp,
       queue,
       actionName,
-      [inputs],
+      [finalInputs],
       suppressDuplicateTaskError,
     );
   };
@@ -328,11 +359,12 @@ export class Actions extends Initializer {
     queue: string = DEFAULT_QUEUE,
     suppressDuplicateTaskError = false,
   ) => {
+    const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
     return api.resque.queue.enqueueIn(
       time,
       queue,
       actionName,
-      [inputs],
+      [finalInputs],
       suppressDuplicateTaskError,
     );
   };

package/initializers/hooks.ts

@@ -0,0 +1,193 @@
+import type { AfterActHook, BeforeActHook } from "../classes/Connection";
+import { Initializer } from "../classes/Initializer";
+import type {
+  AfterRequestHook,
+  BeforeRequestHook,
+  OnConnectHook,
+  OnDisconnectHook,
+  OnMessageHook,
+} from "../servers/web";
+import type { OnEnqueueHook } from "./actionts";
+import type {
+  OnMcpConnectHook,
+  OnMcpDisconnectHook,
+  OnMcpMessageHook,
+} from "./mcp";
+import type { AfterJobHook, BeforeJobHook } from "./resque";
+
+const namespace = "hooks";
+
+declare module "keryx" {
+  export interface API {
+    [namespace]: Awaited<ReturnType<Hooks["initialize"]>>;
+  }
+}
+
+/**
+ * Central registry for framework lifecycle hooks. Plugins register hooks here
+ * from their initializer's `initialize()`; the framework iterates the registered
+ * hooks at runtime.
+ *
+ * Public surface: `api.hooks.web`, `api.hooks.ws`, `api.hooks.mcp`,
+ * `api.hooks.actions`, `api.hooks.resque`. See the respective hook type
+ * definitions for semantics (in `servers/web.ts`, `initializers/mcp.ts`,
+ * `initializers/actionts.ts`, `initializers/resque.ts`).
+ */
+export class Hooks extends Initializer {
+  private webBeforeRequest: BeforeRequestHook[] = [];
+  private webAfterRequest: AfterRequestHook[] = [];
+  private wsOnConnect: OnConnectHook[] = [];
+  private wsOnMessage: OnMessageHook[] = [];
+  private wsOnDisconnect: OnDisconnectHook[] = [];
+  private mcpOnConnect: OnMcpConnectHook[] = [];
+  private mcpOnMessage: OnMcpMessageHook[] = [];
+  private mcpOnDisconnect: OnMcpDisconnectHook[] = [];
+  private actionsOnEnqueue: OnEnqueueHook[] = [];
+  private actionsBeforeAct: BeforeActHook[] = [];
+  private actionsAfterAct: AfterActHook[] = [];
+  private resqueBeforeJob: BeforeJobHook[] = [];
+  private resqueAfterJob: AfterJobHook[] = [];
+
+  constructor() {
+    super(namespace);
+  }
+
+  async initialize() {
+    const self = this;
+    return {
+      web: {
+        /**
+         * Register a hook to run at the start of every HTTP request, before
+         * routing. Covers static files, OAuth, MCP, metrics, and actions.
+         * Does not fire for WebSocket upgrades.
+         */
+        beforeRequest(hook: BeforeRequestHook): void {
+          self.webBeforeRequest.push(hook);
+        },
+        /**
+         * Register a hook to run after the `Response` is built, before
+         * compression. Receives the same `ctx` object passed to `beforeRequest`,
+         * so state stashed in `ctx.metadata` flows through.
+         */
+        afterRequest(hook: AfterRequestHook): void {
+          self.webAfterRequest.push(hook);
+        },
+        /** @internal Iterated by `WebServer.handleIncomingConnection`. */
+        beforeRequestHooks:
+          self.webBeforeRequest as ReadonlyArray<BeforeRequestHook>,
+        /** @internal Iterated by `WebServer.handleIncomingConnection`. */
+        afterRequestHooks:
+          self.webAfterRequest as ReadonlyArray<AfterRequestHook>,
+      },
+      ws: {
+        /**
+         * Register a hook to run when a new WebSocket connection is accepted,
+         * after the `Connection` has been constructed and registered.
+         */
+        onConnect(hook: OnConnectHook): void {
+          self.wsOnConnect.push(hook);
+        },
+        /**
+         * Register a hook to run for each inbound WebSocket message, after
+         * rate-limiting but before message parsing / dispatch.
+         */
+        onMessage(hook: OnMessageHook): void {
+          self.wsOnMessage.push(hook);
+        },
+        /**
+         * Register a hook to run when a WebSocket connection closes, before
+         * channel presence is cleaned up and the connection is destroyed.
+         */
+        onDisconnect(hook: OnDisconnectHook): void {
+          self.wsOnDisconnect.push(hook);
+        },
+        /** @internal Iterated by `WebServer.handleWebSocketConnectionOpen`. */
+        onConnectHooks: self.wsOnConnect as ReadonlyArray<OnConnectHook>,
+        /** @internal Iterated by `WebServer.handleWebSocketConnectionMessage`. */
+        onMessageHooks: self.wsOnMessage as ReadonlyArray<OnMessageHook>,
+        /** @internal Iterated by `WebServer.handleWebSocketConnectionClose`. */
+        onDisconnectHooks:
+          self.wsOnDisconnect as ReadonlyArray<OnDisconnectHook>,
+      },
+      mcp: {
+        /**
+         * Register a hook to run when a new MCP session is initialized (after
+         * the MCP initialize handshake completes).
+         */
+        onConnect(hook: OnMcpConnectHook): void {
+          self.mcpOnConnect.push(hook);
+        },
+        /**
+         * Register a hook to run for each inbound MCP request (POST/GET/DELETE
+         * to the MCP route). Fires before the transport dispatches the request.
+         * `sessionId` is `undefined` for the very first POST that creates a
+         * session.
+         */
+        onMessage(hook: OnMcpMessageHook): void {
+          self.mcpOnMessage.push(hook);
+        },
+        /**
+         * Register a hook to run when an MCP session's transport closes.
+         */
+        onDisconnect(hook: OnMcpDisconnectHook): void {
+          self.mcpOnDisconnect.push(hook);
+        },
+        /** @internal Iterated by the MCP handler on session init. */
+        onConnectHooks: self.mcpOnConnect as ReadonlyArray<OnMcpConnectHook>,
+        /** @internal Iterated by the MCP handler before dispatching a request. */
+        onMessageHooks: self.mcpOnMessage as ReadonlyArray<OnMcpMessageHook>,
+        /** @internal Iterated by the MCP handler on transport close. */
+        onDisconnectHooks:
+          self.mcpOnDisconnect as ReadonlyArray<OnMcpDisconnectHook>,
+      },
+      actions: {
+        /**
+         * Register a hook to run on every enqueue. Fires for `enqueue`,
+         * `enqueueAt`, `enqueueIn`, and per-job inside `fanOut`. Hooks may
+         * mutate inputs by returning a replacement object.
+         */
+        onEnqueue(hook: OnEnqueueHook): void {
+          self.actionsOnEnqueue.push(hook);
+        },
+        /**
+         * Register a hook to run inside `Connection.act()` after params are
+         * validated and before the action's `runBefore` middleware. Fires for
+         * every action invocation across all transports (web, websocket, task,
+         * cli, mcp, …) — inspect `connection.type` to discriminate.
+         */
+        beforeAct(hook: BeforeActHook): void {
+          self.actionsBeforeAct.push(hook);
+        },
+        /**
+         * Register a hook to run inside `Connection.act()` in a `finally` block
+         * after the action completes (success or failure). Receives the same
+         * `ctx` as `beforeAct` plus a unified {@link ActOutcome}. Fires across
+         * all transports.
+         */
+        afterAct(hook: AfterActHook): void {
+          self.actionsAfterAct.push(hook);
+        },
+        /** @internal Iterated by `Actions.enqueue`, `enqueueAt`, `enqueueIn`. */
+        onEnqueueHooks: self.actionsOnEnqueue as ReadonlyArray<OnEnqueueHook>,
+        /** @internal Iterated inside `Connection.act`. */
+        beforeActHooks: self.actionsBeforeAct as ReadonlyArray<BeforeActHook>,
+        /** @internal Iterated inside `Connection.act`. */
+        afterActHooks: self.actionsAfterAct as ReadonlyArray<AfterActHook>,
+      },
+      resque: {
+        /** Register a hook to run before each job's action executes. */
+        beforeJob(hook: BeforeJobHook): void {
+          self.resqueBeforeJob.push(hook);
+        },
+        /** Register a hook to run after each job's action executes (success or failure). */
+        afterJob(hook: AfterJobHook): void {
+          self.resqueAfterJob.push(hook);
+        },
+        /** @internal Iterated inside `wrapActionAsJob.perform`. */
+        beforeJobHooks: self.resqueBeforeJob as ReadonlyArray<BeforeJobHook>,
+        /** @internal Iterated inside `wrapActionAsJob.perform`. */
+        afterJobHooks: self.resqueAfterJob as ReadonlyArray<AfterJobHook>,
+      },
+    };
+  }
+}

package/initializers/mcp.ts

@@ -20,6 +20,29 @@ import type { PubSubMessage } from "./pubsub";
 
 type McpHandleRequest = (req: Request, ip: string) => Promise<Response>;
 
+/**
+ * Runs when a new MCP session is initialized (after the initialize JSON-RPC
+ * handshake). `sessionId` is the server-assigned session id.
+ * Register via `api.hooks.mcp.onConnect(...)`.
+ */
+export type OnMcpConnectHook = (sessionId: string) => Promise<void> | void;
+
+/**
+ * Runs for each inbound MCP HTTP request (POST/GET/DELETE to the MCP route),
+ * before it's dispatched to the transport. `sessionId` is `undefined` for the
+ * very first POST that creates a new session. Register via
+ * `api.hooks.mcp.onMessage(...)`.
+ */
+export type OnMcpMessageHook = (
+  sessionId: string | undefined,
+) => Promise<void> | void;
+
+/**
+ * Runs when an MCP session's transport closes and the session is torn down.
+ * Register via `api.hooks.mcp.onDisconnect(...)`.
+ */
+export type OnMcpDisconnectHook = (sessionId: string) => Promise<void> | void;
+
 const namespace = "mcp";
 
 declare module "keryx" {
@@ -31,7 +54,7 @@ declare module "keryx" {
 export class McpInitializer extends Initializer {
   constructor() {
     super(namespace);
-    this.dependsOn = ["actions", "oauth", "connections", "pubsub"];
+    this.dependsOn = ["hooks", "actions", "oauth", "connections", "pubsub"];
   }
 
   async initialize() {
@@ -187,8 +210,11 @@ export class McpInitializer extends Initializer {
         const transport = new WebStandardStreamableHTTPServerTransport({
           sessionIdGenerator: () => randomUUID(),
           enableJsonResponse: true,
-          onsessioninitialized: (sid) => {
+          onsessioninitialized: async (sid) => {
             transports.set(sid, transport);
+            for (const hook of api.hooks.mcp.onConnectHooks) {
+              await hook(sid);
+            }
           },
           onsessionclosed: (sid) => {
             transports.delete(sid);
@@ -197,10 +223,13 @@ export class McpInitializer extends Initializer {
           },
         });
 
-        transport.onclose = () => {
+        transport.onclose = async () => {
           const sid = transport.sessionId;
           if (sid) {
             transports.delete(sid);
+            for (const hook of api.hooks.mcp.onDisconnectHooks) {
+              await hook(sid);
+            }
           }
           const idx = mcpServers.indexOf(mcpServer);
           if (idx !== -1) mcpServers.splice(idx, 1);
@@ -208,6 +237,9 @@ export class McpInitializer extends Initializer {
 
         await mcpServer.connect(transport);
 
+        for (const hook of api.hooks.mcp.onMessageHooks) {
+          await hook(undefined);
+        }
         return handleTransportRequest(transport, req, authInfo, corsHeaders);
       }
 
@@ -221,6 +253,9 @@ export class McpInitializer extends Initializer {
           );
         }
 
+        for (const hook of api.hooks.mcp.onMessageHooks) {
+          await hook(sessionId);
+        }
         return handleTransportRequest(transport, req, authInfo, corsHeaders);
       }
 

package/initializers/observability.ts

@@ -17,6 +17,55 @@ declare module "keryx" {
   }
 }
 
+type MeterAdd = (value: number, attributes?: Record<string, string>) => void;
+type MeterRecord = (value: number, attributes?: Record<string, string>) => void;
+
+interface HttpMeters {
+  requestsTotal: { add: MeterAdd };
+  requestDuration: { record: MeterRecord };
+}
+interface WsMeters {
+  connections: { add: MeterAdd };
+  messagesTotal: { add: MeterAdd };
+}
+interface McpMeters {
+  sessions: { add: MeterAdd };
+  messagesTotal: { add: MeterAdd };
+}
+interface ActionMeters {
+  executionsTotal: { add: MeterAdd };
+  duration: { record: MeterRecord };
+}
+interface TaskMeters {
+  enqueuedTotal: { add: MeterAdd };
+  executedTotal: { add: MeterAdd };
+  duration: { record: MeterRecord };
+}
+
+const noopAdd: MeterAdd = () => {};
+const noopRecord: MeterRecord = () => {};
+const noopHttp = (): HttpMeters => ({
+  requestsTotal: { add: noopAdd },
+  requestDuration: { record: noopRecord },
+});
+const noopWs = (): WsMeters => ({
+  connections: { add: noopAdd },
+  messagesTotal: { add: noopAdd },
+});
+const noopMcp = (): McpMeters => ({
+  sessions: { add: noopAdd },
+  messagesTotal: { add: noopAdd },
+});
+const noopAction = (): ActionMeters => ({
+  executionsTotal: { add: noopAdd },
+  duration: { record: noopRecord },
+});
+const noopTask = (): TaskMeters => ({
+  enqueuedTotal: { add: noopAdd },
+  executedTotal: { add: noopAdd },
+  duration: { record: noopRecord },
+});
+
 /**
  * Observability initializer — provides OpenTelemetry-based metrics for HTTP requests,
  * WebSocket connections, action executions, and background tasks.
@@ -24,41 +73,86 @@ declare module "keryx" {
  * Enable via `OTEL_METRICS_ENABLED=true`. The built-in Prometheus scrape endpoint is
  * served at `config.observability.metricsRoute` (default `/metrics`) on the existing
  * web server.
+ *
+ * All emission is wired through `api.hooks.*` — call sites elsewhere in the framework
+ * do not reference `api.observability` directly. Meter instruments are private to the
+ * initializer; apps that need custom metrics should create their own `Meter` off the
+ * global OTel `MeterProvider` that this initializer installs.
  */
 export class Observability extends Initializer {
+  private httpMeters: HttpMeters = noopHttp();
+  private wsMeters: WsMeters = noopWs();
+  private mcpMeters: McpMeters = noopMcp();
+  private actionMeters: ActionMeters = noopAction();
+  private taskMeters: TaskMeters = noopTask();
+
   constructor() {
     super(namespace);
-    this.dependsOn = ["actions", "connections"];
+    this.dependsOn = ["hooks", "actions", "connections"];
   }
 
   async initialize() {
-    const noopAdd = (
-      _value: number,
-      _attributes?: Record<string, string>,
-    ) => {};
-    const noopRecord = (
-      _value: number,
-      _attributes?: Record<string, string>,
-    ) => {};
-    return {
+    const ns = {
       enabled: false,
-      http: {
-        requestsTotal: { add: noopAdd },
-        requestDuration: { record: noopRecord },
-        activeConnections: { add: noopAdd },
-      },
-      ws: { connections: { add: noopAdd }, messagesTotal: { add: noopAdd } },
-      action: {
-        executionsTotal: { add: noopAdd },
-        duration: { record: noopRecord },
-      },
-      task: {
-        enqueuedTotal: { add: noopAdd },
-        executedTotal: { add: noopAdd },
-        duration: { record: noopRecord },
-      },
       collectMetrics: async () => "" as string,
     };
+
+    api.hooks.actions.afterAct((actionName, _params, _conn, _ctx, outcome) => {
+      this.actionMeters.executionsTotal.add(1, {
+        action: actionName,
+        status: outcome.success ? "success" : "error",
+      });
+      this.actionMeters.duration.record(outcome.duration, {
+        action: actionName,
+      });
+    });
+
+    api.hooks.actions.onEnqueue((actionName, _inputs, queue) => {
+      this.taskMeters.enqueuedTotal.add(1, { action: actionName, queue });
+    });
+
+    api.hooks.resque.afterJob((actionName, _params, ctx, outcome) => {
+      this.taskMeters.executedTotal.add(1, {
+        action: actionName,
+        queue: ctx.queue,
+        status: outcome.success ? "success" : "failure",
+      });
+      this.taskMeters.duration.record(outcome.duration, {
+        action: actionName,
+      });
+    });
+
+    api.hooks.web.afterRequest((_req, _res, _ctx, outcome) => {
+      const labels = {
+        method: outcome.method,
+        route: outcome.actionName ?? "unknown",
+        status: String(outcome.status),
+      };
+      this.httpMeters.requestsTotal.add(1, labels);
+      this.httpMeters.requestDuration.record(outcome.durationMs, labels);
+    });
+
+    api.hooks.ws.onConnect(() => {
+      this.wsMeters.connections.add(1);
+    });
+    api.hooks.ws.onMessage(() => {
+      this.wsMeters.messagesTotal.add(1);
+    });
+    api.hooks.ws.onDisconnect(() => {
+      this.wsMeters.connections.add(-1);
+    });
+
+    api.hooks.mcp.onConnect(() => {
+      this.mcpMeters.sessions.add(1);
+    });
+    api.hooks.mcp.onMessage(() => {
+      this.mcpMeters.messagesTotal.add(1);
+    });
+    api.hooks.mcp.onDisconnect(() => {
+      this.mcpMeters.sessions.add(-1);
+    });
+
+    return ns;
   }
 
   async start() {
@@ -118,52 +212,58 @@ export class Observability extends Initializer {
     metrics.setGlobalMeterProvider(meterProvider);
     const meter = meterProvider.getMeter(serviceName);
 
-    const ns = api.observability;
-    ns.enabled = true;
+    this.httpMeters = {
+      requestsTotal: meter.createCounter("keryx.http.requests", {
+        description: "Total number of HTTP requests received",
+      }),
+      requestDuration: meter.createHistogram("keryx.http.request.duration", {
+        description: "HTTP request duration in milliseconds",
+        unit: "ms",
+      }),
+    };
 
-    // --- HTTP Metrics ---
-    ns.http.requestsTotal = meter.createCounter("keryx.http.requests", {
-      description: "Total number of HTTP requests received",
-    });
-    ns.http.requestDuration = meter.createHistogram(
-      "keryx.http.request.duration",
-      { description: "HTTP request duration in milliseconds", unit: "ms" },
-    );
-    ns.http.activeConnections = meter.createUpDownCounter(
-      "keryx.http.active_connections",
-      { description: "Number of active HTTP connections" },
-    );
-
-    // --- WebSocket Metrics ---
-    ns.ws.connections = meter.createUpDownCounter("keryx.ws.connections", {
-      description: "Number of active WebSocket connections",
-    });
-    ns.ws.messagesTotal = meter.createCounter("keryx.ws.messages", {
-      description: "Total WebSocket messages received",
-    });
+    this.wsMeters = {
+      connections: meter.createUpDownCounter("keryx.ws.connections", {
+        description: "Number of active WebSocket connections",
+      }),
+      messagesTotal: meter.createCounter("keryx.ws.messages", {
+        description: "Total WebSocket messages received",
+      }),
+    };
 
-    // --- Action Metrics ---
-    ns.action.executionsTotal = meter.createCounter("keryx.action.executions", {
-      description: "Total action executions",
-    });
-    ns.action.duration = meter.createHistogram("keryx.action.duration", {
-      description: "Action execution duration in milliseconds",
-      unit: "ms",
-    });
+    this.mcpMeters = {
+      sessions: meter.createUpDownCounter("keryx.mcp.sessions", {
+        description: "Number of active MCP sessions",
+      }),
+      messagesTotal: meter.createCounter("keryx.mcp.messages", {
+        description: "Total MCP requests received",
+      }),
+    };
 
-    // --- Task Metrics ---
-    ns.task.enqueuedTotal = meter.createCounter("keryx.task.enqueued", {
-      description: "Total tasks enqueued",
-    });
-    ns.task.executedTotal = meter.createCounter("keryx.task.executed", {
-      description: "Total tasks executed by workers",
-    });
-    ns.task.duration = meter.createHistogram("keryx.task.duration", {
-      description: "Task execution duration in milliseconds",
-      unit: "ms",
-    });
+    this.actionMeters = {
+      executionsTotal: meter.createCounter("keryx.action.executions", {
+        description: "Total action executions",
+      }),
+      duration: meter.createHistogram("keryx.action.duration", {
+        description: "Action execution duration in milliseconds",
+        unit: "ms",
+      }),
+    };
+
+    this.taskMeters = {
+      enqueuedTotal: meter.createCounter("keryx.task.enqueued", {
+        description: "Total tasks enqueued",
+      }),
+      executedTotal: meter.createCounter("keryx.task.executed", {
+        description: "Total tasks executed by workers",
+      }),
+      duration: meter.createHistogram("keryx.task.duration", {
+        description: "Task execution duration in milliseconds",
+        unit: "ms",
+      }),
+    };
 
-    // --- System Metrics (observable gauges) ---
+    // System gauge — reads directly from api.connections at scrape time
     meter
       .createObservableGauge("keryx.system.connections", {
         description: "Current number of connections",
@@ -174,43 +274,30 @@ export class Observability extends Initializer {
         }
       });
 
-    ns.collectMetrics = async () => {
+    api.observability.collectMetrics = async () => {
       const { resourceMetrics, errors } = await reader.collect();
       if (errors?.length) {
         logger.warn(`Metrics collection errors: ${errors.join(", ")}`);
       }
       return serializeToPrometheus(resourceMetrics);
     };
+    api.observability.enabled = true;
 
     logger.info(`Observability initialized (service: ${serviceName})`);
   }
 
   async stop() {
-    // Reset to no-ops so the next start() cycle can re-initialize cleanly.
+    // Reset meters to no-ops so the next start() cycle can re-initialize cleanly.
     // MeterProvider is intentionally NOT shut down — shutting it down would
     // make the reader unable to collect, but start() may create a new one.
     // In production stop() is called right before process exit.
-    const noopAdd = (
-      _value: number,
-      _attributes?: Record<string, string>,
-    ) => {};
-    const noopRecord = (
-      _value: number,
-      _attributes?: Record<string, string>,
-    ) => {};
-    const ns = api.observability;
-    ns.enabled = false;
-    ns.http.requestsTotal = { add: noopAdd };
-    ns.http.requestDuration = { record: noopRecord };
-    ns.http.activeConnections = { add: noopAdd };
-    ns.ws.connections = { add: noopAdd };
-    ns.ws.messagesTotal = { add: noopAdd };
-    ns.action.executionsTotal = { add: noopAdd };
-    ns.action.duration = { record: noopRecord };
-    ns.task.enqueuedTotal = { add: noopAdd };
-    ns.task.executedTotal = { add: noopAdd };
-    ns.task.duration = { record: noopRecord };
-    ns.collectMetrics = async () => "";
+    this.httpMeters = noopHttp();
+    this.wsMeters = noopWs();
+    this.mcpMeters = noopMcp();
+    this.actionMeters = noopAction();
+    this.taskMeters = noopTask();
+    api.observability.collectMetrics = async () => "";
+    api.observability.enabled = false;
   }
 }
 

package/initializers/resque.ts

@@ -18,9 +18,56 @@ import {
 import { Initializer } from "../classes/Initializer";
 import { LogFormat } from "../classes/Logger";
 import { TypedError } from "../classes/TypedError";
+import type { TaskInputs } from "./actionts";
 
 const namespace = "resque";
 
+/**
+ * Per-job context passed to {@link BeforeJobHook} and {@link AfterJobHook}.
+ * The same object instance is threaded from `beforeJob` to `afterJob`, so hooks can
+ * stash span refs, timing data, or any other state in `metadata`.
+ */
+export interface JobContext {
+  /** The queue this job was pulled from. Populated from the node-resque worker. */
+  queue: string;
+  /** Mutable scratch space shared between `beforeJob` and `afterJob`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Unified outcome passed to {@link AfterJobHook}. Discriminate via the `success` field.
+ * Covers both the worker `success` and `failure` paths in a single shape.
+ */
+export type JobOutcome =
+  | { success: true; result: unknown; duration: number }
+  | { success: false; error: unknown; duration: number };
+
+/**
+ * Runs inside the job wrapper immediately before the action executes (i.e. before
+ * `connection.act()`). Receives the action name and decoded params, giving plugins
+ * access to trace headers or other correlation data embedded in inputs. Hooks run
+ * sequentially in registration order. Throwing fails the job.
+ */
+export type BeforeJobHook = (
+  actionName: string,
+  params: TaskInputs,
+  ctx: JobContext,
+) => Promise<void> | void;
+
+/**
+ * Runs inside the job wrapper after the action executes, in a `finally` block so it
+ * fires for both success and failure. Receives the same `ctx` passed to `beforeJob`
+ * plus a {@link JobOutcome} describing what happened. Hooks run sequentially in
+ * registration order. Errors thrown by an `afterJob` hook do not mask an action
+ * error but may surface instead of it if the action succeeded.
+ */
+export type AfterJobHook = (
+  actionName: string,
+  params: TaskInputs,
+  ctx: JobContext,
+  outcome: JobOutcome,
+) => Promise<void> | void;
+
 function logResqueEvent(
   level: "info" | "warn",
   textMessage: string,
@@ -49,7 +96,7 @@ let SERVER_JOB_COUNTER = 1;
 export class Resque extends Initializer {
   constructor() {
     super(namespace);
-    this.dependsOn = ["redis", "actions", "process"];
+    this.dependsOn = ["redis", "actions", "process", "hooks"];
   }
 
   /** Create and connect the resque `Queue` instance (used for enqueuing jobs). */
@@ -167,14 +214,6 @@ export class Resque extends Initializer {
       });
 
       worker.on("failure", (queue, job, failure, duration) => {
-        api.observability.task.executedTotal.add(1, {
-          action: job.class,
-          queue,
-          status: "failure",
-        });
-        api.observability.task.duration.record(duration, {
-          action: job.class,
-        });
         logResqueEvent(
           "warn",
           `[resque:${worker.name}] job failed, ${queue}, ${job.class}, ${JSON.stringify(job?.args[0] ?? {})}: ${failure} (${duration}ms)`,
@@ -205,14 +244,6 @@ export class Resque extends Initializer {
       });
 
       worker.on("success", (queue, job: ParsedJob, result, duration) => {
-        api.observability.task.executedTotal.add(1, {
-          action: job.class,
-          queue,
-          status: "success",
-        });
-        api.observability.task.duration.record(duration, {
-          action: job.class,
-        });
         logResqueEvent(
           "info",
           `[resque:${worker.name}] job success ${queue}, ${job.class}, ${JSON.stringify(job.args[0])} | ${JSON.stringify(result)} (${duration}ms)`,
@@ -322,15 +353,41 @@ export class Resque extends Initializer {
 
         const fanOutId = plainParams._fanOutId as string | undefined;
 
+        // node-resque invokes `perform` via `.apply(worker, args)`, so `this`
+        // is the Worker and `Worker.queue` is the queue the current job was
+        // pulled from. TypeScript infers `this` as the Job here because
+        // `perform` lives inside the Job literal, so cast through `unknown` to
+        // read the runtime binding. Exposed on JobContext so hooks (e.g.
+        // observability) can label per-job metrics.
+        const runtimeThis = this as unknown as { queue?: unknown };
+        const currentQueue =
+          typeof runtimeThis?.queue === "string" ? runtimeThis.queue : "";
+        const jobCtx: JobContext = { queue: currentQueue, metadata: {} };
+        const jobStartTime = Date.now();
+
         let response: Awaited<ReturnType<(typeof action)["run"]>>;
         let error: TypedError | undefined;
+        let outcome: JobOutcome | undefined;
         try {
+          for (const hook of api.hooks.resque.beforeJobHooks) {
+            await hook(action.name, plainParams, jobCtx);
+          }
           const payload = await connection.act(action.name, plainParams);
           response = payload.response;
           error = payload.error;
 
           if (error) throw error;
+          outcome = {
+            success: true,
+            result: response,
+            duration: Date.now() - jobStartTime,
+          };
         } catch (e) {
+          outcome = {
+            success: false,
+            error: e,
+            duration: Date.now() - jobStartTime,
+          };
           // Collect fan-out error before re-throwing
           if (fanOutId) {
             const metaKey = `fanout:${fanOutId}`;
@@ -351,6 +408,11 @@ export class Resque extends Initializer {
           }
           throw e;
         } finally {
+          if (outcome) {
+            for (const hook of api.hooks.resque.afterJobHooks) {
+              await hook(action.name, plainParams, jobCtx, outcome);
+            }
+          }
           if (
             action.task &&
             action.task.frequency &&

package/initializers/servers.ts

@@ -17,7 +17,7 @@ declare module "keryx" {
 export class Servers extends Initializer {
   constructor() {
     super(namespace);
-    this.dependsOn = ["actions"];
+    this.dependsOn = ["actions", "hooks"];
     this.runModes = [RUN_MODE.SERVER];
   }
 

package/package.json

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

package/servers/web.ts

@@ -25,10 +25,88 @@ import {
 } from "../util/webSocket";
 import { handleStaticFile } from "../util/webStaticFiles";
 
+/**
+ * Per-request context passed to {@link BeforeRequestHook} and {@link AfterRequestHook}.
+ * The same object instance is passed to both hooks for a given request, so `beforeRequest`
+ * implementations can stash state (e.g. span refs, start time) in `metadata` for
+ * `afterRequest` to pick up.
+ */
+export interface RequestContext {
+  /** Client IP address as reported by `server.requestIP()`, or `"unknown-IP"`. */
+  ip: string;
+  /** Session id from the session cookie, or a freshly minted UUID. */
+  id: string;
+  /** Mutable scratch space shared between `beforeRequest` and `afterRequest`. */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Outcome payload passed to {@link AfterRequestHook} describing the routed request.
+ * `actionName` is `undefined` for paths that don't resolve to an action (static files,
+ * OAuth/MCP endpoints, `/metrics`, 404s).
+ */
+export interface RequestOutcome {
+  /** HTTP method (uppercased). */
+  method: string;
+  /** Response status code. */
+  status: number;
+  /** Resolved action name, if the request routed to an action. */
+  actionName?: string;
+  /** End-to-end handling time in milliseconds (measured at hook-fire time). */
+  durationMs: number;
+}
+
+/**
+ * Runs at the start of every HTTP request, before any routing or static file handling.
+ * WebSocket upgrades do not fire this hook. Throwing an error propagates out of the
+ * request handler. Hooks run sequentially in registration order.
+ */
+export type BeforeRequestHook = (
+  req: Request,
+  ctx: RequestContext,
+) => Promise<void> | void;
+
+/**
+ * Runs after the `Response` is built and before compression. Receives the same `ctx`
+ * object that was passed to the matching `beforeRequest`, plus a {@link RequestOutcome}
+ * with the resolved routing decision (action name, status, duration). Hooks run
+ * sequentially in registration order.
+ */
+export type AfterRequestHook = (
+  req: Request,
+  res: Response,
+  ctx: RequestContext,
+  outcome: RequestOutcome,
+) => Promise<void> | void;
+
+/**
+ * Runs when a new WebSocket connection is accepted, after the {@link Connection}
+ * has been constructed and registered. Register via `api.hooks.ws.onConnect(...)`.
+ */
+export type OnConnectHook = (connection: Connection) => Promise<void> | void;
+
+/**
+ * Runs for each inbound WebSocket message, after rate-limiting but before parsing.
+ * Register via `api.hooks.ws.onMessage(...)`.
+ */
+export type OnMessageHook = (
+  connection: Connection,
+  message: string | Buffer,
+) => Promise<void> | void;
+
+/**
+ * Runs when a WebSocket connection closes, before channel presence is cleaned up
+ * and the connection is destroyed. Register via `api.hooks.ws.onDisconnect(...)`.
+ */
+export type OnDisconnectHook = (connection: Connection) => Promise<void> | void;
+
 /**
  * HTTP + WebSocket server built on `Bun.serve`. Handles REST action routing (with path params),
  * static file serving (with ETag/304 caching), WebSocket connections (actions, PubSub subscribe/unsubscribe),
- * OAuth endpoints, and MCP SSE streams. Exposes `api.servers.web`.
+ * OAuth endpoints, and MCP SSE streams.
+ *
+ * Plugins register HTTP lifecycle hooks via `api.hooks.web.beforeRequest` /
+ * `api.hooks.web.afterRequest`.
  */
 export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
   /** The actual port the server bound to (resolved after start, e.g. when config port is 0). */
@@ -169,7 +247,28 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     )
       return; // upgrade the request to a WebSocket
 
-    const response = await this.handleHttpRequest(req, server, ip, id);
+    const ctx: RequestContext = { ip, id, metadata: {} };
+    const requestStart = Date.now();
+    for (const hook of api.hooks.web.beforeRequestHooks) {
+      await hook(req, ctx);
+    }
+
+    const { response, actionName } = await this.handleHttpRequest(
+      req,
+      server,
+      ip,
+      id,
+    );
+
+    const outcome: RequestOutcome = {
+      method: req.method.toUpperCase(),
+      status: response.status,
+      actionName,
+      durationMs: Date.now() - requestStart,
+    };
+    for (const hook of api.hooks.web.afterRequestHooks) {
+      await hook(req, response, ctx, outcome);
+    }
 
     // SSE and other streaming responses: disable idle timeout and skip compression
     if (response.headers.get("Content-Type")?.includes("text/event-stream")) {
@@ -183,25 +282,27 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
   /**
    * Routes an HTTP request to the appropriate handler (static files, OAuth, MCP, metrics, or actions).
    * Called after WebSocket upgrade handling; the returned Response is compressed by the caller.
+   * Returns `actionName` alongside the response so `afterRequest` hooks can receive a
+   * {@link RequestOutcome} without snooping on internal routing state.
    */
   private async handleHttpRequest(
     req: Request,
     server: ReturnType<typeof Bun.serve>,
     ip: string,
     id: string,
-  ): Promise<Response> {
+  ): Promise<{ response: Response; actionName?: string }> {
     const parsedUrl = parse(req.url!, true);
 
     // Handle static file serving
     if (config.server.web.staticFiles.enabled && req.method === "GET") {
       const staticResponse = await handleStaticFile(req, parsedUrl);
-      if (staticResponse) return staticResponse;
+      if (staticResponse) return { response: staticResponse };
     }
 
     // OAuth route interception (must come before MCP route check)
     if (config.server.mcp.enabled && api.oauth?.handleRequest) {
       const oauthResponse = await api.oauth.handleRequest(req, ip);
-      if (oauthResponse) return oauthResponse;
+      if (oauthResponse) return { response: oauthResponse };
     }
 
     // MCP route interception
@@ -211,7 +312,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
         api.mcp?.handleRequest
       ) {
         server.timeout(req, 0); // disable idle timeout for long-lived MCP SSE streams
-        return api.mcp.handleRequest(req, ip);
+        return { response: await api.mcp.handleRequest(req, ip) };
       }
     }
 
@@ -221,32 +322,36 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       parsedUrl.pathname === config.observability.metricsRoute
     ) {
       const body = await api.observability.collectMetrics();
-      return new Response(body || "", {
-        status: 200,
-        headers: {
-          "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
-        },
-      });
+      return {
+        response: new Response(body || "", {
+          status: 200,
+          headers: {
+            "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+          },
+        }),
+      };
     }
 
     // Don't route .well-known paths to actions (covers both root and
     // sub-path variants like /mcp/.well-known/openid-configuration)
     if (parsedUrl.pathname?.includes("/.well-known/")) {
-      return new Response(null, { status: 404 });
+      return { response: new Response(null, { status: 404 }) };
     }
 
     return this.handleWebAction(req, parsedUrl, ip, id);
   }
 
   /** Called when a new WebSocket connection opens. Creates a `Connection` and wires up broadcast delivery. */
-  handleWebSocketConnectionOpen(ws: ServerWebSocket) {
+  async handleWebSocketConnectionOpen(ws: ServerWebSocket) {
     //@ts-expect-error (ws.data is not defined in the bun types)
     const { ip, id, wsConnectionId } = ws.data;
     const connection = new Connection("websocket", ip, wsConnectionId, ws, id);
     connection.onBroadcastMessageReceived = function (payload: PubSubMessage) {
       ws.send(JSON.stringify({ message: payload }));
     };
-    api.observability.ws.connections.add(1);
+    for (const hook of api.hooks.ws.onConnectHooks) {
+      await hook(connection);
+    }
     logger.info(
       `New websocket connection from ${connection.identifier} (${connection.id})`,
     );
@@ -300,7 +405,9 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       }
     }
 
-    api.observability.ws.messagesTotal.add(1);
+    for (const hook of api.hooks.ws.onMessageHooks) {
+      await hook(connection, message);
+    }
 
     try {
       const parsedMessage = JSON.parse(message.toString());
@@ -341,7 +448,9 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     );
     if (!connection) return;
 
-    api.observability.ws.connections.add(-1);
+    for (const hook of api.hooks.ws.onDisconnectHooks) {
+      await hook(connection);
+    }
     this.wsRateMap.delete(connection.id);
 
     try {
@@ -368,7 +477,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     url: ReturnType<typeof parse>,
     ip: string,
     id: string,
-  ) {
+  ): Promise<{ response: Response; actionName?: string }> {
     if (!this.server) {
       throw new TypedError({
         message: "Server server not started",
@@ -376,11 +485,9 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       });
     }
 
-    const httpStartTime = Date.now();
     let errorStatusCode = 500;
     const httpMethod = req.method?.toUpperCase() as HTTP_METHOD;
 
-    api.observability.http.activeConnections.add(1);
     const connection = new Connection("web", ip, id);
 
     if (
@@ -397,8 +504,9 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
 
     // Handle OPTIONS requests.
     // As we don't really know what action the client wants (HTTP Method is always OPTIONS), we just return a 200 response.
-    if (httpMethod === "OPTIONS")
-      return buildResponse(connection, {}, 200, requestOrigin);
+    if (httpMethod === "OPTIONS") {
+      return { response: buildResponse(connection, {}, 200, requestOrigin) };
+    }
 
     const { actionName, pathParams } = await determineActionName(
       url,
@@ -419,39 +527,24 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     if (response instanceof StreamingResponse) {
       response.onClose = () => {
         connection.destroy();
-        api.observability.http.activeConnections.add(-1);
       };
-
-      api.observability.http.requestsTotal.add(1, {
-        method: httpMethod,
-        route: actionName ?? "unknown",
-        status: "200",
-      });
-
-      return buildResponse(connection, response, 200, requestOrigin);
+      return {
+        response: buildResponse(connection, response, 200, requestOrigin),
+        actionName: actionName ?? undefined,
+      };
     }
 
     connection.destroy();
-    api.observability.http.activeConnections.add(-1);
 
     if (error && ErrorStatusCodes[error.type]) {
       errorStatusCode = ErrorStatusCodes[error.type];
     }
 
-    const statusCode = error ? errorStatusCode : 200;
-    api.observability.http.requestsTotal.add(1, {
-      method: httpMethod,
-      route: actionName ?? "unknown",
-      status: String(statusCode),
-    });
-    api.observability.http.requestDuration.record(Date.now() - httpStartTime, {
-      method: httpMethod,
-      route: actionName ?? "unknown",
-      status: String(statusCode),
-    });
-
-    return error
-      ? buildError(connection, error, errorStatusCode, requestOrigin)
-      : buildResponse(connection, response, 200, requestOrigin);
+    return {
+      response: error
+        ? buildError(connection, error, errorStatusCode, requestOrigin)
+        : buildResponse(connection, response, 200, requestOrigin),
+      actionName: actionName ?? undefined,
+    };
   }
 }