@pikku/inspector 0.12.28 → 0.12.29

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 0.12.29
+
+### 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.
+
+- Updated dependencies [7b5b10a]
+  - @pikku/core@0.12.42
+
 ## 0.12.28
 
 ### Patch Changes

package/dist/add/add-file-with-factory.js

@@ -8,6 +8,7 @@ const wrapperFunctionMap = {
     pikkuAddonServices: 'CreateSingletonServices',
     pikkuWireServices: 'CreateWireServices',
     pikkuAddonWireServices: 'CreateWireServices',
+    pikkuServerLifecycle: 'ServerLifecycle',
 };
 export const addFileWithFactory = (node, checker, methods = new Map(), expectedTypeName, state) => {
     if (ts.isVariableDeclaration(node)) {

package/dist/inspector.js

@@ -30,7 +30,9 @@ export function getInitialInspectorState(rootDir) {
         wireServicesFactories: new Map(),
         wireServicesMeta: new Map(),
         addonRequiredParentServices: [],
+        addonServerlessIncompatible: new Map(),
         configFactories: new Map(),
+        serverLifecycleFactories: new Map(),
         filesAndMethods: {},
         filesAndMethodsErrors: new Map(),
         typesLookup: new Map(),

package/dist/types.d.ts

@@ -303,6 +303,12 @@ export interface InspectorFilesAndMethods {
         type: string;
         typePath: string;
     };
+    serverLifecycleFactory?: {
+        file: string;
+        variable: string;
+        type: string;
+        typePath: string;
+    };
 }
 export interface InspectorDiagnostic {
     code: string;
@@ -354,7 +360,9 @@ export interface InspectorState {
     wireServicesFactories: PathToNameAndType;
     wireServicesMeta: Map<string, string[]>;
     addonRequiredParentServices: string[];
+    addonServerlessIncompatible: Map<string, string[]>;
     configFactories: PathToNameAndType;
+    serverLifecycleFactories: PathToNameAndType;
     filesAndMethods: InspectorFilesAndMethods;
     filesAndMethodsErrors: Map<string, PathToNameAndType>;
     typesLookup: Map<string, ts.Type[]>;

package/dist/utils/get-files-and-methods.d.ts

@@ -13,9 +13,10 @@ export type FilesAndMethods = {
     pikkuConfigFactory: Meta;
     singletonServicesFactory: Meta;
     wireServicesFactory: Meta;
+    serverLifecycleFactory: Meta;
 };
 export type FilesAndMethodsErrors = Map<string, PathToNameAndType>;
-export declare const getFilesAndMethods: ({ singletonServicesTypeImportMap, wireServicesTypeImportMap, userSessionTypeImportMap, configTypeImportMap, wireServicesFactories, singletonServicesFactories, configFactories, }: InspectorState, { configFileType, userSessionType, singletonServicesFactoryType, wireServicesFactoryType, }?: InspectorOptions["types"]) => {
+export declare const getFilesAndMethods: ({ singletonServicesTypeImportMap, wireServicesTypeImportMap, userSessionTypeImportMap, configTypeImportMap, wireServicesFactories, singletonServicesFactories, configFactories, serverLifecycleFactories, }: InspectorState, { configFileType, userSessionType, singletonServicesFactoryType, wireServicesFactoryType, }?: InspectorOptions["types"]) => {
     result: Partial<FilesAndMethods>;
     errors: FilesAndMethodsErrors;
 };

package/dist/utils/get-files-and-methods.js

@@ -46,7 +46,7 @@ const getMetaTypes = (type, map, desiredType, errors) => {
     }
     return;
 };
-export const getFilesAndMethods = ({ singletonServicesTypeImportMap, wireServicesTypeImportMap, userSessionTypeImportMap, configTypeImportMap, wireServicesFactories, singletonServicesFactories, configFactories, }, { configFileType, userSessionType, singletonServicesFactoryType, wireServicesFactoryType, } = {}) => {
+export const getFilesAndMethods = ({ singletonServicesTypeImportMap, wireServicesTypeImportMap, userSessionTypeImportMap, configTypeImportMap, wireServicesFactories, singletonServicesFactories, configFactories, serverLifecycleFactories, }, { configFileType, userSessionType, singletonServicesFactoryType, wireServicesFactoryType, } = {}) => {
     const errors = new Map();
     const result = {
         userSessionType: getMetaTypes('CoreUserSession', userSessionTypeImportMap, userSessionType, errors),
@@ -56,6 +56,7 @@ export const getFilesAndMethods = ({ singletonServicesTypeImportMap, wireService
         pikkuConfigFactory: getMetaTypes('CoreConfig', configFactories, configFileType, errors),
         singletonServicesFactory: getMetaTypes('CreateSingletonServices', singletonServicesFactories, singletonServicesFactoryType, errors),
         wireServicesFactory: getMetaTypes('CreateWireServices', wireServicesFactories, wireServicesFactoryType, errors),
+        serverLifecycleFactory: getMetaTypes('ServerLifecycle', serverLifecycleFactories),
     };
     return { result, errors };
 };

package/dist/utils/load-addon-functions-meta.js

@@ -134,6 +134,20 @@ export async function loadAddonFunctionsMeta(logger, state) {
             catch {
                 // No variables meta — that's fine
             }
+            // Load addon serverlessIncompatible service names from pikku-addon-meta.gen.json
+            try {
+                const addonMetaPath = require.resolve(`${decl.package}/.pikku/console/pikku-addon-meta.gen.json`);
+                const addonMetaRaw = await readFile(addonMetaPath, 'utf-8');
+                const addonMeta = JSON.parse(addonMetaRaw);
+                if (Array.isArray(addonMeta.serverlessIncompatible) &&
+                    addonMeta.serverlessIncompatible.length > 0) {
+                    state.addonServerlessIncompatible.set(namespace, addonMeta.serverlessIncompatible);
+                    logger.debug(`Addon '${namespace}' marks [${addonMeta.serverlessIncompatible.join(', ')}] as serverless-incompatible`);
+                }
+            }
+            catch {
+                // No addon meta or no serverlessIncompatible declared — that's fine
+            }
             // Load addon required parent services from pikku-services.gen
             try {
                 const servicesGenPath = require.resolve(`${decl.package}/.pikku/pikku-services.gen.js`);

package/dist/utils/serialize-inspector-state.d.ts

@@ -56,6 +56,7 @@ export interface SerializableInspectorState {
     ]>;
     wireServicesMeta: Array<[string, string[]]>;
     addonRequiredParentServices: string[];
+    addonServerlessIncompatible: Array<[string, string[]]>;
     configFactories: Array<[
         string,
         {
@@ -64,6 +65,14 @@ export interface SerializableInspectorState {
             typePath: string | null;
         }[]
     ]>;
+    serverLifecycleFactories: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
     filesAndMethods: InspectorState['filesAndMethods'];
     filesAndMethodsErrors: Array<[
         string,

package/dist/utils/serialize-inspector-state.js

@@ -24,7 +24,9 @@ export function serializeInspectorState(state) {
         wireServicesFactories: Array.from(state.wireServicesFactories.entries()),
         wireServicesMeta: Array.from(state.wireServicesMeta.entries()),
         addonRequiredParentServices: state.addonRequiredParentServices,
+        addonServerlessIncompatible: Array.from(state.addonServerlessIncompatible.entries()),
         configFactories: Array.from(state.configFactories.entries()),
+        serverLifecycleFactories: Array.from(state.serverLifecycleFactories.entries()),
         filesAndMethods: state.filesAndMethods,
         filesAndMethodsErrors: Array.from(state.filesAndMethodsErrors.entries()).map(([key, mapValue]) => [key, Array.from(mapValue.entries())]),
         schemaLookup: Array.from(state.schemaLookup.entries()),
@@ -176,7 +178,9 @@ export function deserializeInspectorState(data) {
         wireServicesFactories: new Map(data.wireServicesFactories),
         wireServicesMeta: new Map(data.wireServicesMeta),
         addonRequiredParentServices: data.addonRequiredParentServices || [],
+        addonServerlessIncompatible: new Map(data.addonServerlessIncompatible || []),
         configFactories: new Map(data.configFactories),
+        serverLifecycleFactories: new Map(data.serverLifecycleFactories),
         filesAndMethods: data.filesAndMethods,
         filesAndMethodsErrors: new Map(data.filesAndMethodsErrors.map(([key, entries]) => [
             key,

package/dist/utils/workflow/derive-workflow-plan.js

@@ -43,6 +43,15 @@ function containsLoop(steps) {
 function containsConditional(steps) {
     return steps.some((step) => step.type === 'branch' || step.type === 'switch');
 }
+/**
+ * Turn an internal snake/kebab reason key into a sentence-case display label.
+ * e.g. "awaiting_approval" → "Awaiting approval", "building-image" → "Building image"
+ */
+function reasonToLabel(reason) {
+    return reason
+        .replace(/[-_]/g, ' ')
+        .replace(/^(.)/, (c) => c.toUpperCase());
+}
 /** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
 function collectNamedSteps(steps) {
     const planned = [];
@@ -53,6 +62,16 @@ function collectNamedSteps(steps) {
             case 'sleep':
                 planned.push({ stepName: step.stepName });
                 break;
+            case 'suspend':
+                // Runtime stores the suspend step as `__workflow_suspend:${reason}`.
+                // We surface it in the planned ladder with a readable displayName so
+                // the UI shows it in the right position instead of appending it at the
+                // bottom as an unrecognised orphan.
+                planned.push({
+                    stepName: `__workflow_suspend:${step.reason}`,
+                    displayName: reasonToLabel(step.reason),
+                });
+                break;
             case 'parallel':
                 for (const child of step.children) {
                     planned.push({ stepName: child.stepName });

package/dist/utils/workflow/dsl/extract-dsl-workflow.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { isWorkflowDoCall, isWorkflowSleepCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
+import { isWorkflowDoCall, isWorkflowSleepCall, isWorkflowSuspendCall, isThrowCancelException, extractCancelReason, isParallelFanout, isParallelGroup, isSequentialFanout, isArrayFilter, isArraySome, isArrayEvery, extractForOfVariable, isArrayType, getSourceText, extractSourcePath, } from './patterns.js';
 import { validateNoDisallowedPatterns, validateAwaitedCalls, formatValidationErrors, } from './validation.js';
 import { extractStringLiteral, extractNumberLiteral, } from '../../extract-node-value.js';
 /**
@@ -360,6 +360,9 @@ function extractExpressionStatement(statement, context) {
         if (isWorkflowSleepCall(call, context.checker)) {
             return extractSleepStep(call, context);
         }
+        if (isWorkflowSuspendCall(call, context.checker)) {
+            return extractSuspendStep(call, context);
+        }
         // Check for parallel group or fanout
         if (isParallelFanout(call)) {
             return extractParallelFanout(call, context);
@@ -513,6 +516,28 @@ function extractSleepStep(call, context) {
         return null;
     }
 }
+/**
+ * Extract suspend step from workflow.suspend() call
+ */
+function extractSuspendStep(call, context) {
+    const args = call.arguments;
+    if (args.length < 1)
+        return null;
+    try {
+        const reason = extractStringLiteral(args[0], context.checker);
+        return {
+            type: 'suspend',
+            reason,
+        };
+    }
+    catch (error) {
+        context.errors.push({
+            message: `Failed to extract suspend step: ${error instanceof Error ? error.message : String(error)}`,
+            node: call,
+        });
+        return null;
+    }
+}
 /**
  * Extract cancel step from throw WorkflowCancelledException statement
  */

package/dist/utils/workflow/dsl/patterns.d.ts

@@ -10,6 +10,10 @@ export declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.Ty
  * Check if a call expression is workflow.sleep()
  */
 export declare function isWorkflowSleepCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.suspend()
+ */
+export declare function isWorkflowSuspendCall(node: ts.CallExpression, _checker: ts.TypeChecker): boolean;
 /**
  * Check if a throw statement throws WorkflowCancelledException
  * Matches: throw new WorkflowCancelledException(...) or throw WorkflowCancelledException(...)

package/dist/utils/workflow/dsl/patterns.js

@@ -26,6 +26,18 @@ export function isWorkflowSleepCall(node, checker) {
         ts.isIdentifier(propAccess.expression) &&
         propAccess.expression.text === 'workflow');
 }
+/**
+ * Check if a call expression is workflow.suspend()
+ */
+export function isWorkflowSuspendCall(node, _checker) {
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    return (propAccess.name.text === 'suspend' &&
+        ts.isIdentifier(propAccess.expression) &&
+        propAccess.expression.text === 'workflow');
+}
 /**
  * Check if a throw statement throws WorkflowCancelledException
  * Matches: throw new WorkflowCancelledException(...) or throw WorkflowCancelledException(...)

package/dist/visit.js

@@ -33,6 +33,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addFileWithFactory(node, checker, state.singletonServicesFactories, 'CreateSingletonServices', state);
     addFileWithFactory(node, checker, state.wireServicesFactories, 'CreateWireServices', state);
     addFileWithFactory(node, checker, state.configFactories, 'CreateConfig');
+    addFileWithFactory(node, checker, state.serverLifecycleFactories, 'ServerLifecycle');
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
     addMiddleware(logger, node, checker, state, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.28",
+  "version": "0.12.29",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.40",
+    "@pikku/core": "^0.12.42",
     "openapi-types": "^12.1.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",

package/src/add/add-file-with-factory.ts

@@ -10,6 +10,7 @@ const wrapperFunctionMap: Record<string, string> = {
   pikkuAddonServices: 'CreateSingletonServices',
   pikkuWireServices: 'CreateWireServices',
   pikkuAddonWireServices: 'CreateWireServices',
+  pikkuServerLifecycle: 'ServerLifecycle',
 }
 
 export const addFileWithFactory = (

package/src/add/pii-check.test.ts

@@ -28,7 +28,7 @@ function makeLogger() {
 
 /**
  * Inline Private<T>/Pii<T>/Secret<T> definitions that the test source files use.
- * Mirrors what schema.d.ts emits so the TypeScript program sees the correct
+ * Mirrors what schema.gen.ts emits so the TypeScript program sees the correct
  * structural brand type even without @pikku/core being importable from /tmp.
  */
 // Optional `__classification__?` mirrors what @pikku/core and `pikku db migrate`
@@ -50,7 +50,10 @@ async function runInspect(sourceCode: string) {
   try {
     // The data-classification leak scan is opt-in (off by default to keep it
     // off the `pikku all` hot path); these tests exercise it, so enable it.
-    await inspect(logger, [file], { rootDir: tmpDir, classificationCheck: true })
+    await inspect(logger, [file], {
+      rootDir: tmpDir,
+      classificationCheck: true,
+    })
   } finally {
     await rm(tmpDir, { recursive: true, force: true })
   }

package/src/inspector.ts

@@ -61,7 +61,9 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     wireServicesFactories: new Map(),
     wireServicesMeta: new Map(),
     addonRequiredParentServices: [],
+    addonServerlessIncompatible: new Map(),
     configFactories: new Map(),
+    serverLifecycleFactories: new Map(),
     filesAndMethods: {},
     filesAndMethodsErrors: new Map(),
     typesLookup: new Map(),

package/src/types.ts

@@ -381,6 +381,12 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
+  serverLifecycleFactory?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
 }
 
 export interface InspectorDiagnostic {
@@ -435,7 +441,9 @@ export interface InspectorState {
   wireServicesFactories: PathToNameAndType
   wireServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   addonRequiredParentServices: string[] // services an addon needs from the parent (extracted from pikkuAddonServices 2nd param)
+  addonServerlessIncompatible: Map<string, string[]> // namespace → service names that are serverless-incompatible (scoped per addon)
   configFactories: PathToNameAndType
+  serverLifecycleFactories: PathToNameAndType
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
   typesLookup: Map<string, ts.Type[]> // Lookup for types by name (e.g., function input types, Config type)

package/src/utils/filter-inspector-state.test.ts

@@ -3,7 +3,11 @@ import { strict as assert } from 'node:assert'
 import { filterInspectorState } from './filter-inspector-state.js'
 import type { InspectorState, InspectorFilters } from '../types.js'
 import type { SerializableInspectorState } from './serialize-inspector-state.js'
-import { deserializeInspectorState } from './serialize-inspector-state.js'
+import {
+  deserializeInspectorState,
+  serializeInspectorState,
+} from './serialize-inspector-state.js'
+import { getInitialInspectorState } from '../inspector.js'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -1548,3 +1552,108 @@ describe('filterInspectorState exclude filters', () => {
     assert.ok(!result.http.meta.get['/admin/settings'])
   })
 })
+
+describe('addonServerlessIncompatible scoping', () => {
+  // Service names inside addons are scoped to that addon's namespace.
+  // 'FfmpegService' in addon A is unrelated to 'FfmpegService' in the app or
+  // another addon. The state.addonServerlessIncompatible map must NOT be
+  // merged into the global filter — it is intentionally kept separate.
+
+  test('addon serverlessIncompatible does not bleed into app-level function resolution', () => {
+    const state = createMockInspectorState()
+
+    // App function uses a service named 'FfmpegService' (e.g. its own service,
+    // unrelated to any addon's FfmpegService).
+    ;(state.functions.meta as any).getUsers.services = {
+      services: ['FfmpegService'],
+    }
+
+    // An addon declares FfmpegService as serverless-incompatible for ITS namespace.
+    ;(state as any).addonServerlessIncompatible = new Map([
+      ['ffmpeg', ['FfmpegService']],
+    ])
+
+    // Filter: only keep serverless functions. The filters object does NOT
+    // include serverlessIncompatible — that's app-level config only.
+    const filters: InspectorFilters = {
+      target: ['serverless'],
+    }
+
+    const result = filterInspectorState(state, filters, mockLogger)
+
+    // The app's getUsers function must survive — the addon's scoped
+    // serverlessIncompatible should have no effect on app-level resolution.
+    assert.ok(
+      result.http.meta.get['/api/users'],
+      'app function using same-named service as addon should not be pruned by addon scoping'
+    )
+  })
+
+  test('app-level serverlessIncompatible in filters still prunes matching app functions', () => {
+    const state = createMockInspectorState()
+
+    ;(state.functions.meta as any).getUsers.services = {
+      services: ['HeavyService'],
+    }
+    ;(state as any).addonServerlessIncompatible = new Map([
+      ['some-addon', ['HeavyService']],
+    ])
+
+    // The APP explicitly declares HeavyService incompatible via filters.
+    const filters: InspectorFilters = {
+      target: ['serverless'],
+      serverlessIncompatible: ['HeavyService'],
+    }
+
+    const result = filterInspectorState(state, filters, mockLogger)
+
+    // App explicitly opted in via filters.serverlessIncompatible → pruned.
+    assert.ok(
+      !result.http.meta.get['/api/users'],
+      'app function should be pruned when app explicitly lists service in filters.serverlessIncompatible'
+    )
+  })
+})
+
+describe('addonServerlessIncompatible serialization roundtrip', () => {
+  // Uses getInitialInspectorState to guarantee all Map fields are initialized —
+  // the lightweight mock in createMockInspectorState() omits fields like
+  // schemaLookup that serializeInspectorState needs.
+
+  test('Map serializes to Array<[string, string[]]> and back', () => {
+    const state = getInitialInspectorState('/test')
+    state.addonServerlessIncompatible = new Map([
+      ['ffmpeg', ['FfmpegService', 'FfprobeService']],
+      ['humandesign', ['HumanDesignService']],
+    ])
+
+    const serialized = serializeInspectorState(state)
+    assert.deepStrictEqual(serialized.addonServerlessIncompatible, [
+      ['ffmpeg', ['FfmpegService', 'FfprobeService']],
+      ['humandesign', ['HumanDesignService']],
+    ])
+
+    const restored = deserializeInspectorState(serialized)
+    assert.ok(restored.addonServerlessIncompatible instanceof Map)
+    assert.deepStrictEqual(restored.addonServerlessIncompatible.get('ffmpeg'), [
+      'FfmpegService',
+      'FfprobeService',
+    ])
+    assert.deepStrictEqual(
+      restored.addonServerlessIncompatible.get('humandesign'),
+      ['HumanDesignService']
+    )
+  })
+
+  test('empty Map serializes and restores correctly', () => {
+    const state = getInitialInspectorState('/test')
+    // addonServerlessIncompatible is already an empty Map from getInitialInspectorState
+
+    const serialized = serializeInspectorState(state)
+    assert.deepStrictEqual(serialized.addonServerlessIncompatible, [])
+
+    const restored = deserializeInspectorState(serialized)
+    assert.ok(restored.addonServerlessIncompatible instanceof Map)
+    assert.strictEqual(restored.addonServerlessIncompatible.size, 0)
+  })
+})

package/src/utils/get-files-and-methods.ts

@@ -19,6 +19,7 @@ export type FilesAndMethods = {
   pikkuConfigFactory: Meta
   singletonServicesFactory: Meta
   wireServicesFactory: Meta
+  serverLifecycleFactory: Meta
 }
 
 export type FilesAndMethodsErrors = Map<string, PathToNameAndType>
@@ -92,6 +93,7 @@ export const getFilesAndMethods = (
     wireServicesFactories,
     singletonServicesFactories,
     configFactories,
+    serverLifecycleFactories,
   }: InspectorState,
   {
     configFileType,
@@ -145,6 +147,10 @@ export const getFilesAndMethods = (
       wireServicesFactoryType,
       errors
     ),
+    serverLifecycleFactory: getMetaTypes(
+      'ServerLifecycle',
+      serverLifecycleFactories
+    ),
   }
 
   return { result, errors }

package/src/utils/load-addon-functions-meta.ts

@@ -199,6 +199,29 @@ export async function loadAddonFunctionsMeta(
       } catch {
         // No variables meta — that's fine
       }
+      // Load addon serverlessIncompatible service names from pikku-addon-meta.gen.json
+      try {
+        const addonMetaPath = require.resolve(
+          `${decl.package}/.pikku/console/pikku-addon-meta.gen.json`
+        )
+        const addonMetaRaw = await readFile(addonMetaPath, 'utf-8')
+        const addonMeta = JSON.parse(addonMetaRaw)
+        if (
+          Array.isArray(addonMeta.serverlessIncompatible) &&
+          addonMeta.serverlessIncompatible.length > 0
+        ) {
+          state.addonServerlessIncompatible.set(
+            namespace,
+            addonMeta.serverlessIncompatible
+          )
+          logger.debug(
+            `Addon '${namespace}' marks [${addonMeta.serverlessIncompatible.join(', ')}] as serverless-incompatible`
+          )
+        }
+      } catch {
+        // No addon meta or no serverlessIncompatible declared — that's fine
+      }
+
       // Load addon required parent services from pikku-services.gen
       try {
         const servicesGenPath = require.resolve(

package/src/utils/serialize-inspector-state.ts

@@ -46,12 +46,19 @@ export interface SerializableInspectorState {
   >
   wireServicesMeta: Array<[string, string[]]>
   addonRequiredParentServices: string[]
+  addonServerlessIncompatible: Array<[string, string[]]>
   configFactories: Array<
     [
       string,
       { variable: string; type: string | null; typePath: string | null }[],
     ]
   >
+  serverLifecycleFactories: Array<
+    [
+      string,
+      { variable: string; type: string | null; typePath: string | null }[],
+    ]
+  >
   filesAndMethods: InspectorState['filesAndMethods']
   filesAndMethodsErrors: Array<
     [
@@ -312,7 +319,13 @@ export function serializeInspectorState(
     wireServicesFactories: Array.from(state.wireServicesFactories.entries()),
     wireServicesMeta: Array.from(state.wireServicesMeta.entries()),
     addonRequiredParentServices: state.addonRequiredParentServices,
+    addonServerlessIncompatible: Array.from(
+      state.addonServerlessIncompatible.entries()
+    ),
     configFactories: Array.from(state.configFactories.entries()),
+    serverLifecycleFactories: Array.from(
+      state.serverLifecycleFactories.entries()
+    ),
     filesAndMethods: state.filesAndMethods,
     filesAndMethodsErrors: Array.from(
       state.filesAndMethodsErrors.entries()
@@ -491,7 +504,11 @@ export function deserializeInspectorState(
     wireServicesFactories: new Map(data.wireServicesFactories),
     wireServicesMeta: new Map(data.wireServicesMeta),
     addonRequiredParentServices: data.addonRequiredParentServices || [],
+    addonServerlessIncompatible: new Map(
+      data.addonServerlessIncompatible || []
+    ),
     configFactories: new Map(data.configFactories),
+    serverLifecycleFactories: new Map(data.serverLifecycleFactories),
     filesAndMethods: data.filesAndMethods,
     filesAndMethodsErrors: new Map(
       data.filesAndMethodsErrors.map(([key, entries]) => [

package/src/utils/workflow/derive-workflow-plan.test.ts

@@ -119,4 +119,22 @@ describe('deriveWorkflowPlan', () => {
     assert.equal(plan.deterministic, true)
     assert.deepEqual(plan.plannedSteps, [{ stepName: 'a' }])
   })
+
+  test('suspend steps appear in the plan with __workflow_suspend: key and sentence-case displayName', () => {
+    const plan = deriveWorkflowPlan([
+      rpc('build'),
+      { type: 'suspend', reason: 'building' } as WorkflowStepMeta,
+      rpc('publish'),
+      { type: 'suspend', reason: 'awaiting_approval' } as WorkflowStepMeta,
+      { type: 'suspend', reason: 'building-image' } as WorkflowStepMeta,
+    ])
+    assert.equal(plan.deterministic, true)
+    assert.deepEqual(plan.plannedSteps, [
+      { stepName: 'build' },
+      { stepName: '__workflow_suspend:building', displayName: 'Building' },
+      { stepName: 'publish' },
+      { stepName: '__workflow_suspend:awaiting_approval', displayName: 'Awaiting approval' },
+      { stepName: '__workflow_suspend:building-image', displayName: 'Building image' },
+    ])
+  })
 })

package/src/utils/workflow/derive-workflow-plan.ts

@@ -58,6 +58,16 @@ function containsConditional(steps: WorkflowStepMeta[]): boolean {
   return steps.some((step) => step.type === 'branch' || step.type === 'switch')
 }
 
+/**
+ * Turn an internal snake/kebab reason key into a sentence-case display label.
+ * e.g. "awaiting_approval" → "Awaiting approval", "building-image" → "Building image"
+ */
+function reasonToLabel(reason: string): string {
+  return reason
+    .replace(/[-_]/g, ' ')
+    .replace(/^(.)/, (c) => c.toUpperCase())
+}
+
 /** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
 function collectNamedSteps(steps: WorkflowStepMeta[]): WorkflowPlannedStep[] {
   const planned: WorkflowPlannedStep[] = []
@@ -68,6 +78,16 @@ function collectNamedSteps(steps: WorkflowStepMeta[]): WorkflowPlannedStep[] {
       case 'sleep':
         planned.push({ stepName: step.stepName })
         break
+      case 'suspend':
+        // Runtime stores the suspend step as `__workflow_suspend:${reason}`.
+        // We surface it in the planned ladder with a readable displayName so
+        // the UI shows it in the right position instead of appending it at the
+        // bottom as an unrecognised orphan.
+        planned.push({
+          stepName: `__workflow_suspend:${step.reason}`,
+          displayName: reasonToLabel(step.reason),
+        })
+        break
       case 'parallel':
         for (const child of step.children) {
           planned.push({ stepName: child.stepName })