@pikku/core 0.12.57 → 0.12.60

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.12.60
+
+### Patch Changes
+
+- a3a49f2: fix(workflow): carry `pikkuUserId` onto queued workflow step wires so authed steps rehydrate their session
+
+  A workflow step invoked on the queued (pg-boss) executor received the bare job wire (payload is just `{ runId }`), so `pikkuUserId` was never on the step wire and an authed step (`pikkuFunc`) threw `Authentication required` — even though the run wire persisted the acting user's id and the inline executor worked. `invokeStepRpc` now reads `pikkuUserId` from the persisted run wire and merges it into the step wire override, so authed steps rehydrate their session via the `SessionStore` on both the inline and queued paths.
+
+## 0.12.59
+
+### Patch Changes
+
+- 1f3f510: Warn when a Pikku function body performs a runtime dynamic `import(...)`.
+
+  The inspector now flags any `pikkuFunc`/`pikkuSessionlessFunc` (and friends) whose handler body contains a dynamic `import(...)` call — including nested callbacks — with the new `PKU498` diagnostic. Function bodies run on every invocation, so a dynamic import there adds per-call latency and defeats bundling/tree-shaking; the import belongs at the top of the module or in your services/`wireServices` setup instead.
+
+  Type-only positions like `import('x').Foo` are not flagged. The rule defaults to `warn` — a printed yellow warning that does not fail the build — and is configurable via `lint.functionDynamicImport` in `pikku.config.json` (`'off'` to silence, `'error'` to make it a hard build failure), matching the existing `servicesNotDestructured`/`wiresNotDestructured` lints.
+
+## 0.12.58
+
+### Patch Changes
+
+- 7b17b14: Allow a workflow-graph node's `func` to reference a registered AI agent by name, dispatched as an agent run — exactly like sub-workflows. `executeGraphStep`/`executeGraphNodeInline` now check the agent registry and dispatch matching nodes via the agent-run path (`rpc.agent.run`), so the node's result is the agent's declared output and downstream nodes can `ref()` it. The generated `pikkuWorkflowGraph` wrapper widens its node-func union to also accept `keyof FlattenedWorkflowMap` and `keyof FlattenedAgentMap`, and `ref()` resolves an agent node's output keys.
+- daec082: Drop Node 22 support — the minimum supported runtime is now Node 24 (LTS).
+
+  Node 22 deadlocks `pikku dev` at `loadUserBootstrap` (tsx `register()` + `require(esm)` cycle handling on node 22.12+), and Node 20 is already below our floor. The `engines.node` requirement is raised to `>=24` across all packages, matching `.nvmrc` and the CI test matrix. Closes #751.
+
+- e0fd352: wireGateway: allow `adapter` to be a factory `(services) => GatewayAdapter | Promise<GatewayAdapter>`, resolved lazily on first inbound request (webhook/websocket) or gateway start (listener) and cached. Real platform adapters (WhatsApp Cloud API, Slack) need secrets that only exist after boot, while wireGateway runs at module load — a factory bridges that. Factory adapters register the GET verify route unconditionally since verifyWebhook can't be probed before first resolve.
+
 ## 0.12.57
 
 ### Patch Changes

package/dist/services/local-gateway-service.js

@@ -1,5 +1,5 @@
 import { pikkuState, getSingletonServices } from '../pikku-state.js';
-import { createListenerMessageHandler } from '../wirings/gateway/gateway-runner.js';
+import { createListenerMessageHandler, resolveGatewayAdapter, } from '../wirings/gateway/gateway-runner.js';
 /**
  * Local GatewayService implementation.
  *
@@ -27,8 +27,9 @@ export class LocalGatewayService {
             if (this.activeAdapters.has(name))
                 continue;
             const handleMessage = createListenerMessageHandler(name, config, singletonServices);
-            await config.adapter.init(handleMessage);
-            this.activeAdapters.set(name, config.adapter);
+            const adapter = await resolveGatewayAdapter(config, singletonServices);
+            await adapter.init(handleMessage);
+            this.activeAdapters.set(name, adapter);
             singletonServices.logger.info(`Started listener gateway: ${name}`);
         }
     }

package/dist/wirings/gateway/gateway-runner.d.ts

@@ -1,4 +1,5 @@
-import type { CoreGateway } from './gateway.types.js';
+import type { CoreGateway, GatewayAdapter } from './gateway.types.js';
+export declare const resolveGatewayAdapter: (config: CoreGateway, services: CoreSingletonServices) => Promise<GatewayAdapter>;
 import type { CoreSingletonServices } from '../../types/core.types.js';
 /**
  * Register a messaging gateway.

package/dist/wirings/gateway/gateway-runner.js

@@ -2,6 +2,23 @@ import { pikkuState } from '../../pikku-state.js';
 import { addFunction } from '../../function/function-runner.js';
 import { runMiddleware } from '../../middleware-runner.js';
 import { httpRouter } from '../http/routers/http-router.js';
+/**
+ * Lazily resolve a gateway's adapter. Factories are invoked once with the
+ * singleton services and cached (promise-cached, so concurrent first
+ * requests share one construction).
+ */
+const resolvedAdapters = new WeakMap();
+export const resolveGatewayAdapter = (config, services) => {
+    let resolved = resolvedAdapters.get(config);
+    if (!resolved) {
+        resolved =
+            typeof config.adapter === 'function'
+                ? Promise.resolve(config.adapter(services))
+                : Promise.resolve(config.adapter);
+        resolvedAdapters.set(config, resolved);
+    }
+    return resolved;
+};
 /**
  * Register a messaging gateway.
  *
@@ -67,7 +84,9 @@ const wireWebhookGateway = (config) => {
         auth: false,
     });
     // --- GET handler (webhook verification, e.g. WhatsApp challenge) ---------
-    if (adapter.verifyWebhook) {
+    // Factory adapters can't be probed for verifyWebhook until first resolve,
+    // so register the GET route unconditionally for them.
+    if (typeof adapter === 'function' || adapter.verifyWebhook) {
         const verifyFuncId = `gateway__${name}__verify`;
         funcMeta[verifyFuncId] = {
             pikkuFuncId: verifyFuncId,
@@ -82,7 +101,7 @@ const wireWebhookGateway = (config) => {
         };
         const verifyHandler = {
             auth: false,
-            func: createWebhookVerifyHandler(adapter),
+            func: createWebhookVerifyHandler(config),
         };
         addFunction(verifyFuncId, verifyHandler);
         if (!routes.has('get')) {
@@ -110,9 +129,10 @@ const wireWebhookGateway = (config) => {
  *  6. Auto-send response via adapter if func returns outbound content
  */
 const createWebhookPostHandler = (config) => {
-    const { name, adapter, func: userFunc, middleware: userMiddleware } = config;
+    const { name, func: userFunc, middleware: userMiddleware } = config;
     const userFuncConfig = userFunc;
     return async (services, data, wire) => {
+        const adapter = await resolveGatewayAdapter(config, services);
         // Check for POST-based webhook verification (e.g. Slack url_verification)
         if (adapter.verifyWebhook) {
             const verifyResult = await adapter.verifyWebhook(data, wire.http?.request);
@@ -157,8 +177,9 @@ const createWebhookPostHandler = (config) => {
  * Creates the GET handler for webhook verification challenges.
  * Passes query parameters to the adapter's verifyWebhook method.
  */
-const createWebhookVerifyHandler = (adapter) => {
-    return async (_services, _data, wire) => {
+const createWebhookVerifyHandler = (config) => {
+    return async (services, _data, wire) => {
+        const adapter = await resolveGatewayAdapter(config, services);
         if (!adapter.verifyWebhook) {
             return { error: 'Verification not supported' };
         }
@@ -174,7 +195,7 @@ const createWebhookVerifyHandler = (adapter) => {
 // WebSocket gateway — client connects via WebSocket
 // ---------------------------------------------------------------------------
 const wireWebsocketGateway = (config) => {
-    const { name, route, adapter } = config;
+    const { name, route } = config;
     if (!route) {
         throw new Error(`WebSocket gateway '${name}' requires a route`);
     }
@@ -211,8 +232,8 @@ const wireWebsocketGateway = (config) => {
     // Register onConnect
     addFunction(connectFuncId, {
         auth: false,
-        func: async (_services, _data, wire) => {
-            ;
+        func: async (services, _data, wire) => {
+            const adapter = await resolveGatewayAdapter(config, services);
             wire.gateway = {
                 gatewayName: name,
                 senderId: '',
@@ -227,6 +248,7 @@ const wireWebsocketGateway = (config) => {
     addFunction(messageFuncId, {
         auth: false,
         func: async (services, data, wire) => {
+            const adapter = await resolveGatewayAdapter(config, services);
             const parsed = adapter.parse(data);
             if (!parsed)
                 return;
@@ -290,10 +312,10 @@ const wireListenerGateway = (config) => {
  * @param singletonServices - Singleton services to pass to handler/middleware
  */
 export const createListenerMessageHandler = (name, config, singletonServices) => {
-    const { adapter } = config;
     const userFuncConfig = config.func;
     const userMiddleware = config.middleware;
     return async (rawData) => {
+        const adapter = await resolveGatewayAdapter(config, singletonServices);
         const parsed = adapter.parse(rawData);
         if (!parsed)
             return;

package/dist/wirings/gateway/gateway.types.d.ts

@@ -1,4 +1,4 @@
-import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
+import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CoreSingletonServices } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
 import type { PikkuHTTPRequest } from '../http/http.types.js';
 /**
@@ -69,6 +69,16 @@ export interface GatewayAdapter {
      *  Receives the data (body or query params) and the Pikku HTTP request for additional inspection. */
     verifyWebhook?(data: unknown, request?: PikkuHTTPRequest): WebhookVerificationResult | Promise<WebhookVerificationResult>;
 }
+/**
+ * Factory that builds a GatewayAdapter from singleton services.
+ *
+ * Real platform adapters (WhatsApp Cloud API, Slack, …) need secrets or
+ * services that only exist after boot, while `wireGateway` runs at module
+ * load. Pass a factory instead of an instance and it is resolved lazily on
+ * the first inbound request (webhook/websocket) or on gateway start
+ * (listener), then cached for the lifetime of the gateway.
+ */
+export type GatewayAdapterFactory = (services: CoreSingletonServices) => GatewayAdapter | Promise<GatewayAdapter>;
 /**
  * The gateway wire object available on wire.gateway inside handler functions and middleware
  */
@@ -100,8 +110,9 @@ export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>,
     /** HTTP route for webhook/websocket types */
     route?: string;
     platform?: string;
-    /** The gateway adapter (parse inbound, send outbound) */
-    adapter: GatewayAdapter;
+    /** The gateway adapter (parse inbound, send outbound), or a factory
+     *  resolved lazily from singleton services (for adapters needing secrets) */
+    adapter: GatewayAdapter | GatewayAdapterFactory;
     /** The handler function that processes parsed messages */
     func: PikkuFunctionConfig;
     /** Optional middleware chain (e.g., auth) */

package/dist/wirings/gateway/index.d.ts

@@ -1,2 +1,2 @@
-export { wireGateway, createListenerMessageHandler } from './gateway-runner.js';
-export type { GatewayAdapter, GatewayAttachment, GatewayInboundMessage, GatewayOutboundMessage, GatewayMeta, GatewaysMeta, GatewayTransportType, CoreGateway, PikkuGateway, WebhookVerificationResult, } from './gateway.types.js';
+export { wireGateway, createListenerMessageHandler, resolveGatewayAdapter, } from './gateway-runner.js';
+export type { GatewayAdapter, GatewayAdapterFactory, GatewayAttachment, GatewayInboundMessage, GatewayOutboundMessage, GatewayMeta, GatewaysMeta, GatewayTransportType, CoreGateway, PikkuGateway, WebhookVerificationResult, } from './gateway.types.js';

package/dist/wirings/gateway/index.js

@@ -1 +1 @@
-export { wireGateway, createListenerMessageHandler } from './gateway-runner.js';
+export { wireGateway, createListenerMessageHandler, resolveGatewayAdapter, } from './gateway-runner.js';

package/dist/wirings/workflow/graph/graph-runner.js

@@ -441,6 +441,9 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
     try {
         let result;
         const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
+        const agentMeta = subWorkflowMeta
+            ? undefined
+            : pikkuState(null, 'agent', 'agentsMeta')[rpcName];
         if (subWorkflowMeta) {
             const childWire = {
                 type: 'workflow',
@@ -465,6 +468,10 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
                 throw new ChildWorkflowStartedException(runId, stepId, childRunId);
             }
         }
+        else if (agentMeta) {
+            const agentRun = await rpcService.agent.run(rpcName, data);
+            result = agentRun.result;
+        }
         else {
             result = await invokeGraphNodeRpc(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName);
         }
@@ -523,6 +530,9 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
     try {
         let result;
         const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
+        const agentMeta = subWorkflowMeta
+            ? undefined
+            : pikkuState(null, 'agent', 'agentsMeta')[rpcName];
         if (subWorkflowMeta) {
             const childWire = {
                 type: 'workflow',
@@ -541,6 +551,10 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
             }
             result = childRun?.output;
         }
+        else if (agentMeta) {
+            const agentRun = await rpcService.agent.run(rpcName, input);
+            result = agentRun.result;
+        }
         else {
             result = await invokeGraphNodeRpc(workflowService, rpcService, runId, stepState.stepId, nodeId, rpcName, input, graphName);
         }

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -1082,7 +1082,11 @@ export class PikkuWorkflowService {
      * that differs between transports is who calls it, not the call itself.
      */
     async invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService) {
+        // Carry the run's pikkuUserId onto the step wire so authed steps rehydrate their
+        // session on the queued path too (the bare job wire lacks it; inline already has it).
+        const run = await this.getRun(runId);
         return rpcService.rpcWithWire(rpcName, data, {
+            ...(run?.wire?.pikkuUserId ? { pikkuUserId: run.wire.pikkuUserId } : {}),
             workflowStep: {
                 runId,
                 stepId: stepState.stepId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.57",
+  "version": "0.12.60",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -72,6 +72,6 @@
     "typescript": "^6.0.3"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   }
 }

package/src/services/local-gateway-service.ts

@@ -1,7 +1,10 @@
 import type { GatewayService } from './gateway-service.js'
 import type { GatewayAdapter } from '../wirings/gateway/gateway.types.js'
 import { pikkuState, getSingletonServices } from '../pikku-state.js'
-import { createListenerMessageHandler } from '../wirings/gateway/gateway-runner.js'
+import {
+  createListenerMessageHandler,
+  resolveGatewayAdapter,
+} from '../wirings/gateway/gateway-runner.js'
 
 /**
  * Local GatewayService implementation.
@@ -36,8 +39,9 @@ export class LocalGatewayService implements GatewayService {
         singletonServices
       )
 
-      await config.adapter.init(handleMessage)
-      this.activeAdapters.set(name, config.adapter)
+      const adapter = await resolveGatewayAdapter(config, singletonServices)
+      await adapter.init(handleMessage)
+      this.activeAdapters.set(name, adapter)
       singletonServices.logger.info(`Started listener gateway: ${name}`)
     }
   }

package/src/wirings/gateway/gateway-runner.test.ts

@@ -139,6 +139,76 @@ describe('wireGateway', () => {
       assert.equal(adapter.sentMessages[0].message.text, 'reply')
     })
 
+    test('adapter factory resolves lazily from services and is cached', async () => {
+      const adapter = createMockAdapter({ name: 'factory-mock' })
+      const factoryCalls: any[] = []
+
+      wireGateway({
+        name: 'test-factory',
+        type: 'webhook',
+        route: '/webhooks/factory',
+        adapter: (services: any) => {
+          factoryCalls.push(services)
+          return adapter
+        },
+        func: {
+          func: async () => ({ text: 'pong' }),
+        },
+      })
+
+      httpRouter.initialize()
+
+      // Factory must NOT run at wiring time
+      assert.equal(factoryCalls.length, 0)
+
+      const makeRequest = () =>
+        fetch(
+          new Request('http://localhost/webhooks/factory', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ senderId: 'user-9', text: 'ping' }),
+          })
+        )
+
+      const first = await makeRequest()
+      assert.equal(first.status, 200)
+      const second = await makeRequest()
+      assert.equal(second.status, 200)
+
+      // Factory ran exactly once, with the singleton services
+      assert.equal(factoryCalls.length, 1)
+      assert.equal(typeof factoryCalls[0].logger.info, 'function')
+
+      // Messages flowed through the resolved adapter (auto-send reply)
+      assert.equal(adapter.sentMessages.length, 2)
+      assert.equal(adapter.sentMessages[0].message.text, 'pong')
+    })
+
+    test('factory adapter registers GET verify route unconditionally', async () => {
+      const adapter = createMockAdapter({
+        verifyResult: { verified: true, response: { challenge: 'abc' } },
+      })
+
+      wireGateway({
+        name: 'test-factory-verify',
+        type: 'webhook',
+        route: '/webhooks/factory-verify',
+        adapter: async () => adapter,
+        func: { func: async () => {} },
+      })
+
+      httpRouter.initialize()
+
+      const response = await fetch(
+        new Request('http://localhost/webhooks/factory-verify?token=x', {
+          method: 'GET',
+        })
+      )
+      assert.equal(response.status, 200)
+      const body = await response.json()
+      assert.deepEqual(body, { challenge: 'abc' })
+    })
+
     test('returns 200 OK for ignored events (adapter returns null)', async () => {
       const adapter = createMockAdapter({ parseResult: null })
       const funcCalls: any[] = []

package/src/wirings/gateway/gateway-runner.ts

@@ -8,6 +8,28 @@ import type {
   GatewayOutboundMessage,
   PikkuGateway,
 } from './gateway.types.js'
+
+/**
+ * Lazily resolve a gateway's adapter. Factories are invoked once with the
+ * singleton services and cached (promise-cached, so concurrent first
+ * requests share one construction).
+ */
+const resolvedAdapters = new WeakMap<CoreGateway, Promise<GatewayAdapter>>()
+
+export const resolveGatewayAdapter = (
+  config: CoreGateway,
+  services: CoreSingletonServices
+): Promise<GatewayAdapter> => {
+  let resolved = resolvedAdapters.get(config)
+  if (!resolved) {
+    resolved =
+      typeof config.adapter === 'function'
+        ? Promise.resolve(config.adapter(services))
+        : Promise.resolve(config.adapter)
+    resolvedAdapters.set(config, resolved)
+  }
+  return resolved
+}
 import type {
   PikkuWire,
   PikkuRawWire,
@@ -94,8 +116,10 @@ const wireWebhookGateway = (config: CoreGateway): void => {
   } as any)
 
   // --- GET handler (webhook verification, e.g. WhatsApp challenge) ---------
+  // Factory adapters can't be probed for verifyWebhook until first resolve,
+  // so register the GET route unconditionally for them.
 
-  if (adapter.verifyWebhook) {
+  if (typeof adapter === 'function' || adapter.verifyWebhook) {
     const verifyFuncId = `gateway__${name}__verify`
 
     funcMeta[verifyFuncId] = {
@@ -113,7 +137,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
 
     const verifyHandler = {
       auth: false,
-      func: createWebhookVerifyHandler(adapter),
+      func: createWebhookVerifyHandler(config),
     }
 
     addFunction(verifyFuncId, verifyHandler as any)
@@ -145,7 +169,7 @@ const wireWebhookGateway = (config: CoreGateway): void => {
  *  6. Auto-send response via adapter if func returns outbound content
  */
 const createWebhookPostHandler = (config: CoreGateway) => {
-  const { name, adapter, func: userFunc, middleware: userMiddleware } = config
+  const { name, func: userFunc, middleware: userMiddleware } = config
   const userFuncConfig = userFunc as {
     func: Function
     middleware?: CorePikkuMiddleware[]
@@ -156,6 +180,8 @@ const createWebhookPostHandler = (config: CoreGateway) => {
     data: unknown,
     wire: PikkuWire
   ) => {
+    const adapter = await resolveGatewayAdapter(config, services)
+
     // Check for POST-based webhook verification (e.g. Slack url_verification)
     if (adapter.verifyWebhook) {
       const verifyResult = await adapter.verifyWebhook(data, wire.http?.request)
@@ -207,12 +233,13 @@ const createWebhookPostHandler = (config: CoreGateway) => {
  * Creates the GET handler for webhook verification challenges.
  * Passes query parameters to the adapter's verifyWebhook method.
  */
-const createWebhookVerifyHandler = (adapter: GatewayAdapter) => {
+const createWebhookVerifyHandler = (config: CoreGateway) => {
   return async (
-    _services: CoreSingletonServices,
+    services: CoreSingletonServices,
     _data: unknown,
     wire: PikkuWire
   ) => {
+    const adapter = await resolveGatewayAdapter(config, services)
     if (!adapter.verifyWebhook) {
       return { error: 'Verification not supported' }
     }
@@ -232,7 +259,7 @@ const createWebhookVerifyHandler = (adapter: GatewayAdapter) => {
 // ---------------------------------------------------------------------------
 
 const wireWebsocketGateway = (config: CoreGateway): void => {
-  const { name, route, adapter } = config
+  const { name, route } = config
   if (!route) {
     throw new Error(`WebSocket gateway '${name}' requires a route`)
   }
@@ -279,7 +306,8 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
   // Register onConnect
   addFunction(connectFuncId, {
     auth: false,
-    func: async (_services: any, _data: unknown, wire: PikkuWire) => {
+    func: async (services: any, _data: unknown, wire: PikkuWire) => {
+      const adapter = await resolveGatewayAdapter(config, services)
       ;(wire as any).gateway = {
         gatewayName: name,
         senderId: '',
@@ -295,6 +323,7 @@ const wireWebsocketGateway = (config: CoreGateway): void => {
   addFunction(messageFuncId, {
     auth: false,
     func: async (services: any, data: unknown, wire: PikkuWire) => {
+      const adapter = await resolveGatewayAdapter(config, services)
       const parsed = adapter.parse(data)
       if (!parsed) return
 
@@ -371,7 +400,6 @@ export const createListenerMessageHandler = (
   config: CoreGateway,
   singletonServices: CoreSingletonServices
 ): ((rawData: unknown) => Promise<void>) => {
-  const { adapter } = config
   const userFuncConfig = config.func as {
     func: Function
     middleware?: CorePikkuMiddleware[]
@@ -379,6 +407,7 @@ export const createListenerMessageHandler = (
   const userMiddleware = config.middleware as CorePikkuMiddleware[] | undefined
 
   return async (rawData: unknown): Promise<void> => {
+    const adapter = await resolveGatewayAdapter(config, singletonServices)
     const parsed = adapter.parse(rawData)
     if (!parsed) return
 

package/src/wirings/gateway/gateway.types.ts

@@ -2,6 +2,7 @@ import type {
   CommonWireMeta,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
+  CoreSingletonServices,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunctionConfig,
@@ -83,6 +84,19 @@ export interface GatewayAdapter {
   ): WebhookVerificationResult | Promise<WebhookVerificationResult>
 }
 
+/**
+ * Factory that builds a GatewayAdapter from singleton services.
+ *
+ * Real platform adapters (WhatsApp Cloud API, Slack, …) need secrets or
+ * services that only exist after boot, while `wireGateway` runs at module
+ * load. Pass a factory instead of an instance and it is resolved lazily on
+ * the first inbound request (webhook/websocket) or on gateway start
+ * (listener), then cached for the lifetime of the gateway.
+ */
+export type GatewayAdapterFactory = (
+  services: CoreSingletonServices
+) => GatewayAdapter | Promise<GatewayAdapter>
+
 /**
  * The gateway wire object available on wire.gateway inside handler functions and middleware
  */
@@ -122,8 +136,9 @@ export type CoreGateway<
   /** HTTP route for webhook/websocket types */
   route?: string
   platform?: string
-  /** The gateway adapter (parse inbound, send outbound) */
-  adapter: GatewayAdapter
+  /** The gateway adapter (parse inbound, send outbound), or a factory
+   *  resolved lazily from singleton services (for adapters needing secrets) */
+  adapter: GatewayAdapter | GatewayAdapterFactory
   /** The handler function that processes parsed messages */
   func: PikkuFunctionConfig
   /** Optional middleware chain (e.g., auth) */

package/src/wirings/gateway/index.ts

@@ -1,6 +1,11 @@
-export { wireGateway, createListenerMessageHandler } from './gateway-runner.js'
+export {
+  wireGateway,
+  createListenerMessageHandler,
+  resolveGatewayAdapter,
+} from './gateway-runner.js'
 export type {
   GatewayAdapter,
+  GatewayAdapterFactory,
   GatewayAttachment,
   GatewayInboundMessage,
   GatewayOutboundMessage,