@pikku/core 0.12.56 → 0.12.58

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 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
+
+- 60ad8cb: fix dev-server hot reload so edited AND new functions/routes apply without a restart
+  - `@pikku/core`: the hot reloader fed raw zod `input`/`output` schemas into the JSON-schema map, so `compileAllSchemas` threw `Failed to compile schema` on every reload and the reload aborted (only the function body sometimes swapped, half-updated). It now registers function implementations only and leaves schemas to the codegen JSON output. New function exports are registered too (previously only already-registered names were replaced). Reloads write into the startup functions map directly to avoid a race with the dev watcher's codegen-scoped state swap, and re-import via a uniquely-named sibling copy since neither Bun nor tsx bust the module cache on a `?t=` query.
+  - New `reloadGeneratedMeta` (exported from `@pikku/core/dev`) re-reads the regenerated wiring meta + JSON schemas into the running process so new/changed routes, RPCs, queues and agents resolve without a restart.
+  - `@pikku/cli`: `pikku dev` now calls `reloadGeneratedMeta` after each watch-triggered codegen pass and re-imports the changed files once fresh meta is in state, so a NEW route in a changed wiring file registers (its `wireHTTP` no longer no-ops on missing meta).
+  - `@pikku/schema-cfworker`: `compileSchema` recompiles when a schema's value changes (not only on first sight), so hot-reloaded schemas take effect.
+
+- 8f5c998: Fix dev hot-reload dropping runtime-registered function/queue meta. `reloadGeneratedMeta` replaced the whole `function`/`queue` meta maps with the generated JSON, wiping entries the framework registers at service-init (the workflow orchestrator, per-workflow queue workers, and other `addFunction`'d internals that never appear in the generated files). Workflow jobs then failed with `Function meta not found: pikkuWorkflowOrchestrator`. The reload now merges over the existing maps so those internals survive.
+
 ## 0.12.56
 
 ### Patch Changes

package/dist/dev/hot-reload.d.ts

@@ -1,10 +1,14 @@
 import type { Logger } from '../services/logger.js';
+export * from './reload-meta.js';
 interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;
     pikkuDir?: string;
 }
-export declare function pikkuDevReloader(options: PikkuDevReloaderOptions): Promise<{
+export interface PikkuDevReloaderHandle {
     close: () => void;
-}>;
-export {};
+    /** Re-import every file changed since the last drain (post-codegen, once
+     *  fresh meta is in state). */
+    reimportPending: () => Promise<void>;
+}
+export declare function pikkuDevReloader(options: PikkuDevReloaderOptions): Promise<PikkuDevReloaderHandle>;

package/dist/dev/hot-reload.js

@@ -1,15 +1,14 @@
 import { watch } from 'node:fs';
-import { stat, readFile } from 'node:fs/promises';
-import { join, resolve, relative } from 'node:path';
+import { stat, readFile, copyFile, rm } from 'node:fs/promises';
+import { basename, dirname, join, resolve, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { register } from 'tsx/esm/api';
 import { pikkuState } from '../pikku-state.js';
-import { addFunction } from '../function/function-runner.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
-import { addSchema, compileAllSchemas } from '../schema.js';
+export * from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
         value !== null &&
@@ -44,11 +43,31 @@ const ensureTsxRegistered = () => {
     register();
     tsxRegistered = true;
 };
+let tempCounter = 0;
 const reimportModule = async (filePath, useTsx = false) => {
     try {
         if (useTsx) {
-            ensureTsxRegistered();
-            return await import(`${pathToFileURL(resolve(filePath)).href}?t=${Date.now()}`);
+            // Import a uniquely-named sibling copy: a `?t=` query does NOT bust
+            // the cache on either runtime (Bun keys module identity on the bare
+            // path; tsx's transform cache keys on the file path too), so a fresh
+            // path is the only reliable re-import. Same directory → identical
+            // resolution for relative and package-`imports` (#…) specifiers. The
+            // dot-prefix keeps it out of the watcher.
+            if (!process.versions.bun) {
+                // Node needs tsx's loader to import raw .ts; Bun imports it natively.
+                ensureTsxRegistered();
+            }
+            const abs = resolve(filePath);
+            const tempPath = join(dirname(abs), `.pikku-hot-${++tempCounter}-${basename(abs)}`);
+            await copyFile(abs, tempPath);
+            try {
+                return await import(pathToFileURL(tempPath).href);
+            }
+            finally {
+                await rm(tempPath, { force: true }).catch(() => {
+                    // Best-effort temp cleanup; a leftover dotfile is watcher-ignored.
+                });
+            }
         }
         const content = await readFile(resolve(filePath), 'utf-8');
         const dataUrl = 'data:text/javascript;base64,' + Buffer.from(content).toString('base64');
@@ -62,7 +81,10 @@ const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
         !filename.endsWith('.d.ts') &&
-        !filename.endsWith('.gen.ts'));
+        !filename.endsWith('.gen.ts') &&
+        // Hidden files: editor/sed atomic-write temps and our own hot-reload
+        // sibling copies must never trigger a reload of themselves.
+        !basename(filename).startsWith('.'));
 };
 export async function pikkuDevReloader(options) {
     const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
@@ -73,6 +95,7 @@ export async function pikkuDevReloader(options) {
     const handleFileChange = async (changedTsFile) => {
         const start = Date.now();
         const reloadedNames = [];
+        const addedNames = [];
         const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d));
         if (!srcDir)
             return;
@@ -87,48 +110,59 @@ export async function pikkuDevReloader(options) {
             logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`);
             return;
         }
-        let schemasChanged = false;
+        // Register every function-config export — replacing known functions AND
+        // adding new ones (a brand-new function becomes callable as soon as its
+        // meta lands via reloadGeneratedMeta after the next codegen pass).
+        // Write into the map captured at startup, NOT pikkuState's current one:
+        // a dev-server watcher may have temporarily swapped in a codegen-scoped
+        // map for the same file event (runAllWithCommandState), and a write to
+        // that map is silently discarded when it restores the original.
+        // Schemas are NOT touched here: `input`/`output` hold raw zod schemas,
+        // while the schema map carries codegen-generated JSON schemas — mixing the
+        // two crashed every reload. Fresh JSON schemas arrive via
+        // reloadGeneratedMeta once codegen has re-emitted them.
         for (const [exportName, exportValue] of Object.entries(mod)) {
-            if (isFunctionConfig(exportValue) && functionsMap.has(exportName)) {
-                addFunction(exportName, exportValue);
+            if (!isFunctionConfig(exportValue))
+                continue;
+            const isNew = !functionsMap.has(exportName);
+            functionsMap.set(exportName, exportValue);
+            if (isNew)
+                addedNames.push(exportName);
+            else
                 reloadedNames.push(exportName);
-                if (exportValue.input) {
-                    addSchema(exportName, exportValue.input);
-                    schemasChanged = true;
-                }
-                if (exportValue.output) {
-                    addSchema(`${exportName}Output`, exportValue.output);
-                    schemasChanged = true;
-                }
-            }
         }
-        if (reloadedNames.length > 0) {
-            clearMiddlewareCache();
-            clearPermissionsCache();
-            clearChannelMiddlewareCache();
-            httpRouter.reset();
-            if (schemasChanged) {
-                try {
-                    compileAllSchemas(logger);
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    if (msg.includes('SchemaService') ||
-                        (msg.includes('schema') && msg.includes('not'))) {
-                        logger.warn('Schema recompilation skipped (no SchemaService)');
-                    }
-                    else {
-                        logger.error(`Schema recompilation failed: ${msg}`);
-                        return;
-                    }
-                }
-            }
+        // Re-importing the module re-ran its wire* side effects (wireHTTP et al
+        // are keyed map-sets, so re-registration replaces/adds) — reset the
+        // router and caches even when no function export changed, so a
+        // wiring-only file edit rebuilds the route matchers too.
+        clearMiddlewareCache();
+        clearPermissionsCache();
+        clearChannelMiddlewareCache();
+        httpRouter.reset();
+        if (reloadedNames.length > 0 || addedNames.length > 0) {
             const elapsed = Date.now() - start;
-            logger.info(`Hot-reloaded: ${reloadedNames.join(', ')} (${elapsed}ms)`);
+            const parts = [];
+            if (reloadedNames.length > 0)
+                parts.push(reloadedNames.join(', '));
+            if (addedNames.length > 0)
+                parts.push(`new: ${addedNames.join(', ')}`);
+            logger.info(`Hot-reloaded: ${parts.join('; ')} (${elapsed}ms)`);
         }
     };
     let debounceTimer;
     const pendingChanges = new Set();
+    // Files re-imported since the last reimportPending() drain. A dev-server
+    // watcher drains this after its codegen pass so wire* registrations that
+    // were skipped for missing meta (a NEW route) run again with fresh meta.
+    const postCodegenQueue = new Set();
+    const safeHandleFileChange = async (file) => {
+        try {
+            await handleFileChange(file);
+        }
+        catch (err) {
+            logger.error(`Hot-reload error for ${relative(process.cwd(), file)}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
     const scheduleReload = (filePath) => {
         pendingChanges.add(filePath);
         if (debounceTimer)
@@ -137,12 +171,8 @@ export async function pikkuDevReloader(options) {
             const files = [...pendingChanges];
             pendingChanges.clear();
             for (const file of files) {
-                try {
-                    await handleFileChange(file);
-                }
-                catch (err) {
-                    logger.error(`Hot-reload error for ${relative(process.cwd(), file)}: ${err instanceof Error ? err.message : String(err)}`);
-                }
+                postCodegenQueue.add(file);
+                await safeHandleFileChange(file);
             }
         }, 50);
     };
@@ -168,5 +198,18 @@ export async function pikkuDevReloader(options) {
                 watcher.close();
             }
         },
+        // Drain the queue of recently re-imported files and import them again.
+        // A dev-server watcher calls this AFTER its codegen pass has refreshed
+        // the generated meta (reloadGeneratedMeta): wire* registrations skip
+        // routes whose meta doesn't exist yet, so a wiring file changed
+        // alongside a NEW function only registers its new route when
+        // re-imported after the fresh meta has landed.
+        reimportPending: async () => {
+            const files = [...postCodegenQueue];
+            postCodegenQueue.clear();
+            for (const file of files) {
+                await safeHandleFileChange(file);
+            }
+        },
     };
 }

package/dist/dev/reload-meta.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from '../services/logger.js';
+import type { SchemaService } from '../services/schema-service.js';
+export interface ReloadGeneratedMetaOptions {
+    /** The project's generated output directory (the CLI's resolved outDir). */
+    pikkuDir: string;
+    logger: Logger;
+    /** Used to recompile validators for changed schemas; falls back to the
+     *  schema service on the registered singleton services. */
+    schemaService?: SchemaService;
+}
+/**
+ * Re-reads the codegen output (wiring meta + JSON schemas) into the running
+ * process so new and changed functions become callable without a server
+ * restart. The generated `*-meta.gen.ts` files are plain
+ * `pikkuState(area, key, <json>)` side effects, but they cannot be
+ * re-imported after a dev-time codegen — the ESM cache pins both the wrapper
+ * and its JSON import — so this reads the JSON sources directly and applies
+ * the same state.
+ *
+ * Meant to be called by a dev-server watcher after each codegen pass. Routes
+ * registered by NEW `wireHTTP` files are not picked up (their modules were
+ * never imported); those still need a restart.
+ */
+export declare function reloadGeneratedMeta(options: ReloadGeneratedMetaOptions): Promise<void>;

package/dist/dev/reload-meta.js

@@ -0,0 +1,99 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pikkuState } from '../pikku-state.js';
+import { addSchema, compileAllSchemas } from '../schema.js';
+import { clearMiddlewareCache } from '../middleware-runner.js';
+import { clearPermissionsCache } from '../permissions.js';
+import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
+import { httpRouter } from '../wirings/http/routers/http-router.js';
+const readJson = async (logger, file) => {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf-8');
+    }
+    catch {
+        // The project doesn't use this wiring type — nothing generated.
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        logger.error(`Hot-reload could not parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+};
+/**
+ * Re-reads the codegen output (wiring meta + JSON schemas) into the running
+ * process so new and changed functions become callable without a server
+ * restart. The generated `*-meta.gen.ts` files are plain
+ * `pikkuState(area, key, <json>)` side effects, but they cannot be
+ * re-imported after a dev-time codegen — the ESM cache pins both the wrapper
+ * and its JSON import — so this reads the JSON sources directly and applies
+ * the same state.
+ *
+ * Meant to be called by a dev-server watcher after each codegen pass. Routes
+ * registered by NEW `wireHTTP` files are not picked up (their modules were
+ * never imported); those still need a restart.
+ */
+export async function reloadGeneratedMeta(options) {
+    const { pikkuDir, logger, schemaService } = options;
+    const dir = resolve(pikkuDir);
+    const functionsMeta = await readJson(logger, join(dir, 'function/pikku-functions-meta.gen.json'));
+    // Merge over the existing map, don't replace it: framework internals like
+    // pikkuWorkflowOrchestrator / the per-workflow queue workers are registered
+    // at service-init (pikku-workflow-service.ts), never in the generated JSON —
+    // a wholesale replace drops them and workflow jobs then fail with
+    // "Function meta not found: pikkuWorkflowOrchestrator".
+    if (functionsMeta) {
+        const existing = pikkuState(null, 'function', 'meta') ?? {};
+        pikkuState(null, 'function', 'meta', { ...existing, ...functionsMeta });
+    }
+    const httpMeta = await readJson(logger, join(dir, 'http/pikku-http-wirings-meta.gen.json'));
+    if (httpMeta)
+        pikkuState(null, 'http', 'meta', httpMeta);
+    const rpcMeta = await readJson(logger, join(dir, 'rpc/pikku-rpc-wirings-meta.internal.gen.json'));
+    if (rpcMeta)
+        pikkuState(null, 'rpc', 'meta', rpcMeta);
+    const queueMeta = await readJson(logger, join(dir, 'queue/pikku-queue-workers-wirings-meta.gen.json'));
+    // Same reason as function meta: the workflow service adds its orchestrator /
+    // step queues (and wf-orchestrator-* / wf-step-* per-workflow queues) here at
+    // init, absent from the generated JSON — merge so they survive the reload.
+    if (queueMeta) {
+        const existing = pikkuState(null, 'queue', 'meta') ?? {};
+        pikkuState(null, 'queue', 'meta', { ...existing, ...queueMeta });
+    }
+    const agentMeta = await readJson(logger, join(dir, 'agent/pikku-agent-wirings-meta.gen.json'));
+    if (agentMeta?.agentsMeta) {
+        pikkuState(null, 'agent', 'agentsMeta', agentMeta.agentsMeta);
+    }
+    // Generated JSON schemas: <outDir>/schemas/schemas/<Name>.schema.json.
+    // Re-adding replaces the map entry; the schema service recompiles any
+    // validator whose stored schema value no longer matches.
+    const schemasDir = join(dir, 'schemas', 'schemas');
+    let schemaFiles = [];
+    try {
+        schemaFiles = await readdir(schemasDir);
+    }
+    catch {
+        // No generated schemas — a schema-less project.
+    }
+    for (const file of schemaFiles) {
+        if (!file.endsWith('.schema.json'))
+            continue;
+        const schema = await readJson(logger, join(schemasDir, file));
+        if (schema) {
+            addSchema(file.slice(0, -'.schema.json'.length), schema);
+        }
+    }
+    clearMiddlewareCache();
+    clearPermissionsCache();
+    clearChannelMiddlewareCache();
+    httpRouter.reset();
+    try {
+        compileAllSchemas(logger, schemaService);
+    }
+    catch (err) {
+        logger.error(`Hot-reload schema recompilation failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.56",
+  "version": "0.12.58",
   "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/dev/hot-reload.test.ts

@@ -152,29 +152,36 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
     assert.ok(reloadLog, 'Should log hot-reload message')
   })
 
-  test('should not replace a function that is not registered', async (t) => {
+  test('should register a brand-new function export', async (t) => {
     if (!(await ensureRecursiveWatchAvailable(t, tmpDir))) return
 
     addFunction('registeredFunc', {
       func: async () => ({ name: 'registered' }),
     })
 
-    await writeFunctionModule(tmpDir, 'unknownFunc.ts', '{ name: "unknown" }')
-
     reloader = await pikkuDevReloader({
       srcDirectories: [tmpDir],
       logger: mockLogger,
       pikkuDir: tmpDir,
     })
 
-    await writeFunctionModule(tmpDir, 'unknownFunc.ts', '{ name: "updated" }')
+    await writeFunctionModule(tmpDir, 'unknownFunc.ts', '{ name: "unknown" }')
 
     await wait(300)
 
-    assert.equal(
-      pikkuState(null, 'function', 'functions').has('unknownFunc'),
-      false
-    )
+    const func = pikkuState(null, 'function', 'functions').get('unknownFunc')!
+    assert.ok(func, 'New function export should be registered')
+    assert.deepEqual(await func.func({} as any, {}, {} as any), {
+      name: 'unknown',
+    })
+    const newLog = mockLogger
+      .getLogs()
+      .find(
+        (l) =>
+          l.message.includes('Hot-reloaded') &&
+          l.message.includes('new: unknownFunc')
+      )
+    assert.ok(newLog, 'Should log the newly registered function')
   })
 
   test('should keep old code when JS import fails', async (t) => {