@pikku/inspector 0.12.70 → 0.12.73

package/src/source-file-cache.ts

@@ -0,0 +1,73 @@
+import * as ts from 'typescript'
+import { createHash } from 'crypto'
+
+/**
+ * Parsed source files, kept across programs so a re-inspection only re-parses
+ * what changed. Keyed by path; an entry is valid while the file's content
+ * hash matches.
+ *
+ * This is the incremental reuse `oldProgram` used to give, without its cost.
+ * Passing the previous ts.Program keeps that program reachable, and a program
+ * memoises its type checker — so every re-inspection held a second, fully
+ * exercised checker for the sake of skipping a re-parse. A bare SourceFile
+ * carries its AST and binder symbols and nothing else; sharing it between
+ * programs is what the language service's document registry does.
+ *
+ * Module-level on purpose: `inspect()` is called several times per `pikku all`
+ * (and indefinitely in watch mode) from one process, and the cache is only
+ * worth having if it outlives the call.
+ */
+const cache = new Map<string, { hash: string; file: ts.SourceFile }>()
+
+export interface SourceFileCacheHost extends ts.CompilerHost {
+  /** Files served from the cache by the program just built. */
+  readonly reused: () => number
+  /**
+   * Drop entries the program did not use, so a file that left the project
+   * (or watch mode's churn) does not pin its AST forever.
+   */
+  readonly prune: (program: ts.Program) => void
+}
+
+export const createSourceFileCacheHost = (
+  options: ts.CompilerOptions
+): SourceFileCacheHost => {
+  const host = ts.createCompilerHost(options, true)
+  let reused = 0
+
+  host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+    let text: string | undefined
+    try {
+      text = host.readFile(fileName)
+    } catch (e) {
+      onError?.(e instanceof Error ? e.message : String(e))
+      return undefined
+    }
+    if (text === undefined) return undefined
+
+    const hash = createHash('sha1').update(text).digest('hex')
+    const hit = cache.get(fileName)
+    if (hit && hit.hash === hash) {
+      reused++
+      return hit.file
+    }
+    const file = ts.createSourceFile(
+      fileName,
+      text,
+      languageVersionOrOptions,
+      true
+    )
+    cache.set(fileName, { hash, file })
+    return file
+  }
+
+  return Object.assign(host, {
+    reused: () => reused,
+    prune: (program: ts.Program) => {
+      const live = new Set(program.getSourceFiles().map((sf) => sf.fileName))
+      for (const fileName of cache.keys()) {
+        if (!live.has(fileName)) cache.delete(fileName)
+      }
+    },
+  })
+}

package/src/types.ts

@@ -290,6 +290,27 @@ export type AddonConfig = {
   forceInclude?: boolean
 }
 
+export interface InspectorPassStats {
+  /** Source files in the ts.Program, node_modules and lib included. */
+  files: number
+  /** Files under rootDir the inspector actually swept. */
+  projectFiles: number
+  /**
+   * Files served from the source-file cache without re-parsing. Zero on a
+   * first pass; on a re-inspection it should be nearly all of `files` — that
+   * reuse is what keeps a re-inspection cheaper than a cold one.
+   */
+  filesReused: number
+  /** Checker work, as `tsc --extendedDiagnostics` counts it. */
+  types: number
+  instantiations: number
+  symbols: number
+  cpuMs: number
+  wallMs: number
+  /** V8 heap in use when the pass finished, before any GC. */
+  heapUsedMb: number
+}
+
 export type InspectorOptions = Partial<{
   setupOnly: boolean
   rootDir: string
@@ -526,12 +547,20 @@ export interface InspectorState {
   wireServicesFactories: PathToNameAndType
   wireServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   addonRequiredParentServices: string[] // services an addon needs from the parent (extracted from pikkuAddonServices 2nd param)
+  addonCreatedServices: string[] // services an addon's own pikkuAddonServices factory builds itself
+  addonServicesFactorySeen: boolean // this project declares a pikkuAddonServices factory, i.e. it is an addon
   addonServerlessIncompatible: Map<string, string[]> // namespace → service names that are serverless-incompatible (scoped per addon)
   configFactories: PathToNameAndType
   serverLifecycleFactories: PathToNameAndType
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
   typesLookup: Map<string, ts.Type[]> // Lookup for types by name (e.g., function input types, Config type)
+  /**
+   * What this pass cost, in counts rather than time where it can be counted:
+   * counts don't move with the machine, so they are what a perf gate can
+   * compare across runners (see benchmarks/bench-codegen-perf.ts).
+   */
+  stats?: InspectorPassStats
   schemaLookup: Map<string, SchemaRef> // Lookup for schemas by name for deferred JSON Schema conversion (supports Standard Schema vendors)
   schemas: Record<string, JSONValue>
   http: InspectorHTTPState
@@ -634,6 +663,16 @@ export interface InspectorState {
   agents: {
     agentsMeta: AgentsMeta
     files: Map<string, { path: string; exportedName: string }>
+    /**
+     * Agent registry keys named by a `runAgent`/`rpc.agent.run` call in a
+     * function body, keyed by the file the call was written in.
+     *
+     * The lookup those calls perform is in-process, so the agent has to be
+     * registered in the same deployment unit as its caller. Without this the
+     * deploy analyzer only ever saw an agent as its own unit, and a caller in
+     * another unit failed at run time with "AI agent not found".
+     */
+    invokedAgentsByFile: Map<string, Set<string>>
   }
   scorers: {
     scorersMeta: ScorerMeta

package/src/utils/filter-inspector-state.test.ts

@@ -2063,3 +2063,145 @@ describe('Workflow file pruning', () => {
     assert.equal(Object.keys(state.workflows.graphMeta).length, 2)
   })
 })
+
+describe('invokedAgentsByFile', () => {
+  test('round-trips through serialize/deserialize', () => {
+    const state = getInitialInspectorState('/test/project')
+    state.agents.invokedAgentsByFile = new Map([
+      ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+      [
+        '/test/project/src/api/tasks.ts',
+        new Set(['houseAssistant', 'gardenAssistant']),
+      ],
+    ])
+    const restored = deserializeInspectorState(
+      JSON.parse(JSON.stringify(serializeInspectorState(state as any)))
+    )
+    assert.ok(restored.agents.invokedAgentsByFile instanceof Map)
+    assert.strictEqual(restored.agents.invokedAgentsByFile.size, 2)
+    assert.deepStrictEqual(
+      [
+        ...restored.agents.invokedAgentsByFile.get(
+          '/test/project/src/api/tasks.ts'
+        )!,
+      ].sort(),
+      ['gardenAssistant', 'houseAssistant']
+    )
+  })
+
+  test('deserializing legacy state without the field yields an empty Map', () => {
+    const serialized = JSON.parse(
+      JSON.stringify(
+        serializeInspectorState(
+          getInitialInspectorState('/test/project') as any
+        )
+      )
+    )
+    delete serialized.agents.invokedAgentsByFile
+    const restored = deserializeInspectorState(serialized)
+    assert.ok(restored.agents.invokedAgentsByFile instanceof Map)
+    assert.strictEqual(restored.agents.invokedAgentsByFile.size, 0)
+  })
+
+  test('the filtered map is a clone, not the original', () => {
+    const state = createMockInspectorState()
+    state.agents = {
+      agentsMeta: {},
+      files: new Map(),
+      invokedAgentsByFile: new Map([
+        ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+      ]),
+    }
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    filtered.agents.invokedAgentsByFile.clear()
+    assert.strictEqual(state.agents.invokedAgentsByFile.size, 1)
+  })
+
+  test('keeps the entry of a kept function file and prunes the rest', () => {
+    const state = createMockInspectorState()
+    state.agents = {
+      agentsMeta: {},
+      files: new Map(),
+      invokedAgentsByFile: new Map([
+        ['/test/project/src/api/users.ts', new Set(['houseAssistant'])],
+        ['/test/project/src/admin/settings.ts', new Set(['adminAssistant'])],
+      ]),
+    }
+    const filtered = filterInspectorState(
+      state,
+      { names: ['getUsers'] },
+      mockLogger
+    )
+    assert.deepStrictEqual(
+      [...filtered.agents.invokedAgentsByFile.keys()],
+      ['/test/project/src/api/users.ts']
+    )
+  })
+
+  describe('Wired addon retention', () => {
+    // A unit that owns the generic `/rpc/:rpcName` catch-all (the rpcCaller
+    // unit, and agent units) dispatches arbitrary RPCs at runtime via
+    // `rpc.exposed(name)`, including namespaced addon RPCs like
+    // `admin:createUser`. No app-local function statically references those
+    // ids, so the catch-all must be enough to keep every wired addon's
+    // declaration — otherwise the per-unit bootstrap omits the addon package
+    // bootstrap and `rpc.exposed('admin:createUser')` throws RPCNotFoundError
+    // on a deployed stage.
+    const withAddons = () => {
+      const state = createMockInspectorState()
+      state.rpc.wireAddonDeclarations = new Map([
+        ['admin', { package: '@pikku/addon-admin' } as any],
+        ['console', { package: '@pikku/addon-console' } as any],
+      ])
+      state.rpc.usedAddons = new Set(['admin', 'console'])
+      return state
+    }
+
+    test('keeps all wired addons for a unit with the /rpc/:rpcName catch-all', () => {
+      const result = filterInspectorState(
+        withAddons(),
+        { names: ['/rpc/:rpcName', 'http:post:/rpc/:rpcName', 'rpcCaller'] },
+        mockLogger
+      )
+      assert.deepStrictEqual(
+        [...result.rpc.wireAddonDeclarations.keys()].sort(),
+        ['admin', 'console']
+      )
+      assert.deepStrictEqual([...result.rpc.usedAddons].sort(), [
+        'admin',
+        'console',
+      ])
+    })
+
+    test('drops wired addons for a unit without the catch-all that references no namespace', () => {
+      const result = filterInspectorState(
+        withAddons(),
+        { names: ['getUsers'] },
+        mockLogger
+      )
+      assert.deepStrictEqual([...result.rpc.wireAddonDeclarations.keys()], [])
+      assert.deepStrictEqual([...result.rpc.usedAddons], [])
+    })
+
+    test('still keeps an addon a surviving function statically references, without the catch-all', () => {
+      const state = withAddons()
+      state.serviceAggregation.usedFunctions.add('getUsers')
+      state.rpc.invokedFunctionsByFile = new Map([
+        ['/test/project/src/api/users.ts', new Set(['admin:createUser'])],
+      ])
+      const result = filterInspectorState(
+        state,
+        { names: ['getUsers'] },
+        mockLogger
+      )
+      assert.deepStrictEqual(
+        [...result.rpc.wireAddonDeclarations.keys()],
+        ['admin']
+      )
+    })
+  })
+})

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

@@ -507,6 +507,15 @@ export function filterInspectorState(
       ...state.agents,
       agentsMeta: JSON.parse(JSON.stringify(state.agents?.agentsMeta ?? {})),
       files: new Map(),
+      invokedAgentsByFile: new Map(
+        [
+          ...(state.agents?.invokedAgentsByFile ??
+            new Map<string, Set<string>>()),
+        ].map(([file, agents]): [string, Set<string>] => [
+          file,
+          new Set(agents),
+        ])
+      ),
     },
     // Scorers carry through every filter. They are named by the agents that
     // survive it, and a deployment that quietly stopped grading would look
@@ -1210,6 +1219,16 @@ export function filterInspectorState(
     filteredState.serviceAggregation.requiredServices.add('queueService')
   }
 
+  const keptFunctionFiles = new Set<string>()
+  for (const file of filteredState.functions.files.values()) {
+    if (file?.path) keptFunctionFiles.add(file.path)
+  }
+  for (const file of filteredState.agents.invokedAgentsByFile.keys()) {
+    if (!keptFunctionFiles.has(file)) {
+      filteredState.agents.invokedAgentsByFile.delete(file)
+    }
+  }
+
   if ((filteredState.rpc.wireAddonDeclarations?.size ?? 0) > 0) {
     const referencedIds = new Set<string>(
       filteredState.serviceAggregation.usedFunctions
@@ -1239,8 +1258,21 @@ export function filterInspectorState(
     ) as Array<{ tools?: string[] }>) {
       for (const tool of agentMeta.tools ?? []) referencedIds.add(tool)
     }
+    // A unit carrying the generic `/rpc/:rpcName` catch-all (the rpcCaller
+    // unit, and agent units) dispatches arbitrary RPCs at runtime via
+    // `rpc.exposed(name)`, including namespaced addon RPCs (e.g.
+    // `admin:createUser`). Those never appear in referencedIds because no
+    // app-local function statically references them, so keep every wired
+    // addon's declaration for such units — otherwise the per-unit bootstrap
+    // omits the addon package bootstrap and `rpc.exposed('admin:createUser')`
+    // throws RPCNotFoundError on the deployed stage.
+    const hasRpcCatchAll = (filters.names ?? []).includes('/rpc/:rpcName')
     const keptNamespaces = new Set<string>()
     for (const namespace of filteredState.rpc.wireAddonDeclarations.keys()) {
+      if (hasRpcCatchAll) {
+        keptNamespaces.add(namespace)
+        continue
+      }
       const prefix = `${namespace}:`
       for (const id of referencedIds) {
         if (id.startsWith(prefix)) {

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

@@ -13,6 +13,7 @@ import {
   validateAgentToolReferences,
   validateAgentModels,
   validateSchemaReferences,
+  proseOpensWithActor,
 } from './post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorState, InspectorLogger } from '../types.js'
@@ -1050,3 +1051,44 @@ describe('validateSchemaReferences', () => {
     assert.match(diagnostics[0]!.message, /2 function contracts name a schema/)
   })
 })
+
+describe('proseOpensWithActor', () => {
+  test('a quoted actor opening the prose doubles the subject', () => {
+    assert.equal(
+      proseOpensWithActor(`'sam' creates the browser-journey client`, 'sam'),
+      true
+    )
+  })
+
+  test('quotes and case are decoration, not the point', () => {
+    assert.equal(proseOpensWithActor('Sam creates the client', 'sam'), true)
+    assert.equal(proseOpensWithActor('sam creates the client', 'sam'), true)
+    assert.equal(proseOpensWithActor(`"sam" creates the client`, 'sam'), true)
+  })
+
+  test("an actor's own possessive is still the doubled subject", () => {
+    assert.equal(proseOpensWithActor("sam's client is created", 'sam'), true)
+  })
+
+  test('naming someone mid-sentence is ordinary prose', () => {
+    assert.equal(proseOpensWithActor('sends sam an invite', 'sam'), false)
+  })
+
+  // A persona keyed after a role noun must keep the word as a word: refusing
+  // "creates the admin client" for an actor called `admin` would make the
+  // check the reason to rename the persona.
+  test('an actor key that is also a common noun is only refused as the subject', () => {
+    assert.equal(
+      proseOpensWithActor('creates the admin client', 'admin'),
+      false
+    )
+    assert.equal(proseOpensWithActor('admin creates the client', 'admin'), true)
+  })
+
+  test('a longer name starting with the actor key is a different person', () => {
+    assert.equal(
+      proseOpensWithActor('samantha creates the client', 'sam'),
+      false
+    )
+  })
+})

package/src/utils/post-process.ts

@@ -22,6 +22,7 @@ import { relative } from 'node:path'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
 import { flattenScopeDefinitions } from '@pikku/core/scope'
 import type { WorkflowStepMeta } from '@pikku/core/workflow'
+import type { ScenarioStepMeta } from '@pikku/core/scenario'
 import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js'
 
 /**
@@ -381,6 +382,35 @@ export function aggregateRequiredServices(
       requiredServices.add(service)
     }
   }
+
+  // 8. When this project IS an addon, what it needs from its parent is whatever
+  // its functions use minus whatever its own factory builds. Reading only the
+  // factory's second parameter missed everything the functions destructure and
+  // the factory never names — `kysely` above all — which left the contract empty
+  // and let a consumer omit it and fail at the first query instead of at build.
+  if (state.addonServicesFactorySeen) {
+    // Every function an addon declares is part of its published surface — a
+    // consumer calls it — so none of them are reachable from a local wiring and
+    // `usedFunctions` is empty. Aggregating only from wirings left the services
+    // map claiming an addon needs nothing, which is what drove addons to list
+    // their own services under `forceRequiredServices` by hand.
+    for (const funcMeta of Object.values(state.functions.meta)) {
+      addServices(funcMeta?.services)
+    }
+
+    const createdSet = new Set(state.addonCreatedServices ?? [])
+    const parentServices = new Set(parentDeclared)
+    for (const service of requiredServices) {
+      if (
+        !createdSet.has(service) &&
+        !internalServices.has(service) &&
+        !defaultServices.has(service)
+      ) {
+        parentServices.add(service)
+      }
+    }
+    state.addonRequiredParentServices = [...parentServices]
+  }
 }
 
 export function validateSecretOverrides(
@@ -911,6 +941,85 @@ export function validateScenarioServices(
   }
 }
 
+/**
+ * Does this step's prose open by naming the actor who is already its subject?
+ *
+ * `composeStepProse` renders the actor as the sentence's subject, so a step
+ * authored as `'sam' creates the client` reads "Given sam 'sam' creates the
+ * client". Only the subject position counts: a persona keyed after a role noun
+ * ("admin") must still be able to say "creates the admin client", and naming
+ * someone mid-sentence — "sends sam an invite" — is ordinary prose.
+ */
+export const proseOpensWithActor = (prose: string, actor: string): boolean => {
+  if (!actor) {
+    return false
+  }
+  const escaped = actor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^["'“‘\\s]*${escaped}(?:['’]s)?\\b`, 'i').test(prose)
+}
+
+/**
+ * The prose that will actually render for one step, in the runtime's own
+ * precedence: a call-site description overrides the step's template, which
+ * overrides its declared description, which falls back to the durable name.
+ *
+ * Every candidate is returned rather than only the winner, because a template
+ * is authored where the actor is not yet known — so it is wrong at every call
+ * site that runs it as the persona it names, not just the winning one.
+ */
+const renderableProse = (
+  step: ScenarioStepMeta,
+  stepMeta: { description?: string; scenarioStepTemplate?: string } | undefined
+): string[] => {
+  const description = step.options?.description
+  if (description) {
+    return [step.stepName, description]
+  }
+  return [
+    step.stepName,
+    stepMeta?.scenarioStepTemplate,
+    stepMeta?.description,
+  ].filter((prose): prose is string => typeof prose === 'string')
+}
+
+/**
+ * A step's prose must not open by naming the actor it already runs as (PKU681).
+ *
+ * The reporter renders the actor as the sentence's subject, so `'sam' creates
+ * the client` run as `actors.sam` reads "Given sam 'sam' creates the client" —
+ * and the hardcoded copy silently desyncs the moment the call site changes
+ * actor. Only the subject position is refused; naming someone mid-sentence is
+ * ordinary prose, and a persona keyed after a role noun can still say "creates
+ * the admin client".
+ */
+const validateStepProse = (
+  logger: InspectorLogger,
+  workflowName: string,
+  step: ScenarioStepMeta,
+  stepMeta: { description?: string; scenarioStepTemplate?: string } | undefined
+): void => {
+  const actor = step.actor
+  if (!actor) {
+    return
+  }
+  const offender = renderableProse(step, stepMeta).find((prose) =>
+    proseOpensWithActor(prose, actor)
+  )
+  if (offender === undefined) {
+    return
+  }
+  logger.critical(
+    ErrorCode.SCENARIO_STEP_PROSE_NAMES_ACTOR,
+    `Scenario '${workflowName}' names its actor in the step prose: '${offender}' runs as '${actor}'. ` +
+      `The reporter already renders the actor as the subject, so this reads ` +
+      `"${capitaliseFirst(step.phase)} ${actor} ${offender}". Drop the name and let ` +
+      `{ actor: actors.${actor} } supply it — the step reads as a bare third-person predicate.`
+  )
+}
+
+const capitaliseFirst = (value: string): string =>
+  value.charAt(0).toUpperCase() + value.slice(1)
+
 /**
  * Walk every scenario step, wherever it is nested, and validate the two things
  * that can only be known once both the workflow meta and the function meta
@@ -949,6 +1058,7 @@ export function validateScenarioSteps(
         }
         state.serviceAggregation.usedFunctions.add(step.stepFunc)
         const stepMeta = state.functions.meta[step.stepFunc]
+        validateStepProse(logger, workflowName, step, stepMeta)
         if (stepMeta?.scenarioStepRequiresActor && !step.actor) {
           const why = stepMeta.scenarioStepSurfaces?.includes('browser')
             ? 'declares a browser binding'

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

@@ -51,6 +51,8 @@ export interface SerializableInspectorState {
   >
   wireServicesMeta: Array<[string, string[]]>
   addonRequiredParentServices: string[]
+  addonCreatedServices: string[]
+  addonServicesFactorySeen: boolean
   addonServerlessIncompatible: Array<[string, string[]]>
   configFactories: Array<
     [
@@ -186,6 +188,7 @@ export interface SerializableInspectorState {
     files: string[]
   }
   agents: {
+    invokedAgentsByFile?: Array<[string, string[]]>
     agentsMeta: InspectorState['agents']['agentsMeta']
     files: [string, { path: string; exportedName: string }][]
   }
@@ -335,6 +338,8 @@ export function serializeInspectorState(
     wireServicesFactories: Array.from(state.wireServicesFactories.entries()),
     wireServicesMeta: Array.from(state.wireServicesMeta.entries()),
     addonRequiredParentServices: state.addonRequiredParentServices,
+    addonCreatedServices: state.addonCreatedServices,
+    addonServicesFactorySeen: state.addonServicesFactorySeen,
     addonServerlessIncompatible: Array.from(
       state.addonServerlessIncompatible.entries()
     ),
@@ -417,6 +422,11 @@ export function serializeInspectorState(
     agents: {
       agentsMeta: state.agents?.agentsMeta ?? {},
       files: Array.from(state.agents?.files?.entries() ?? []),
+      invokedAgentsByFile: Array.from(
+        (
+          state.agents?.invokedAgentsByFile ?? new Map<string, Set<string>>()
+        ).entries()
+      ).map(([file, agents]): [string, string[]] => [file, Array.from(agents)]),
     },
     scorers: {
       scorersMeta: state.scorers?.scorersMeta ?? {},
@@ -544,6 +554,8 @@ export function deserializeInspectorState(
     wireServicesFactories: new Map(data.wireServicesFactories),
     wireServicesMeta: new Map(data.wireServicesMeta),
     addonRequiredParentServices: data.addonRequiredParentServices || [],
+    addonCreatedServices: data.addonCreatedServices || [],
+    addonServicesFactorySeen: data.addonServicesFactorySeen ?? false,
     addonServerlessIncompatible: new Map(
       data.addonServerlessIncompatible || []
     ),
@@ -626,6 +638,11 @@ export function deserializeInspectorState(
     agents: {
       agentsMeta: data.agents?.agentsMeta || {},
       files: new Map(data.agents?.files || []),
+      invokedAgentsByFile: new Map(
+        (data.agents?.invokedAgentsByFile || []).map(
+          ([file, agents]): [string, Set<string>] => [file, new Set(agents)]
+        )
+      ),
     },
     scorers: {
       scorersMeta: data.scorers?.scorersMeta || {},