@pikku/inspector 0.12.41 → 0.12.43

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

@@ -63,9 +63,7 @@ function containsConditional(steps: WorkflowStepMeta[]): boolean {
  * e.g. "awaiting_approval" → "Awaiting approval", "building-image" → "Building image"
  */
 function reasonToLabel(reason: string): string {
-  return reason
-    .replace(/[-_]/g, ' ')
-    .replace(/^(.)/, (c) => c.toUpperCase())
+  return reason.replace(/[-_]/g, ' ').replace(/^(.)/, (c) => c.toUpperCase())
 }
 
 /** Flatten named steps (rpc/inline/sleep/parallel children) in source order. */
@@ -88,13 +86,22 @@ function collectNamedSteps(steps: WorkflowStepMeta[]): WorkflowPlannedStep[] {
           displayName: reasonToLabel(step.reason),
         })
         break
+      case 'approval':
+        // Same as suspend, but namespaced `__workflow_approval:` to match the
+        // runtime's separate step key.
+        planned.push({
+          stepName: `__workflow_approval:${step.reason}`,
+          displayName: reasonToLabel(step.reason),
+        })
+        break
       case 'parallel':
         for (const child of step.children) {
           planned.push({ stepName: child.stepName })
         }
         break
       case 'branch':
-        for (const b of step.branches) planned.push(...collectNamedSteps(b.steps))
+        for (const b of step.branches)
+          planned.push(...collectNamedSteps(b.steps))
         if (step.elseSteps) planned.push(...collectNamedSteps(step.elseSteps))
         break
       case 'switch':

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

@@ -8,6 +8,7 @@ import type {
   FanoutStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  ApprovalStepMeta,
   SetStepMeta,
   SwitchStepMeta,
   SwitchCaseMeta,
@@ -25,6 +26,7 @@ import {
   extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
+  isWorkflowApprovalCall,
   isThrowCancelException,
   extractCancelReason,
   isParallelFanout,
@@ -520,6 +522,22 @@ function extractExpressionStatement(
       return extractSuspendStep(call, context)
     }
 
+    if (isWorkflowApprovalCall(call, context.checker)) {
+      const step = extractApprovalStep(call, context, outputVar)
+
+      // Unlike suspend, an approval yields a value, so a downstream step can
+      // reference it — track the binding the same way workflow.do() does.
+      if (outputVar && step) {
+        const type = context.checker.getTypeAtLocation(expr)
+        context.outputVars.set(outputVar, { type, node: expr })
+        if (isArrayType(type, context.checker)) {
+          context.arrayVars.add(outputVar)
+        }
+      }
+
+      return step
+    }
+
     // Check for parallel group or fanout
     if (isParallelFanout(call)) {
       return extractParallelFanout(call, context)
@@ -738,6 +756,54 @@ function extractSuspendStep(
   }
 }
 
+/**
+ * Extract approval step from workflow.approval() call
+ */
+function extractApprovalStep(
+  call: ts.CallExpression,
+  context: ExtractionContext,
+  outputVar?: string
+): ApprovalStepMeta | null {
+  const args = call.arguments
+  if (args.length < 1) return null
+
+  try {
+    const reason = extractStringLiteral(args[0], context.checker)
+    const step: ApprovalStepMeta = {
+      type: 'approval',
+      reason,
+    }
+    if (outputVar) {
+      step.outputVar = outputVar
+    }
+    // The `schema` option is a runtime value validated inside the workflow body,
+    // so it is deliberately not serialized here — only `expiry`, which the graph
+    // and planned-step ladder need in order to describe the gate.
+    const options = args[1]
+    if (options && ts.isObjectLiteralExpression(options)) {
+      for (const prop of options.properties) {
+        if (
+          ts.isPropertyAssignment(prop) &&
+          prop.name.getText() === 'expiry' &&
+          (ts.isStringLiteral(prop.initializer) ||
+            ts.isNumericLiteral(prop.initializer))
+        ) {
+          step.expiry = ts.isNumericLiteral(prop.initializer)
+            ? Number(prop.initializer.text)
+            : prop.initializer.text
+        }
+      }
+    }
+    return step
+  } catch (error) {
+    context.errors.push({
+      message: `Failed to extract approval step: ${error instanceof Error ? error.message : String(error)}`,
+      node: call,
+    })
+    return null
+  }
+}
+
 /**
  * Extract cancel step from throw WorkflowCancelledException statement
  */

package/src/utils/workflow/dsl/patterns.ts

@@ -4,6 +4,18 @@ import * as ts from 'typescript'
  * Pattern detection helpers for DSL workflow extraction
  */
 
+/**
+ * The wire object handed to a DSL func is named `workflow` in a workflow and
+ * `scenario` in a scenario — both carry the same `do`/`sleep`/`suspend` DSL, so
+ * step extraction accepts either identifier.
+ */
+export function isWorkflowWireIdentifier(expr: ts.Expression): boolean {
+  return (
+    ts.isIdentifier(expr) &&
+    (expr.text === 'workflow' || expr.text === 'scenario')
+  )
+}
+
 /**
  * Check if a call expression is workflow.do() or workflow.expectEventually()
  * (both are RPC steps; expectEventually is the polling variant used by scenarios)
@@ -20,8 +32,7 @@ export function isWorkflowDoCall(
   return (
     (propAccess.name.text === 'do' ||
       propAccess.name.text === 'expectEventually') &&
-    ts.isIdentifier(propAccess.expression) &&
-    propAccess.expression.text === 'workflow'
+    isWorkflowWireIdentifier(propAccess.expression)
   )
 }
 
@@ -34,8 +45,7 @@ export function isWorkflowExpectEventuallyCall(
   return (
     ts.isPropertyAccessExpression(node.expression) &&
     node.expression.name.text === 'expectEventually' &&
-    ts.isIdentifier(node.expression.expression) &&
-    node.expression.expression.text === 'workflow'
+    isWorkflowWireIdentifier(node.expression.expression)
   )
 }
 
@@ -83,8 +93,7 @@ export function isWorkflowSleepCall(
   const propAccess = node.expression
   return (
     propAccess.name.text === 'sleep' &&
-    ts.isIdentifier(propAccess.expression) &&
-    propAccess.expression.text === 'workflow'
+    isWorkflowWireIdentifier(propAccess.expression)
   )
 }
 
@@ -102,8 +111,25 @@ export function isWorkflowSuspendCall(
   const propAccess = node.expression
   return (
     propAccess.name.text === 'suspend' &&
-    ts.isIdentifier(propAccess.expression) &&
-    propAccess.expression.text === 'workflow'
+    isWorkflowWireIdentifier(propAccess.expression)
+  )
+}
+
+/**
+ * Check if a call expression is workflow.approval()
+ */
+export function isWorkflowApprovalCall(
+  node: ts.CallExpression,
+  _checker: ts.TypeChecker
+): boolean {
+  if (!ts.isPropertyAccessExpression(node.expression)) {
+    return false
+  }
+
+  const propAccess = node.expression
+  return (
+    propAccess.name.text === 'approval' &&
+    isWorkflowWireIdentifier(propAccess.expression)
   )
 }
 

package/src/utils/workflow/dsl/validation.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript'
+import { isWorkflowWireIdentifier } from './patterns.js'
 
 /**
  * Validation rules for DSL workflows
@@ -78,8 +79,7 @@ export function validateNoDisallowedPatterns(
         const propAccess = node.expression
         if (
           propAccess.name.text === 'do' &&
-          ts.isIdentifier(propAccess.expression) &&
-          propAccess.expression.text === 'workflow'
+          isWorkflowWireIdentifier(propAccess.expression)
         ) {
           const secondArg = node.arguments[1]
           if (
@@ -154,8 +154,7 @@ export function validateAwaitedCalls(node: ts.Node): ValidationError[] {
         const propAccess = node.expression
         if (
           (propAccess.name.text === 'do' || propAccess.name.text === 'sleep') &&
-          ts.isIdentifier(propAccess.expression) &&
-          propAccess.expression.text === 'workflow'
+          isWorkflowWireIdentifier(propAccess.expression)
         ) {
           if (!parentIsAwait && !insidePromiseAll) {
             errors.push({

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

@@ -132,6 +132,21 @@ function convertStepToNode(
       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]
+    }
+
     case 'inline': {
       const node: FlowNode = {
         nodeId,

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
@@ -94,6 +97,7 @@ export interface NodeOptions {
  */
 export type FlowType =
   | 'sleep'
+  | 'approval'
   | 'branch'
   | 'parallel'
   | 'fanout'
@@ -128,6 +132,8 @@ interface BaseNode {
   onError?: string | string[]
   /** Execution options */
   options?: NodeOptions
+  /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+  notes?: string
 }
 
 /**
@@ -209,6 +215,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)