@pikku/inspector 0.12.27 → 0.12.29

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/add/rpc-type-cast.test.ts

@@ -0,0 +1,123 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+
+function makeLogger() {
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  const logger: InspectorLogger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }) => criticals.push({ code, message }),
+    critical: (code, message) => criticals.push({ code, message }),
+    hasCriticalErrors: () => criticals.length > 0,
+  }
+  return { logger, criticals }
+}
+
+async function runInspect(sourceCode: string) {
+  const tmpDir = await mkdtemp(join(tmpdir(), 'pikku-rpc-cast-test-'))
+  const file = join(tmpDir, 'funcs.ts')
+  await writeFile(file, sourceCode)
+  const { logger, criticals } = makeLogger()
+  try {
+    await inspect(logger, [file], { rootDir: tmpDir })
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true })
+  }
+  return criticals
+}
+
+describe('RPC type-cast check — PKU940', () => {
+  test('flags rpc.invoke() with an as-cast on an argument', async () => {
+    const criticals = await runInspect(`
+declare const rpc: { invoke: (name: string, data: unknown) => Promise<unknown> }
+export async function doWork() {
+  return rpc.invoke('someFunction', { id: 1 } as any)
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.ok(hit, `Expected PKU940 but got: ${JSON.stringify(criticals)}`)
+  })
+
+  test('flags rpc.invoke() with an angle-bracket cast on an argument', async () => {
+    const criticals = await runInspect(`
+declare const rpc: { invoke: (name: string, data: unknown) => Promise<unknown> }
+export async function doWork() {
+  return rpc.invoke('someFunction', <any>{ id: 1 })
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.ok(hit, `Expected PKU940 but got: ${JSON.stringify(criticals)}`)
+  })
+
+  test('flags rpc.invoke() result cast with as any', async () => {
+    const criticals = await runInspect(`
+declare const rpc: { invoke: (name: string, data: unknown) => Promise<unknown> }
+export async function doWork() {
+  return (rpc.invoke('someFunction', { id: 1 }) as any)
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.ok(hit, `Expected PKU940 but got: ${JSON.stringify(criticals)}`)
+  })
+
+  test('flags rpc.invoke() result cast with as never', async () => {
+    const criticals = await runInspect(`
+declare const rpc: { invoke: (name: string, data: unknown) => Promise<unknown> }
+export async function doWork() {
+  return (rpc.invoke('someFunction', { id: 1 }) as never)
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.ok(hit, `Expected PKU940 but got: ${JSON.stringify(criticals)}`)
+  })
+
+  test('does not flag a clean rpc.invoke() call', async () => {
+    const criticals = await runInspect(`
+declare const rpc: { invoke: (name: string, data: unknown) => Promise<unknown> }
+export async function doWork() {
+  return rpc.invoke('someFunction', { id: 1 })
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.equal(
+      hit,
+      undefined,
+      `Expected no PKU940 but got: ${JSON.stringify(hit)}`
+    )
+  })
+
+  test('does not flag as-casts on unrelated calls', async () => {
+    const criticals = await runInspect(`
+declare function otherFn(data: unknown): Promise<unknown>
+export async function doWork() {
+  return otherFn({ id: 1 } as any)
+}
+`)
+    const hit = criticals.find(
+      (c) => c.code === ErrorCode.RPC_INVOCATION_TYPE_CAST
+    )
+    assert.equal(
+      hit,
+      undefined,
+      `Expected no PKU940 but got: ${JSON.stringify(hit)}`
+    )
+  })
+})

package/src/error-codes.ts

@@ -88,6 +88,8 @@ export enum ErrorCode {
   // Addon authoring errors
   ADDON_WIRING_NOT_ALLOWED = 'PKU920',
   ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = 'PKU921',
+
+  RPC_INVOCATION_TYPE_CAST = 'PKU940',
 }
 
 /**

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

@@ -263,6 +263,10 @@ export type InspectorFilters = {
   // to 'server'. Sourced from `pikku.config.json` →
   // `deploy.serverlessIncompatible`. Used only when deploy filters are set.
   serverlessIncompatible?: string[]
+  // Default deploy target for functions without an explicit `deploy` flag.
+  // Sourced from `pikku.config.json` → `deploy.defaultTarget`. Used only
+  // when deploy filters are set. Defaults to 'serverless'.
+  defaultTarget?: 'serverless' | 'server'
 }
 
 export type AddonConfig = {
@@ -377,6 +381,12 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
+  serverLifecycleFactory?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
 }
 
 export interface InspectorDiagnostic {
@@ -431,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/filter-inspector-state.ts

@@ -340,9 +340,15 @@ export function filterInspectorState(
       ? new Set(filters.excludeTarget)
       : null
     const incompatible = new Set(filters.serverlessIncompatible ?? [])
+    const defaultTarget = filters.defaultTarget ?? 'serverless'
     keptByDeploy = new Set<string>()
     for (const [funcId, funcMeta] of Object.entries(state.functions.meta)) {
-      const target = resolveDeployTarget(funcMeta as any, incompatible, funcId)
+      const target = resolveDeployTarget(
+        funcMeta as any,
+        incompatible,
+        funcId,
+        defaultTarget
+      )
       if (allowed && !allowed.has(target)) continue
       if (excluded && excluded.has(target)) continue
       keptByDeploy.add(funcId)
@@ -1062,10 +1068,10 @@ export function filterInspectorState(
   }
 
   // Step dispatch is decided purely per-function: a workflow step runs via the
-  // queue only when its function opts out of inline execution (inline: false).
-  // Such a unit needs workflowService + queueService injected even though the
-  // function itself doesn't reference them. Check the ORIGINAL graph meta
-  // (before filtering pruned it).
+  // queue only when its function is marked `workflowQueued: true`. Such a unit
+  // needs workflowService + queueService injected even though the function
+  // itself doesn't reference them. Check the ORIGINAL graph meta (before
+  // filtering pruned it).
   const survivingFuncIds = new Set(Object.keys(filteredState.functions.meta))
   const resolveFuncId = (rpcName: string): string =>
     filteredState.rpc.internalMeta[rpcName] ??
@@ -1081,8 +1087,8 @@ export function filterInspectorState(
       if (!survivingFuncIds.has(funcId) && !survivingFuncIds.has(rpcName))
         continue
       const funcMeta = (filteredState.functions.meta[funcId] ??
-        filteredState.functions.meta[rpcName]) as { inline?: boolean }
-      if (funcMeta?.inline === false) {
+        filteredState.functions.meta[rpcName]) as { workflowQueued?: boolean }
+      if (funcMeta?.workflowQueued === true) {
         filteredState.serviceAggregation.requiredServices.add('workflowService')
         filteredState.serviceAggregation.requiredServices.add('queueService')
       }

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/post-process.ts

@@ -290,10 +290,17 @@ export function aggregateRequiredServices(
       }
     }
 
-    // Per-step queues
+    // Per-step queues — only for steps explicitly marked workflowQueued: true
     for (const node of Object.values(graph.nodes)) {
       if (!('rpcName' in node) || !node.rpcName) continue
       const rpcName = node.rpcName as string
+      const funcId =
+        state.rpc?.internalMeta?.[rpcName] ??
+        state.rpc?.exposedMeta?.[rpcName] ??
+        rpcName
+      const funcMeta = (state.functions.meta[funcId] ??
+        state.functions.meta[rpcName]) as { workflowQueued?: boolean }
+      if (funcMeta?.workflowQueued !== true) continue
       const stepQueueName = `wf-step-${toKebab(rpcName)}`
       if (!state.queueWorkers.meta[stepQueueName]) {
         state.queueWorkers.meta[stepQueueName] = {

package/src/utils/resolve-deploy-target.test.ts

@@ -102,4 +102,34 @@ describe('resolveDeployTarget', () => {
       'server'
     )
   })
+
+  test('defaultTarget: server overrides the serverless default', () => {
+    assert.strictEqual(
+      resolveDeployTarget({}, new Set(), '<unknown>', 'server'),
+      'server'
+    )
+  })
+
+  test('explicit deploy flag wins over defaultTarget', () => {
+    assert.strictEqual(
+      resolveDeployTarget({ deploy: 'serverless' }, new Set(), 'fn', 'server'),
+      'serverless'
+    )
+    assert.strictEqual(
+      resolveDeployTarget({ deploy: 'server' }, new Set(), 'fn', 'serverless'),
+      'server'
+    )
+  })
+
+  test('serverlessIncompatible still forces server regardless of defaultTarget', () => {
+    assert.strictEqual(
+      resolveDeployTarget(
+        { services: { services: ['metaService'] } as any },
+        new Set(['metaService']),
+        'fn',
+        'serverless'
+      ),
+      'server'
+    )
+  })
 })

package/src/utils/resolve-deploy-target.ts

@@ -29,7 +29,8 @@ export class IncompatibleDeployTargetError extends Error {
  *      - throw if the function explicitly declares `deploy: 'serverless'`
  *      - otherwise target is 'server'
  *   2. Explicit `funcMeta.deploy: 'serverless' | 'server'`
- *   3. Default 'serverless'
+ *   3. `defaultTarget` (sourced from `pikku.config.json` →
+ *      `deploy.defaultTarget`, falling back to 'serverless')
  *
  * Used both by the per-unit deploy analyzer (when bucketing functions
  * into deployment units) and by `filterInspectorState` (when
@@ -39,7 +40,8 @@ export class IncompatibleDeployTargetError extends Error {
 export function resolveDeployTarget(
   funcMeta: Pick<FunctionMeta, 'deploy' | 'services'>,
   serverlessIncompatible: Set<string>,
-  functionName = '<unknown>'
+  functionName = '<unknown>',
+  defaultTarget: 'serverless' | 'server' = 'serverless'
 ): 'serverless' | 'server' {
   // Service compatibility wins over the explicit flag — a serverless
   // bundle of a function that needs (e.g.) node:fs would crash at runtime.
@@ -59,5 +61,5 @@ export function resolveDeployTarget(
 
   if (funcMeta.deploy === 'server') return 'server'
   if (funcMeta.deploy === 'serverless') return 'serverless'
-  return 'serverless'
+  return defaultTarget
 }

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 })

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -7,6 +7,7 @@ import type {
   ParallelGroupStepMeta,
   FanoutStepMeta,
   CancelStepMeta,
+  SuspendStepMeta,
   SetStepMeta,
   SwitchStepMeta,
   SwitchCaseMeta,
@@ -21,6 +22,7 @@ import type {
 import {
   isWorkflowDoCall,
   isWorkflowSleepCall,
+  isWorkflowSuspendCall,
   isThrowCancelException,
   extractCancelReason,
   isParallelFanout,
@@ -512,6 +514,10 @@ function extractExpressionStatement(
       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)
@@ -698,6 +704,31 @@ function extractSleepStep(
   }
 }
 
+/**
+ * Extract suspend step from workflow.suspend() call
+ */
+function extractSuspendStep(
+  call: ts.CallExpression,
+  context: ExtractionContext
+): SuspendStepMeta | null {
+  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
  */