@pikku/inspector 0.12.70 → 0.12.73

package/CHANGELOG.md

@@ -1,3 +1,59 @@
+## 0.12.73
+
+### Patch Changes
+
+- 6519c66: Report what each inspector pass did, not only how long it took. `inspect()` now records per-pass work counters on the state (`stats`: files in the program, files reused from the previous program, type/instantiation/symbol counts, CPU and wall time, heap in use), and `pikku all` prints one `[INSPECT]` row per pass under `PIKKU_TIMING`. The codegen benchmark gates on those counts and on live heap per pass instead of on step timings, which swing with the runner, and its fixture now includes an agent so the post-agent re-inspection is actually exercised.
+- 5447dba: Keep parsed source files across inspector passes. A re-inspection in `pikku all` used to re-parse and re-bind every file, because the previous `ts.Program` — the thing TypeScript reuses parses from — had to be dropped to free its type checker. The inspector now builds each program through a compiler host with a content-hashed `SourceFile` cache, so a re-inspection parses only what codegen just wrote while holding no checker: on the 500-function benchmark the re-inspection reuses all 908 files, its CPU time falls by a third, and peak heap drops.
+
+## 0.12.72
+
+### Patch Changes
+
+- 202cb72: Refuse a scenario step whose prose opens with its own actor (PKU681). The
+  reporter already renders the actor as the sentence's subject, so a step
+  authored as `'sam' creates the client` and run as `{ actor: actors.sam }`
+  reads "Given sam 'sam' creates the client" — and the hardcoded name desyncs
+  the moment the call site changes actor. Only the subject position is refused:
+  naming someone else mid-sentence, or an actor keyed after a role noun used as
+  a noun ("creates the admin client"), is left alone.
+
+## 0.12.71
+
+### Patch Changes
+
+- 9015400: Derive an addon's required parent services from what its functions actually use.
+
+  An addon's functions are its published surface — a consumer calls them, nothing
+  wires them locally — so `usedFunctions` was empty for an addon's own build and no
+  function services were ever aggregated. The generated services map came out
+  claiming the addon needed nothing beyond the framework defaults, and
+  `requiredParentServices` was derived only from the second parameter of
+  `pikkuAddonServices`, which names what the factory reads rather than what its
+  functions destructure.
+
+  The visible cost was an addon that consumed `kysely` in all fifteen of its
+  functions and declared it nowhere: the consuming project was never told to supply
+  it, the addon lost it at runtime, and every query failed on the first call. The
+  only way out was to list the missing names under `forceRequiredServices`, which
+  is a detection escape hatch and was never meant to carry a contract.
+
+  An addon build now aggregates services from every declared function, and treats
+  as parent-provided whatever it uses but does not build itself. What the factory
+  builds is read from the object literals it returns, minus anything it took off
+  the parent bag first — a forwarded service is not a created one, which is how
+  `@pikku/addon-admin` returns `scopeService` and friends without claiming to own
+  them. Names destructured from the second parameter in the function body, rather
+  than in the parameter list, are picked up too.
+
+- 8852a75: Register an agent invoked from a function body in the calling deployment unit.
+
+  `runAgent('houseAssistant', ...)` and `rpc.agent.run('houseAssistant', ...)` resolve against the in-process agent registry, but the deploy analyzer only ever put an agent's registration in its own `agent-*` unit. A function calling one landed in a separate unit whose bootstrap never registered it, so the deployed worker threw `AI agent not found: houseAssistant`.
+
+  The inspector now records a string-literal agent name passed to `runAgent` / `streamAgent` / `rpc.agent.run` / `rpc.agent.stream` in a function body under `agents.invokedAgentsByFile`, mirroring what it already does for `rpc.invoke` targets. The analyzer carries those names on the calling unit as `invokedAgents` and adds the `ai-model` / `ai-storage` service requirements, and per-unit codegen puts the agent — and its tools — into that unit's filter names so its wiring is generated there too. A dynamic (template-literal) agent name is warned about, as it is for `rpc.invoke`.
+
+- Updated dependencies [f4e2e89]
+  - @pikku/core@0.12.102
+
 ## 0.12.70
 
 ### Patch Changes

package/dist/add/add-file-with-factory.js

@@ -10,6 +10,93 @@ const wrapperFunctionMap = {
     pikkuAddonWireServices: 'CreateWireServices',
     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) => {
+    const forwarded = [];
+    const secondParam = functionNode.parameters[1];
+    if (!secondParam)
+        return forwarded;
+    const collectBinding = (pattern) => {
+        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) => {
+        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) => {
+    const returned = [];
+    const collect = (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) => {
+        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, checker, methods = new Map(), expectedTypeName, state) => {
     if (ts.isVariableDeclaration(node)) {
         const fileName = node.getSourceFile().fileName;
@@ -57,20 +144,15 @@ export const addFileWithFactory = (node, checker, methods = new Map(), expectedT
                         }
                         // 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/dist/add/add-rpc-invocations.js

@@ -42,6 +42,33 @@ function extractNamespace(functionRef) {
     }
     return null;
 }
+function agentInvocationName(expression) {
+    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:
@@ -80,6 +107,27 @@ export function addRPCInvocations(node, state, logger) {
                 state.workflows.invokedWorkflows.add(workflowName);
             }
         }
+        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/dist/error-codes.d.ts

@@ -24,6 +24,7 @@ export declare 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/dist/error-codes.js

@@ -26,6 +26,7 @@ export var ErrorCode;
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
+    ErrorCode["SCENARIO_STEP_PROSE_NAMES_ACTOR"] = "PKU681";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";

package/dist/inspector.js

@@ -5,6 +5,7 @@ import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
+import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
@@ -36,6 +37,8 @@ export function getInitialInspectorState(rootDir) {
         wireServicesFactories: new Map(),
         wireServicesMeta: new Map(),
         addonRequiredParentServices: [],
+        addonCreatedServices: [],
+        addonServicesFactorySeen: false,
         addonServerlessIncompatible: new Map(),
         configFactories: new Map(),
         serverLifecycleFactories: new Map(),
@@ -116,6 +119,7 @@ export function getInitialInspectorState(rootDir) {
         agents: {
             agentsMeta: {},
             files: new Map(),
+            invokedAgentsByFile: new Map(),
         },
         scorers: {
             scorersMeta: {},
@@ -270,10 +274,13 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         allowJs: false,
         checkJs: false,
     };
+    const cpuStart = process.cpuUsage();
     const startProgram = performance.now();
-    const program = ts.createProgram(normalizedRouteFiles, compilerOptions, undefined, // host
-    options.oldProgram);
-    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files${options.oldProgram ? ', incremental' : ''})`);
+    const host = createSourceFileCacheHost(compilerOptions);
+    const program = ts.createProgram(normalizedRouteFiles, compilerOptions, host, options.oldProgram);
+    host.prune(program);
+    const filesReused = host.reused();
+    logger.debug(`Created program in ${(performance.now() - startProgram).toFixed(0)}ms (${normalizedRouteFiles.length} files, ${filesReused} source files reused)`);
     const startChecker = performance.now();
     const checker = program.getTypeChecker();
     logger.debug(`Got type checker in ${(performance.now() - startChecker).toFixed(2)}ms`);
@@ -414,6 +421,18 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validatePersonaRoles(logger, state);
         logger.endValidationPass?.();
     }
+    const cpu = process.cpuUsage(cpuStart);
+    state.stats = {
+        files: program.getSourceFiles().length,
+        projectFiles: sourceFiles.length,
+        filesReused,
+        types: program.getTypeCount(),
+        instantiations: program.getInstantiationCount(),
+        symbols: program.getSymbolCount(),
+        cpuMs: Math.round((cpu.user + cpu.system) / 1000),
+        wallMs: Math.round(performance.now() - startProgram),
+        heapUsedMb: Math.round(process.memoryUsage().heapUsed / 1048576),
+    };
     state.program = program;
     return state;
 };

package/dist/source-file-cache.d.ts

@@ -0,0 +1,11 @@
+import * as ts from 'typescript';
+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 declare const createSourceFileCacheHost: (options: ts.CompilerOptions) => SourceFileCacheHost;

package/dist/source-file-cache.js

@@ -0,0 +1,54 @@
+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();
+export const createSourceFileCacheHost = (options) => {
+    const host = ts.createCompilerHost(options, true);
+    let reused = 0;
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+        let text;
+        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) => {
+            const live = new Set(program.getSourceFiles().map((sf) => sf.fileName));
+            for (const fileName of cache.keys()) {
+                if (!live.has(fileName))
+                    cache.delete(fileName);
+            }
+        },
+    });
+};

package/dist/types.d.ts

@@ -223,6 +223,26 @@ export type AddonConfig = {
     secretOverrides?: Record<string, string>;
     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;
@@ -448,12 +468,20 @@ export interface InspectorState {
     wireServicesFactories: PathToNameAndType;
     wireServicesMeta: Map<string, string[]>;
     addonRequiredParentServices: string[];
+    addonCreatedServices: string[];
+    addonServicesFactorySeen: boolean;
     addonServerlessIncompatible: Map<string, string[]>;
     configFactories: PathToNameAndType;
     serverLifecycleFactories: PathToNameAndType;
     filesAndMethods: InspectorFilesAndMethods;
     filesAndMethodsErrors: Map<string, PathToNameAndType>;
     typesLookup: Map<string, ts.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>;
     schemas: Record<string, JSONValue>;
     http: InspectorHTTPState;
@@ -571,6 +599,16 @@ export interface InspectorState {
             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/dist/utils/filter-inspector-state.js

@@ -385,6 +385,13 @@ export function filterInspectorState(state, filters, logger) {
             ...state.agents,
             agentsMeta: JSON.parse(JSON.stringify(state.agents?.agentsMeta ?? {})),
             files: new Map(),
+            invokedAgentsByFile: new Map([
+                ...(state.agents?.invokedAgentsByFile ??
+                    new Map()),
+            ].map(([file, agents]) => [
+                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
@@ -870,6 +877,16 @@ export function filterInspectorState(state, filters, logger) {
     if (filteredState.serviceAggregation.requiredServices.has('workflowService')) {
         filteredState.serviceAggregation.requiredServices.add('queueService');
     }
+    const keptFunctionFiles = new Set();
+    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(filteredState.serviceAggregation.usedFunctions);
         const keptFiles = new Set();
@@ -897,8 +914,21 @@ export function filterInspectorState(state, filters, logger) {
             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();
         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/dist/utils/post-process.d.ts

@@ -101,6 +101,16 @@ export declare function validateAgentModels(logger: InspectorLogger, state: Insp
  * the check read `undefined` there and never fired.
  */
 export declare function validateScenarioServices(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * 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 declare const proseOpensWithActor: (prose: string, actor: string) => boolean;
 /**
  * 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

package/dist/utils/post-process.js

@@ -313,6 +313,31 @@ export function aggregateRequiredServices(state) {
             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(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
@@ -734,6 +759,67 @@ export function validateScenarioServices(logger, state) {
         }
     }
 }
+/**
+ * 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, actor) => {
+    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, stepMeta) => {
+    const description = step.options?.description;
+    if (description) {
+        return [step.stepName, description];
+    }
+    return [
+        step.stepName,
+        stepMeta?.scenarioStepTemplate,
+        stepMeta?.description,
+    ].filter((prose) => 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, workflowName, step, stepMeta) => {
+    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) => 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
@@ -765,6 +851,7 @@ export function validateScenarioSteps(logger, state) {
                 }
                 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/dist/utils/serialize-inspector-state.d.ts

@@ -57,6 +57,8 @@ export interface SerializableInspectorState {
     ]>;
     wireServicesMeta: Array<[string, string[]]>;
     addonRequiredParentServices: string[];
+    addonCreatedServices: string[];
+    addonServicesFactorySeen: boolean;
     addonServerlessIncompatible: Array<[string, string[]]>;
     configFactories: Array<[
         string,
@@ -210,6 +212,7 @@ export interface SerializableInspectorState {
         files: string[];
     };
     agents: {
+        invokedAgentsByFile?: Array<[string, string[]]>;
         agentsMeta: InspectorState['agents']['agentsMeta'];
         files: [string, {
             path: string;