@pikku/inspector 0.12.59 → 0.12.61

package/src/add/add-wire-remote-addon.ts

@@ -45,7 +45,10 @@ export function addWireRemoteAddon(
     ) {
       hasAuth = true
       for (const authProp of prop.initializer.properties) {
-        if (!ts.isPropertyAssignment(authProp) || !ts.isIdentifier(authProp.name))
+        if (
+          !ts.isPropertyAssignment(authProp) ||
+          !ts.isIdentifier(authProp.name)
+        )
           continue
         if (
           authProp.name.text === 'credentialId' &&

package/src/add/add-workflow-graph-foreach.test.ts

@@ -0,0 +1,174 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { InspectorLogger } from '../types.js'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+async function inspectGraph(graphSource: string[], graphName: string) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-foreach-'))
+  const stepFile = join(rootDir, 'my.steps.ts')
+  const graphFile = join(rootDir, 'my.graph.ts')
+
+  await writeFile(
+    stepFile,
+    [
+      "import { pikkuSessionlessFunc } from '@pikku/core'",
+      'export const listRows = pikkuSessionlessFunc({ func: async () => ({ rows: [] }) })',
+      'export const postVideo = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+    ].join('\n')
+  )
+  await writeFile(graphFile, graphSource.join('\n'))
+
+  try {
+    const state = await inspect(makeLogger(), [stepFile, graphFile], {
+      rootDir,
+    })
+    const graph = state.workflows.graphMeta[graphName]
+    assert.ok(graph, `graph meta '${graphName}' should be registered`)
+    return graph
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('addWorkflowGraph — forEach extraction', () => {
+  test('forEach node id and $item() lower into the serialized meta', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'foreach-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        "      forEach: 'listRows',",
+        '      input: (ref, template, $item) => ({',
+        "        url: $item('URL VIDEO'),",
+        '        whole: $item(),',
+        "        listed: ref('listRows'),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'foreach-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.deepEqual(node.forEach, { $ref: 'listRows' })
+    assert.equal(node.mode, undefined)
+    assert.deepEqual(node.input, {
+      url: { $ref: '$item', path: 'URL VIDEO' },
+      whole: { $ref: '$item', path: undefined },
+      listed: { $ref: 'listRows', path: undefined },
+    })
+  })
+
+  test('forEach accepts a (ref) callback with a path, plus a sequential mode', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'foreach-callback-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        "      forEach: (ref) => ref('listRows', 'rows'),",
+        "      mode: 'sequential',",
+        "      input: (ref, template, $item) => ({ url: $item('URL') }),",
+        '    },',
+        '  },',
+        '})',
+      ],
+      'foreach-callback-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.deepEqual(node.forEach, { $ref: 'listRows', path: 'rows' })
+    assert.equal(node.mode, 'sequential')
+  })
+
+  test('an existing (ref) => ... node keeps its exact input and gains no forEach', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        "import { template } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'plain-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        '      input: (ref) => ({',
+        "        rows: ref('listRows', 'rows'),",
+        "        label: template('rows: $0', [ref('listRows', 'rows')]),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'plain-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.equal(node.forEach, undefined)
+    assert.equal(node.mode, undefined)
+    assert.deepEqual(node.input, {
+      rows: { $ref: 'listRows', path: 'rows' },
+      label: {
+        $template: {
+          parts: ['rows: ', ''],
+          expressions: [{ $ref: 'listRows', path: 'rows' }],
+        },
+      },
+    })
+  })
+
+  test('an existing (ref, template) => ... node still resolves template from the 2nd param', async () => {
+    const graph = await inspectGraph(
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'two-param-graph',",
+        "  nodes: { listRows: 'listRows', postVideo: 'postVideo' },",
+        '  config: {',
+        "    listRows: { next: 'postVideo' },",
+        '    postVideo: {',
+        '      input: (ref, template) => ({',
+        "        label: template('rows: $0', [ref('listRows', 'rows')]),",
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ],
+      'two-param-graph'
+    )
+
+    const node = graph.nodes['postVideo'] as any
+    assert.equal(node.forEach, undefined)
+    assert.deepEqual(node.input, {
+      label: {
+        $template: {
+          parts: ['rows: ', ''],
+          expressions: [{ $ref: 'listRows', path: 'rows' }],
+        },
+      },
+    })
+  })
+})

package/src/add/add-workflow-graph.ts

@@ -10,7 +10,8 @@ import type {
 function extractAstValue(
   expr: ts.Expression,
   refParamName: string,
-  templateParamName: string | undefined
+  templateParamName: string | undefined,
+  itemParamName?: string
 ): unknown {
   // `'GET' as const` / parenthesised values wrap the real initializer — see
   // through them or the whole property is silently dropped from the meta.
@@ -43,6 +44,12 @@ function extractAstValue(
           args[1] && ts.isStringLiteral(args[1]) ? args[1].text : undefined
         return { $ref: nodeId, path } as DataRef
       }
+      if (itemParamName && callee.text === itemParamName) {
+        const pathArg = expr.arguments[0]
+        const path =
+          pathArg && ts.isStringLiteral(pathArg) ? pathArg.text : undefined
+        return { $ref: '$item', path } as DataRef
+      }
       if (templateParamName && callee.text === templateParamName) {
         const templateStr =
           expr.arguments[0] && ts.isStringLiteral(expr.arguments[0])
@@ -55,7 +62,8 @@ function extractAstValue(
             const resolved = extractAstValue(
               el,
               refParamName,
-              templateParamName
+              templateParamName,
+              itemParamName
             )
             if (
               typeof resolved === 'object' &&
@@ -84,7 +92,7 @@ function extractAstValue(
   }
   if (ts.isArrayLiteralExpression(expr)) {
     return expr.elements.map((el) =>
-      extractAstValue(el, refParamName, templateParamName)
+      extractAstValue(el, refParamName, templateParamName, itemParamName)
     )
   }
   if (ts.isObjectLiteralExpression(expr)) {
@@ -100,7 +108,8 @@ function extractAstValue(
       obj[key] = extractAstValue(
         prop.initializer,
         refParamName,
-        templateParamName
+        templateParamName,
+        itemParamName
       )
     }
     return obj
@@ -160,6 +169,13 @@ function extractInputMapping(
       ? node.parameters[1].name.text
       : 'template'
 
+  // `$item` is appended after `template` so neither existing arrow shape —
+  // `(ref) => ...` nor `(ref, template) => ...` — shifts a parameter.
+  const itemParamName =
+    node.parameters.length > 2 && ts.isIdentifier(node.parameters[2].name)
+      ? node.parameters[2].name.text
+      : undefined
+
   const input: Record<string, unknown | DataRef> = {}
 
   for (const prop of bodyObj.properties) {
@@ -176,7 +192,8 @@ function extractInputMapping(
     const value = extractAstValue(
       prop.initializer,
       refParamName,
-      templateParamName
+      templateParamName,
+      itemParamName
     )
     if (value !== undefined) {
       input[key] = value
@@ -186,6 +203,49 @@ function extractInputMapping(
   return input
 }
 
+/**
+ * Extract a `forEach` source, authored either as a bare node id (`'listRows'`)
+ * or as a callback returning a ref (`(ref) => ref('listRows', 'rows')`).
+ */
+function extractForEachConfig(node: ts.Node): DataRef | undefined {
+  while (ts.isAsExpression(node) || ts.isParenthesizedExpression(node)) {
+    node = node.expression
+  }
+
+  if (ts.isStringLiteral(node)) {
+    return { $ref: node.text }
+  }
+
+  if (ts.isArrowFunction(node)) {
+    const refParamName =
+      node.parameters.length > 0 && ts.isIdentifier(node.parameters[0].name)
+        ? node.parameters[0].name.text
+        : 'ref'
+
+    let body: ts.Node = node.body
+    if (ts.isBlock(body)) {
+      for (const stmt of body.statements) {
+        if (ts.isReturnStatement(stmt) && stmt.expression) {
+          body = stmt.expression
+        }
+      }
+    }
+    if (!ts.isExpression(body)) return undefined
+
+    const value = extractAstValue(body, refParamName, undefined)
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      '$ref' in value &&
+      typeof (value as DataRef).$ref === 'string'
+    ) {
+      return value as DataRef
+    }
+  }
+
+  return undefined
+}
+
 /**
  * Extract next config (string, array, or record)
  */
@@ -380,6 +440,8 @@ function extractGraphFromNewFormat(
       nodeId,
       rpcName,
       input: {},
+      forEach: undefined,
+      mode: undefined,
       next: undefined,
       onError: undefined,
       retries: undefined,
@@ -410,6 +472,8 @@ function extractGraphFromNewFormat(
           nodes[nodeId].next = nodeConfig.next
           nodes[nodeId].onError = nodeConfig.onError
           nodes[nodeId].input = nodeConfig.input
+          nodes[nodeId].forEach = nodeConfig.forEach
+          nodes[nodeId].mode = nodeConfig.mode
           nodes[nodeId].retries = nodeConfig.retries
           nodes[nodeId].retryDelay = nodeConfig.retryDelay
           nodes[nodeId].notes = nodeConfig.notes
@@ -431,6 +495,8 @@ function extractNodeConfigFromObject(
   next: any
   onError: any
   input: Record<string, any>
+  forEach: DataRef | undefined
+  mode: string | undefined
   retries: number | undefined
   retryDelay: string | number | undefined
   notes: string | undefined
@@ -438,6 +504,8 @@ function extractNodeConfigFromObject(
   let next: any = undefined
   let onError: any = undefined
   let input: Record<string, any> = {}
+  let forEach: DataRef | undefined = undefined
+  let mode: string | undefined = undefined
   let retries: number | undefined = undefined
   let retryDelay: string | number | undefined = undefined
   let notes: string | undefined = undefined
@@ -453,6 +521,10 @@ function extractNodeConfigFromObject(
       onError = extractNextConfig(prop.initializer, checker)
     } else if (propName === 'input') {
       input = extractInputMapping(prop.initializer, checker)
+    } else if (propName === 'forEach') {
+      forEach = extractForEachConfig(prop.initializer)
+    } else if (propName === 'mode') {
+      mode = extractStringLiteral(prop.initializer, checker)
     } else if (propName === 'retries') {
       if (ts.isNumericLiteral(prop.initializer)) {
         retries = Number(prop.initializer.text)
@@ -468,7 +540,7 @@ function extractNodeConfigFromObject(
     }
   }
 
-  return { next, onError, input, retries, retryDelay, notes }
+  return { next, onError, input, forEach, mode, retries, retryDelay, notes }
 }
 
 /**

package/src/add/add-workflow-sleep-expression.test.ts

@@ -77,10 +77,9 @@ describe('sleep with a duration that is not a literal', () => {
 
   test('a literal duration still round-trips as a value', async () => {
     const { graph, diags } = await run(
-      [
-        "  await workflow.sleep('Wait', '5s')",
-        '  return { sent: true }',
-      ].join('\n')
+      ["  await workflow.sleep('Wait', '5s')", '  return { sent: true }'].join(
+        '\n'
+      )
     )
 
     assert.deepEqual(diags, [])

package/src/add/addon-contracts.test.ts

@@ -178,7 +178,7 @@ describe('addon contract metadata', () => {
     await writeFile(
       appFile,
       [
-        "import { wireAddon } from '@pikku/core/rpc'",
+        "import { wireAddon } from '@pikku/core/addon'",
         "import { wireHTTPRoutes } from '@pikku/core/http'",
         "import { wireChannel } from '@pikku/core/channel'",
         "import { wireCLI } from '@pikku/core/cli'",

package/src/add/config-value-metadata.test.ts

@@ -167,3 +167,97 @@ describe('config value metadata (docsUrl)', () => {
     }
   })
 })
+
+/**
+ * `optional` and `required` are the deploy gate's whole input. A flag the
+ * inspector drops leaves the gate seeing a bare declaration, which is how an
+ * optional secret suspends a deploy over a value production is meant NOT to
+ * have.
+ */
+describe('config value gating flags', () => {
+  test('carries optional from defineSecret into the definition', async () => {
+    const rootDir = await mkdtemp(`${fixtureRoot}-secret-optional-`)
+    const file = join(rootDir, 'secret.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { defineSecret } from '@pikku/core'",
+        "import { z } from 'zod'",
+        'export const ActorSchema = z.string()',
+        'export const StripeSchema = z.string()',
+        'defineSecret({',
+        "  name: 'scenarioActor',",
+        "  displayName: 'Scenario Actor Secret',",
+        "  secretId: 'SCENARIO_ACTOR_SECRET',",
+        '  optional: true,',
+        '  schema: ActorSchema,',
+        '})',
+        'defineSecret({',
+        "  name: 'stripe',",
+        "  displayName: 'Stripe',",
+        "  secretId: 'STRIPE_KEY',",
+        '  schema: StripeSchema,',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      const optional = state.secrets.definitions.find(
+        (d) => d.secretId === 'SCENARIO_ACTOR_SECRET'
+      )
+      const required = state.secrets.definitions.find(
+        (d) => d.secretId === 'STRIPE_KEY'
+      )
+      assert.equal(optional!.optional, true)
+      assert.equal(required!.optional, undefined)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('carries required from defineVariable into the definition', async () => {
+    const rootDir = await mkdtemp(`${fixtureRoot}-variable-required-`)
+    const file = join(rootDir, 'variable.ts')
+
+    await writeFile(
+      file,
+      [
+        "import { defineVariable } from '@pikku/core'",
+        "import { z } from 'zod'",
+        'export const ConsoleUrlSchema = z.string()',
+        'export const CorsSchema = z.string()',
+        'defineVariable({',
+        "  name: 'consoleUrl',",
+        "  displayName: 'Console URL',",
+        "  variableId: 'CONSOLE_URL',",
+        '  required: true,',
+        '  schema: ConsoleUrlSchema,',
+        '})',
+        'defineVariable({',
+        "  name: 'corsOrigins',",
+        "  displayName: 'Allowed Browser Origins',",
+        "  variableId: 'CORS_ORIGINS',",
+        '  schema: CorsSchema,',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: ErrorCode; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [file], { rootDir })
+      const required = state.variables.definitions.find(
+        (d) => d.variableId === 'CONSOLE_URL'
+      )
+      const optional = state.variables.definitions.find(
+        (d) => d.variableId === 'CORS_ORIGINS'
+      )
+      assert.equal(required!.required, true)
+      assert.equal(optional!.required, undefined)
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/secret-sink-check.test.ts

@@ -75,7 +75,10 @@ async function runInspect(source: string) {
   await writeFile(file, PRELUDE + source)
   const { logger, diagnostics } = makeLogger()
   try {
-    await inspect(logger, [file], { rootDir: tmpDir, classificationCheck: true })
+    await inspect(logger, [file], {
+      rootDir: tmpDir,
+      classificationCheck: true,
+    })
   } finally {
     await rm(tmpDir, { recursive: true, force: true })
   }

package/src/error-codes.ts

@@ -22,7 +22,7 @@ export enum ErrorCode {
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
   SCENARIO_HAS_SERVICES = 'PKU673',
   EXPECT_EVENTUALLY_SCENARIO_ONLY = 'PKU675',
-  SCENARIO_BROWSER_STEP_NEEDS_ACTOR = 'PKU677',
+  SCENARIO_STEP_NEEDS_ACTOR = 'PKU677',
   SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
   SCENARIO_NOT_EXTRACTABLE = 'PKU679',
   SCENARIO_HAS_NO_ASSERTION = 'PKU680',
@@ -34,6 +34,7 @@ export enum ErrorCode {
   // Remote addon (wireRemoteAddon) validation
   REMOTE_ADDON_NOT_DEV_DEPENDENCY = 'PKU338',
   REMOTE_ADDON_AUTH_UNRESOLVED = 'PKU339',
+  ADDON_NOT_INSTALLED = 'PKU340',
 
   // Database schema codegen warnings
   DB_COLUMN_NAME_TYPE_CONTRADICTION = 'PKU480',
@@ -106,6 +107,7 @@ export enum ErrorCode {
   DUPLICATE_CORE_VERSION = 'PKU717',
   CORE_VERSION_SKEW = 'PKU718',
   SPLIT_TYPE_IDENTITY = 'PKU719',
+  SINGLETON_SERVICES_TYPE_UNRESOLVED = 'PKU724',
 
   // Data classification errors
   PII_IN_OUTPUT = 'PKU910',

package/src/index.ts

@@ -21,6 +21,8 @@ export {
   generateCustomTypes,
   sanitizeTypeName,
 } from './utils/custom-types-generator.js'
+export { unresolvedSchemaReferences } from './utils/post-process.js'
+export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js'
 export {
   createEmptyManifest,
   serializeManifest,
@@ -32,10 +34,7 @@ export type {
   VersionManifest,
   VersionManifestEntry,
 } from './utils/contract-hashes.js'
-export type {
-  InspectorFeature,
-  InspectorFeatureEntry,
-} from './types.js'
+export type { InspectorFeature, InspectorFeatureEntry } from './types.js'
 export { serializeMCPJson } from './utils/serialize-mcp-json.js'
 export type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js'
 export {

package/src/inspector.ts

@@ -1,6 +1,6 @@
 import * as ts from 'typescript'
 import { performance } from 'perf_hooks'
-import { dirname, resolve } from 'path'
+import { dirname, relative, resolve } from 'path'
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 import type {
@@ -42,7 +42,7 @@ import { validateExposedFunctionsGated } from './utils/validate-exposed-function
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js'
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
-import { pikkuState } from '@pikku/core/ecosystem'
+import { pikkuState } from '@pikku/core/state'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js'
 import {
@@ -51,6 +51,10 @@ import {
 } from './utils/workflow/graph/finalize-workflow-wires.js'
 import { generateAllSchemas } from './utils/schema-generator.js'
 import { extractSecretUsage } from './utils/extract-secret-usage.js'
+import {
+  accumulateSurfaceUsage,
+  surfaceUsageArea,
+} from './utils/extract-surface-usage.js'
 import {
   loadAddonFunctionsMeta,
   loadAddonSchemas,
@@ -186,6 +190,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       files: new Set(),
       usage: new Map(),
     },
+    surfaceUsage: {},
     credentials: {
       definitions: [],
       files: new Set(),
@@ -221,7 +226,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       instances: {},
       tagMiddleware: new Map(),
     },
-    aiMiddleware: {
+    agentMiddleware: {
       definitions: {},
     },
     permissions: {
@@ -378,11 +383,23 @@ export const inspect = async (
 
   const state = getInitialInspectorState(rootDir)
 
+  const surfaceAreaCache = new Map<string, string | null>()
   for (const sourceFile of sourceFiles) {
     const usage = extractSecretUsage(sourceFile)
     if (usage.keys.length > 0 || usage.dynamic.length > 0) {
       state.secrets.usage.set(sourceFile.fileName, usage)
     }
+    // Counted in the sweep that already has this file open. The public surface
+    // is documentation, and documentation may not cost a project a second pass
+    // over its source.
+    accumulateSurfaceUsage(
+      sourceFile,
+      {
+        area: surfaceUsageArea(sourceFile.fileName, rootDir, surfaceAreaCache),
+        file: relative(rootDir, sourceFile.fileName),
+      },
+      state.surfaceUsage
+    )
   }
 
   // First sweep: add all functions

package/src/types.ts

@@ -1,5 +1,6 @@
 import type * as ts from 'typescript'
 import type { SecretUsage } from './utils/extract-secret-usage.js'
+import type { SurfaceUsageCounts } from './utils/extract-surface-usage.js'
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel'
 import type { GatewaysMeta } from '@pikku/core/gateway'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
@@ -12,8 +13,8 @@ import type {
   MCPToolMeta,
   MCPPromptMeta,
 } from '@pikku/core/mcp'
-import type { AIAgentMeta } from '@pikku/core/ai-agent'
-import type { ScorerMeta } from '@pikku/core/ai-scorer'
+import type { AgentsMeta } from '@pikku/core/agent'
+import type { ScorerMeta } from '@pikku/core/agent-scorer'
 import type { CLIMeta } from '@pikku/core/cli'
 import type { CLICommandMeta } from '@pikku/core/cli'
 import type { NodesMeta } from '@pikku/core/node'
@@ -24,12 +25,12 @@ import type { SystemRoleDefinitions } from '@pikku/core/role'
 import type { PersonaDefinitions } from '@pikku/core/persona'
 import type { VariableDefinitions } from '@pikku/core/variable'
 import type { TypesMap } from './types-map.js'
+import type { FunctionsMeta } from '@pikku/core/services'
 import type {
-  FunctionsMeta,
   FunctionServicesMeta,
   FunctionWiresMeta,
-  JSONValue,
-} from '@pikku/core'
+} from '@pikku/core/function'
+import type { JSONValue } from '@pikku/core/utils'
 import type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js'
 import type { ErrorCode, CodedDiagnostic } from './error-codes.js'
 import type {
@@ -613,7 +614,7 @@ export interface InspectorState {
     files: Set<string>
   }
   agents: {
-    agentsMeta: AIAgentMeta
+    agentsMeta: AgentsMeta
     files: Map<string, { path: string; exportedName: string }>
   }
   scorers: {
@@ -654,6 +655,8 @@ export interface InspectorState {
     /** Secret reads found per source file, keyed by absolute path. */
     usage: Map<string, SecretUsage>
   }
+  /** How often each `#pikku/*` export is imported, and from where. */
+  surfaceUsage: SurfaceUsageCounts
   credentials: {
     definitions: CredentialDefinitions
     files: Set<string>
@@ -681,7 +684,7 @@ export interface InspectorState {
   }
   middleware: InspectorMiddlewareState
   channelMiddleware: InspectorChannelMiddlewareState
-  aiMiddleware: InspectorAIMiddlewareState
+  agentMiddleware: InspectorAIMiddlewareState
   permissions: InspectorPermissionState
   serviceAggregation: {
     requiredServices: Set<string>