@pikku/core 0.12.40 → 0.12.42

package/src/types/core.types.ts

@@ -178,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.
@@ -285,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 */
@@ -294,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
@@ -333,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
  */
@@ -341,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>
 
@@ -527,7 +533,7 @@ export type CreateWireServices<
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
   services: SingletonServices,
-  wire: PikkuWire<unknown, unknown, false, UserSession>
+  wire: PikkuRawWire
 ) => Promise<WireServices<Services, SingletonServices>>
 
 /**
@@ -538,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/dsl/index.ts

@@ -21,6 +21,7 @@ export type {
   InlineStepMeta,
   SleepStepMeta,
   CancelStepMeta,
+  SuspendStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,
   FilterStepMeta,

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -239,6 +239,15 @@ export interface SwitchStepMeta {
   defaultSteps?: WorkflowStepMeta[]
 }
 
+/**
+ * Suspend step metadata (workflow.suspend())
+ */
+export interface SuspendStepMeta {
+  type: 'suspend'
+  /** Reason string passed to workflow.suspend() — becomes the durable step key */
+  reason: string
+}
+
 /**
  * Filter step metadata (array.filter)
  */
@@ -283,6 +292,7 @@ export type WorkflowStepMeta =
   | InlineStepMeta
   | SleepStepMeta
   | CancelStepMeta
+  | SuspendStepMeta
   | SwitchStepMeta
   | FilterStepMeta
   | ArrayPredicateStepMeta

package/src/wirings/workflow/index.ts

@@ -101,6 +101,7 @@ export type {
   InlineStepMeta,
   SleepStepMeta,
   CancelStepMeta,
+  SuspendStepMeta,
   SetStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,

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, {

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

@@ -144,7 +144,10 @@ export class WorkflowDispatchException extends Error {
     public readonly stepName: string,
     options?: { cause?: unknown }
   ) {
-    super(`Failed to dispatch workflow step '${stepName}' (run ${runId})`, options)
+    super(
+      `Failed to dispatch workflow step '${stepName}' (run ${runId})`,
+      options
+    )
     this.name = 'WorkflowDispatchException'
   }
 }
@@ -184,6 +187,16 @@ addError(WorkflowRunFailedError, {
   message: 'Workflow run failed.',
 })
 
+export class WorkflowRunCancelledError extends PikkuError {
+  constructor() {
+    super('Workflow was cancelled')
+  }
+}
+addError(WorkflowRunCancelledError, {
+  status: 409,
+  message: 'Workflow was cancelled.',
+})
+
 export class WorkflowServiceNotInitialized extends Error {}
 export class WorkflowStepNameNotString extends Error {
   constructor(stepName: any) {
@@ -237,16 +250,13 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
   }
 
-  public rewireQueueWorkers(): void {
-    this.wireQueueWorkers()
-  }
-
   /**
    * Wire the queue-based orchestrator/step/sleeper workers.
    * Subclasses that orchestrate without queues (e.g. Durable Objects) should
    * pass `wireQueues: false` to the base constructor and skip this entirely.
+   * Call this explicitly after adding addons dynamically.
    */
-  protected wireQueueWorkers(): void {
+  public wireQueueWorkers(): void {
     const functions = pikkuState(null, 'function', 'functions')
     const functionsMeta = pikkuState(null, 'function', 'meta')
 
@@ -426,7 +436,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     // Build step summaries from history (latest attempt per step)
     const stepMap = new Map<
       string,
-      { status: StepStatus; startedAt?: Date; completedAt?: Date; attempts: number }
+      {
+        status: StepStatus
+        startedAt?: Date
+        completedAt?: Date
+        attempts: number
+      }
     >()
     for (const step of history) {
       const existing = stepMap.get(step.stepName)
@@ -920,7 +935,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     const queueService = this.verifyQueueService()
     await queueService.add(
       this.getStepWorkerQueueName(rpcName),
-      JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })),
+      JSON.parse(
+        JSON.stringify({ runId, stepName, rpcName, data, fromStepName })
+      ),
       this.resolveStepJobOptions(stepOptions)
     )
   }
@@ -1185,7 +1202,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
           throw new WorkflowRunFailedError(run.error?.message)
         }
         if (run.status === 'cancelled') {
-          throw new Error('Workflow was cancelled')
+          throw new WorkflowRunCancelledError()
         }
         return run.output
       }
@@ -1837,7 +1854,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
             }
             if (WORKFLOW_END_STATES.has(childRun.status)) {
               if (childRun.status === 'failed') {
-                throw new Error(childRun.error?.message || 'Sub-workflow failed')
+                throw new Error(
+                  childRun.error?.message || 'Sub-workflow failed'
+                )
               }
               if (childRun.status === 'cancelled') {
                 throw new Error('Sub-workflow was cancelled')

package/src/wirings/workflow/workflow.types.ts

@@ -24,6 +24,7 @@ export type {
   InlineStepMeta,
   SleepStepMeta,
   CancelStepMeta,
+  SuspendStepMeta,
   SetStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,
@@ -54,8 +55,10 @@ export interface WorkflowServiceConfig {
 }
 
 export interface WorkflowPlannedStep {
-  /** Human-readable step label for UI timeline */
+  /** Durable step key — matches the runtime step name stored in the DB */
   stepName: string
+  /** Optional human-readable label for the UI timeline (falls back to stepName) */
+  displayName?: string
 }
 
 /**