@pikku/inspector 0.12.70 → 0.12.72

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

@@ -13,6 +13,106 @@ const wrapperFunctionMap: Record<string, string> = {
   pikkuServerLifecycle: 'ServerLifecycle',
 }
 
+/**
+ * What an addon's `pikkuAddonServices` factory takes from the parent: the names
+ * destructured off its second parameter, either in the parameter list or from a
+ * `const { … } = existingServices` in the body.
+ */
+const extractForwardedServices = (
+  functionNode: ts.ArrowFunction | ts.FunctionExpression
+): string[] => {
+  const forwarded: string[] = []
+  const secondParam = functionNode.parameters[1]
+  if (!secondParam) return forwarded
+
+  const collectBinding = (pattern: ts.ObjectBindingPattern) => {
+    for (const elem of pattern.elements) {
+      if (elem.dotDotDotToken) continue
+      const name =
+        elem.propertyName && ts.isIdentifier(elem.propertyName)
+          ? elem.propertyName.text
+          : ts.isIdentifier(elem.name)
+            ? elem.name.text
+            : undefined
+      if (name) forwarded.push(name)
+    }
+  }
+
+  if (ts.isObjectBindingPattern(secondParam.name)) {
+    collectBinding(secondParam.name)
+    return forwarded
+  }
+
+  if (!ts.isIdentifier(secondParam.name)) return forwarded
+  const paramName = secondParam.name.text
+  const body = functionNode.body
+  if (!ts.isBlock(body)) return forwarded
+
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isVariableDeclaration(node) &&
+      ts.isObjectBindingPattern(node.name) &&
+      node.initializer &&
+      ts.isIdentifier(node.initializer) &&
+      node.initializer.text === paramName
+    ) {
+      collectBinding(node.name)
+    }
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(body, visit)
+
+  return forwarded
+}
+
+/**
+ * The service names the factory's returned object literals name. A spread is
+ * skipped — it carries the parent's bag through rather than naming anything —
+ * and a name the factory took off the parent is a forward, not a creation.
+ */
+const extractReturnedServices = (
+  functionNode: ts.ArrowFunction | ts.FunctionExpression
+): string[] => {
+  const returned: string[] = []
+
+  const collect = (expression: ts.Expression) => {
+    while (ts.isParenthesizedExpression(expression)) {
+      expression = expression.expression
+    }
+    if (!ts.isObjectLiteralExpression(expression)) return
+    for (const property of expression.properties) {
+      if (ts.isSpreadAssignment(property)) continue
+      const name = property.name
+      if (name && (ts.isIdentifier(name) || ts.isStringLiteral(name))) {
+        returned.push(name.text)
+      }
+    }
+  }
+
+  const body = functionNode.body
+  if (!ts.isBlock(body)) {
+    collect(body)
+    return returned
+  }
+
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node)
+    ) {
+      return
+    }
+    if (ts.isReturnStatement(node) && node.expression) {
+      collect(node.expression)
+    }
+    ts.forEachChild(node, visit)
+  }
+  ts.forEachChild(body, visit)
+
+  return returned
+}
+
 export const addFileWithFactory = (
   node: ts.Node,
   checker: ts.TypeChecker,
@@ -77,23 +177,15 @@ export const addFileWithFactory = (
 
             // Extract existing services an addon needs from the parent
             // (second parameter of pikkuAddonServices callback)
-            if (
-              wrapperFunctionName === 'pikkuAddonServices' &&
-              functionNode &&
-              functionNode.parameters.length >= 2
-            ) {
-              const secondParam = functionNode.parameters[1]
-              if (secondParam && ts.isObjectBindingPattern(secondParam.name)) {
-                for (const elem of secondParam.name.elements) {
-                  const name =
-                    elem.propertyName && ts.isIdentifier(elem.propertyName)
-                      ? elem.propertyName.text
-                      : ts.isIdentifier(elem.name)
-                        ? elem.name.text
-                        : undefined
-                  if (name) {
-                    state.addonRequiredParentServices.push(name)
-                  }
+            if (wrapperFunctionName === 'pikkuAddonServices' && functionNode) {
+              state.addonServicesFactorySeen = true
+              const forwarded = new Set(extractForwardedServices(functionNode))
+              for (const name of forwarded) {
+                state.addonRequiredParentServices.push(name)
+              }
+              for (const name of extractReturnedServices(functionNode)) {
+                if (!forwarded.has(name)) {
+                  state.addonCreatedServices.push(name)
                 }
               }
             }

package/src/add/add-rpc-invocations.test.ts

@@ -161,3 +161,127 @@ export async function doWork() {
     }
   })
 })
+
+describe('add-rpc-invocations — invokedAgentsByFile', () => {
+  test('a body-level runAgent() is attributed to its source file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+export async function askTheHouse() {
+  return runAgent('houseAssistant', { message: 'hi' })
+}
+`,
+      'other.ts': `
+export const unrelated = () => 'no agents here'
+`,
+    })
+    try {
+      const byFile = state.agents.invokedAgentsByFile
+      assert.strictEqual(byFile.size, 1)
+      const [file, agents] = [...byFile.entries()][0]!
+      assert.ok(file.endsWith('caller.ts'))
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('rpc.agent.run() is an agent invocation too', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function askTheHouse() {
+  return rpc.agent.run('houseAssistant', { message: 'hi' })
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('a non-null assertion on the rpc receiver is still an invocation', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const rpc: { agent: { stream: (name: string, input: unknown) => Promise<unknown> } } | undefined
+export async function askTheHouse() {
+  return rpc!.agent.stream('houseAssistant', { message: 'hi' })
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents], ['houseAssistant'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('multiple agent calls in one file accumulate under that file', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+declare const rpc: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function askEveryone() {
+  await runAgent('houseAssistant', {})
+  return rpc.agent.run('gardenAssistant', {})
+}
+`,
+    })
+    try {
+      const agents = [...state.agents.invokedAgentsByFile.values()][0]!
+      assert.deepStrictEqual([...agents].sort(), [
+        'gardenAssistant',
+        'houseAssistant',
+      ])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('a dynamic agent name is warned about, not recorded', async () => {
+    const warnings: string[] = []
+    const dir = await mkdtemp(join(tmpdir(), 'pikku-agent-invocations-test-'))
+    const path = join(dir, 'caller.ts')
+    await writeFile(
+      path,
+      `
+declare const runAgent: (name: string, input: unknown) => Promise<unknown>
+declare const suffix: string
+export async function askTheHouse() {
+  return runAgent(\`house-\${suffix}\`, {})
+}
+`
+    )
+    const logger = makeLogger()
+    logger.warn = (message: string) => {
+      warnings.push(message)
+    }
+    try {
+      const state = await inspect(logger, [path], { rootDir: dir })
+      assert.strictEqual(state.agents.invokedAgentsByFile.size, 0)
+      assert.ok(warnings.some((w) => w.includes('dynamic agent invocation')))
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('run() on some other receiver is left alone', async () => {
+    const { state, dir } = await inspectFiles({
+      'caller.ts': `
+declare const client: { agent: { run: (name: string, input: unknown) => Promise<unknown> } }
+export async function doWork() {
+  return client.agent.run('notAnAgentCall', {})
+}
+`,
+    })
+    try {
+      assert.strictEqual(state.agents.invokedAgentsByFile.size, 0)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-rpc-invocations.ts

@@ -51,6 +51,33 @@ function extractNamespace(functionRef: string): string | null {
   return null
 }
 
+function agentInvocationName(
+  expression: ts.Expression
+): 'runAgent' | 'streamAgent' | 'rpc.agent.run' | 'rpc.agent.stream' | null {
+  if (ts.isIdentifier(expression)) {
+    if (expression.text === 'runAgent') return 'runAgent'
+    if (expression.text === 'streamAgent') return 'streamAgent'
+    return null
+  }
+  if (!ts.isPropertyAccessExpression(expression)) return null
+  const method = expression.name.text
+  if (method !== 'run' && method !== 'stream') return null
+  const agentReceiver = invocationReceiver(expression.expression)
+  if (
+    !ts.isPropertyAccessExpression(agentReceiver) ||
+    agentReceiver.name.text !== 'agent'
+  ) {
+    return null
+  }
+  const rpcReceiver = invocationReceiver(agentReceiver.expression)
+  const isRpc = ts.isIdentifier(rpcReceiver)
+    ? rpcReceiver.text === 'rpc'
+    : ts.isPropertyAccessExpression(rpcReceiver) &&
+      rpcReceiver.name.text === 'rpc'
+  if (!isRpc) return null
+  return method === 'run' ? 'rpc.agent.run' : 'rpc.agent.stream'
+}
+
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
  * Also detects addon usage via:
@@ -99,6 +126,31 @@ export function addRPCInvocations(
       }
     }
 
+    const agentCall = agentInvocationName(expression)
+    if (agentCall) {
+      const [firstArg] = args
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        const agentName = firstArg.text
+        logger.debug(`• Found ${agentCall}() call: ${agentName}`)
+        const sourceFileName = node.getSourceFile().fileName
+        let byFile = state.agents.invokedAgentsByFile.get(sourceFileName)
+        if (!byFile) {
+          byFile = new Set()
+          state.agents.invokedAgentsByFile.set(sourceFileName, byFile)
+        }
+        byFile.add(agentName)
+      } else if (
+        firstArg &&
+        (ts.isTemplateExpression(firstArg) ||
+          ts.isNoSubstitutionTemplateLiteral(firstArg))
+      ) {
+        logger.warn(`• Found dynamic agent invocation: ${firstArg.getText()}`)
+        logger.warn(
+          `\tYou can only use string literals for agent names, with ' or " and not \``
+        )
+      }
+    }
+
     // Check for rpc.invoke('...') calls
     const invokeReceiver = ts.isPropertyAccessExpression(expression)
       ? invocationReceiver(expression.expression)

package/src/add/add-scenario-step.test.ts

@@ -245,6 +245,67 @@ describe('pikkuScenarioStep', () => {
     }
   })
 
+  test('a step whose prose opens with its own actor is a PKU681 critical', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given(`'shopper' buys an apple`, 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `the reporter already renders the actor as the subject, so this reads "Given shopper 'shopper' buys an apple", got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('an unquoted, capitalised actor opening the prose is caught too', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('Shopper buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `quotes and case are decoration — the subject is still doubled, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('a call-site description naming the actor is caught as well as the step name', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper, description: `shopper buys an apple` })",
+      "await scenario.then('sees a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.ok(
+        criticals.find((c) => c.code === 'PKU681'),
+        `the description is what actually renders when it is given, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
+  test('an actor named mid-sentence is left alone', async () => {
+    const { criticals, cleanup } = await run([
+      "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",
+      "await scenario.then('sends shopper a receipt', 'seesAReceipt', {}, { actor: actors.shopper })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU681').length,
+        0,
+        `only the subject position doubles up; naming someone mid-sentence is ordinary prose, got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
   test('a scenario that never asserts is a PKU680 critical', async () => {
     const { criticals, cleanup } = await run([
       "await scenario.given('buys an apple', 'buysAnApple', { qty: 1 }, { actor: actors.shopper })",

package/src/error-codes.ts

@@ -26,6 +26,7 @@ export enum ErrorCode {
   SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
   SCENARIO_NOT_EXTRACTABLE = 'PKU679',
   SCENARIO_HAS_NO_ASSERTION = 'PKU680',
+  SCENARIO_STEP_PROSE_NAMES_ACTOR = 'PKU681',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
   WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',

package/src/inspector.ts

@@ -83,6 +83,8 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     wireServicesFactories: new Map(),
     wireServicesMeta: new Map(),
     addonRequiredParentServices: [],
+    addonCreatedServices: [],
+    addonServicesFactorySeen: false,
     addonServerlessIncompatible: new Map(),
     configFactories: new Map(),
     serverLifecycleFactories: new Map(),
@@ -163,6 +165,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     agents: {
       agentsMeta: {},
       files: new Map(),
+      invokedAgentsByFile: new Map(),
     },
     scorers: {
       scorersMeta: {},

package/src/types.ts

@@ -526,6 +526,8 @@ 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
@@ -634,6 +636,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,82 @@ 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']
+    )
+  })
+})

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

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
+    )
+  })
+})