@pikku/inspector 0.12.33 → 0.12.35

package/src/utils/post-process.test.ts

@@ -0,0 +1,254 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { aggregateRequiredServices } from './post-process.js'
+import type { InspectorState } from '../types.js'
+
+function makeState(
+  overrides: {
+    usedFunctions?: string[]
+    functionsMeta?: Record<string, any>
+    addonFunctions?: Record<string, Record<string, any>>
+    addonRequiredParentServices?: string[]
+  } = {}
+): Omit<InspectorState, 'typesLookup'> {
+  return {
+    serviceAggregation: {
+      requiredServices: new Set<string>(),
+      usedFunctions: new Set(overrides.usedFunctions ?? []),
+      usedMiddleware: new Set<string>(),
+      usedPermissions: new Set<string>(),
+      allSingletonServices: [],
+      allWireServices: [],
+    },
+    functions: { meta: overrides.functionsMeta ?? {} },
+    middleware: { definitions: {}, tagMiddleware: new Map() },
+    permissions: { definitions: {}, tagPermissions: new Map() },
+    http: {
+      meta: {
+        get: {},
+        post: {},
+        put: {},
+        patch: {},
+        delete: {},
+        head: {},
+        options: {},
+      },
+      routeMiddleware: new Map(),
+      routePermissions: new Map(),
+    },
+    channels: { meta: {} },
+    queueWorkers: { meta: {} },
+    scheduledTasks: { meta: {} },
+    mcpEndpoints: { toolsMeta: {}, promptsMeta: {}, resourcesMeta: {} },
+    agents: { agentsMeta: {} },
+    workflows: { meta: {}, graphMeta: {} },
+    wireServicesMeta: new Map(),
+    rpc: { internalMeta: {}, exposedMeta: {} },
+    addonFunctions: overrides.addonFunctions ?? {},
+    addonRequiredParentServices: overrides.addonRequiredParentServices ?? [],
+  } as unknown as Omit<InspectorState, 'typesLookup'>
+}
+
+const CONSOLE_PARENT_SERVICES = [
+  'metaService',
+  'aiAgentRunner',
+  'deploymentService',
+  'credentialService',
+]
+
+describe('aggregateRequiredServices — per-function addon services', () => {
+  test('a used addon function adds only its own parent services', () => {
+    const state = makeState({
+      usedFunctions: ['console:getSchema'],
+      addonFunctions: {
+        console: {
+          getSchema: {
+            services: { optimized: true, services: ['metaService'] },
+          },
+          runAgent: {
+            services: {
+              optimized: true,
+              services: ['aiAgentRunner', 'deploymentService'],
+            },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('metaService'))
+    assert.ok(!required.has('aiAgentRunner'))
+    assert.ok(!required.has('deploymentService'))
+    assert.ok(!required.has('credentialService'))
+  })
+
+  test('an addon-created service falls back to the full parent blanket', () => {
+    const state = makeState({
+      usedFunctions: ['console:editCode'],
+      addonFunctions: {
+        console: {
+          editCode: {
+            services: {
+              optimized: true,
+              services: ['codeEditService', 'metaService'],
+            },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    for (const service of CONSOLE_PARENT_SERVICES) {
+      assert.ok(required.has(service), `expected blanket to add ${service}`)
+    }
+  })
+
+  test('missing services meta (old addon build) falls back to the blanket', () => {
+    const state = makeState({
+      usedFunctions: ['console:getSchema'],
+      addonFunctions: { console: { getSchema: {} } },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    for (const service of CONSOLE_PARENT_SERVICES) {
+      assert.ok(required.has(service), `expected blanket to add ${service}`)
+    }
+  })
+
+  test('a bare project function colliding with an addon function name adds nothing', () => {
+    const state = makeState({
+      usedFunctions: ['getAgentThreads'],
+      functionsMeta: {
+        getAgentThreads: {
+          services: { optimized: true, services: ['kysely'] },
+        },
+      },
+      addonFunctions: {
+        console: {
+          getAgentThreads: {
+            services: { optimized: true, services: ['metaService'] },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('kysely'))
+    assert.ok(!required.has('metaService'))
+    assert.ok(!required.has('aiAgentRunner'))
+  })
+
+  test('no used addon functions adds no parent services', () => {
+    const state = makeState({
+      usedFunctions: ['listTasks'],
+      functionsMeta: {
+        listTasks: { services: { optimized: true, services: ['kysely'] } },
+      },
+      addonFunctions: {
+        console: {
+          getSchema: {
+            services: { optimized: true, services: ['metaService'] },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(!required.has('metaService'))
+    assert.ok(!required.has('aiAgentRunner'))
+  })
+
+  test('internal services in addon function meta never force the blanket', () => {
+    const state = makeState({
+      usedFunctions: ['console:getSchema'],
+      addonFunctions: {
+        console: {
+          getSchema: {
+            services: {
+              optimized: true,
+              services: ['metaService', 'rpc', 'channel'],
+            },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('metaService'))
+    assert.ok(!required.has('aiAgentRunner'))
+    assert.ok(!required.has('rpc'))
+  })
+
+  test('default framework services in addon function meta never force the blanket', () => {
+    const state = makeState({
+      usedFunctions: ['ext:goodbye'],
+      addonFunctions: {
+        ext: {
+          goodbye: {
+            services: { optimized: true, services: ['logger', 'config'] },
+          },
+        },
+      },
+      addonRequiredParentServices: ['greetingStore', 'auditSink'],
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(!required.has('greetingStore'))
+    assert.ok(!required.has('auditSink'))
+  })
+
+  test('a ref()-wired route (inline id + namespaced target) aggregates the target services', () => {
+    const state = makeState({
+      usedFunctions: [
+        'http:get:/function-tests/stream',
+        'console:streamFunctionTests',
+      ],
+      functionsMeta: {
+        'http:get:/function-tests/stream': {
+          services: { optimized: false, services: [] },
+        },
+      },
+      addonFunctions: {
+        console: {
+          streamFunctionTests: {
+            services: { optimized: true, services: ['metaService'] },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('metaService'))
+    assert.ok(!required.has('aiAgentRunner'))
+  })
+
+  test('multiple used addon functions union their parent services', () => {
+    const state = makeState({
+      usedFunctions: ['console:getSchema', 'console:runAgent'],
+      addonFunctions: {
+        console: {
+          getSchema: {
+            services: { optimized: true, services: ['metaService'] },
+          },
+          runAgent: {
+            services: { optimized: true, services: ['aiAgentRunner'] },
+          },
+        },
+      },
+      addonRequiredParentServices: CONSOLE_PARENT_SERVICES,
+    })
+    aggregateRequiredServices(state)
+    const required = state.serviceAggregation.requiredServices
+    assert.ok(required.has('metaService'))
+    assert.ok(required.has('aiAgentRunner'))
+    assert.ok(!required.has('deploymentService'))
+    assert.ok(!required.has('credentialService'))
+  })
+})

package/src/utils/post-process.ts

@@ -325,20 +325,47 @@ export function aggregateRequiredServices(
   }
 
   // 7. Services that consumed addons need from the parent project.
-  // These are required ONLY by units that actually deploy an addon function;
-  // a unit that merely calls the addon over RPC (or never touches it) must not
-  // carry them, or every per-unit bundle would over-include the addon's
-  // parent-service dependencies (e.g. aiAgentRunner, deploymentService) and
-  // defeat per-unit tree-shaking.
-  const addonFuncIds = new Set<string>()
-  for (const fns of Object.values(state.addonFunctions ?? {})) {
-    for (const id of Object.keys(fns)) addonFuncIds.add(id)
-  }
-  const unitDeploysAddonFn = [...usedFunctions].some((fn) =>
-    addonFuncIds.has(fn)
-  )
-  if (unitDeploysAddonFn) {
-    for (const service of state.addonRequiredParentServices ?? []) {
+  const addonFnServices = new Map<string, string[] | undefined>()
+  for (const [namespace, fns] of Object.entries(state.addonFunctions ?? {})) {
+    for (const [id, meta] of Object.entries(fns)) {
+      addonFnServices.set(
+        `${namespace}:${id}`,
+        (meta as { services?: FunctionServicesMeta })?.services?.services
+      )
+    }
+  }
+  const parentDeclared = state.addonRequiredParentServices ?? []
+  const parentDeclaredSet = new Set(parentDeclared)
+  const defaultServices = new Set([
+    'config',
+    'logger',
+    'variables',
+    'schema',
+    'secrets',
+  ])
+  let usesAddonFn = false
+  let addonFactoryNeeded = false
+  for (const funcId of usedFunctions) {
+    if (!addonFnServices.has(funcId)) continue
+    usesAddonFn = true
+    const services = addonFnServices.get(funcId)
+    if (!services) {
+      addonFactoryNeeded = true
+      continue
+    }
+    for (const service of services) {
+      if (parentDeclaredSet.has(service)) {
+        requiredServices.add(service)
+      } else if (
+        !internalServices.has(service) &&
+        !defaultServices.has(service)
+      ) {
+        addonFactoryNeeded = true
+      }
+    }
+  }
+  if (usesAddonFn && addonFactoryNeeded) {
+    for (const service of parentDeclared) {
       requiredServices.add(service)
     }
   }

package/src/utils/serialize-inspector-state.ts

@@ -155,6 +155,7 @@ export interface SerializableInspectorState {
     exposedMeta: InspectorState['rpc']['exposedMeta']
     exposedFiles: Array<[string, { path: string; exportedName: string }]>
     invokedFunctions: string[]
+    invokedFunctionsByFile?: Array<[string, string[]]>
     usedAddons: string[]
     wireAddonDeclarations: Array<
       [
@@ -379,6 +380,11 @@ export function serializeInspectorState(
       exposedMeta: state.rpc.exposedMeta,
       exposedFiles: Array.from(state.rpc.exposedFiles.entries()),
       invokedFunctions: Array.from(state.rpc.invokedFunctions),
+      invokedFunctionsByFile: Array.from(
+        (
+          state.rpc.invokedFunctionsByFile ?? new Map<string, Set<string>>()
+        ).entries()
+      ).map(([file, fns]): [string, string[]] => [file, Array.from(fns)]),
       usedAddons: Array.from(state.rpc.usedAddons),
       wireAddonDeclarations: Array.from(
         state.rpc.wireAddonDeclarations.entries()
@@ -565,6 +571,11 @@ export function deserializeInspectorState(
       exposedMeta: data.rpc.exposedMeta,
       exposedFiles: new Map(data.rpc.exposedFiles),
       invokedFunctions: new Set(data.rpc.invokedFunctions),
+      invokedFunctionsByFile: new Map(
+        (data.rpc.invokedFunctionsByFile || []).map(
+          ([file, fns]): [string, Set<string>] => [file, new Set(fns)]
+        )
+      ),
       usedAddons: new Set(data.rpc.usedAddons || []),
       wireAddonDeclarations: new Map(data.rpc.wireAddonDeclarations || []),
       wireAddonFiles: new Set(data.rpc.wireAddonFiles || []),

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

@@ -21,6 +21,8 @@ import type {
 } from '@pikku/core/workflow'
 import {
   isWorkflowDoCall,
+  isWorkflowExpectEventuallyCall,
+  extractActorFromOptions,
   isWorkflowSleepCall,
   isWorkflowSuspendCall,
   isThrowCancelException,
@@ -553,10 +555,15 @@ function extractRpcStep(
     const inputs =
       args.length >= 3 ? extractInputSources(args[2], context) : undefined
 
-    // Extract options from fourth argument
+    // do(step, rpc, data, options?) vs expectEventually(step, rpc, data, predicate, options?)
+    const expectEventually = isWorkflowExpectEventuallyCall(call)
+    const optionsIndex = expectEventually ? 4 : 3
+    const optionsArg =
+      args.length > optionsIndex ? args[optionsIndex] : undefined
+
     const options =
-      args.length >= 4 && ts.isObjectLiteralExpression(args[3])
-        ? extractStepOptions(args[3], context)
+      optionsArg && ts.isObjectLiteralExpression(optionsArg)
+        ? extractStepOptions(optionsArg, context)
         : undefined
 
     return {
@@ -566,6 +573,8 @@ function extractRpcStep(
       outputVar,
       inputs,
       options,
+      actor: extractActorFromOptions(optionsArg),
+      expectEventually: expectEventually || undefined,
     }
   } catch (error) {
     context.errors.push({

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

@@ -5,7 +5,8 @@ import * as ts from 'typescript'
  */
 
 /**
- * Check if a call expression is workflow.do()
+ * Check if a call expression is workflow.do() or workflow.expectEventually()
+ * (both are RPC steps; expectEventually is the polling variant used by user flows)
  */
 export function isWorkflowDoCall(
   node: ts.CallExpression,
@@ -17,12 +18,57 @@ export function isWorkflowDoCall(
 
   const propAccess = node.expression
   return (
-    propAccess.name.text === 'do' &&
+    (propAccess.name.text === 'do' ||
+      propAccess.name.text === 'expectEventually') &&
     ts.isIdentifier(propAccess.expression) &&
     propAccess.expression.text === 'workflow'
   )
 }
 
+/**
+ * Check if a call expression is workflow.expectEventually()
+ */
+export function isWorkflowExpectEventuallyCall(
+  node: ts.CallExpression
+): boolean {
+  return (
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'expectEventually' &&
+    ts.isIdentifier(node.expression.expression) &&
+    node.expression.expression.text === 'workflow'
+  )
+}
+
+/**
+ * Extract the actor NAME from a step options object literal:
+ * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
+ * or not statically resolvable.
+ */
+export function extractActorFromOptions(
+  optionsArg: ts.Expression | undefined
+): string | undefined {
+  if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return
+  for (const prop of optionsArg.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === 'actor'
+    ) {
+      const init = prop.initializer
+      if (ts.isPropertyAccessExpression(init)) {
+        return init.name.text
+      }
+      if (
+        ts.isElementAccessExpression(init) &&
+        ts.isStringLiteral(init.argumentExpression)
+      ) {
+        return init.argumentExpression.text
+      }
+    }
+  }
+  return
+}
+
 /**
  * Check if a call expression is workflow.sleep()
  */

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

@@ -93,6 +93,12 @@ function convertStepToNode(
         rpcName: step.rpcName,
         next: nextNodeId,
       }
+      if (step.actor) {
+        node.actor = step.actor
+      }
+      if (step.expectEventually) {
+        node.expectEventually = true
+      }
       if (step.inputs) {
         if (step.inputs === 'passthrough') {
           // Entire data is passed through - store as reference to trigger
@@ -403,8 +409,10 @@ export function convertDslToGraph(
     name: workflowName,
     pikkuFuncId: meta.pikkuFuncId,
     source,
+    title: meta.title,
     description: meta.description,
     tags: meta.tags,
+    actors: meta.actors,
     context: meta.context,
     nodes: nodesRecord,
     entryNodeIds,

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

@@ -142,6 +142,10 @@ export interface FunctionNode extends BaseNode {
   outputVar?: string
   /** Hash of nodeId + RPC input/output schemas for version detection */
   stepHash?: string
+  /** User-flow actor name this step runs as (workflow.do {actor: actors.x}) */
+  actor?: string
+  /** True for workflow.expectEventually polling steps (user flows) */
+  expectEventually?: boolean
 }
 
 /**
@@ -191,10 +195,14 @@ export interface SerializedWorkflowGraph {
   pikkuFuncId: string
   /** Source type: 'dsl' for pikkuWorkflowFunc, 'graph' for pikkuWorkflowGraph */
   source: WorkflowSourceType
+  /** Optional short display name */
+  title?: string
   /** Optional description */
   description?: string
   /** Tags for organization */
   tags?: string[]
+  /** Actor names a user flow's steps run as */
+  actors?: string[]
   /** If true, workflow always executes inline without queues */
   inline?: boolean
   /** Workflow context/state variables (from Zod schema) */