@pikku/core 0.12.40 → 0.12.42

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.12.42
+
+### Patch Changes
+
+- 7b5b10a: fix(workflow): include suspend steps in plannedSteps with readable displayName
+
+  `workflow.suspend(reason)` calls now appear in the static `plannedSteps` ladder
+  produced by `deriveWorkflowPlan`. Previously the inspector ignored them, so the
+  runtime's `__workflow_suspend:<reason>` steps had no planned counterpart and
+  the UI appended them as orphans at the bottom of the step list instead of
+  showing them at the correct position.
+
+  Changes:
+  - `WorkflowPlannedStep` gains an optional `displayName` field — the human-
+    readable label to show in the UI (falls back to `stepName` when absent).
+  - New `SuspendStepMeta` type added to `WorkflowStepMeta`.
+  - Inspector extracts `workflow.suspend('reason')` calls and emits a
+    `SuspendStepMeta` step with `type: 'suspend'` and `reason`.
+  - `collectNamedSteps` maps a suspend step to
+    `{ stepName: '__workflow_suspend:<reason>', displayName: '<reason>' }`,
+    matching the key the runtime stores so the UI can overlay live status
+    onto the planned position.
+
+## 0.12.41
+
+### Patch Changes
+
+- 04db6a2: Make `rpc` a required property on `PikkuWire`. It is always lazily initialised by the function runner on every invocation regardless of wire type, so marking it optional was misleading.
+
 ## 0.12.40
 
 ### Patch Changes

package/dist/function/function-runner.d.ts

@@ -1,4 +1,4 @@
-import type { CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
+import type { CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuRawWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
 import type { SessionService } from '../services/user-session-service.js';
@@ -19,7 +19,7 @@ export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTy
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[];
     coerceDataFromSchema?: boolean;
     tags?: string[];
-    wire: PikkuWire;
+    wire: PikkuRawWire;
     sessionService?: SessionService<CoreUserSession>;
     credentialWireService?: PikkuCredentialWireService;
     packageName?: string | null;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
+export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
@@ -47,7 +47,7 @@ export type { WireAddonConfig } from './wirings/rpc/wire-addon.js';
 export type { PikkuPackageState } from './types/state.types.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, checkAuthPermissions, } from './permissions.js';
-export { isSerializable, stopSingletonServices } from './utils.js';
+export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';

package/dist/index.js

@@ -17,7 +17,7 @@ export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addTagPermission, addTagPermission as addPermission, addGlobalPermission, checkAuthPermissions, } from './permissions.js';
-export { isSerializable, stopSingletonServices } from './utils.js';
+export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { SchedulerService } from './services/scheduler-service.js';

package/dist/services/credential-wire-service.d.ts

@@ -1,12 +1,12 @@
 import type { CredentialService } from './credential-service.js';
-import type { PikkuWire } from '../types/core.types.js';
+import type { PikkuRawWire } from '../types/core.types.js';
 export declare class PikkuCredentialWireService {
     private credentialService?;
     private wire?;
     private credentials;
     private loaded;
     private loadPromise;
-    constructor(credentialService?: CredentialService | undefined, wire?: PikkuWire | undefined);
+    constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined);
     set(name: string, value: unknown): void;
     get<T = unknown>(name: string): T | null | Promise<T | null>;
     getAll(): Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/services/in-memory-workflow-service.d.ts

@@ -17,6 +17,7 @@ import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunW
  * ```
  */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
+    constructor();
     private sleepTimers;
     private runs;
     private steps;

package/dist/services/in-memory-workflow-service.js

@@ -17,6 +17,9 @@ import { isExpectedError } from '../errors/error-handler.js';
  * ```
  */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
+    constructor() {
+        super({ wireQueues: false });
+    }
     sleepTimers = new Set();
     runs = new Map();
     steps = new Map(); // keyed by `${runId}:${stepName}`

package/dist/services/pikku-user-id.d.ts

@@ -1,3 +1,3 @@
-import type { PikkuWire } from '../types/core.types.js';
-export type PikkuUserIdResolver = (wire: PikkuWire) => string | undefined;
+import type { PikkuRawWire } from '../types/core.types.js';
+export type PikkuUserIdResolver = (wire: PikkuRawWire) => string | undefined;
 export declare const defaultPikkuUserIdResolver: PikkuUserIdResolver;

package/dist/services/workflow-service.d.ts

@@ -6,6 +6,7 @@ import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run
  * Handles workflow execution, replay, orchestration logic, and run-level state
  */
 export interface WorkflowService {
+    wireQueueWorkers?(): void;
     createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
         plannedSteps?: WorkflowPlannedStep[];

package/dist/types/core.types.d.ts

@@ -126,7 +126,7 @@ export type JSONValue = JSONPrimitive | 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.
  */
@@ -214,7 +214,10 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 /**
  * Represents different forms of wire within Pikku and the outside world.
  */
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown> = Partial<{
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown> = {
+    /** 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 */
@@ -223,7 +226,6 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     functionId: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
-    rpc: TypedRPC;
     channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out> : PikkuChannel<unknown, Out> | undefined;
     scheduledTask: PikkuScheduledTask;
     queue: PikkuQueue;
@@ -255,10 +257,14 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
         durability: AuditDurability;
     };
 }>;
+/**
+ * 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
  */
-export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire<unknown, unknown, false, UserSession>, next: () => Promise<void>) => Promise<void>;
+export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire, next: () => Promise<void>) => Promise<void>;
 /**
  * Priority levels for middleware execution order.
  * Lower priority runs first (outermost in the onion model).
@@ -356,11 +362,18 @@ export type CreateSingletonServices<Config extends CoreConfig, SingletonServices
 /**
  * Defines a function type for creating session-specific services.
  */
-export type CreateWireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wire: PikkuWire<unknown, unknown, false, UserSession>) => Promise<WireServices<Services, SingletonServices>>;
+export type CreateWireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wire: PikkuRawWire) => Promise<WireServices<Services, SingletonServices>>;
 /**
  * Defines a function type for creating config.
  */
 export type CreateConfig<Config extends CoreConfig, 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/dist/utils.d.ts

@@ -1,5 +1,5 @@
 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';
 export declare const closeWireServices: (logger: Logger, wireServices: WireServices) => Promise<void>;
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
@@ -12,3 +12,5 @@ export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) =>
  * @param singletonServices - The parent singleton services to stop
  */
 export declare const stopSingletonServices: () => Promise<void>;
+/** Wrap server lifecycle hooks so the inspector can discover them. */
+export declare const pikkuServerLifecycle: <SS extends CoreSingletonServices = CoreSingletonServices>(lifecycle: ServerLifecycle<SS>) => ServerLifecycle<SS>;

package/dist/utils.js

@@ -105,3 +105,5 @@ export const stopSingletonServices = async () => {
         await stopService(logger, name, service);
     }
 };
+/** Wrap server lifecycle hooks so the inspector can discover them. */
+export const pikkuServerLifecycle = (lifecycle) => lifecycle;

package/dist/wirings/channel/channel-middleware-runner.d.ts

@@ -1,4 +1,4 @@
-import type { CoreSingletonServices, MiddlewareMetadata, PikkuWire } from '../../types/core.types.js';
+import type { CoreSingletonServices, MiddlewareMetadata, PikkuRawWire } from '../../types/core.types.js';
 import type { CorePikkuChannelMiddleware } from './channel.types.js';
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;
@@ -7,4 +7,4 @@ export declare const combineChannelMiddleware: (wireType: string, uid: string, {
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];
     packageName?: string | null;
 }) => readonly CorePikkuChannelMiddleware[];
-export declare function wrapChannelWithMiddleware<Out>(wire: PikkuWire, services: CoreSingletonServices, middlewares: readonly CorePikkuChannelMiddleware[]): PikkuWire;
+export declare function wrapChannelWithMiddleware<Out>(wire: PikkuRawWire, services: CoreSingletonServices, middlewares: readonly CorePikkuChannelMiddleware[]): PikkuRawWire;

package/dist/wirings/channel/local/local-eventhub-service.js

@@ -50,10 +50,13 @@ export class LocalEventHubService {
                 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/dist/wirings/rpc/rpc-runner.d.ts

@@ -1,4 +1,4 @@
-import type { CoreServices, PikkuWire } from '../../types/core.types.js';
+import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
 import type { CoreUserSession } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
@@ -19,7 +19,7 @@ export declare class ContextAwareRPCService {
     private wire;
     private options;
     private packageName;
-    constructor(services: CoreServices, wire: PikkuWire, options: {
+    constructor(services: CoreServices, wire: PikkuRawWire, options: {
         requiresAuth?: boolean;
         sessionService?: SessionService<CoreUserSession>;
     }, packageName?: string | null);
@@ -32,7 +32,7 @@ export declare class ContextAwareRPCService {
      * @private
      */
     private invokeAddonFunction;
-    rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuWire): Promise<Out>;
+    rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuRawWire): Promise<Out>;
     startWorkflow<In = any>(workflowName: string, input: In, options?: {
         startNode?: string;
         wire?: {
@@ -94,7 +94,7 @@ export declare class ContextAwareRPCService {
     remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
 }
 export declare class PikkuRPCService<Services extends CoreServices, TypedRPC = PikkuRPC> {
-    getContextRPCService(services: Services, wire: PikkuWire, requiresAuthOrOptions?: boolean | {
+    getContextRPCService(services: Services, wire: PikkuRawWire, requiresAuthOrOptions?: boolean | {
         requiresAuth?: boolean;
         sessionService?: SessionService<CoreUserSession>;
     } | undefined, depth?: number, packageName?: string | null): TypedRPC;

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

@@ -110,16 +110,8 @@ export class ContextAwareRPCService {
         return await this.rpc(funcName, data);
     }
     async rpc(funcName, data) {
-        const rpcDepth = this.wire.rpc?.depth || 0;
         const updatedWire = {
             ...this.wire,
-            rpc: this.wire.rpc
-                ? {
-                    ...this.wire.rpc,
-                    depth: rpcDepth + 1,
-                    global: false,
-                }
-                : undefined,
         };
         // Check addon namespace first (e.g. 'stripe:createCharge')
         if (funcName.includes(':')) {
@@ -197,17 +189,9 @@ export class ContextAwareRPCService {
         });
     }
     async rpcWithWire(rpcName, data, wire) {
-        const rpcDepth = this.wire.rpc?.depth || 0;
         const mergedWire = {
             ...this.wire,
             ...wire,
-            rpc: this.wire.rpc
-                ? {
-                    ...this.wire.rpc,
-                    depth: rpcDepth + 1,
-                    global: false,
-                }
-                : undefined,
         };
         if (rpcName.includes(':')) {
             return this.invokeAddonFunction(rpcName, data, mergedWire);

package/dist/wirings/workflow/dsl/index.d.ts

@@ -2,4 +2,4 @@
  * DSL (Domain Specific Language) workflow exports
  */
 export { addWorkflow } from './workflow-runner.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -230,6 +230,14 @@ export interface SwitchStepMeta {
     /** Default case steps (optional) */
     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)
  */
@@ -263,7 +271,7 @@ export interface ArrayPredicateStepMeta {
 /**
  * Workflow step metadata (extracted by inspector)
  */
-export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SuspendStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
 /**
  * Workflow step wire context for RPC functions
  * Provides step-level metadata including retry attempt tracking

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

@@ -12,4 +12,4 @@ export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-vali
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
 export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -66,6 +66,9 @@ export declare class WorkflowRunFailedError extends PikkuError {
     };
     constructor(message?: string);
 }
+export declare class WorkflowRunCancelledError extends PikkuError {
+    constructor();
+}
 export declare class WorkflowServiceNotInitialized extends Error {
 }
 export declare class WorkflowStepNameNotString extends Error {
@@ -85,13 +88,13 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         mirror?: WorkflowRunMirror;
     });
     private safeMirror;
-    rewireQueueWorkers(): void;
     /**
      * 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;
+    wireQueueWorkers(): void;
     /**
      * Check if a run is executing inline (without queues)
      */

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

@@ -131,6 +131,15 @@ addError(WorkflowRunFailedError, {
     status: 422,
     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 {
@@ -177,13 +186,11 @@ export class PikkuWorkflowService {
             }
         }
     }
-    rewireQueueWorkers() {
-        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.
      */
     wireQueueWorkers() {
         const functions = pikkuState(null, 'function', 'functions');
@@ -683,7 +690,7 @@ export class PikkuWorkflowService {
                     throw new WorkflowRunFailedError(run.error?.message);
                 }
                 if (run.status === 'cancelled') {
-                    throw new Error('Workflow was cancelled');
+                    throw new WorkflowRunCancelledError();
                 }
                 return run.output;
             }

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

@@ -1,7 +1,7 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -19,8 +19,10 @@ export interface WorkflowServiceConfig {
     sleeperRPCName: string;
 }
 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;
 }
 /**
  * Workflow run status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.40",
+  "version": "0.12.42",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/function/function-runner.ts

@@ -11,6 +11,7 @@ import type {
   CorePikkuMiddleware,
   PikkuWiringTypes,
   PikkuWire,
+  PikkuRawWire,
   MiddlewareMetadata,
   PermissionMetadata,
   CoreSingletonServices,
@@ -37,7 +38,7 @@ import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
 async function resolveSession(
-  wire: PikkuWire,
+  wire: PikkuRawWire,
   singletonServices: CoreSingletonServices,
   sessionService?: SessionService<CoreUserSession>
 ): Promise<void> {
@@ -234,7 +235,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
     coerceDataFromSchema?: boolean
     tags?: string[]
-    wire: PikkuWire
+    wire: PikkuRawWire
     sessionService?: SessionService<CoreUserSession>
     credentialWireService?: PikkuCredentialWireService
     packageName?: string | null

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   CoreSingletonServices,
   CoreUserSession,
   CreateConfig,
+  ServerLifecycle,
   FunctionMeta,
   FunctionRuntimeMeta,
   FunctionServicesMeta,
@@ -28,6 +29,7 @@ export type {
   PickRequired,
   PikkuAIMiddlewareHooks,
   PikkuWire,
+  PikkuRawWire,
   PikkuWiringTypes,
   RequireAtLeastOne,
   SerializedError,
@@ -187,7 +189,11 @@ export {
   addGlobalPermission,
   checkAuthPermissions,
 } from './permissions.js'
-export { isSerializable, stopSingletonServices } from './utils.js'
+export {
+  isSerializable,
+  stopSingletonServices,
+  pikkuServerLifecycle,
+} from './utils.js'
 export {
   getSingletonServices,
   getCreateWireServices,

package/src/services/credential-wire-service.ts

@@ -1,6 +1,6 @@
 import type { CredentialService } from './credential-service.js'
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
-import type { PikkuWire } from '../types/core.types.js'
+import type { PikkuRawWire } from '../types/core.types.js'
 
 export class PikkuCredentialWireService {
   private credentials: Record<string, unknown> = {}
@@ -9,7 +9,7 @@ export class PikkuCredentialWireService {
 
   constructor(
     private credentialService?: CredentialService,
-    private wire?: PikkuWire
+    private wire?: PikkuRawWire
   ) {}
 
   set(name: string, value: unknown): void {

package/src/services/in-memory-workflow-service.test.ts

@@ -366,7 +366,7 @@ describe('InMemoryWorkflowService', () => {
   })
 
   describe('queue worker registration', () => {
-    test('rewireQueueWorkers registers workflow queues added after construction', () => {
+    test('wireQueueWorkers registers workflow queues added after construction', () => {
       const stepQueue = 'wf-step-regression-enrich'
       const orchQueue = 'wf-orchestrator-regression-onboarding'
 
@@ -385,7 +385,7 @@ describe('InMemoryWorkflowService', () => {
       assert.strictEqual(getQueueWorkers().has(stepQueue), false)
       assert.strictEqual(getQueueWorkers().has(orchQueue), false)
 
-      ws.rewireQueueWorkers()
+      ws.wireQueueWorkers()
 
       assert.strictEqual(getQueueWorkers().has(stepQueue), true)
       assert.strictEqual(getQueueWorkers().has(orchQueue), true)

package/src/services/in-memory-workflow-service.ts

@@ -39,6 +39,10 @@ export class InMemoryWorkflowService
   extends PikkuWorkflowService
   implements WorkflowRunService
 {
+  constructor() {
+    super({ wireQueues: false })
+  }
+
   private sleepTimers = new Set<ReturnType<typeof setTimeout>>()
   private runs = new Map<string, WorkflowRun>()
   private steps = new Map<string, StepState>() // keyed by `${runId}:${stepName}`
@@ -451,7 +455,9 @@ export class InMemoryWorkflowService
     return nodeIds.filter((id) => !existingSteps.has(id))
   }
 
-  async getStepInstances(runId: string): Promise<
+  async getStepInstances(
+    runId: string
+  ): Promise<
     Array<{ stepName: string; status: StepStatus; fromStepName?: string }>
   > {
     const prefix = `${runId}:`

package/src/services/pikku-user-id.ts

@@ -1,6 +1,6 @@
-import type { PikkuWire } from '../types/core.types.js'
+import type { PikkuRawWire } from '../types/core.types.js'
 
-export type PikkuUserIdResolver = (wire: PikkuWire) => string | undefined
+export type PikkuUserIdResolver = (wire: PikkuRawWire) => string | undefined
 
 export const defaultPikkuUserIdResolver: PikkuUserIdResolver = (wire) => {
   // Explicit pikkuUserId on wire (set by earlier middleware or runner)

package/src/services/workflow-service.ts

@@ -18,6 +18,7 @@ import type {
  * Handles workflow execution, replay, orchestration logic, and run-level state
  */
 export interface WorkflowService {
+  wireQueueWorkers?(): void
   // Run-level state operations
   createRun(
     workflowName: string,