@pikku/inspector 0.12.70 → 0.12.72

package/CHANGELOG.md

@@ -1,3 +1,52 @@
+## 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

@@ -36,6 +36,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 +118,7 @@ export function getInitialInspectorState(rootDir) {
         agents: {
             agentsMeta: {},
             files: new Map(),
+            invokedAgentsByFile: new Map(),
         },
         scorers: {
             scorersMeta: {},

package/dist/types.d.ts

@@ -448,6 +448,8 @@ export interface InspectorState {
     wireServicesFactories: PathToNameAndType;
     wireServicesMeta: Map<string, string[]>;
     addonRequiredParentServices: string[];
+    addonCreatedServices: string[];
+    addonServicesFactorySeen: boolean;
     addonServerlessIncompatible: Map<string, string[]>;
     configFactories: PathToNameAndType;
     serverLifecycleFactories: PathToNameAndType;
@@ -571,6 +573,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();

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;

package/dist/utils/serialize-inspector-state.js

@@ -24,6 +24,8 @@ export function serializeInspectorState(state) {
         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()),
         configFactories: Array.from(state.configFactories.entries()),
         serverLifecycleFactories: Array.from(state.serverLifecycleFactories.entries()),
@@ -94,6 +96,7 @@ export function serializeInspectorState(state) {
         agents: {
             agentsMeta: state.agents?.agentsMeta ?? {},
             files: Array.from(state.agents?.files?.entries() ?? []),
+            invokedAgentsByFile: Array.from((state.agents?.invokedAgentsByFile ?? new Map()).entries()).map(([file, agents]) => [file, Array.from(agents)]),
         },
         scorers: {
             scorersMeta: state.scorers?.scorersMeta ?? {},
@@ -198,6 +201,8 @@ export function deserializeInspectorState(data) {
         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 || []),
         configFactories: new Map(data.configFactories),
         serverLifecycleFactories: new Map(data.serverLifecycleFactories),
@@ -272,6 +277,7 @@ export function deserializeInspectorState(data) {
         agents: {
             agentsMeta: data.agents?.agentsMeta || {},
             files: new Map(data.agents?.files || []),
+            invokedAgentsByFile: new Map((data.agents?.invokedAgentsByFile || []).map(([file, agents]) => [file, new Set(agents)])),
         },
         scorers: {
             scorersMeta: data.scorers?.scorersMeta || {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.70",
+  "version": "0.12.72",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.100"
+    "@pikku/core": "^0.12.102"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.100",
+    "@pikku/core": "^0.12.102",
     "@types/node": "^24.13.3"
   },
   "engines": {

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

@@ -0,0 +1,134 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../inspector.js'
+import type { ErrorCode } from '../error-codes.js'
+import type { InspectorLogger } from '../types.js'
+import {
+  serializeInspectorState,
+  deserializeInspectorState,
+} from '../utils/serialize-inspector-state.js'
+
+const makeLogger = (criticals: Array<{ code: ErrorCode; message: string }>) =>
+  ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ severity, code, message }) => {
+      if (severity !== 'warn') {
+        criticals.push({ code, message })
+      }
+    },
+    critical: (code: ErrorCode, message: string) => {
+      criticals.push({ code, message })
+    },
+    hasCriticalErrors: () => criticals.length > 0,
+  }) satisfies InspectorLogger
+
+const inspectSource = async (prefix: string, source: string) => {
+  const rootDir = await mkdtemp(join(tmpdir(), prefix))
+  const file = join(rootDir, 'services.ts')
+  await writeFile(file, source)
+  const criticals: Array<{ code: ErrorCode; message: string }> = []
+  try {
+    const state = await inspect(makeLogger(criticals), [file], { rootDir })
+    return { state, criticals }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('pikkuAddonServices — what an addon takes from its parent', () => {
+  test('a name destructured in the body, not the parameter list, is still forwarded', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-body-destructure-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    const { kysely, secrets } = existingServices',
+        '    return { ...existingServices, stripeApi: makeStripe(secrets) }',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    assert.ok(
+      state.addonRequiredParentServices.includes('kysely'),
+      'kysely is read off the parent bag and must be declared as required'
+    )
+    assert.deepEqual(state.addonCreatedServices, ['stripeApi'])
+    assert.equal(state.addonServicesFactorySeen, true)
+  })
+
+  test('an object rest is a binding name, not a service', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-object-rest-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, { kysely, ...parentServices }) => ({',
+        '    ...parentServices,',
+        '    kysely,',
+        '    stripeApi: makeStripe(),',
+        '  })',
+        ')',
+      ].join('\n')
+    )
+
+    assert.deepEqual(state.addonRequiredParentServices, ['kysely'])
+    assert.ok(
+      !state.addonRequiredParentServices.includes('parentServices'),
+      'a rest binding names the leftover bag, not a service the parent provides'
+    )
+  })
+
+  test('a parenthesised return still yields its created services', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-parenthesised-return-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    return ({ ...existingServices, stripeApi: makeStripe() })',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    assert.deepEqual(state.addonCreatedServices, ['stripeApi'])
+    assert.ok(
+      !state.addonRequiredParentServices.includes('stripeApi'),
+      'a service the factory builds is not one the parent has to supply'
+    )
+  })
+
+  test('the addon contract survives a serialize/deserialize round trip', async () => {
+    const { state } = await inspectSource(
+      'pikku-addon-round-trip-',
+      [
+        "import { pikkuAddonServices } from '#pikku/addon/setup'",
+        'export const createSingletonServices = pikkuAddonServices(',
+        '  async (_config, existingServices) => {',
+        '    const { kysely } = existingServices',
+        '    return { ...existingServices, stripeApi: makeStripe(kysely) }',
+        '  }',
+        ')',
+      ].join('\n')
+    )
+
+    const restored = deserializeInspectorState(
+      JSON.parse(JSON.stringify(serializeInspectorState(state)))
+    )
+
+    assert.deepEqual(
+      restored.addonRequiredParentServices,
+      state.addonRequiredParentServices
+    )
+    assert.deepEqual(restored.addonCreatedServices, ['stripeApi'])
+    assert.equal(restored.addonServicesFactorySeen, true)
+  })
+})