@pikku/core 0.12.56 → 0.12.58

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,

package/src/wirings/workflow/graph/graph-runner.test.ts

@@ -677,6 +677,140 @@ describe('graph-runner bugs', () => {
     delete metaState['testInlineMetaGraph']
   })
 
+  test('executeGraphStep dispatches an agent-name node via the agent-run path and returns its result', async () => {
+    const ws = new InMemoryWorkflowService()
+
+    const agentsMeta = pikkuState(null, 'agent', 'agentsMeta')
+    agentsMeta['summarize'] = {
+      name: 'summarize',
+      inputSchema: null,
+      outputSchema: null,
+      workingMemorySchema: null,
+    } as any
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState['testAgentNode'] = {
+      name: 'testAgentNode',
+      pikkuFuncId: 'testAgentNode',
+      source: 'graph',
+      entryNodeIds: ['a'],
+      graphHash: 'agent-node-hash',
+      nodes: {
+        a: { nodeId: 'a', rpcName: 'summarize' },
+      },
+    }
+
+    const runId = await ws.createRun(
+      'testAgentNode',
+      {},
+      false,
+      'agent-node-hash',
+      { type: 'test' }
+    )
+    const agentInput = { message: 'hi', threadId: 't', resourceId: 'r' }
+    const step = await ws.insertStepState(runId, 'a', 'summarize', agentInput)
+
+    let agentRunCall: { name: string; input: any } | null = null
+    const rpcService = {
+      rpcWithWire: async () => {
+        throw new Error('should not invoke rpcWithWire for an agent node')
+      },
+      agent: {
+        run: async (name: string, input: any) => {
+          agentRunCall = { name, input }
+          return {
+            runId: 'agent-run-1',
+            result: { summary: 'done' },
+            usage: { inputTokens: 1, outputTokens: 2 },
+          }
+        },
+      },
+    }
+
+    const result = await executeGraphStep(
+      ws,
+      rpcService,
+      runId,
+      step.stepId,
+      'a',
+      'summarize',
+      agentInput,
+      'testAgentNode'
+    )
+
+    assert.deepEqual(result, { summary: 'done' })
+    assert.deepEqual(agentRunCall, { name: 'summarize', input: agentInput })
+
+    delete metaState['testAgentNode']
+    delete agentsMeta['summarize']
+  })
+
+  test('inline graph dispatches an agent node and a downstream node consumes its result', async () => {
+    const ws = new InMemoryWorkflowService()
+
+    const agentsMeta = pikkuState(null, 'agent', 'agentsMeta')
+    agentsMeta['classifier'] = {
+      name: 'classifier',
+      inputSchema: null,
+      outputSchema: null,
+      workingMemorySchema: null,
+    } as any
+
+    let consumed: any = null
+    const rpcService = {
+      rpcWithWire: async (rpcName: string, data: any) => {
+        if (rpcName === 'consume') {
+          consumed = data
+          return { ok: true }
+        }
+        return {}
+      },
+      agent: {
+        run: async () => ({
+          runId: 'r',
+          result: { category: 'urgent' },
+          usage: { inputTokens: 0, outputTokens: 0 },
+        }),
+      },
+    }
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState['testInlineAgentNode'] = {
+      name: 'testInlineAgentNode',
+      pikkuFuncId: 'testInlineAgentNode',
+      source: 'graph',
+      entryNodeIds: ['agentNode'],
+      graphHash: 'inline-agent-hash',
+      nodes: {
+        agentNode: {
+          nodeId: 'agentNode',
+          rpcName: 'classifier',
+          next: 'consume',
+        },
+        consume: {
+          nodeId: 'consume',
+          rpcName: 'consume',
+          input: { category: { $ref: 'agentNode', path: 'category' } },
+        },
+      },
+    }
+
+    const { runId } = await runWorkflowGraph(
+      ws,
+      'testInlineAgentNode',
+      { message: 'x', threadId: 't', resourceId: 'r' },
+      rpcService,
+      true
+    )
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+    assert.deepEqual(consumed, { category: 'urgent' })
+
+    delete metaState['testInlineAgentNode']
+    delete agentsMeta['classifier']
+  })
+
   test('queueGraphNode forwards node retries to queue attempts and backoff', async () => {
     const ws = new InMemoryWorkflowService()
     const enqueued: Array<{ queueName: string; data: any; options: any }> = []

package/src/wirings/workflow/graph/graph-runner.ts

@@ -621,6 +621,9 @@ export async function executeGraphStep(
     let result: any
 
     const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName]
+    const agentMeta = subWorkflowMeta
+      ? undefined
+      : pikkuState(null, 'agent', 'agentsMeta')[rpcName]
     if (subWorkflowMeta) {
       const childWire: WorkflowRunWire = {
         type: 'workflow',
@@ -650,6 +653,9 @@ export async function executeGraphStep(
       } else {
         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,
@@ -760,6 +766,9 @@ async function executeGraphNodeInline(
     let result: any
 
     const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName]
+    const agentMeta = subWorkflowMeta
+      ? undefined
+      : pikkuState(null, 'agent', 'agentsMeta')[rpcName]
     if (subWorkflowMeta) {
       const childWire: WorkflowRunWire = {
         type: 'workflow',
@@ -783,6 +792,9 @@ async function executeGraphNodeInline(
         throw new Error('Sub-workflow was cancelled')
       }
       result = childRun?.output
+    } else if (agentMeta) {
+      const agentRun = await rpcService.agent.run(rpcName, input)
+      result = agentRun.result
     } else {
       result = await invokeGraphNodeRpc(
         workflowService,