keryx 0.26.0 → 0.29.1

package/classes/Connection.ts

@@ -256,14 +256,6 @@ export class Connection<
 
     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

@@ -36,6 +36,11 @@ 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,
@@ -48,7 +53,11 @@ export { TransactionMiddleware } from "./middleware/transaction";
 export type {
   AfterRequestHook,
   BeforeRequestHook,
+  OnConnectHook,
+  OnDisconnectHook,
+  OnMessageHook,
   RequestContext,
+  RequestOutcome,
   WebServer,
 } from "./servers/web";
 export { buildProgram } from "./util/cli";

package/initializers/actionts.ts

@@ -130,10 +130,6 @@ export class Actions extends Initializer {
     }
     queue = queue ?? action?.task?.queue ?? DEFAULT_QUEUE;
     const finalInputs = await this.runOnEnqueueHooks(actionName, inputs, queue);
-    api.observability.task.enqueuedTotal.add(1, {
-      action: actionName,
-      queue,
-    });
     return api.resque.queue.enqueue(queue, actionName, [finalInputs]);
   };
 

package/initializers/hooks.ts

@@ -1,7 +1,18 @@
 import type { AfterActHook, BeforeActHook } from "../classes/Connection";
 import { Initializer } from "../classes/Initializer";
-import type { AfterRequestHook, BeforeRequestHook } from "../servers/web";
+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";
@@ -17,13 +28,20 @@ declare module "keryx" {
  * from their initializer's `initialize()`; the framework iterates the registered
  * hooks at runtime.
  *
- * Public surface: `api.hooks.web`, `api.hooks.actions`, `api.hooks.resque`. See
- * the respective hook type definitions for semantics (in `servers/web.ts`,
+ * 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[] = [];
@@ -61,6 +79,67 @@ export class Hooks extends Initializer {
         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`,

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

@@ -28,6 +28,8 @@ const namespace = "resque";
  * 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>;
 }
@@ -212,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)`,
@@ -250,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)`,
@@ -367,16 +353,25 @@ export class Resque extends Initializer {
 
         const fanOutId = plainParams._fanOutId as string | undefined;
 
-        const jobCtx: JobContext = { metadata: {} };
+        // 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();
-        for (const hook of api.hooks.resque.beforeJobHooks) {
-          await hook(action.name, plainParams, jobCtx);
-        }
 
         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;

package/package.json

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

package/servers/web.ts

@@ -40,6 +40,22 @@ export interface RequestContext {
   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
@@ -52,15 +68,38 @@ export type BeforeRequestHook = (
 
 /**
  * Runs after the `Response` is built and before compression. Receives the same `ctx`
- * object that was passed to the matching `beforeRequest`. Hooks run sequentially in
- * registration order.
+ * 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),
@@ -209,14 +248,26 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       return; // upgrade the request to a WebSocket
 
     const ctx: RequestContext = { ip, id, metadata: {} };
+    const requestStart = Date.now();
     for (const hook of api.hooks.web.beforeRequestHooks) {
       await hook(req, ctx);
     }
 
-    const response = await this.handleHttpRequest(req, server, ip, id);
+    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);
+      await hook(req, response, ctx, outcome);
     }
 
     // SSE and other streaming responses: disable idle timeout and skip compression
@@ -231,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
@@ -259,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) };
       }
     }
 
@@ -269,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})`,
     );
@@ -348,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());
@@ -389,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 {
@@ -416,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",
@@ -424,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 (
@@ -445,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,
@@ -467,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,
+    };
   }
 }

package/util/cli.ts

@@ -41,6 +41,10 @@ export async function buildProgram(opts: {
     .option("--no-interactive", "Skip prompts and use defaults")
     .option("--no-db", "Skip database setup files")
     .option("--no-example", "Skip example action")
+    .option(
+      "--force",
+      "Scaffold into an existing directory (skips files that already exist)",
+    )
     .action(async (projectName: string | undefined, cmdOpts) => {
       let options: ScaffoldOptions;
 
@@ -49,11 +53,12 @@ export async function buildProgram(opts: {
         options = {
           includeDb: cmdOpts.db !== false,
           includeExample: cmdOpts.example !== false,
+          force: cmdOpts.force === true,
         };
       } else {
         const result = await interactiveScaffold(projectName);
         projectName = result.projectName;
-        options = result.options;
+        options = { ...result.options, force: cmdOpts.force === true };
       }
 
       const targetDir = path.resolve(process.cwd(), projectName);

package/util/scaffold.ts

@@ -9,6 +9,12 @@ import { loadScaffoldTemplate as loadTemplate } from "./componentRegistry";
 export interface ScaffoldOptions {
   includeDb: boolean;
   includeExample: boolean;
+  /**
+   * When true, scaffold into an existing directory instead of refusing.
+   * Files that already exist on disk are left untouched (merge-skip); only
+   * missing files are created. User files are never overwritten.
+   */
+  force?: boolean;
 }
 
 async function prompt(question: string, defaultValue: string): Promise<string> {
@@ -263,9 +269,15 @@ export async function scaffoldProject(
   const keryxVersion = pkg.version;
   const createdFiles: string[] = [];
 
-  if (fs.existsSync(targetDir)) {
+  const dirExists = fs.existsSync(targetDir);
+  if (dirExists && !options.force) {
     throw new Error(`Directory "${projectName}" already exists`);
   }
+  if (dirExists && options.force) {
+    console.log(
+      `  ⚠ scaffolding into existing directory — existing files will be preserved`,
+    );
+  }
 
   fs.mkdirSync(targetDir, { recursive: true });
 
@@ -273,6 +285,10 @@ export async function scaffoldProject(
 
   const write = async (filePath: string, content: string) => {
     const fullPath = path.join(targetDir, filePath);
+    if (options.force && fs.existsSync(fullPath)) {
+      console.log(`  ⊘ skipped  ${filePath}`);
+      return;
+    }
     fs.mkdirSync(path.dirname(fullPath), { recursive: true });
     await Bun.write(fullPath, content);
     createdFiles.push(filePath);