@pikku/inspector 0.12.42 → 0.12.44

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -91,6 +91,7 @@ function convertStepToNode(
       const node: FunctionNode = {
         nodeId,
         rpcName: step.rpcName,
+        stepName: step.stepName,
         next: nextNodeId,
       }
       if (step.actor) {
@@ -116,9 +117,24 @@ function convertStepToNode(
       if (step.options) {
         node.options = {
           retries: step.options.retries,
-          retryDelay: step.options.retryDelay?.toString(),
+          retryDelay: step.options.retryDelay,
         }
       }
+      // An onError handler is written as an rpc name, but the graph routes to
+      // node ids — materialise a node for it so the console has something to
+      // draw the error edge to, exactly as in a hand-authored graph.
+      if (step.options?.onError) {
+        const handlerId = `${nodeId}_onError`
+        node.onError = handlerId
+        return [
+          node,
+          {
+            nodeId: handlerId,
+            rpcName: step.options.onError,
+            stepName: `${step.stepName} (on error)`,
+          } satisfies FunctionNode,
+        ]
+      }
       return [node]
     }
 
@@ -126,7 +142,37 @@ function convertStepToNode(
       const node: FlowNode = {
         nodeId,
         flow: 'sleep',
+        stepName: step.stepName,
         duration: step.duration,
+        expression: step.expression,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'suspend': {
+      // A suspend yields no value, but it must still be a node: the previous
+      // step's `next` points at it, so omitting it dead-ends traversal and
+      // silently deletes every step that follows.
+      const node: FlowNode = {
+        nodeId,
+        flow: 'suspend',
+        reason: step.reason,
+        next: nextNodeId,
+      }
+      return [node]
+    }
+
+    case 'approval': {
+      // Unlike `suspend` — which has no output and so is deliberately absent
+      // from the graph — an approval yields a value a later step can reference,
+      // so it must be a real node for $ref resolution and graphHash to see it.
+      const node: FlowNode = {
+        nodeId,
+        flow: 'approval',
+        reason: step.reason,
+        outputVar: step.outputVar,
+        expiry: step.expiry,
         next: nextNodeId,
       }
       return [node]
@@ -199,16 +245,32 @@ function convertStepToNode(
         entry: string
       }> = []
 
+      // A case with no statements falls through to the next one. Dropping it
+      // would lose the value entirely, so it is held until an entry exists.
+      let fallingThrough: Array<{ value?: unknown; expression?: string }> = []
+
       for (let i = 0; i < step.cases.length; i++) {
         const caseSteps = convertStepsToNodes(
           step.cases[i].steps,
           `${nodeId}_case${i}`
         )
-        if (caseSteps.length > 0) {
+        if (caseSteps.length === 0) {
+          fallingThrough.push({
+            value: step.cases[i].value,
+            expression: step.cases[i].expression,
+          })
+          continue
+        }
+        {
+          const entry = caseSteps[0].nodeId
+          for (const pending of fallingThrough) {
+            cases.push({ ...pending, entry })
+          }
+          fallingThrough = []
           cases.push({
             value: step.cases[i].value,
             expression: step.cases[i].expression,
-            entry: caseSteps[0].nodeId,
+            entry,
           })
           // Link last case node to next (unless terminal flow)
           if (nextNodeId) {
@@ -238,6 +300,14 @@ function convertStepToNode(
         }
       }
 
+      // Cases falling through past the last one land in default, or exit.
+      const trailingEntry = defaultEntry ?? nextNodeId
+      if (trailingEntry) {
+        for (const pending of fallingThrough) {
+          cases.push({ ...pending, entry: trailingEntry })
+        }
+      }
+
       const node: FlowNode = {
         nodeId,
         flow: 'switch',
@@ -279,13 +349,13 @@ function convertStepToNode(
     }
 
     case 'fanout': {
-      // Convert child step
-      const childNodes = convertStepToNode(
-        step.child,
-        0,
-        [step.child],
-        `${nodeId}_item`
-      )
+      // Convert the per-iteration body into a `next`-chained sequence
+      const childNodes: SerializedGraphNode[] = []
+      for (let i = 0; i < step.body.length; i++) {
+        childNodes.push(
+          ...convertStepToNode(step.body[i], i, step.body, `${nodeId}_item`)
+        )
+      }
 
       const node: FlowNode = {
         nodeId,
@@ -333,6 +403,7 @@ function convertStepToNode(
         nodeId,
         flow: 'return',
         outputs: step.outputs,
+        spread: step.spread,
       }
       return [node]
     }
@@ -352,6 +423,7 @@ function convertStepToNode(
         flow: 'set',
         variable: step.variable,
         value: step.value,
+        expression: step.expression,
         next: nextNodeId,
       }
       return [node]

package/src/utils/workflow/graph/fanout-node-identity.test.ts

@@ -0,0 +1,105 @@
+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 type { InspectorLogger } from '../../../types.js'
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const notify = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'n' }),",
+  '})',
+].join('\n')
+
+async function nodesFor(body: string): Promise<Record<string, any>> {
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  } as unknown as InspectorLogger
+
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-fid-'))
+  const stepFile = join(rootDir, 'w.steps.ts')
+  const wfFile = join(rootDir, 'w.workflow.ts')
+  await writeFile(stepFile, STEP_FILE)
+  await writeFile(
+    wfFile,
+    [
+      "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+      'export const wf = pikkuWorkflowFunc(async (_, data: any, { workflow }) => {',
+      body,
+      '})',
+    ].join('\n')
+  )
+  try {
+    const state: any = await inspect(logger, [stepFile, wfFile], { rootDir })
+    const gm = state.workflows.graphMeta
+    const graph = (
+      gm instanceof Map ? [...gm.values()] : Object.values(gm)
+    )[0] as any
+    return graph?.nodes ?? {}
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('fanout node identity — a body step must not overwrite its own loop', () => {
+  test('the fanout node survives alongside its named body step', async () => {
+    const nodes = await nodesFor(
+      [
+        '  await Promise.all(',
+        '    data.users.map(async (u: any) => {',
+        "      await workflow.do('Notify', 'notify', { id: u.id })",
+        '    })',
+        '  )',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const fanout = Object.values(nodes).find(
+      (n: any) => n.flow === 'fanout'
+    ) as any
+    assert.ok(
+      fanout,
+      `the loop must be in the graph — without it the workflow renders as a single call, got: ${JSON.stringify(nodes)}`
+    )
+    assert.ok(
+      fanout.childEntry && nodes[fanout.childEntry],
+      'the fanout must point at a body entry node that exists'
+    )
+    assert.notEqual(
+      fanout.nodeId,
+      fanout.childEntry,
+      'a fanout and its body entry must not share a node id'
+    )
+    assert.equal((nodes[fanout.childEntry] as any).rpcName, 'notify')
+  })
+
+  test('the step following a fanout is still reachable', async () => {
+    const nodes = await nodesFor(
+      [
+        '  await Promise.all(',
+        '    data.users.map(async (u: any) => {',
+        "      await workflow.do('Notify', 'notify', { id: u.id })",
+        '    })',
+        '  )',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const fanout = Object.values(nodes).find(
+      (n: any) => n.flow === 'fanout'
+    ) as any
+    assert.ok(fanout, 'a fanout node should exist')
+    assert.ok(
+      fanout.next && nodes[fanout.next],
+      `the return after the loop must stay reachable, got: ${JSON.stringify(nodes)}`
+    )
+  })
+})

package/src/utils/workflow/graph/finalize-workflows.test.ts

@@ -0,0 +1,50 @@
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { computeGraphHash } from './finalize-workflows.js'
+import type {
+  SerializedWorkflowGraph,
+  FunctionNode,
+} from './workflow-graph.types.js'
+
+function graph(
+  overrides: Partial<SerializedWorkflowGraph> = {},
+  nodeOverrides: Partial<FunctionNode> = {}
+): SerializedWorkflowGraph {
+  const node: FunctionNode = {
+    nodeId: 'a',
+    rpcName: 'doThing',
+    input: { x: { $ref: 'trigger', path: 'x' } },
+    next: 'b',
+    ...nodeOverrides,
+  }
+  return {
+    name: 'wf',
+    pikkuFuncId: 'wf',
+    source: 'graph',
+    nodes: { a: node, b: { nodeId: 'b', rpcName: 'finish' } },
+    entryNodeIds: ['a'],
+    ...overrides,
+  }
+}
+
+test('computeGraphHash: node-level notes do not change the hash', () => {
+  const without = computeGraphHash(graph())
+  const withNote = computeGraphHash(
+    graph({}, { notes: 'imported node "Do Thing"' })
+  )
+  assert.strictEqual(withNote, without)
+})
+
+test('computeGraphHash: graph-level notes do not change the hash', () => {
+  const without = computeGraphHash(graph())
+  const withNotes = computeGraphHash(
+    graph({ notes: ['sticky note one', 'sticky note two'] })
+  )
+  assert.strictEqual(withNotes, without)
+})
+
+test('computeGraphHash: a topology change DOES change the hash', () => {
+  const base = computeGraphHash(graph())
+  const changed = computeGraphHash(graph({}, { next: 'c' }))
+  assert.notStrictEqual(changed, base)
+})

package/src/utils/workflow/graph/finalize-workflows.ts

@@ -102,12 +102,23 @@ function computeStepHashes(
   }
 }
 
-function computeGraphHash(graph: SerializedWorkflowGraph): string {
+/**
+ * Hash of graph topology only. `notes` (node- and graph-level) is deliberately
+ * excluded so editing documentation never changes the hash / marks the workflow
+ * as a new version.
+ */
+export function computeGraphHash(graph: SerializedWorkflowGraph): string {
+  const nodesForHash = Object.fromEntries(
+    Object.entries(graph.nodes).map(([nodeId, node]) => {
+      const { notes: _notes, ...rest } = node as { notes?: string }
+      return [nodeId, rest]
+    })
+  )
   return hashString(
     canonicalJSON({
       source: graph.source,
       context: graph.context,
-      nodes: graph.nodes,
+      nodes: nodesForHash,
       entryNodeIds: graph.entryNodeIds,
     }),
     12

package/src/utils/workflow/graph/serialize-workflow-graph.ts

@@ -89,12 +89,14 @@ export function serializeWorkflowGraph(
         input?: (ref: any) => Record<string, unknown>
         next?: string | string[] | Record<string, string | string[]>
         onError?: string | string[]
+        notes?: string
       }
     >
   },
   options?: {
     description?: string
     tags?: string[]
+    notes?: string[]
   }
 ): SerializedWorkflowGraph {
   const nodes: Record<string, SerializedGraphNode> = {}
@@ -149,6 +151,9 @@ export function serializeWorkflowGraph(
       next: serializeNext(node.next),
       onError: node.onError,
     }
+    if (node.notes !== undefined) {
+      funcNode.notes = node.notes
+    }
     nodes[nodeId] = funcNode
 
     // Entry nodes have no incoming edges
@@ -163,6 +168,7 @@ export function serializeWorkflowGraph(
     source: 'graph' as const,
     description: options?.description,
     tags: options?.tags,
+    notes: options?.notes,
     nodes,
     entryNodeIds,
   }

package/src/utils/workflow/graph/workflow-graph.types.ts

@@ -76,6 +76,9 @@ export type SerializedNext =
       /** Default target if no conditions match */
       default?: string | string[]
     }
+  // Key-based branching: the running node picks a key via `graph.branch(key)`,
+  // routing to `next[key]`. Keys are branch/output identifiers, not predicates.
+  | Record<string, string | string[]>
 
 /**
  * Node execution options
@@ -83,8 +86,8 @@ export type SerializedNext =
 export interface NodeOptions {
   /** Number of retry attempts on failure */
   retries?: number
-  /** Delay between retries (e.g., '1s', '5s') */
-  retryDelay?: string
+  /** Delay between retries (e.g., '1s', '5s', or a number of milliseconds) */
+  retryDelay?: string | number
   /** Timeout for node execution (e.g., '30s', '5m') */
   timeout?: string
 }
@@ -94,6 +97,8 @@ export interface NodeOptions {
  */
 export type FlowType =
   | 'sleep'
+  | 'suspend'
+  | 'approval'
   | 'branch'
   | 'parallel'
   | 'fanout'
@@ -128,6 +133,8 @@ interface BaseNode {
   onError?: string | string[]
   /** Execution options */
   options?: NodeOptions
+  /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+  notes?: string
 }
 
 /**
@@ -209,6 +216,8 @@ export interface SerializedWorkflowGraph {
   context?: WorkflowContext
   /** Serialized nodes */
   nodes: Record<string, SerializedGraphNode>
+  /** Graph-level free-text notes (e.g. imported sticky notes). Non-semantic — excluded from graphHash. */
+  notes?: string[]
   /** Entry node(s) - first nodes to execute */
   entryNodeIds: string[]
   /** Hash of graph topology (nodes, edges, input mappings) */

package/src/visit.ts

@@ -20,12 +20,14 @@ import { addChannel } from './add/add-channel.js'
 import { addGateway } from './add/add-gateway.js'
 import { addRPCInvocations } from './add/add-rpc-invocations.js'
 import { addWireAddon } from './add/add-wire-addon.js'
+import { addWireRemoteAddon } from './add/add-wire-remote-addon.js'
 import { addMiddleware } from './add/add-middleware.js'
 import { addPermission } from './add/add-permission.js'
 import { addCLI, addCLIRenderers } from './add/add-cli.js'
 import { addAuth } from './add/add-auth.js'
 import { addSecret } from './add/add-secret.js'
 import { addCredential } from './add/add-credential.js'
+import { addScope } from './add/add-scope.js'
 import { addVariable } from './add/add-variable.js'
 import { addWorkflowGraph } from './add/add-workflow-graph.js'
 import { addAIAgent } from './add/add-ai-agent.js'
@@ -96,6 +98,7 @@ export const visitSetup = (
 
   addRPCInvocations(node, state, logger)
   addWireAddon(node, state, logger)
+  addWireRemoteAddon(node, state, logger)
   addMiddleware(logger, node, checker, state, options)
   addPermission(logger, node, checker, state, options)
   addApprovalDescription(logger, node, checker, state, options)
@@ -147,6 +150,7 @@ export const visitRoutes = (
   addAuth(logger, node, checker, state, nextOptions)
   addSecret(logger, node, checker, state, nextOptions)
   addCredential(logger, node, checker, state, nextOptions)
+  addScope(logger, node, checker, state, nextOptions)
   addVariable(logger, node, checker, state, nextOptions)
 
   addHTTPRoute(logger, node, checker, state, nextOptions)