@pikku/inspector 0.12.59 → 0.12.61

package/src/utils/post-process.ts

@@ -7,11 +7,12 @@ import type {
 } from '../types.js'
 import type {
   FunctionServicesMeta,
-  MiddlewareMetadata,
   PermissionMetadata,
-} from '@pikku/core'
+} from '@pikku/core/function'
+import type { MiddlewareMetadata } from '@pikku/core/middleware'
 import type ts from 'typescript'
 import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join } from 'node:path'
 import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
@@ -308,12 +309,12 @@ export function aggregateRequiredServices(
     }
   }
 
-  // AI agents need aiStorage + aiRunState + agentRunService + aiAgentRunner
+  // AI agents need agentStorage + agentRunState + agentRunService + agentRunner
   if (Object.keys(state.agents.agentsMeta).length > 0) {
-    requiredServices.add('aiStorage')
-    requiredServices.add('aiRunState')
+    requiredServices.add('agentStorage')
+    requiredServices.add('agentRunState')
     requiredServices.add('agentRunService')
-    requiredServices.add('aiAgentRunner')
+    requiredServices.add('agentRunner')
   }
 
   // Channels need eventHub for pub/sub
@@ -480,10 +481,56 @@ export function validateVariableOverrides(
 }
 
 /**
+ * Can `pkg` be resolved from `rootDir`, by any means the loader would use?
+ *
+ * Resolution is attempted against `<pkg>/package.json` first and the bare
+ * specifier second, because neither alone is conclusive. A package with a
+ * restrictive `exports` map refuses the first with
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` — which is not a failure at all: reaching the
+ * exports map means the package was found. Only a module-not-found from both
+ * attempts means it is genuinely absent.
+ */
+const isPackageResolvable = (pkg: string, rootDir: string): boolean => {
+  const NOT_FOUND = new Set(['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'])
+  let req: ReturnType<typeof createRequire>
+  try {
+    req = createRequire(join(rootDir, 'package.json'))
+  } catch {
+    return true // cannot ask; do not accuse
+  }
+  for (const specifier of [`${pkg}/package.json`, pkg]) {
+    try {
+      req.resolve(specifier)
+      return true
+    } catch (e: any) {
+      if (!NOT_FOUND.has(e?.code)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Every wired addon must be installed, in the bucket matching how it is used.
+ *
  * A `wireRemoteAddon` package ships types only — its handlers run on the host —
  * so it MUST be a devDependency, not a production dependency (a prod dep would
- * drag in the runtime deps remote consumption exists to avoid). This is the
- * mirror image of `wireAddon`, which requires a production dependency.
+ * drag in the runtime deps remote consumption exists to avoid).
+ *
+ * A plain `wireAddon` only has to be *resolvable*. The failure it allows is
+ * quiet in a way the remote one is not — an absent package makes the metadata
+ * load fail, which is caught and downgraded to a warning, so every
+ * `ref('<namespace>:…')` resolves against nothing and the surface is dead at
+ * runtime. The generated console is the common case: `scaffold.console` emits
+ * `wireAddon({ package: '@pikku/addon-console' })` and refs into it, and a
+ * project that never installed the package gets a console that 404s with
+ * nothing in the build output saying why.
+ *
+ * Deliberately a resolution check and not a `package.json` one. An addon is
+ * discovered because it is *wired*, not because it is a declared dependency —
+ * addons arrive by workspace link, by a local `addons/` directory recorded in
+ * `pikku-addons.json`, and by plain install, and only the last of those shows
+ * up in `dependencies`. Asking the resolver is the only question that matches
+ * what the loader will actually do.
  */
 export function validateRemoteAddonDependencies(
   logger: InspectorLogger,
@@ -492,10 +539,19 @@ export function validateRemoteAddonDependencies(
   const { wireAddonDeclarations } = state.rpc
   if (!wireAddonDeclarations || wireAddonDeclarations.size === 0) return
 
-  const hasRemote = Array.from(wireAddonDeclarations.values()).some(
-    (d) => d.remote
-  )
-  if (!hasRemote) return
+  // Local addons first, and independently of the manifest below: their check
+  // asks the resolver, not `package.json`, so a project without a manifest (as
+  // in some tests) must not skip it.
+  for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+    if (decl.remote) continue
+    if (isPackageResolvable(decl.package, state.rootDir)) continue
+    logger.critical(
+      ErrorCode.ADDON_NOT_INSTALLED,
+      `Addon '${namespace}' ('${decl.package}') is wired with wireAddon but cannot be resolved — every ref('${namespace}:…') will resolve to nothing and the surface will be dead at runtime. Install it, or remove the wireAddon call.`
+    )
+  }
+
+  if (!Array.from(wireAddonDeclarations.values()).some((d) => d.remote)) return
 
   const pkgJsonPath = join(state.rootDir, 'package.json')
   if (!existsSync(pkgJsonPath)) return // no manifest to check (e.g. some tests)
@@ -724,10 +780,7 @@ export function computeRequiredSchemas(
  * the functions that are actually invoked, so this blocks CI through
  * `--fail-on-error` without failing a dev server over a function nobody calls.
  */
-export function validateSchemaReferences(
-  logger: InspectorLogger,
-  state: InspectorState
-): void {
+export function unresolvedSchemaReferences(state: InspectorState): string[] {
   const { functions, schemas } = state
   const available = new Set(Object.keys(schemas ?? {}))
   const unresolved: string[] = []
@@ -752,6 +805,15 @@ export function validateSchemaReferences(
     }
   }
 
+  return unresolved
+}
+
+export function validateSchemaReferences(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const unresolved = unresolvedSchemaReferences(state)
+
   if (unresolved.length === 0) return
 
   logger.diagnostic({
@@ -842,10 +904,11 @@ export function validateScenarioServices(
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a step declaring a `browser` binding must be given an actor (PKU677), since
- *   the browser context signs in as that persona. It is checked statically even
- *   though the binding only runs on a browser run: a step that can never be
- *   driven by a human is a latent failure, not a passing default run.
+ * - a step that runs as a persona must be given one (PKU677) — declared by
+ *   `actor: true`, or implied by a `browser` binding, since the browser context
+ *   signs in as that persona. It is checked statically even though a browser
+ *   binding only runs on a browser run: a step that can never be driven by a
+ *   human is a latent failure, not a passing default run.
  * - a scenario written as a step ladder must assert something (PKU680).
  *
  * It also marks the step's function as used, so `scenario run` boots the
@@ -872,14 +935,14 @@ export function validateScenarioSteps(
         }
         state.serviceAggregation.usedFunctions.add(step.stepFunc)
         const stepMeta = state.functions.meta[step.stepFunc]
-        if (
-          stepMeta?.scenarioStepSurfaces?.includes('browser') &&
-          !step.actor
-        ) {
+        if (stepMeta?.scenarioStepRequiresActor && !step.actor) {
+          const why = stepMeta.scenarioStepSurfaces?.includes('browser')
+            ? 'declares a browser binding'
+            : 'is driven by a persona'
           logger.critical(
-            ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR,
-            `Scenario '${workflowName}' calls step '${step.stepFunc}', which declares a browser binding, without an actor. ` +
-              `Pass { actor: actors.<name> } so the browser context signs in as that persona.`
+            ErrorCode.SCENARIO_STEP_NEEDS_ACTOR,
+            `Scenario '${workflowName}' calls step '${step.stepFunc}', which ${why}, without an actor. ` +
+              `Pass { actor: actors.<name> } so it runs as that persona.`
           )
         }
         continue
@@ -1230,7 +1293,7 @@ export function validateScopeReferences(
  *
  * The description check is separate and opt-in (`--strict-meta`), because the
  * description is what the model is told the tool does: without one, the tool is
- * offered to it under its own name (`ai-agent-prepare.ts`), which is a silent
+ * offered to it under its own name (`agent-prepare.ts`), which is a silent
  * quality loss rather than a failure. A title deliberately does not satisfy it —
  * a title labels a tool in a UI, it does not tell a model when to reach for it.
  */

package/src/utils/resolve-deploy-target.ts

@@ -1,4 +1,4 @@
-import type { FunctionMeta } from '@pikku/core'
+import type { FunctionMeta } from '@pikku/core/services'
 
 /**
  * Thrown when a function's explicit `deploy: 'serverless'` conflicts

package/src/utils/resolve-function-meta.ts

@@ -1,4 +1,4 @@
-import type { FunctionMeta, FunctionsMeta } from '@pikku/core'
+import type { FunctionMeta, FunctionsMeta } from '@pikku/core/services'
 
 /**
  * Look up function metadata by pikkuFuncId, checking both local functions

package/src/utils/resolve-function-types.ts

@@ -1,5 +1,5 @@
 import type { TypesMap } from '../types-map.js'
-import type { FunctionsMeta } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
 
 export function resolveFunctionIOTypes(
   pikkuFuncId: string,

package/src/utils/resolve-versions.ts

@@ -1,4 +1,4 @@
-import { parseVersionedId, formatVersionedId } from '@pikku/core'
+import { parseVersionedId, formatVersionedId } from '@pikku/core/utils'
 import type { CLICommandMeta } from '@pikku/core/cli'
 import type { InspectorState, InspectorLogger } from '../types.js'
 import { ErrorCode } from '../error-codes.js'

package/src/utils/schema-generator.ts

@@ -12,7 +12,8 @@ import { createGenerator, RootlessError } from 'ts-json-schema-generator'
 import { register } from 'tsx/esm/api'
 import * as z from 'zod'
 import { zodToTs, createAuxiliaryTypeStore } from 'zod-to-ts'
-import type { FunctionsMeta, JSONValue } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
+import type { JSONValue } from '@pikku/core/utils'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
 import type { TypesMap } from '../types-map.js'
 import { ErrorCode } from '../error-codes.js'

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

@@ -1,5 +1,5 @@
 import type { SecretUsage } from './extract-secret-usage.js'
-import type { JSONValue } from '@pikku/core'
+import type { JSONValue } from '@pikku/core/utils'
 import type {
   InspectorDiagnostic,
   InspectorFeature,
@@ -212,6 +212,7 @@ export interface SerializableInspectorState {
     files: string[]
     usage: Record<string, SecretUsage>
   }
+  surfaceUsage: InspectorState['surfaceUsage']
   credentials: {
     definitions: InspectorState['credentials']['definitions']
     files: string[]
@@ -263,8 +264,8 @@ export interface SerializableInspectorState {
       ]
     >
   }
-  aiMiddleware: {
-    definitions: InspectorState['aiMiddleware']['definitions']
+  agentMiddleware: {
+    definitions: InspectorState['agentMiddleware']['definitions']
   }
   permissions: {
     definitions: InspectorState['permissions']['definitions']
@@ -440,6 +441,7 @@ export function serializeInspectorState(
       files: Array.from(state.secrets.files),
       usage: Object.fromEntries(state.secrets.usage),
     },
+    surfaceUsage: state.surfaceUsage,
     credentials: {
       definitions: state.credentials.definitions,
       files: Array.from(state.credentials.files),
@@ -473,8 +475,8 @@ export function serializeInspectorState(
         state.channelMiddleware.tagMiddleware.entries()
       ),
     },
-    aiMiddleware: {
-      definitions: state.aiMiddleware.definitions,
+    agentMiddleware: {
+      definitions: state.agentMiddleware.definitions,
     },
     permissions: {
       definitions: state.permissions.definitions,
@@ -648,6 +650,7 @@ export function deserializeInspectorState(
       files: new Set(data.secrets?.files || []),
       usage: new Map(Object.entries(data.secrets?.usage || {})),
     },
+    surfaceUsage: data.surfaceUsage || {},
     credentials: {
       definitions: data.credentials?.definitions || [],
       files: new Set(data.credentials?.files || []),
@@ -679,8 +682,8 @@ export function deserializeInspectorState(
       instances: data.channelMiddleware?.instances || {},
       tagMiddleware: new Map(data.channelMiddleware?.tagMiddleware || []),
     },
-    aiMiddleware: {
-      definitions: data.aiMiddleware?.definitions || {},
+    agentMiddleware: {
+      definitions: data.agentMiddleware?.definitions || {},
     },
     permissions: {
       definitions: data.permissions.definitions,

package/src/utils/serialize-mcp-json.ts

@@ -1,5 +1,5 @@
 import type { InspectorLogger, InspectorState } from '../types.js'
-import type { JSONValue } from '@pikku/core'
+import type { JSONValue } from '@pikku/core/utils'
 import { resolveFunctionMeta } from './resolve-function-meta.js'
 
 interface MCPEndpoint {

package/src/utils/serialize-openapi-json.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
 import type { InspectorLogger } from '../types.js'
 import _convertSchema from '@openapi-contrib/json-schema-to-openapi-schema'

package/src/utils/validate-auth-sessionless.ts

@@ -2,6 +2,7 @@ import type * as ts from 'typescript'
 import { getPropertyValue } from './get-property-value.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorLogger, InspectorState } from '../types.js'
+import { resolveFunctionMeta } from './resolve-function-meta.js'
 
 export function validateAuthSessionless(
   logger: InspectorLogger,
@@ -11,7 +12,7 @@ export function validateAuthSessionless(
   wireDescription: string,
   inheritedAuth?: boolean
 ): boolean {
-  const fnMeta = state.functions.meta[funcName]
+  const fnMeta = resolveFunctionMeta(state, funcName)
   if (!fnMeta) return true
 
   const routeAuth = getPropertyValue(obj, 'auth')

package/src/utils/validate-tags-resolve-to-middleware.test.ts

@@ -59,7 +59,10 @@ describe('validateTagsResolveToMiddleware', () => {
   })
 
   test('stays quiet when http middleware is registered for the tag', () => {
-    assert.deepEqual(run(stateWith({ console: { tags: ['admin'] } }, ['admin'])), [])
+    assert.deepEqual(
+      run(stateWith({ console: { tags: ['admin'] } }, ['admin'])),
+      []
+    )
   })
 
   test('stays quiet when only channel middleware is registered for the tag', () => {

package/src/utils/workflow/dsl/extract-approval-policy.test.ts

@@ -26,7 +26,10 @@ const approvalStepFor = (options: string): ApprovalStepMeta => {
 
   let node: ts.Node | undefined
   const visit = (n: ts.Node) => {
-    if (ts.isCallExpression(n) && n.expression.getText() === 'pikkuWorkflowFunc') {
+    if (
+      ts.isCallExpression(n) &&
+      n.expression.getText() === 'pikkuWorkflowFunc'
+    ) {
       node = n
     }
     ts.forEachChild(n, visit)

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

@@ -1,7 +1,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert'
 import { convertDslToGraph } from './convert-dsl-to-graph.js'
-import type { WorkflowsMeta } from '@pikku/core'
+import type { WorkflowsMeta } from '@pikku/core/workflow'
 
 const scenarioMeta = (
   overrides: Partial<WorkflowsMeta[string]> = {}

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

@@ -1,5 +1,9 @@
-import type { FunctionsMeta } from '@pikku/core'
-import { isVersionedId, formatVersionedId, parseVersionedId } from '@pikku/core'
+import type { FunctionsMeta } from '@pikku/core/services'
+import {
+  isVersionedId,
+  formatVersionedId,
+  parseVersionedId,
+} from '@pikku/core/utils'
 import type { SerializedWorkflowGraph } from './workflow-graph.types.js'
 import { canonicalJSON, hashString } from '../../hash.js'
 import { convertDslToGraph } from './convert-dsl-to-graph.js'

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

@@ -1,4 +1,4 @@
-import { isRef } from '@pikku/core/workflow'
+import { isRef, template } from '@pikku/core/workflow'
 import type {
   SerializedWorkflowGraph,
   SerializedGraphNode,
@@ -36,6 +36,26 @@ function serializeInputMapping(
   return result
 }
 
+/**
+ * Convert a `forEach` source — a bare node id, a ref, or a `(ref) => ref(...)`
+ * callback — to the serialized DataRef form
+ */
+function serializeForEach(
+  forEach: unknown,
+  createRef: (nodeId: string, path?: string) => { nodeId: string; path?: string }
+): DataRef | undefined {
+  if (forEach === undefined) return undefined
+  if (typeof forEach === 'string') return { $ref: forEach }
+  if (typeof forEach === 'function') {
+    return serializeForEach(
+      (forEach as (ref: unknown) => unknown)(createRef),
+      createRef
+    )
+  }
+  if (isRef(forEach)) return convertRef(forEach)
+  return undefined
+}
+
 /**
  * Convert next config from runtime format to serialized format
  * Runtime uses Record<string, string | string[]> for branching with graph.branch()
@@ -73,7 +93,9 @@ export function serializeWorkflowGraph(
       string,
       {
         func: { name?: string }
-        input?: (ref: any) => Record<string, unknown>
+        input?: (ref: any, template?: any, $item?: any) => Record<string, unknown>
+        forEach?: string | { nodeId: string; path?: string } | ((ref: any) => unknown)
+        mode?: 'parallel' | 'sequential'
         next?: string | string[] | Record<string, string | string[]>
         onError?: string | string[]
         notes?: string
@@ -96,6 +118,8 @@ export function serializeWorkflowGraph(
     path,
   })
 
+  const createItemRef = (path?: string) => createRef('$item', path)
+
   // Track which nodes have incoming edges
   const hasIncomingEdge = new Set<string>()
 
@@ -124,7 +148,7 @@ export function serializeWorkflowGraph(
     // Evaluate input callback to get the mapping
     let input: Record<string, unknown | DataRef> = {}
     if (node.input) {
-      const rawInput = node.input(createRef)
+      const rawInput = node.input(createRef, template, createItemRef)
       input = serializeInputMapping(rawInput)
     }
 
@@ -138,6 +162,13 @@ export function serializeWorkflowGraph(
       next: serializeNext(node.next),
       onError: node.onError,
     }
+    const forEach = serializeForEach(node.forEach, createRef)
+    if (forEach) {
+      funcNode.forEach = forEach
+      if (node.mode !== undefined) {
+        funcNode.mode = node.mode
+      }
+    }
     if (node.notes !== undefined) {
       funcNode.notes = node.notes
     }

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

@@ -141,11 +141,21 @@ interface BaseNode {
 /**
  * Function node - calls an RPC
  */
+/** How the per-item instances of a `forEach` node run */
+export type ForEachMode = 'parallel' | 'sequential'
+
 export interface FunctionNode extends BaseNode {
   /** RPC function name */
   rpcName: string
   /** Input mapping - values can be literals or DataRefs */
   input?: Record<string, unknown | DataRef>
+  /**
+   * Run this node once per element of the referenced array. The node's own
+   * result becomes the ordered array of per-item results.
+   */
+  forEach?: DataRef
+  /** How the per-item instances run. Defaults to 'parallel'. */
+  mode?: ForEachMode
   /** Output variable name for storing result */
   outputVar?: string
   /** Hash of nodeId + RPC input/output schemas for version detection */

package/src/visit.ts

@@ -33,8 +33,8 @@ import { addPersonas } from './add/add-personas.js'
 import { addVariable } from './add/add-variable.js'
 import { addWorkflowGraph } from './add/add-workflow-graph.js'
 import { addFeature } from './add/add-feature.js'
-import { addAIAgent } from './add/add-ai-agent.js'
-import { addAIScorer } from './add/add-ai-scorer.js'
+import { addAgent } from './add/add-agent.js'
+import { addAgentScorer } from './add/add-agent-scorer.js'
 import { addApprovalDescription } from './add/add-approval-description.js'
 
 export const visitSetup = (
@@ -172,8 +172,8 @@ export const visitRoutes = (
   addMCPPrompt(logger, node, checker, state, nextOptions)
   addWorkflowGraph(logger, node, checker, state, nextOptions)
   addFeature(logger, node, checker, state, nextOptions)
-  addAIAgent(logger, node, checker, state, nextOptions)
-  addAIScorer(logger, node, checker, state, nextOptions)
+  addAgent(logger, node, checker, state, nextOptions)
+  addAgentScorer(logger, node, checker, state, nextOptions)
 
   ts.forEachChild(node, (child) =>
     visitRoutes(logger, checker, child, state, nextOptions)