@pikku/inspector 0.12.59 → 0.12.61

package/dist/utils/serialize-inspector-state.d.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, InspectorState } from '../types.js';
 /**
  * Serializable version of InspectorState that can be saved to JSON
@@ -242,6 +242,7 @@ export interface SerializableInspectorState {
         files: string[];
         usage: Record<string, SecretUsage>;
     };
+    surfaceUsage: InspectorState['surfaceUsage'];
     credentials: {
         definitions: InspectorState['credentials']['definitions'];
         files: string[];
@@ -279,8 +280,8 @@ export interface SerializableInspectorState {
             InspectorState['channelMiddleware']['tagMiddleware'] extends Map<string, infer V> ? V : never
         ]>;
     };
-    aiMiddleware: {
-        definitions: InspectorState['aiMiddleware']['definitions'];
+    agentMiddleware: {
+        definitions: InspectorState['agentMiddleware']['definitions'];
     };
     permissions: {
         definitions: InspectorState['permissions']['definitions'];

package/dist/utils/serialize-inspector-state.js

@@ -118,6 +118,7 @@ export function serializeInspectorState(state) {
             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),
@@ -149,8 +150,8 @@ export function serializeInspectorState(state) {
             instances: state.channelMiddleware.instances,
             tagMiddleware: Array.from(state.channelMiddleware.tagMiddleware.entries()),
         },
-        aiMiddleware: {
-            definitions: state.aiMiddleware.definitions,
+        agentMiddleware: {
+            definitions: state.agentMiddleware.definitions,
         },
         permissions: {
             definitions: state.permissions.definitions,
@@ -295,6 +296,7 @@ export function deserializeInspectorState(data) {
             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 || []),
@@ -326,8 +328,8 @@ export function deserializeInspectorState(data) {
             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/dist/utils/serialize-openapi-json.d.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';
 interface ErrorDetails {

package/dist/utils/validate-auth-sessionless.js

@@ -1,7 +1,8 @@
 import { getPropertyValue } from './get-property-value.js';
 import { ErrorCode } from '../error-codes.js';
+import { resolveFunctionMeta } from './resolve-function-meta.js';
 export function validateAuthSessionless(logger, obj, state, funcName, wireDescription, inheritedAuth) {
-    const fnMeta = state.functions.meta[funcName];
+    const fnMeta = resolveFunctionMeta(state, funcName);
     if (!fnMeta)
         return true;
     const routeAuth = getPropertyValue(obj, 'auth');

package/dist/utils/workflow/graph/finalize-workflows.js

@@ -1,4 +1,4 @@
-import { isVersionedId, formatVersionedId, parseVersionedId } from '@pikku/core';
+import { isVersionedId, formatVersionedId, parseVersionedId, } from '@pikku/core/utils';
 import { canonicalJSON, hashString } from '../../hash.js';
 import { convertDslToGraph } from './convert-dsl-to-graph.js';
 import { deriveWorkflowPlan } from '../derive-workflow-plan.js';

package/dist/utils/workflow/graph/serialize-workflow-graph.d.ts

@@ -11,7 +11,12 @@ export declare function serializeWorkflowGraph(definition: {
         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;

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -1,4 +1,4 @@
-import { isRef } from '@pikku/core/workflow';
+import { isRef, template } from '@pikku/core/workflow';
 /**
  * Convert a RefValue (from runtime) to DataRef (serialized)
  */
@@ -23,6 +23,22 @@ function serializeInputMapping(input) {
     }
     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, createRef) {
+    if (forEach === undefined)
+        return undefined;
+    if (typeof forEach === 'string')
+        return { $ref: forEach };
+    if (typeof forEach === 'function') {
+        return serializeForEach(forEach(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()
@@ -59,6 +75,7 @@ export function serializeWorkflowGraph(definition, options) {
         nodeId,
         path,
     });
+    const createItemRef = (path) => createRef('$item', path);
     // Track which nodes have incoming edges
     const hasIncomingEdge = new Set();
     // First pass: identify nodes with incoming edges
@@ -88,7 +105,7 @@ export function serializeWorkflowGraph(definition, options) {
         // Evaluate input callback to get the mapping
         let input = {};
         if (node.input) {
-            const rawInput = node.input(createRef);
+            const rawInput = node.input(createRef, template, createItemRef);
             input = serializeInputMapping(rawInput);
         }
         // Get RPC name from func
@@ -100,6 +117,13 @@ export function serializeWorkflowGraph(definition, options) {
             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/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -90,11 +90,20 @@ 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/dist/visit.js

@@ -28,8 +28,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 = (logger, checker, node, state, options) => {
     addFileExtendsCoreType(node, checker, state.singletonServicesTypeImportMap, 'CoreSingletonServices', state);
@@ -88,7 +88,7 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     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));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.59",
+  "version": "0.12.61",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -35,23 +35,23 @@
     "prepublishOnly": "yarn build"
   },
   "dependencies": {
-    "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
+    "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.4",
     "openapi-types": "^12.1.3",
-    "path-to-regexp": "^8.3.0",
-    "ts-json-schema-generator": "2.9.1-next.16",
-    "tsx": "^4.21.0",
+    "path-to-regexp": "^8.4.2",
+    "ts-json-schema-generator": "2.9.1-next.18",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "zod": "^4.3.6",
+    "zod": "^4.4.3",
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.83"
+    "@pikku/core": "^0.12.85"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.83",
-    "@types/node": "^24.11.0"
+    "@pikku/core": "^0.12.85",
+    "@types/node": "^24.13.3"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/src/add/{add-ai-scorer.test.ts → add-agent-scorer.test.ts}

@@ -23,7 +23,7 @@ const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
   }) satisfies InspectorLogger
 
 const inspectSources = async (sources: Record<string, string>) => {
-  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-ai-scorer-'))
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-add-agent-scorer-'))
   const files: Record<string, string> = {}
   for (const [name, source] of Object.entries(sources)) {
     files[name] = join(rootDir, name)
@@ -43,16 +43,16 @@ const inspectSources = async (sources: Record<string, string>) => {
 const inspectSource = (source: string) =>
   inspectSources({ 'grading.scorer.ts': source })
 
-describe('addAIScorer', () => {
+describe('addAgentScorer', () => {
   test('reads the lane off which constructor was called, not off a field', async () => {
     const { state, criticals } = await inspectSource(
       [
-        `export const brevity = pikkuAIScorer({`,
+        `export const brevity = pikkuAgentScorer({`,
         `  name: 'brevity',`,
         `  description: 'Shorter answers score higher',`,
         `  score: () => ({ score: 1 }),`,
         `})`,
-        `export const helpfulness = pikkuAIJudge({`,
+        `export const helpfulness = pikkuAgentJudge({`,
         `  name: 'helpfulness',`,
         `  description: 'Does the answer help',`,
         `  model: 'claude-opus-5',`,
@@ -69,7 +69,7 @@ describe('addAIScorer', () => {
   test('defaults an unstated sample rate to grading every run', async () => {
     const { state } = await inspectSource(
       [
-        `export const brevity = pikkuAIScorer({`,
+        `export const brevity = pikkuAgentScorer({`,
         `  name: 'brevity',`,
         `  description: 'Shorter answers score higher',`,
         `  score: () => ({ score: 1 }),`,
@@ -84,7 +84,7 @@ describe('addAIScorer', () => {
   test('carries the sample rate and the reference requirement into the meta', async () => {
     const { state } = await inspectSource(
       [
-        `export const correctness = pikkuAIJudge({`,
+        `export const correctness = pikkuAgentJudge({`,
         `  name: 'correctness',`,
         `  description: 'Is the answer right',`,
         `  model: 'claude-opus-5',`,
@@ -105,7 +105,7 @@ describe('addAIScorer', () => {
   test('rejects a sample rate that is not a fraction', async () => {
     const { state, criticals } = await inspectSource(
       [
-        `export const brevity = pikkuAIScorer({`,
+        `export const brevity = pikkuAgentScorer({`,
         `  name: 'brevity',`,
         `  description: 'Shorter answers score higher',`,
         `  sampleRate: 50,`,
@@ -122,7 +122,7 @@ describe('addAIScorer', () => {
   test('a scorer with no description is refused, since the meta is what names it', async () => {
     const { criticals } = await inspectSource(
       [
-        `export const brevity = pikkuAIScorer({`,
+        `export const brevity = pikkuAgentScorer({`,
         `  name: 'brevity',`,
         `  score: () => ({ score: 1 }),`,
         `})`,
@@ -135,7 +135,7 @@ describe('addAIScorer', () => {
   test('records where a scorer was declared, so codegen can import it back', async () => {
     const { state } = await inspectSource(
       [
-        `export const brevity = pikkuAIScorer({`,
+        `export const brevity = pikkuAgentScorer({`,
         `  name: 'brevity',`,
         `  description: 'Shorter answers score higher',`,
         `  score: () => ({ score: 1 }),`,
@@ -153,7 +153,7 @@ describe('addAIScorer', () => {
 
 describe('an agent asking to be graded', () => {
   const scorerFile = [
-    `export const brevity = pikkuAIScorer({`,
+    `export const brevity = pikkuAgentScorer({`,
     `  name: 'brevity',`,
     `  description: 'Shorter answers score higher',`,
     `  score: () => ({ score: 1 }),`,
@@ -162,7 +162,7 @@ describe('an agent asking to be graded', () => {
 
   const agent = (scorers: string) =>
     [
-      `export const assistant = pikkuAIAgent({`,
+      `export const assistant = pikkuAgent({`,
       `  name: 'assistant',`,
       `  description: 'Answers questions',`,
       `  goal: 'Answer the question.',`,

package/src/add/{add-ai-scorer.ts → add-agent-scorer.ts}

@@ -5,16 +5,16 @@ import { extractFunctionName } from '../utils/extract-function-name.js'
 import { ErrorCode } from '../error-codes.js'
 
 /**
- * `pikkuAIScorer` grades in code and `pikkuAIJudge` grades with a model, which
+ * `pikkuAgentScorer` grades in code and `pikkuAgentJudge` grades with a model, which
  * is the whole difference between the two lanes — so the lane is read off which
  * constructor was called rather than from a field an author could contradict.
  */
 const LANES: Record<string, 'fast' | 'slow'> = {
-  pikkuAIScorer: 'fast',
-  pikkuAIJudge: 'slow',
+  pikkuAgentScorer: 'fast',
+  pikkuAgentJudge: 'slow',
 }
 
-export const addAIScorer: AddWiring = (logger, node, checker, state) => {
+export const addAgentScorer: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) return
 
   const expression = node.expression

package/src/add/{add-ai-agent.test.ts → add-agent.test.ts}

@@ -2,7 +2,7 @@ import { describe, test } from 'node:test'
 import assert from 'node:assert'
 import * as ts from 'typescript'
 
-import { resolveWorkflowReferences } from './add-ai-agent.js'
+import { resolveWorkflowReferences } from './add-agent.js'
 import type { InspectorLogger } from '../types.js'
 
 function createSourceFile(code: string): ts.SourceFile {

package/src/add/{add-ai-agent.ts → add-agent.ts}

@@ -12,7 +12,7 @@ import {
 import {
   resolveMiddleware,
   resolveChannelMiddleware,
-  resolveAIMiddleware,
+  resolveAgentMiddleware,
 } from '../utils/middleware.js'
 import { resolvePermissions } from '../utils/permissions.js'
 import { ErrorCode } from '../error-codes.js'
@@ -119,7 +119,7 @@ function resolveAgentReferences(
       logger.critical(
         ErrorCode.INVALID_VALUE,
         `AI agent '${agentName}' agents array contains a string literal '${element.text}'. ` +
-          `Use an agent reference instead (e.g., import the pikkuAIAgent variable).`
+          `Use an agent reference instead (e.g., import the pikkuAgent variable).`
       )
       continue
     }
@@ -134,7 +134,7 @@ function resolveAgentReferences(
       logger.critical(
         ErrorCode.INVALID_VALUE,
         `AI agent '${agentName}' agents array contains identifier '${element.text}' ` +
-          `that could not be resolved to a pikkuAIAgent.`
+          `that could not be resolved to a pikkuAgent.`
       )
     }
   }
@@ -319,7 +319,7 @@ function resolveIdentifierToAgentName(
     if (
       ts.isCallExpression(decl.initializer) &&
       ts.isIdentifier(decl.initializer.expression) &&
-      decl.initializer.expression.text === 'pikkuAIAgent'
+      decl.initializer.expression.text === 'pikkuAgent'
     ) {
       if (ts.isIdentifier(decl.name)) {
         return decl.name.text
@@ -363,13 +363,7 @@ function resolveScorerNames(
   return names.length > 0 ? names : null
 }
 
-export const addAIAgent: AddWiring = (
-  logger,
-  node,
-  checker,
-  state,
-  options
-) => {
+export const addAgent: AddWiring = (logger, node, checker, state, options) => {
   if (!ts.isCallExpression(node)) {
     return
   }
@@ -378,7 +372,7 @@ export const addAIAgent: AddWiring = (
   const firstArg = args[0]
   const expression = node.expression
 
-  if (!ts.isIdentifier(expression) || expression.text !== 'pikkuAIAgent') {
+  if (!ts.isIdentifier(expression) || expression.text !== 'pikkuAgent') {
     return
   }
 
@@ -401,14 +395,12 @@ export const addAIAgent: AddWiring = (
 
     const roleValue = getPropertyValue(obj, 'role') as string | null
     const personalityValue = getPropertyValue(obj, 'personality') as
-      | string
-      | null
+      string | null
     const goalValue = getPropertyValue(obj, 'goal') as string | null
 
     const maxStepsValue = getPropertyValue(obj, 'maxSteps') as number | null
     const temperatureValue = getPropertyValue(obj, 'temperature') as
-      | number
-      | null
+      number | null
     const toolChoiceValue = getPropertyValue(obj, 'toolChoice') as string | null
     const scorersValue = resolveScorerNames(obj, nameValue || '', logger)
     const toolsValue = resolveToolReferences(
@@ -579,7 +571,7 @@ export const addAIAgent: AddWiring = (
       tags,
       checker
     )
-    const aiMiddleware = resolveAIMiddleware(state, obj, checker)
+    const agentMiddleware = resolveAgentMiddleware(state, obj, checker)
     const permissions = resolvePermissions(state, obj, tags, checker)
 
     state.serviceAggregation.usedFunctions.add(agentKey)
@@ -623,7 +615,7 @@ export const addAIAgent: AddWiring = (
       workingMemorySchema,
       middleware,
       channelMiddleware,
-      aiMiddleware,
+      agentMiddleware,
       permissions,
     }
 
@@ -632,10 +624,10 @@ export const addAIAgent: AddWiring = (
     const funcMeta = state.functions.meta[agentKey]
     if (funcMeta?.services) {
       for (const svc of [
-        'aiStorage',
-        'aiRunState',
+        'agentStorage',
+        'agentRunState',
         'agentRunService',
-        'aiAgentRunner',
+        'agentRunner',
       ]) {
         if (!funcMeta.services.services.includes(svc)) {
           funcMeta.services.services.push(svc)

package/src/add/add-auth.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import type { FunctionServicesMeta } from '@pikku/core'
+import type { FunctionServicesMeta } from '@pikku/core/function'
 import type { AddWiring } from '../types.js'
 import { ErrorCode } from '../error-codes.js'
 import { extractServicesFromFunction } from '../utils/extract-services.js'
@@ -89,7 +89,7 @@ const readArrayProp = (
 
 /**
  * Read the callee name of a `plugins: [...]` entry. better-auth plugins are
- * factory calls (`bearer()`, `twoFactor({ ... })`, `admin()`); the entry's id
+ * factory calls (`bearer()`, `twoFactor({ ... })`, `ban()`); the entry's id
  * is the called function's name. Member-expression callees (`foo.bar()`) and
  * non-call entries are ignored.
  */

package/src/add/add-cli.ts

@@ -630,6 +630,12 @@ function processOptions(
             }
             break
 
+          case 'type':
+            if (ts.isStringLiteral(optProp.initializer)) {
+              option.type = optProp.initializer.text
+            }
+            break
+
           case 'default':
             // Extract default value from expression
             if (ts.isStringLiteral(optProp.initializer)) {

package/src/add/add-credential.ts

@@ -39,11 +39,9 @@ export const addCredential: AddWiring = (
 
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const displayNameValue = getPropertyValue(obj, 'displayName') as
-      | string
-      | null
+      string | null
     const descriptionValue = getPropertyValue(obj, 'description') as
-      | string
-      | null
+      string | null
     const typeValue = getPropertyValue(obj, 'type') as string | null
     const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
 
@@ -126,8 +124,7 @@ export const addCredential: AddWiring = (
         'appCredentialSecretId'
       ) as string | null
       const tokenSecretId = getPropertyValue(oauth2Obj, 'tokenSecretId') as
-        | string
-        | null
+        string | null
       const authorizationUrl = getPropertyValue(
         oauth2Obj,
         'authorizationUrl'

package/src/add/add-file-with-factory.ts

@@ -61,9 +61,7 @@ export const addFileWithFactory = (
           if (state && callExpression.arguments.length > 0) {
             const firstArg = callExpression.arguments[0]
             let functionNode:
-              | ts.ArrowFunction
-              | ts.FunctionExpression
-              | undefined
+              ts.ArrowFunction | ts.FunctionExpression | undefined
 
             if (ts.isArrowFunction(firstArg)) {
               functionNode = firstArg
@@ -179,9 +177,7 @@ export const addFileWithFactory = (
             node.initializer
           ) {
             let functionNode:
-              | ts.ArrowFunction
-              | ts.FunctionExpression
-              | undefined
+              ts.ArrowFunction | ts.FunctionExpression | undefined
             if (ts.isArrowFunction(node.initializer)) {
               functionNode = node.initializer
             } else if (ts.isFunctionExpression(node.initializer)) {