@pikku/core 0.12.40 → 0.12.41

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.40",
+  "version": "0.12.41",
   "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,

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(