@pikku/core 0.12.39 → 0.12.41

package/src/types/core.types.ts

@@ -119,8 +119,12 @@ export type FunctionRuntimeMeta = {
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'
   sessionless?: boolean
-  /** When false, workflow steps calling this function are dispatched via the queue. Defaults to true (inline). */
-  inline?: boolean
+  /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
+  workflowQueued?: boolean
+  /** Retry count when this function is used as a workflow step. */
+  workflowRetries?: number
+  /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
+  workflowTimeout?: string
   version?: number
   approvalRequired?: boolean
   approvalDescription?: string
@@ -174,8 +178,7 @@ export type JSONValue =
 /**
  * Utility type for making certain keys required and leaving the rest as optional.
  */
-export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>> &
-  Partial<T>
+export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>
 
 /**
  * Utility type for making certain keys optional while keeping the rest required.
@@ -281,7 +284,10 @@ export type PikkuWire<
   MCPTools extends string | never = never,
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
   TriggerOutput = unknown,
-> = Partial<{
+> = {
+  /** Always present — lazily initialised on first access for every function invocation */
+  rpc: TypedRPC
+} & Partial<{
   wireType: PikkuWiringTypes
   wireId: string
   /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
@@ -290,7 +296,6 @@ export type PikkuWire<
   functionId: string
   http: PikkuHTTP<In>
   mcp: PikkuMCP<MCPTools>
-  rpc: TypedRPC
   channel: [IsChannel] extends [null]
     ? PikkuChannel<unknown, Out>
     : PikkuChannel<unknown, Out> | undefined
@@ -329,6 +334,11 @@ export type PikkuWire<
   }
 }>
 
+/**
+ * Wire object as constructed by runners, before rpc is lazily added by the function runner.
+ */
+export type PikkuRawWire = Omit<PikkuWire, 'rpc'>
+
 /**
  * A function that can wrap an wire and be called before or after
  */
@@ -337,7 +347,7 @@ export type CorePikkuMiddleware<
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  wires: PikkuWire<unknown, unknown, false, UserSession>,
+  wires: PikkuWire,
   next: () => Promise<void>
 ) => Promise<void>
 
@@ -523,7 +533,7 @@ export type CreateWireServices<
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  wire: PikkuWire<unknown, unknown, false, UserSession>
+  wire: PikkuRawWire
 ) => Promise<WireServices<Services, SingletonServices>>
 
 /**
@@ -534,6 +544,16 @@ export type CreateConfig<
   RemainingArgs extends any[] = unknown[],
 > = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>
 
+/** Server lifecycle hooks for startup and shutdown phases. */
+export type ServerLifecycle<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+> = {
+  beforeStart?: (services: SingletonServices) => void | Promise<void>
+  afterStart?: (services: SingletonServices) => void | Promise<void>
+  beforeStop?: (services: SingletonServices) => void | Promise<void>
+  afterStop?: (services: SingletonServices) => void | Promise<void>
+}
+
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */

package/src/utils.ts

@@ -1,5 +1,9 @@
 import type { Logger } from './services/logger.js'
-import type { WireServices } from './types/core.types.js'
+import type {
+  CoreSingletonServices,
+  ServerLifecycle,
+  WireServices,
+} from './types/core.types.js'
 import { getSingletonServices, getAllPackageStates } from './pikku-state.js'
 
 export const closeWireServices = async (
@@ -127,3 +131,10 @@ export const stopSingletonServices = async (): Promise<void> => {
     await stopService(logger, name, service)
   }
 }
+
+/** Wrap server lifecycle hooks so the inspector can discover them. */
+export const pikkuServerLifecycle = <
+  SS extends CoreSingletonServices = CoreSingletonServices,
+>(
+  lifecycle: ServerLifecycle<SS>
+): ServerLifecycle<SS> => lifecycle

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -1,4 +1,4 @@
-import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
+import type { PikkuRawWire, CoreUserSession } from '../../types/core.types.js'
 import type {
   CoreAIAgent,
   AIAgentInput,
@@ -397,7 +397,7 @@ export async function buildToolDefs(
         needsApproval: needsApproval || undefined,
         approvalDescriptionFn,
         execute: async (toolInput: unknown) => {
-          const wire: PikkuWire = params.sessionService
+          const wire: PikkuRawWire = params.sessionService
             ? { ...createMiddlewareSessionWireProps(params.sessionService) }
             : {}
           const rpcService = new ContextAwareRPCService(

package/src/wirings/channel/channel-common.ts

@@ -1,6 +1,7 @@
 import type {
   CoreSingletonServices,
   CorePikkuMiddleware,
+  PikkuRawWire,
   PikkuWire,
   MiddlewareMetadata,
 } from '../../types/core.types.js'
@@ -73,7 +74,7 @@ export const runChannelLifecycleWithMiddleware = async ({
     }
   )
 
-  let wire: PikkuWire = { channel }
+  let wire: PikkuRawWire = { channel }
   if (allChannelMiddleware.length > 0) {
     wire = wrapChannelWithMiddleware(wire, services, allChannelMiddleware)
   }
@@ -90,7 +91,12 @@ export const runChannelLifecycleWithMiddleware = async ({
   }
 
   if (allMiddleware.length > 0) {
-    return await runMiddleware(services, wire, allMiddleware, runLifecycle)
+    return await runMiddleware(
+      services,
+      wire as unknown as PikkuWire,
+      allMiddleware,
+      runLifecycle
+    )
   } else {
     return await runLifecycle()
   }

package/src/wirings/channel/channel-middleware-runner.ts

@@ -1,7 +1,7 @@
 import type {
   CoreSingletonServices,
   MiddlewareMetadata,
-  PikkuWire,
+  PikkuRawWire,
 } from '../../types/core.types.js'
 import type { CorePikkuChannelMiddleware } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
@@ -87,10 +87,10 @@ export const combineChannelMiddleware = (
 }
 
 export function wrapChannelWithMiddleware<Out>(
-  wire: PikkuWire,
+  wire: PikkuRawWire,
   services: CoreSingletonServices,
   middlewares: readonly CorePikkuChannelMiddleware[]
-): PikkuWire {
+): PikkuRawWire {
   if (middlewares.length === 0 || !wire.channel) return wire
 
   const channel = wire.channel

package/src/wirings/channel/local/local-channel-runner.ts

@@ -4,7 +4,11 @@ import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import type { CoreChannel, RunChannelOptions } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import type { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type {
+  PikkuRawWire,
+  PikkuWire,
+  WireServices,
+} from '../../../types/core.types.js'
 import { isProduction } from '../../../env.js'
 import { getErrorResponse } from '../../../errors/error-handler.js'
 import { handleHTTPError } from '../../../handle-error.js'
@@ -46,7 +50,7 @@ const runUpgradeMiddleware = async (
       {
         http,
         ...createMiddlewareSessionWireProps(userSession),
-      },
+      } as unknown as PikkuWire,
       middleware
     )
   }
@@ -123,7 +127,7 @@ export const runLocalChannel = async ({
         singletonServices.logger
       )
       const channel = channelHandler.getChannel()
-      const wire: PikkuWire = {
+      const wire: PikkuRawWire = {
         channel,
         ...createMiddlewareSessionWireProps(userSession),
       }

package/src/wirings/channel/local/local-eventhub-service.ts

@@ -69,9 +69,12 @@ export class LocalEventHubService<
       if (channelId === toChannelId) continue // Skip sending to the sender
       const channel = this.channels.get(toChannelId)
       if (channel) {
-        channel.send(data, isBinary)
-      } else {
-        // TODO: Websocket is closed, remove the channel from the topic
+        try {
+          channel.send(data, isBinary)
+        } catch {
+          // Channel closed (e.g. SSE ReadableStream controller already closed on browser disconnect) — clean up
+          this.onChannelClosed(toChannelId)
+        }
       }
     }
   }

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -1,6 +1,6 @@
 import type {
   CoreUserSession,
-  PikkuWire,
+  PikkuRawWire,
   WireServices,
 } from '../../../types/core.types.js'
 import { closeWireServices } from '../../../utils.js'
@@ -120,7 +120,7 @@ export const runChannelConnect = async ({
     channel.getState = () => channelStore.getState(channelId) as any
     channel.clearState = () => channelStore.clearState(channelId)
 
-    const wire: PikkuWire = {
+    const wire: PikkuRawWire = {
       channel,
       ...createMiddlewareSessionWireProps(userSession),
     }
@@ -216,7 +216,7 @@ export const runChannelDisconnect = async ({
     }
   }
 
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),
   }
@@ -288,7 +288,7 @@ export const runChannelMessage = async (
     }
   }
 
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),
   }

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

@@ -19,7 +19,7 @@ import type {
   CoreSingletonServices,
   CoreServices,
   CreateWireServices,
-  PikkuWire,
+  PikkuRawWire,
   CreateConfig,
   CreateSingletonServices,
 } from '../../types/core.types.js'
@@ -356,7 +356,7 @@ export async function runCLICommand({
     singletonServices.sessionStore
   )
 
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     cli: {
       program,
       command: commandPath,

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

@@ -10,6 +10,7 @@ import type {
 } from './gateway.types.js'
 import type {
   PikkuWire,
+  PikkuRawWire,
   CorePikkuMiddleware,
   CoreSingletonServices,
 } from '../../types/core.types.js'
@@ -381,7 +382,7 @@ export const createListenerMessageHandler = (
     const parsed = adapter.parse(rawData)
     if (!parsed) return
 
-    const wire: PikkuWire = {}
+    const wire: PikkuRawWire = {}
     const gateway: PikkuGateway = {
       gatewayName: name,
       senderId: parsed.senderId,
@@ -403,7 +404,12 @@ export const createListenerMessageHandler = (
     }
 
     if (allMiddleware.length > 0) {
-      await runMiddleware(singletonServices, wire, allMiddleware, exec)
+      await runMiddleware(
+        singletonServices,
+        wire as unknown as PikkuWire,
+        allMiddleware,
+        exec
+      )
     } else {
       await exec()
     }

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

@@ -18,6 +18,7 @@ import type {
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
   WireServices,
+  PikkuRawWire,
   PikkuWire,
   PikkuWiringTypes,
 } from '../../types/core.types.js'
@@ -408,7 +409,7 @@ const executeRoute = async (
     }
   }
 
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     traceId: requestId,
     http,
     channel,
@@ -586,7 +587,7 @@ export const fetchData = async <In, Out>(
       if (apiType.toLowerCase() === 'options') {
         const httpGroups = pikkuState(null, 'middleware', 'httpGroup')
         const globalMiddleware = httpGroups['*']
-        const wire: PikkuWire = { http: http! }
+        const wire = { http: http! } as unknown as PikkuWire
         if (globalMiddleware) {
           await runMiddleware(
             singletonServices,

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

@@ -1,4 +1,4 @@
-import type { PikkuWire } from '../../types/core.types.js'
+import type { PikkuRawWire } from '../../types/core.types.js'
 import type {
   CoreMCPResource,
   CoreMCPPrompt,
@@ -217,7 +217,7 @@ async function runMCPPikkuFunc(
     const mcpSessionService = new PikkuSessionService(
       singletonServices.sessionStore
     )
-    const wire: PikkuWire = {
+    const wire: PikkuRawWire = {
       mcp: mcpWire,
       ...createMiddlewareSessionWireProps(mcpSessionService),
     }

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

@@ -1,4 +1,4 @@
-import type { PikkuWire } from '../../types/core.types.js'
+import type { PikkuRawWire } from '../../types/core.types.js'
 import type { CoreQueueWorker, QueueJob, PikkuQueue } from './queue.types.js'
 import type {
   CorePikkuFunctionConfig,
@@ -156,7 +156,7 @@ export async function runQueueJob({
   try {
     logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
 
-    const wire: PikkuWire = {
+    const wire: PikkuRawWire = {
       traceId: resolvedTraceId,
       queue,
     }

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

@@ -1,4 +1,8 @@
-import type { CoreServices, PikkuWire } from '../../types/core.types.js'
+import type {
+  CoreServices,
+  PikkuWire,
+  PikkuRawWire,
+} from '../../types/core.types.js'
 import type { SessionService } from '../../services/user-session-service.js'
 import type { CoreUserSession } from '../../types/core.types.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
@@ -100,7 +104,7 @@ const resolvePikkuFunction = (
 export class ContextAwareRPCService {
   constructor(
     private services: CoreServices,
-    private wire: PikkuWire,
+    private wire: PikkuRawWire,
     private options: {
       requiresAuth?: boolean
       sessionService?: SessionService<CoreUserSession>
@@ -136,16 +140,8 @@ export class ContextAwareRPCService {
     funcName: string,
     data: In
   ): Promise<Out> {
-    const rpcDepth = this.wire.rpc?.depth || 0
-    const updatedWire: PikkuWire = {
+    const updatedWire: PikkuRawWire = {
       ...this.wire,
-      rpc: this.wire.rpc
-        ? {
-            ...this.wire.rpc,
-            depth: rpcDepth + 1,
-            global: false,
-          }
-        : undefined,
     }
 
     // Check addon namespace first (e.g. 'stripe:createCharge')
@@ -209,7 +205,7 @@ export class ContextAwareRPCService {
   private async invokeAddonFunction<In = any, Out = any>(
     namespacedFunction: string,
     data: In,
-    wire: PikkuWire
+    wire: PikkuRawWire
   ): Promise<Out> {
     // Resolve namespace to package name
     const resolved = resolveNamespace(namespacedFunction)
@@ -248,19 +244,11 @@ export class ContextAwareRPCService {
   public async rpcWithWire<In = any, Out = any>(
     rpcName: string,
     data: In,
-    wire: PikkuWire
+    wire: PikkuRawWire
   ): Promise<Out> {
-    const rpcDepth = this.wire.rpc?.depth || 0
-    const mergedWire: PikkuWire = {
+    const mergedWire: PikkuRawWire = {
       ...this.wire,
       ...wire,
-      rpc: this.wire.rpc
-        ? {
-            ...this.wire.rpc,
-            depth: rpcDepth + 1,
-            global: false,
-          }
-        : undefined,
     }
 
     if (rpcName.includes(':')) {
@@ -438,7 +426,7 @@ export class PikkuRPCService<
   // Convenience function for initializing
   getContextRPCService(
     services: Services,
-    wire: PikkuWire,
+    wire: PikkuRawWire,
     requiresAuthOrOptions?:
       | boolean
       | {
@@ -456,7 +444,7 @@ export class PikkuRPCService<
         : { requiresAuth: requiresAuthOrOptions }
     const serviceRPC = new ContextAwareRPCService(
       services,
-      wire,
+      wire as PikkuWire,
       options,
       packageName
     )

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

@@ -1,4 +1,4 @@
-import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
+import type { PikkuRawWire, CoreUserSession } from '../../types/core.types.js'
 import type { CoreScheduledTask } from './scheduler.types.js'
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
 import {
@@ -97,7 +97,7 @@ export async function runScheduledTask({
   }
 
   // Create the scheduled task wire object
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     traceId: resolvedTraceId,
     scheduledTask: {
       name,

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

@@ -1,4 +1,4 @@
-import type { PikkuWire } from '../../types/core.types.js'
+import type { PikkuRawWire } from '../../types/core.types.js'
 import type {
   CoreTrigger,
   CoreTriggerSource,
@@ -99,7 +99,7 @@ export async function setupTrigger<TInput = unknown, TOutput = unknown>({
     )
   }
 
-  const wire: PikkuWire = {
+  const wire: PikkuRawWire = {
     trigger: {
       invoke: (data: unknown) => {
         singletonServices.logger.info(`Trigger fired: ${name}`)

package/src/wirings/workflow/pikku-workflow-service.test.ts

@@ -10,10 +10,11 @@ import {
 } from './pikku-workflow-service.js'
 
 describe('pikku-workflow-service worker registration', () => {
-  test('registers sleeper function metadata', () => {
+  test('registers sleeper function metadata after wireQueueWorkers', () => {
     resetPikkuState()
 
-    new InMemoryWorkflowService()
+    const ws = new InMemoryWorkflowService()
+    ws.wireQueueWorkers()
 
     const functionMeta = pikkuState(null, 'function', 'meta')
     assert.deepEqual(functionMeta.pikkuWorkflowSleeper, {
@@ -126,19 +127,19 @@ describe('pikku-workflow-service run-level inline', () => {
 describe('pikku-workflow-service per-function step dispatch', () => {
   // Expose the protected dispatchStep so we can assert the dispatch decision
   // in isolation: a step queues only when its function opts out of inline
-  // execution (inline: false).
+  // execution (workflowQueued: true).
   class TestWorkflowService extends InMemoryWorkflowService {
     public callDispatchStep(rpcName: string) {
       return this.dispatchStep('run-1', 'step-1', rpcName, {})
     }
   }
 
-  const setupFunction = (rpcName: string, inline?: boolean) => {
+  const setupFunction = (rpcName: string, workflowQueued?: boolean) => {
     pikkuState(null, 'rpc', 'meta')[rpcName] = rpcName as any
     pikkuState(null, 'function', 'meta')[rpcName] = {
       pikkuFuncId: rpcName,
       sessionless: true,
-      ...(inline === undefined ? {} : { inline }),
+      ...(workflowQueued === undefined ? {} : { workflowQueued }),
     } as any
   }
 
@@ -166,7 +167,7 @@ describe('pikku-workflow-service per-function step dispatch', () => {
     cleanup('defaultInlineStep')
   })
 
-  test('inline: false step IS dispatched to the queue when a queueService exists', async () => {
+  test('workflowQueued: true step IS dispatched to the queue when a queueService exists', async () => {
     const ws = new TestWorkflowService()
     let queued = false
     pikkuState(null, 'package', 'singletonServices', {
@@ -178,36 +179,25 @@ describe('pikku-workflow-service per-function step dispatch', () => {
       },
     } as any)
 
-    setupFunction('queuedStep', false)
+    setupFunction('queuedStep', true)
     const dispatched = await ws.callDispatchStep('queuedStep')
-    assert.equal(dispatched, true, 'inline:false step should dispatch')
-    assert.equal(queued, true, 'inline:false step should queue')
+    assert.equal(dispatched, true, 'workflowQueued step should dispatch')
+    assert.equal(queued, true, 'workflowQueued step should queue')
     cleanup('queuedStep')
   })
 
-  test('inline: false step warns and runs inline when no queueService is configured', async () => {
+  test('workflowQueued: true step throws when no queueService is configured', async () => {
     const ws = new TestWorkflowService()
-    let warned = false
     pikkuState(null, 'package', 'singletonServices', {
-      logger: {
-        error() {},
-        info() {},
-        warn: () => {
-          warned = true
-        },
-        debug() {},
-      },
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
       // no queueService
     } as any)
 
-    setupFunction('queuedStepNoQueue', false)
-    const dispatched = await ws.callDispatchStep('queuedStepNoQueue')
-    assert.equal(
-      dispatched,
-      false,
-      'falls back to inline when no queue service'
+    setupFunction('queuedStepNoQueue', true)
+    await assert.rejects(
+      () => ws.callDispatchStep('queuedStepNoQueue'),
+      /workflowQueued: true.*no queue service/i
     )
-    assert.equal(warned, true, 'should warn about the misconfiguration')
     cleanup('queuedStepNoQueue')
   })
 })