@pikku/core 0.12.70 → 0.12.71

package/dist/wirings/workflow/workflow.types.d.ts

@@ -182,11 +182,6 @@ export interface WorkflowRunService {
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
     deleteRun(id: string): Promise<boolean>;
 }
 /**
@@ -367,7 +362,7 @@ export interface WorkflowRuntimeMeta {
     /** Pikku function name (for execution) */
     pikkuFuncId: string;
     /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'scenario' (complex + actor steps) */
-    source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'scenario';
+    source: 'dsl' | 'complex' | 'graph' | 'scenario';
     /** Optional description */
     description?: string;
     /** Tags for organization */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.70",
+  "version": "0.12.71",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/services/in-memory-queue-service.test.ts

@@ -23,7 +23,10 @@ const registerWorker = (
 ) => {
   const calls = { count: 0 }
   const funcId = `queue_${queueName}`
-  pikkuState(null, 'queue', 'meta')[queueName] = { pikkuFuncId: funcId, name: queueName }
+  pikkuState(null, 'queue', 'meta')[queueName] = {
+    pikkuFuncId: funcId,
+    name: queueName,
+  }
   pikkuState(null, 'function', 'meta')[funcId] = {
     pikkuFuncId: funcId,
     inputSchemaName: null,
@@ -55,6 +58,68 @@ const waitUntil = async (
   return predicate()
 }
 
+// Register a queue worker that records the payload each delivery carried.
+const registerRecordingWorker = (queueName: string) => {
+  const received: any[] = []
+  const funcId = `queue_${queueName}`
+  pikkuState(null, 'queue', 'meta')[queueName] = {
+    pikkuFuncId: funcId,
+    name: queueName,
+  }
+  pikkuState(null, 'function', 'meta')[funcId] = {
+    pikkuFuncId: funcId,
+    inputSchemaName: null,
+    outputSchemaName: null,
+    sessionless: true,
+  } as any
+  wireQueueWorker({
+    name: queueName,
+    func: {
+      auth: false,
+      func: async (_services: any, data: any) => {
+        received.push(data)
+      },
+    },
+  } as any)
+  return received
+}
+
+describe('InMemoryQueueService payload isolation', () => {
+  test('a job carries the payload as it was when added', async () => {
+    const received = registerRecordingWorker('mutated')
+    const queue = new InMemoryQueueService()
+    const payload = { items: ['a'] }
+
+    await queue.add('mutated', payload, { delay: 0 })
+    payload.items.push('b')
+
+    assert.equal(await waitUntil(() => received.length === 1), true)
+    assert.deepEqual(
+      received[0].items,
+      ['a'],
+      'the worker saw a mutation made after the job was queued — a real queue would have serialised it away'
+    )
+  })
+
+  test('a payload arrives shaped the way a real queue would deliver it', async () => {
+    const received = registerRecordingWorker('serialised')
+    const queue = new InMemoryQueueService()
+
+    await queue.add(
+      'serialised',
+      { when: new Date('2020-01-01T00:00:00.000Z') },
+      { delay: 0 }
+    )
+
+    assert.equal(await waitUntil(() => received.length === 1), true)
+    assert.equal(
+      received[0].when,
+      '2020-01-01T00:00:00.000Z',
+      'a Date survived as a Date, so dev behaviour diverges from every real queue backend'
+    )
+  })
+})
+
 describe('InMemoryQueueService retry', () => {
   test('redelivers a transiently-failing job until it succeeds', async () => {
     const calls = registerWorker('flaky', (count) => {

package/src/services/in-memory-queue-service.ts

@@ -11,6 +11,12 @@ import { runQueueJob } from '../wirings/queue/queue-runner.js'
  * a real queue — and redelivers a failed job up to `options.attempts` times with
  * backoff, so a transiently-failing workflow step recovers exactly as it would
  * on pg-boss/bullmq instead of being silently dropped on its first error.
+ *
+ * Payloads are JSON round-tripped on the way in, because every real backend
+ * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
+ * therefore never sees the caller's live object. Doing it here keeps dev
+ * behaviour honest, and keeps the callers — who cannot know which backend they
+ * are talking to — from having to serialise defensively.
  */
 export class InMemoryQueueService implements QueueService {
   readonly supportsResults = false
@@ -25,13 +31,15 @@ export class InMemoryQueueService implements QueueService {
     const maxAttempts = Math.max(1, options?.attempts ?? 1)
     let attemptsMade = 0
     const createdAt = new Date()
+    const payload: T =
+      data === undefined ? data : (JSON.parse(JSON.stringify(data)) as T)
 
     const runAttempt = async () => {
       attemptsMade++
       const job: QueueJob<T> = {
         id: jobId,
         queueName,
-        data,
+        data: payload,
         status: () => 'active',
         metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
         pikkuUserId: options?.pikkuUserId,
@@ -41,7 +49,10 @@ export class InMemoryQueueService implements QueueService {
       } catch (e: any) {
         if (attemptsMade < maxAttempts) {
           // Transient failure — redeliver with backoff, mirroring a real queue.
-          setTimeout(runAttempt, this.backoffDelay(options?.backoff, attemptsMade))
+          setTimeout(
+            runAttempt,
+            this.backoffDelay(options?.backoff, attemptsMade)
+          )
         } else {
           console.error(
             `[InMemoryQueue] Job ${jobId} on ${queueName} failed after ${attemptsMade} attempt(s):`,

package/src/services/in-memory-workflow-service.ts

@@ -456,6 +456,18 @@ export class InMemoryWorkflowService
     return nodeIds.filter((id) => !existingSteps.has(id))
   }
 
+  protected override async listStepStates(
+    runId: string
+  ): Promise<Array<StepState & { stepName: string }>> {
+    const prefix = `${runId}:`
+    const steps: Array<StepState & { stepName: string }> = []
+    for (const [key, step] of this.steps.entries()) {
+      if (!key.startsWith(prefix)) continue
+      steps.push({ ...step, stepName: key.substring(prefix.length) })
+    }
+    return steps
+  }
+
   async getStepInstances(
     runId: string
   ): Promise<
@@ -560,29 +572,4 @@ export class InMemoryWorkflowService
     if (!version) return null
     return { graph: version.graph, source: version.source }
   }
-
-  async getAIGeneratedWorkflows(
-    agentName?: string
-  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>> {
-    const results: Array<{
-      workflowName: string
-      graphHash: string
-      graph: any
-    }> = []
-    const prefix = agentName ? `ai:${agentName}:` : 'ai:'
-    for (const [key, value] of this.workflowVersions) {
-      if (value.source !== 'ai-agent' || value.status !== 'active') continue
-      const separatorIdx = key.lastIndexOf(':')
-      const wfName = key.substring(0, separatorIdx)
-      const hash = key.substring(separatorIdx + 1)
-      if (wfName.startsWith(prefix)) {
-        results.push({
-          workflowName: wfName,
-          graphHash: hash,
-          graph: value.graph,
-        })
-      }
-    }
-    return results
-  }
 }

package/src/services/workflow-service.ts

@@ -64,6 +64,13 @@ export interface WorkflowService {
     rpcService: any,
     options?: { inline?: boolean; startNode?: string }
   ): Promise<{ runId: string }>
+  /**
+   * Start a run and wait for it to end.
+   *
+   * `pollIntervalMs` is the ceiling on the wait between reads of the run, not a
+   * fixed cadence: polling starts far shorter than this and widens towards it,
+   * so a run that finishes quickly is not held for a whole interval.
+   */
   runToCompletion<I>(
     name: string,
     input: I,
@@ -119,8 +126,4 @@ export interface WorkflowService {
     name: string,
     graphHash: string
   ): Promise<{ graph: any; source: string } | null>
-
-  getAIGeneratedWorkflows(
-    agentName?: string
-  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>>
 }

package/src/types/core.types.ts

@@ -139,6 +139,13 @@ export type FunctionRuntimeMeta = {
    * may drive a browser or assert against fixtures.
    */
   scenarioStep?: boolean
+  /**
+   * The function behind a `pikkuScenario(...)` — a scenario's own body, as
+   * opposed to the steps it calls. Marked for the same reason as
+   * `scenarioStep`: a scenario is only ever run by `pikku scenario run`, so it
+   * has to be held back from the app bootstrap and from every deployed unit.
+   */
+  scenario?: boolean
   mcp?: boolean
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'

package/src/wirings/ai-agent/ai-agent-agui.test.ts

@@ -510,22 +510,6 @@ describe('wrapChannelWithAGUI — Pikku CUSTOM events', () => {
     assert.deepEqual(c.value.data, [{ title: 'foo' }])
   })
 
-  it('emits CUSTOM pikku:workflow-created', () => {
-    const { channel, events } = makeChannel()
-    const wrapped = wrapChannelWithAGUI(channel)
-
-    wrapped.send({
-      type: 'workflow-created',
-      workflowName: 'myFlow',
-      graph: { nodes: [] },
-    } as AIStreamEvent)
-
-    const c = find(events, 'CUSTOM', 'pikku:workflow-created')
-    assert.ok(c)
-    assert.equal(c.value.workflowName, 'myFlow')
-    assert.deepEqual(c.value.graph, { nodes: [] })
-  })
-
   it('emits CUSTOM pikku:agent-call', () => {
     const { channel, events } = makeChannel()
     const wrapped = wrapChannelWithAGUI(channel)

package/src/wirings/ai-agent/ai-agent-agui.ts

@@ -333,15 +333,6 @@ export function wrapChannelWithAGUI(
           break
         }
 
-        case 'workflow-created': {
-          send({
-            type: 'CUSTOM',
-            name: 'pikku:workflow-created',
-            value: { workflowName: event.workflowName, graph: event.graph },
-          })
-          break
-        }
-
         case 'agent-call': {
           send({
             type: 'CUSTOM',

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -462,8 +462,7 @@ export function createScopedChannel(
         event.type === 'tool-call' ||
         event.type === 'tool-result' ||
         event.type === 'usage' ||
-        event.type === 'error' ||
-        event.type === 'workflow-created'
+        event.type === 'error'
       ) {
         parent.send({ ...event, agent: agentName, session } as AIStreamEvent)
       } else {

package/src/wirings/ai-agent/ai-agent.types.ts

@@ -350,13 +350,6 @@ export type AIStreamEvent =
       session?: string
     }
   | { type: 'audio-done'; agent?: string; session?: string }
-  | {
-      type: 'workflow-created'
-      workflowName: string
-      graph: any
-      agent?: string
-      session?: string
-    }
   | {
       type: 'data'
       name: string

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

@@ -538,8 +538,9 @@ export async function continueGraph(
     return
   }
 
-  const run = await workflowService.getRun(runId)
-  const triggerInput = run?.input
+  // The same run read a few lines up: nothing between here and there writes it,
+  // and `input` is fixed at creation anyway.
+  const triggerInput = currentRun?.input
 
   for (const fire of plan.toFire) {
     const node = nodes[fire.logical]

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

@@ -1,150 +1,7 @@
 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, [])
-  })
-})
+import { generateMermaidDiagram } from './graph-validation.js'
 
 describe('generateMermaidDiagram', () => {
   it('generates valid mermaid output', () => {

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

@@ -1,6 +1,3 @@
-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]
@@ -15,199 +12,6 @@ function normalizeTargets(value: unknown): string[] {
   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>,

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

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