@pikku/inspector 0.12.49 → 0.12.52

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

@@ -1,6 +1,19 @@
 import * as ts from 'typescript'
 import type { InspectorState, InspectorLogger } from '../types.js'
 
+function parseStringArray(node: ts.Expression): string[] | undefined {
+  if (!ts.isArrayLiteralExpression(node)) return undefined
+  const values: string[] = []
+  for (const element of node.elements) {
+    // A non-literal entry (a spread, a const reference) is not statically
+    // knowable. Dropping the whole array rather than a silent partial keeps a
+    // consumer from reading a short list as the complete set of gates.
+    if (!ts.isStringLiteral(element)) return undefined
+    values.push(element.text)
+  }
+  return values
+}
+
 function parseStringRecord(
   obj: ts.ObjectLiteralExpression
 ): Record<string, string> {
@@ -41,6 +54,9 @@ export function addWireAddon(
   let pkg: string | undefined
   let rpcEndpoint: string | undefined
   let mcp: boolean | undefined
+  let auth: boolean | undefined
+  let tags: string[] | undefined
+  let scopes: string[] | undefined
   let secretOverrides: Record<string, string> | undefined
   let variableOverrides: Record<string, string> | undefined
   let credentialOverrides: Record<string, string> | undefined
@@ -61,6 +77,16 @@ export function addWireAddon(
         prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
     ) {
       mcp = prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+    } else if (
+      key === 'auth' &&
+      (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+        prop.initializer.kind === ts.SyntaxKind.FalseKeyword)
+    ) {
+      auth = prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+    } else if (key === 'tags') {
+      tags = parseStringArray(prop.initializer)
+    } else if (key === 'scopes') {
+      scopes = parseStringArray(prop.initializer)
     } else if (
       key === 'secretOverrides' &&
       ts.isObjectLiteralExpression(prop.initializer)
@@ -86,6 +112,9 @@ export function addWireAddon(
     package: pkg,
     rpcEndpoint,
     mcp,
+    auth,
+    tags,
+    scopes,
     secretOverrides,
     variableOverrides,
     credentialOverrides,

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

@@ -104,17 +104,17 @@ describe('addon authoring bans', () => {
     })
   })
 
-  test('wireSecret inside an addon is allowed', async () => {
+  test('defineSecret inside an addon is allowed', async () => {
     const source = [
-      "import { wireSecret } from '@pikku/core'",
-      "wireSecret({ name: 'example', secretId: 'EXAMPLE' } as any)",
+      "import { defineSecret } from '@pikku/core'",
+      "defineSecret({ name: 'example', secretId: 'EXAMPLE' } as any)",
     ].join('\n')
     await withTempApp(source, async (file, rootDir) => {
       const { logger, criticals } = recordingLogger()
       await inspect(logger, [file], { rootDir, isAddon: true })
       assert.ok(
         !criticals.some((c) => c.code === ErrorCode.ADDON_WIRING_NOT_ALLOWED),
-        `expected wireSecret to be allowed, got ${JSON.stringify(criticals)}`
+        `expected defineSecret to be allowed, got ${JSON.stringify(criticals)}`
       )
     })
   })

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

@@ -36,17 +36,17 @@ const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
  * downstream, which is exactly how `displayName` went unused.
  */
 describe('config value metadata (docsUrl)', () => {
-  test('carries docsUrl from wireSecret into the definition', async () => {
+  test('carries docsUrl from defineSecret into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-secret-`)
     const file = join(rootDir, 'secret.ts')
 
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const StripeKeySchema = z.string()',
-        'wireSecret({',
+        'defineSecret({',
         "  name: 'stripeKey',",
         "  displayName: 'Stripe Secret Key',",
         "  secretId: 'STRIPE_SECRET_KEY',",
@@ -76,10 +76,10 @@ describe('config value metadata (docsUrl)', () => {
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const ApiKeySchema = z.string()',
-        'wireSecret({',
+        'defineSecret({',
         "  name: 'apiKey',",
         "  displayName: 'API Key',",
         "  secretId: 'API_KEY',",
@@ -101,17 +101,17 @@ describe('config value metadata (docsUrl)', () => {
     }
   })
 
-  test('carries docsUrl from wireVariable into the definition', async () => {
+  test('carries docsUrl from defineVariable into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-variable-`)
     const file = join(rootDir, 'variable.ts')
 
     await writeFile(
       file,
       [
-        "import { wireVariable } from '@pikku/core'",
+        "import { defineVariable } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const ConsoleUrlSchema = z.string()',
-        'wireVariable({',
+        'defineVariable({',
         "  name: 'consoleUrl',",
         "  displayName: 'Console URL',",
         "  variableId: 'CONSOLE_URL',",
@@ -134,17 +134,17 @@ describe('config value metadata (docsUrl)', () => {
     }
   })
 
-  test('carries docsUrl from wireCredential into the definition', async () => {
+  test('carries docsUrl from defineCredential into the definition', async () => {
     const rootDir = await mkdtemp(`${fixtureRoot}-credential-`)
     const file = join(rootDir, 'credential.ts')
 
     await writeFile(
       file,
       [
-        "import { wireCredential } from '@pikku/core'",
+        "import { defineCredential } from '@pikku/core'",
         "import { z } from 'zod'",
         'export const TokenSchema = z.object({ token: z.string() })',
-        'wireCredential({',
+        'defineCredential({',
         "  name: 'githubToken',",
         "  displayName: 'GitHub Token',",
         "  type: 'wire',",

package/src/add/wire-name-literal.test.ts

@@ -62,9 +62,9 @@ describe('wiring name must be a string literal', () => {
     await writeFile(
       file,
       [
-        "import { wireSecret } from '@pikku/core'",
+        "import { defineSecret } from '@pikku/core'",
         'const SECRET_ID = "STRIPE_SECRET_KEY"',
-        'wireSecret({',
+        'defineSecret({',
         '  secretId: SECRET_ID,',
         "  name: 'Stripe secret key',",
         "  displayName: 'Stripe secret key',",

package/src/error-codes.ts

@@ -25,6 +25,7 @@ export enum ErrorCode {
   SCENARIO_BROWSER_STEP_NEEDS_ACTOR = 'PKU677',
   SCENARIO_STEP_TARGET_NOT_STATIC = 'PKU678',
   SCENARIO_NOT_EXTRACTABLE = 'PKU679',
+  SCENARIO_HAS_NO_ASSERTION = 'PKU680',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
   INVALID_DSL_WORKFLOW = 'PKU641',
   WORKFLOW_GRAPH_ADDON_NOT_WIRED = 'PKU642',
@@ -53,6 +54,8 @@ export enum ErrorCode {
   ROUTE_PARAM_MISMATCH = 'PKU571',
   ROUTE_QUERY_MISMATCH = 'PKU572',
   AUTH_DISABLED_REQUIRES_SESSIONLESS = 'PKU573',
+  EXPOSED_FUNCTION_HAS_NO_GATE = 'PKU574',
+  TAG_RESOLVES_TO_NO_MIDDLEWARE = 'PKU575',
 
   // Versioning errors
   DUPLICATE_FUNCTION_VERSION = 'PKU850',
@@ -70,6 +73,11 @@ export enum ErrorCode {
   MISSING_MODEL = 'PKU145',
   INVALID_MODEL = 'PKU146',
 
+  // Agent tool reference errors
+  AGENT_TOOL_UNKNOWN_NAMESPACE = 'PKU152',
+  AGENT_TOOL_NOT_FOUND = 'PKU153',
+  AGENT_TOOL_MISSING_DESCRIPTION = 'PKU154',
+
   // File structure errors
   SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
 
@@ -90,6 +98,11 @@ export enum ErrorCode {
   ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = 'PKU921',
 
   RPC_INVOCATION_TYPE_CAST = 'PKU940',
+
+  // Secret boundary errors
+  SECRET_SERVICE_ALIASED = 'PKU950',
+  SECRET_NOT_DECLARED = 'PKU951',
+  SECRET_KEY_NOT_STATIC = 'PKU952',
 }
 
 /**

package/src/index.ts

@@ -32,7 +32,10 @@ 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

@@ -15,22 +15,31 @@ import {
   aggregateRequiredServices,
   stampAuthHandlerServices,
   validateAgentModels,
+  validateAgentToolReferences,
   validateSecretOverrides,
   validateVariableOverrides,
   validateCredentialOverrides,
   validateRemoteAddonDependencies,
   validateRemoteAddonAuth,
   validateScopeReferences,
+  validateSystemRoleScopes,
+  validatePersonaRoles,
   computeResolvedIOTypes,
   computeMiddlewareGroupsMeta,
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
+  computeSecretBrokers,
+  validateNoSecretAliasServices,
+  validateSecretUsage,
   computeDiagnostics,
   validateSchemaWiringSeparation,
   validateScenarioServices,
   validateScenarioSteps,
   validateWorkflowGraphAddons,
 } from './utils/post-process.js'
+import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js'
+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/internal'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
@@ -40,6 +49,7 @@ import {
   finalizeWorkflowWires,
 } from './utils/workflow/graph/finalize-workflow-wires.js'
 import { generateAllSchemas } from './utils/schema-generator.js'
+import { extractSecretUsage } from './utils/extract-secret-usage.js'
 import {
   loadAddonFunctionsMeta,
   loadAddonSchemas,
@@ -169,6 +179,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     secrets: {
       definitions: [],
       files: new Set(),
+      usage: new Map(),
     },
     credentials: {
       definitions: [],
@@ -178,6 +189,14 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       definitions: [],
       files: new Set(),
     },
+    systemRoles: {
+      definitions: [],
+      files: new Set(),
+    },
+    personas: {
+      definitions: [],
+      files: new Set(),
+    },
     variables: {
       definitions: [],
       files: new Set(),
@@ -354,6 +373,13 @@ export const inspect = async (
 
   const state = getInitialInspectorState(rootDir)
 
+  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)
+    }
+  }
+
   // First sweep: add all functions
   const startSetup = performance.now()
   for (const sourceFile of sourceFiles) {
@@ -451,11 +477,21 @@ export const inspect = async (
     computeResolvedIOTypes(state)
     computeMiddlewareGroupsMeta(state)
     computePermissionsGroupsMeta(state)
+    computeSecretBrokers(state)
+    validateNoSecretAliasServices(logger, checker, state)
+    validateSecretUsage(logger, state)
     computeDiagnostics(state)
     validateSchemaWiringSeparation(logger, state)
     validateWorkflowGraphAddons(logger, state)
     validateScenarioServices(logger, state)
     validateScenarioSteps(logger, state)
+    // Needs every route, every function and every wireAddon declaration
+    // together, so it can only run once the whole program is inspected.
+    annotateHttpRouteAuth(state)
+    // Last of the validators: they read function meta and every wireAddon
+    // declaration together, so they need the whole program inspected.
+    validateExposedFunctionsGated(logger, state)
+    validateTagsResolveToMiddleware(logger, state)
 
     if (options.openAPI) {
       state.openAPISpec = await generateOpenAPISpec(
@@ -469,12 +505,15 @@ export const inspect = async (
     }
 
     validateAgentModels(logger, state)
+    validateAgentToolReferences(logger, state, options)
     validateSecretOverrides(logger, state)
     validateVariableOverrides(logger, state)
     validateCredentialOverrides(logger, state)
     validateRemoteAddonDependencies(logger, state)
     validateRemoteAddonAuth(logger, state)
     validateScopeReferences(logger, state)
+    validateSystemRoleScopes(logger, state)
+    validatePersonaRoles(logger, state)
   }
 
   state.program = program

package/src/types.ts

@@ -1,4 +1,5 @@
 import type * as ts from 'typescript'
+import type { SecretUsage } from './utils/extract-secret-usage.js'
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel'
 import type { GatewaysMeta } from '@pikku/core/gateway'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
@@ -18,6 +19,8 @@ import type { NodesMeta } from '@pikku/core/node'
 import type { SecretDefinitions } from '@pikku/core/secret'
 import type { CredentialDefinitions } from '@pikku/core/credential'
 import type { ScopeDefinitions } from '@pikku/core/scope'
+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 {
@@ -48,14 +51,31 @@ export type MetaInputTypes = Map<
   }
 >
 
-export interface MiddlewareGroupMeta {
+/** One `addHTTPMiddleware`/`addTagMiddleware`/`addChannelMiddleware` call. */
+export interface MiddlewareRegistration {
   exportName: string | null // null if not exported
   sourceFile: string
   position: number
+  isFactory: boolean // true if wrapped in () => add...()
+}
+
+export interface MiddlewareGroupMeta extends MiddlewareRegistration {
   services: FunctionServicesMeta
   count: number
   instanceIds: string[]
-  isFactory: boolean // true if wrapped in () => add...()
+  /**
+   * The registrations after the first, when several files add middleware for
+   * the same pattern or tag.
+   *
+   * A group is keyed by its pattern/tag, so without this a second file's call
+   * overwrote the first's and only the survivor got an import emitted into
+   * pikku-middleware.gen.ts — the losing file was never imported, so its
+   * registration never ran. The runtime composes repeated registrations for a
+   * pattern happily; only codegen dropped one, which is how an app could lose
+   * its session-bridge middleware to an unrelated `'*'` group and see nothing
+   * go wrong until a request arrived without a session.
+   */
+  additionalRegistrations?: MiddlewareRegistration[]
 }
 
 export interface InspectorHTTPState {
@@ -272,6 +292,12 @@ export type InspectorOptions = Partial<{
   setupOnly: boolean
   rootDir: string
   isAddon: boolean
+  /**
+   * Fail the build on metadata that only an agent needs — currently an agent
+   * tool with no description. Off by default: the runtime falls back to the
+   * tool's own name, so this is a quality gate rather than a correctness one.
+   */
+  strictMeta: boolean
   sourceFile: ts.SourceFile
   /**
    * The project's tsconfig, read for its path mappings only. The inspector's
@@ -530,6 +556,15 @@ export interface InspectorState {
         package: string
         rpcEndpoint?: string
         mcp?: boolean
+        /**
+         * The addon's own gates. `runPikkuFunc` applies these to every function
+         * in the package, on every wiring path — not just `namespace:function`.
+         * Absent when the declared value was not a statically-knowable literal,
+         * which must be read as "unknown", never as "ungated".
+         */
+        auth?: boolean
+        tags?: string[]
+        scopes?: string[]
         /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
         remote?: boolean
         /** wireRemoteAddon: whether an `auth` binding was supplied (vs a public surface) */
@@ -586,6 +621,8 @@ export interface InspectorState {
   secrets: {
     definitions: SecretDefinitions
     files: Set<string>
+    /** Secret reads found per source file, keyed by absolute path. */
+    usage: Map<string, SecretUsage>
   }
   credentials: {
     definitions: CredentialDefinitions
@@ -595,6 +632,14 @@ export interface InspectorState {
     definitions: ScopeDefinitions
     files: Set<string>
   }
+  systemRoles: {
+    definitions: SystemRoleDefinitions
+    files: Set<string>
+  }
+  personas: {
+    definitions: PersonaDefinitions
+    files: Set<string>
+  }
   variables: {
     definitions: VariableDefinitions
     files: Set<string>

package/src/utils/annotate-http-route-auth.test.ts

@@ -0,0 +1,163 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import { annotateHttpRouteAuth } from './annotate-http-route-auth.js'
+
+const ADDON_PACKAGE = '@addon/console'
+
+/**
+ * A single GET route plus the function it points at, with the four inputs the
+ * resolution reads spread across both.
+ */
+const resolve = (
+  route: Record<string, unknown>,
+  meta: Record<string, unknown> = {},
+  addons: Record<string, unknown> = {}
+): boolean | undefined => {
+  const state = {
+    functions: { meta: { handler: { pikkuFuncId: 'handler', ...meta } } },
+    http: {
+      meta: {
+        get: {
+          '/thing': {
+            pikkuFuncId: 'handler',
+            route: '/thing',
+            method: 'get',
+            ...route,
+          },
+        },
+      },
+    },
+    rpc: { wireAddonDeclarations: new Map(Object.entries(addons)) },
+  } as any
+
+  annotateHttpRouteAuth(state)
+  return state.http.meta.get['/thing'].requiresSession
+}
+
+describe('annotateHttpRouteAuth', () => {
+  test('a pikkuFunc always requires a session', () => {
+    assert.equal(resolve({}, { sessionless: false }), true)
+  })
+
+  test('a sessionless function on a plain route does not', () => {
+    assert.equal(resolve({}, { sessionless: true }), false)
+  })
+
+  test("the function's own auth requires one", () => {
+    assert.equal(resolve({}, { sessionless: true, auth: true }), true)
+  })
+
+  test("the route's auth requires one, even of a sessionless function", () => {
+    assert.equal(resolve({ auth: true }, { sessionless: true }), true)
+  })
+
+  test('an explicit auth: false on the route does not undo the function', () => {
+    // Layers only ever tighten. A route cannot open a pikkuFunc back up.
+    assert.equal(resolve({ auth: false }, { sessionless: false }), true)
+  })
+
+  test('function scopes require one', () => {
+    // Scopes are matched against the session's and fail closed, so an
+    // anonymous caller is rejected — reporting the route as open would be a lie.
+    assert.equal(resolve({}, { sessionless: true, scopes: ['admin'] }), true)
+  })
+
+  test("the addon's auth requires one", () => {
+    assert.equal(
+      resolve(
+        { packageName: ADDON_PACKAGE },
+        { sessionless: true },
+        { console: { package: ADDON_PACKAGE, auth: true } }
+      ),
+      true
+    )
+  })
+
+  test("the addon's scopes require one", () => {
+    assert.equal(
+      resolve(
+        { packageName: ADDON_PACKAGE },
+        { sessionless: true },
+        { console: { package: ADDON_PACKAGE, scopes: ['admin'] } }
+      ),
+      true
+    )
+  })
+
+  test("another package's addon gate does not reach this route", () => {
+    assert.equal(
+      resolve(
+        { packageName: '@app/api' },
+        { sessionless: true },
+        { console: { package: ADDON_PACKAGE, auth: true } }
+      ),
+      false
+    )
+  })
+
+  test('an ungated addon leaves the route as its function found it', () => {
+    assert.equal(
+      resolve(
+        { packageName: ADDON_PACKAGE },
+        { sessionless: true },
+        { console: { package: ADDON_PACKAGE } }
+      ),
+      false
+    )
+  })
+
+  test('a ref route resolves against its target', () => {
+    const state = {
+      functions: {
+        meta: {
+          inline: { pikkuFuncId: 'inline', sessionless: true },
+          target: { pikkuFuncId: 'target', sessionless: false },
+        },
+      },
+      http: {
+        meta: {
+          get: {
+            '/thing': {
+              pikkuFuncId: 'inline',
+              refTarget: 'target',
+              route: '/thing',
+              method: 'get',
+            },
+          },
+        },
+      },
+      rpc: { wireAddonDeclarations: new Map() },
+    } as any
+
+    annotateHttpRouteAuth(state)
+    assert.equal(state.http.meta.get['/thing'].requiresSession, true)
+  })
+
+  test('a route whose function meta is missing is not reported as open', () => {
+    const state = {
+      functions: { meta: {} },
+      http: {
+        meta: {
+          get: {
+            '/thing': {
+              pikkuFuncId: 'gone',
+              route: '/thing',
+              method: 'get',
+              auth: true,
+            },
+          },
+        },
+      },
+      rpc: { wireAddonDeclarations: new Map() },
+    } as any
+
+    annotateHttpRouteAuth(state)
+    assert.equal(state.http.meta.get['/thing'].requiresSession, true)
+  })
+
+  test('tolerates http state being absent', () => {
+    assert.doesNotThrow(() =>
+      annotateHttpRouteAuth({ functions: { meta: {} } } as any)
+    )
+  })
+})

package/src/utils/annotate-http-route-auth.ts

@@ -0,0 +1,52 @@
+import type { InspectorState } from '../types.js'
+
+/**
+ * Resolve, per HTTP route, whether reaching it requires a session.
+ *
+ * Four separate places can demand one — the function's `sessionless`, the
+ * function's own `auth`, the route's (or its group's) `auth`, and the addon the
+ * function belongs to — and they combine with OR: any of them is enough. Until
+ * this was written down, "which routes are open?" could only be answered by
+ * joining all four by hand, and getting the join wrong reads an open route as a
+ * closed one, which is the direction that costs something.
+ *
+ * A scope gate counts as requiring a session. Scopes are checked against the
+ * session's and fail closed, so an anonymous caller is rejected either way; not
+ * counting them would mark a route open that nobody can reach anonymously.
+ *
+ * Anything not statically knowable resolves to requiring a session, matching
+ * `validateExposedFunctionsGated`: an over-cautious `true` costs a route that
+ * looks stricter than it is, a wrong `false` costs an audit.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export function annotateHttpRouteAuth(state: InspectorState): void {
+  const gatedPackages = packagesGatedByTheirAddon(state)
+
+  for (const routes of Object.values(state.http?.meta ?? {})) {
+    for (const route of Object.values(routes)) {
+      const meta = state.functions.meta[route.refTarget ?? route.pikkuFuncId]
+
+      route.requiresSession =
+        // A pikkuFunc always requires a session, on every path.
+        meta?.sessionless === false ||
+        meta?.auth === true ||
+        (meta?.scopes?.length ?? 0) > 0 ||
+        route.auth === true ||
+        (route.packageName !== undefined &&
+          gatedPackages.has(route.packageName))
+    }
+  }
+}
+
+/** Packages whose `wireAddon` demands a session from everything inside them. */
+function packagesGatedByTheirAddon(state: InspectorState): Set<string> {
+  const gated = new Set<string>()
+  for (const declaration of state.rpc?.wireAddonDeclarations?.values() ?? []) {
+    if (!declaration.package) continue
+    if (declaration.auth === true || (declaration.scopes?.length ?? 0) > 0) {
+      gated.add(declaration.package)
+    }
+  }
+  return gated
+}

package/src/utils/extract-function-name.ts

@@ -46,9 +46,19 @@ export function funcIdToTypeName(id: string): string {
 }
 
 /**
- * `pikkuScenarioStep({ name })` is the one wrapper whose `name` is its identity:
- * scenarios reference a step by that string, so it must become the pikkuFuncId
- * (and hence the generated step map's key), not just a cosmetic label the way
+ * The step wrappers, whichever kind of subject acts in them. A scenario calls a
+ * platform or addon step by name exactly as it calls a persona one.
+ */
+const SCENARIO_STEP_WRAPPERS = new Set([
+  'pikkuScenarioStep',
+  'pikkuPlatformScenarioStep',
+  'pikkuAddonScenarioStep',
+])
+
+/**
+ * A scenario step is the one wrapper whose `name` is its identity: scenarios
+ * reference a step by that string, so it must become the pikkuFuncId (and hence
+ * the generated step map's key), not just a cosmetic label the way
  * `pikkuMiddleware`/`pikkuAgent` use it.
  */
 function extractScenarioStepName(
@@ -58,7 +68,7 @@ function extractScenarioStepName(
   if (
     !ts.isCallExpression(callExpr) ||
     !ts.isIdentifier(callExpr.expression) ||
-    callExpr.expression.text !== 'pikkuScenarioStep'
+    !SCENARIO_STEP_WRAPPERS.has(callExpr.expression.text)
   ) {
     return
   }