@pikku/core 0.12.2 → 0.12.3

package/src/wirings/workflow/graph/graph-validation.test.ts

@@ -0,0 +1,170 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  computeEntryNodeIds,
+  validateWorkflowWiring,
+  generateMermaidDiagram,
+} from './graph-validation.js'
+
+describe('computeEntryNodeIds', () => {
+  it('returns nodes not referenced by any other node', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: 'middle' },
+      middle: { rpcName: 'b', next: 'end' },
+      end: { rpcName: 'c' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('returns multiple entry nodes for parallel starts', () => {
+    const nodes = {
+      a: { rpcName: 'x' },
+      b: { rpcName: 'y' },
+      c: { rpcName: 'z', next: 'a' },
+    }
+    const entries = computeEntryNodeIds(nodes)
+    assert.ok(entries.includes('b'))
+    assert.ok(entries.includes('c'))
+    assert.ok(!entries.includes('a'))
+  })
+
+  it('returns empty for fully circular graph', () => {
+    const nodes = {
+      a: { rpcName: 'x', next: 'b' },
+      b: { rpcName: 'y', next: 'a' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), [])
+  })
+
+  it('handles onError references', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: 'ok', onError: 'err' },
+      ok: { rpcName: 'b' },
+      err: { rpcName: 'c' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('handles branching next as object', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: { yes: 'b', no: 'c' } },
+      b: { rpcName: 'x' },
+      c: { rpcName: 'y' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+
+  it('handles parallel next as array', () => {
+    const nodes = {
+      start: { rpcName: 'a', next: ['b', 'c'] },
+      b: { rpcName: 'x' },
+      c: { rpcName: 'y' },
+    }
+    assert.deepEqual(computeEntryNodeIds(nodes), ['start'])
+  })
+})
+
+describe('validateWorkflowWiring', () => {
+  const tools = ['toolA', 'toolB', 'toolC']
+
+  it('returns no errors for a valid workflow', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
+      step2: { rpcName: 'toolB', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+
+  it('errors on missing rpcName', () => {
+    const nodes = {
+      step1: { input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("missing 'rpcName'")))
+  })
+
+  it('errors on unknown tool', () => {
+    const nodes = {
+      step1: { rpcName: 'unknownTool', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes('unknown tool')))
+  })
+
+  it('errors on next referencing unknown node', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', next: 'nonexistent' },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'nonexistent'")))
+  })
+
+  it('errors on onError referencing unknown node', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', onError: 'missing' },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
+  })
+
+  it('errors on input referencing unknown node', () => {
+    const nodes = {
+      step1: {
+        rpcName: 'toolA',
+        input: { field: { $ref: 'missing', path: 'x' } },
+      },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.ok(errors.some((e) => e.includes("unknown node 'missing'")))
+  })
+
+  it('allows trigger refs without errors', () => {
+    const nodes = {
+      step1: {
+        rpcName: 'toolA',
+        input: { field: { $ref: 'trigger', path: 'title' } },
+        next: 'step2',
+      },
+      step2: { rpcName: 'toolB', input: {} },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+
+  it('allows valid node-to-node refs', () => {
+    const nodes = {
+      step1: { rpcName: 'toolA', input: {}, next: 'step2' },
+      step2: {
+        rpcName: 'toolB',
+        input: { data: { $ref: 'step1', path: 'result' } },
+      },
+    }
+    const errors = validateWorkflowWiring(nodes, tools)
+    assert.deepEqual(errors, [])
+  })
+})
+
+describe('generateMermaidDiagram', () => {
+  it('generates valid mermaid output', () => {
+    const nodes = {
+      start: { rpcName: 'toolA', next: 'end' },
+      end: { rpcName: 'toolB' },
+    }
+    const result = generateMermaidDiagram('test-wf', nodes, ['start'])
+    assert.ok(result.includes('graph TD'))
+    assert.ok(result.includes('start([toolA])'))
+    assert.ok(result.includes('end[toolB]'))
+    assert.ok(result.includes('start --> end'))
+  })
+
+  it('shows error edges with dotted lines', () => {
+    const nodes = {
+      start: { rpcName: 'toolA', onError: 'handler' },
+      handler: { rpcName: 'toolB' },
+    }
+    const result = generateMermaidDiagram('test-wf', nodes, ['start'])
+    assert.ok(result.includes('start -.->|error| handler'))
+  })
+})

package/src/wirings/workflow/graph/graph-validation.ts

@@ -0,0 +1,237 @@
+import { pikkuState } from '../../../pikku-state.js'
+import { resolveNamespace } from '../../rpc/rpc-runner.js'
+
+function normalizeTargets(value: unknown): string[] {
+  if (!value) return []
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.filter((v) => typeof v === 'string')
+  if (typeof value === 'object') {
+    const targets: string[] = []
+    for (const v of Object.values(value as Record<string, unknown>)) {
+      targets.push(...normalizeTargets(v))
+    }
+    return targets
+  }
+  return []
+}
+
+function collectRefs(value: unknown, refs: Set<string>): void {
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    '$ref' in value &&
+    typeof (value as any).$ref === 'string'
+  ) {
+    refs.add((value as any).$ref)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectRefs(item, refs)
+    return
+  }
+  if (typeof value === 'object' && value !== null) {
+    for (const v of Object.values(value)) collectRefs(v, refs)
+  }
+}
+
+function resolveToolMeta(toolName: string): {
+  fnMeta: any
+  schemas: Map<string, any>
+} | null {
+  const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
+
+  if (resolved) {
+    const fnMeta = pikkuState(resolved.package, 'function', 'meta')[
+      resolved.function
+    ]
+    const schemas = pikkuState(resolved.package, 'misc', 'schemas')
+    return fnMeta ? { fnMeta, schemas } : null
+  }
+
+  const rpcMeta = pikkuState(null, 'rpc', 'meta')
+  const pikkuFuncId = rpcMeta[toolName]
+  if (!pikkuFuncId) return null
+
+  const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
+  const schemas = pikkuState(null, 'misc', 'schemas')
+  return fnMeta ? { fnMeta, schemas } : null
+}
+
+export function computeEntryNodeIds(nodes: Record<string, any>): string[] {
+  const referenced = new Set<string>()
+  for (const node of Object.values(nodes)) {
+    if (node.next) {
+      for (const target of normalizeTargets(node.next)) {
+        referenced.add(target)
+      }
+    }
+    if (node.onError) {
+      for (const target of normalizeTargets(node.onError)) {
+        referenced.add(target)
+      }
+    }
+  }
+  return Object.keys(nodes).filter((id) => !referenced.has(id))
+}
+
+export function validateWorkflowWiring(
+  nodes: Record<string, any>,
+  toolNames: string[]
+): string[] {
+  const errors: string[] = []
+  const nodeIds = new Set(Object.keys(nodes))
+  const toolSet = new Set(toolNames)
+
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    if (!node.rpcName) {
+      errors.push(`Node '${nodeId}' is missing 'rpcName'`)
+      continue
+    }
+
+    if (!toolSet.has(node.rpcName)) {
+      errors.push(
+        `Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`
+      )
+      continue
+    }
+
+    const nextTargets = normalizeTargets(node.next)
+    for (const target of nextTargets) {
+      if (!nodeIds.has(target)) {
+        errors.push(
+          `Node '${nodeId}' routes to unknown node '${target}' in 'next'`
+        )
+      }
+    }
+
+    const errorTargets = normalizeTargets(node.onError)
+    for (const target of errorTargets) {
+      if (!nodeIds.has(target)) {
+        errors.push(
+          `Node '${nodeId}' routes to unknown node '${target}' in 'onError'`
+        )
+      }
+    }
+
+    if (!node.input) continue
+
+    const refs = new Set<string>()
+    collectRefs(node.input, refs)
+
+    for (const ref of refs) {
+      if (ref === 'trigger' || ref === '$item') {
+        const targetMeta = resolveToolMeta(node.rpcName)
+        if (targetMeta?.fnMeta?.inputSchemaName) {
+          const targetSchema = targetMeta.schemas.get(
+            targetMeta.fnMeta.inputSchemaName
+          )
+          if (targetSchema?.properties) {
+            for (const [field, fieldValue] of Object.entries(
+              node.input as Record<string, any>
+            )) {
+              if (
+                typeof fieldValue === 'object' &&
+                fieldValue !== null &&
+                fieldValue.$ref === ref &&
+                !fieldValue.path
+              ) {
+                const targetType = targetSchema.properties[field]?.type
+                if (targetType && targetType !== 'object') {
+                  errors.push(
+                    `Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`
+                  )
+                }
+              }
+            }
+          }
+        }
+        continue
+      }
+
+      if (!nodeIds.has(ref)) {
+        errors.push(
+          `Node '${nodeId}' references unknown node '${ref}' in input`
+        )
+        continue
+      }
+
+      const sourceNode = nodes[ref]
+      if (!sourceNode?.rpcName) continue
+
+      const sourceMeta = resolveToolMeta(sourceNode.rpcName)
+      if (!sourceMeta?.fnMeta?.outputSchemaName) continue
+
+      const sourceSchema = sourceMeta.schemas.get(
+        sourceMeta.fnMeta.outputSchemaName
+      )
+      if (!sourceSchema?.properties) continue
+
+      for (const [field, fieldValue] of Object.entries(
+        node.input as Record<string, any>
+      )) {
+        if (
+          typeof fieldValue === 'object' &&
+          fieldValue !== null &&
+          fieldValue.$ref === ref &&
+          fieldValue.path
+        ) {
+          const pathRoot = fieldValue.path.split('.')[0]
+          if (
+            sourceSchema.properties &&
+            !(pathRoot in sourceSchema.properties)
+          ) {
+            errors.push(
+              `Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`
+            )
+            continue
+          }
+
+          const targetMeta = resolveToolMeta(node.rpcName)
+          if (!targetMeta?.fnMeta?.inputSchemaName) continue
+          const targetSchema = targetMeta.schemas.get(
+            targetMeta.fnMeta.inputSchemaName
+          )
+          if (!targetSchema?.properties?.[field]) continue
+
+          const sourceType = sourceSchema.properties[pathRoot]?.type
+          const targetType = targetSchema.properties[field].type
+          if (sourceType && targetType && sourceType !== targetType) {
+            errors.push(
+              `Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`
+            )
+          }
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+export function generateMermaidDiagram(
+  workflowName: string,
+  nodes: Record<string, any>,
+  entryNodeIds: string[]
+): string {
+  const lines: string[] = ['graph TD']
+
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    const label = node.rpcName || nodeId
+    const isEntry = entryNodeIds.includes(nodeId)
+    lines.push(
+      `  ${nodeId}${isEntry ? '([' : '['}${label}${isEntry ? '])' : ']'}`
+    )
+
+    const nextTargets = normalizeTargets(node.next)
+    for (const target of nextTargets) {
+      lines.push(`  ${nodeId} --> ${target}`)
+    }
+
+    const errorTargets = normalizeTargets(node.onError)
+    for (const target of errorTargets) {
+      lines.push(`  ${nodeId} -.->|error| ${target}`)
+    }
+  }
+
+  return lines.join('\n')
+}

package/src/wirings/workflow/graph/index.ts

@@ -12,3 +12,8 @@ export {
   type PikkuWorkflowGraphConfig,
   type PikkuWorkflowGraphResult,
 } from './wire-workflow-graph.js'
+export {
+  validateWorkflowWiring,
+  computeEntryNodeIds,
+  generateMermaidDiagram,
+} from './graph-validation.js'

package/src/wirings/workflow/index.ts

@@ -34,6 +34,7 @@ export type {
   WorkflowServiceConfig,
   WorkflowRunWire,
   WorkflowStatus,
+  WorkflowVersionStatus,
   StepStatus,
   WorkflowRun,
   StepState,

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -13,6 +13,7 @@ import type {
   WorkflowRun,
   WorkflowRunWire,
   WorkflowStatus,
+  WorkflowVersionStatus,
   WorkflowServiceConfig,
   WorkflowStepOptions,
 } from './workflow.types.js'
@@ -339,7 +340,14 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     name: string,
     graphHash: string,
     graph: any,
-    source: string
+    source: string,
+    status?: WorkflowVersionStatus
+  ): Promise<void>
+
+  abstract updateWorkflowVersionStatus(
+    name: string,
+    graphHash: string,
+    status: WorkflowVersionStatus
   ): Promise<void>
 
   abstract getWorkflowVersion(
@@ -347,6 +355,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     graphHash: string
   ): Promise<{ graph: any; source: string } | null>
 
+  abstract getAIGeneratedWorkflows(
+    agentName?: string
+  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>>
+
   // ============================================================================
   // Workflow Lifecycle Methods
   // ============================================================================
@@ -426,8 +438,7 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       throw new WorkflowNotFoundError(name)
     }
 
-    // Check if this is a graph workflow (source === 'graph')
-    if (workflowMeta.source === 'graph') {
+    if (workflowMeta.source === 'graph' || workflowMeta.source === 'ai-agent') {
       const shouldInline =
         options?.inline || !getSingletonServices()?.queueService
       return runWorkflowGraph(

package/src/wirings/workflow/workflow.types.ts

@@ -60,6 +60,11 @@ export type WorkflowStatus =
   | 'failed'
   | 'cancelled'
 
+/**
+ * Workflow version status (for AI-generated workflows)
+ */
+export type WorkflowVersionStatus = 'draft' | 'active' | 'declined'
+
 /**
  * Workflow step status
  */
@@ -150,6 +155,9 @@ export interface WorkflowRunService {
     name: string,
     graphHash: string
   ): Promise<{ graph: any; source: string } | null>
+  getAIGeneratedWorkflows(
+    agentName?: string
+  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>>
   deleteRun(id: string): Promise<boolean>
 }
 
@@ -228,7 +236,7 @@ export interface WorkflowRuntimeMeta {
   /** Pikku function name (for execution) */
   pikkuFuncId: string
   /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-  source: 'dsl' | 'complex' | 'graph'
+  source: 'dsl' | 'complex' | 'graph' | 'ai-agent'
   /** Optional description */
   description?: string
   /** Tags for organization */