@pikku/inspector 0.12.59 → 0.12.61

package/dist/add/add-http-route.js

@@ -128,22 +128,27 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
     const packageName = ts.isIdentifier(funcInitializer)
         ? resolveAddonName(funcInitializer, checker, state.rpc.wireAddonDeclarations)
         : null;
+    // A ref()-wired route points straight at the addon function, the same way the
+    // CLI and channel adders record one. The addon's own metadata is the contract
+    // — and it is authoritative where the checker is not: `ref('ns:fn')` only
+    // types precisely once the consumer's own rpc map already lists the addon's
+    // functions, so a cold run inferred the whole `FlattenedRPCMap` and a warm one
+    // inferred the real input. The addon's metadata says which it is either way.
+    //
+    // The route stays the consuming app's all the same, so it records no
+    // packageName: that names the package a wire *runs in*, and running this one
+    // inside the addon would hand it the addon's middleware and services instead
+    // of the app's. `ref` reaches the addon over RPC, which enters it properly.
     if (refAddonTarget) {
         const targetMeta = resolveFunctionMeta(state, refAddonTarget);
         if (!targetMeta) {
             logger.warn(`Skipping route '${fullRoute}': addon function metadata for '${refAddonTarget}' is not available yet.`);
             return;
         }
+        funcName = refAddonTarget;
     }
-    ensureFunctionMetadata(state, funcName, fullRoute, funcInitializer, checker, extracted.isHelper);
-    // Propagate sessionless from the addon target so the runtime can correctly
-    // determine whether a session is required for ref()-based routes.
-    if (refAddonTarget) {
-        const targetMeta = resolveFunctionMeta(state, refAddonTarget);
-        const inlineMeta = state.functions.meta[funcName];
-        if (targetMeta && inlineMeta && targetMeta.sessionless !== undefined) {
-            inlineMeta.sessionless = targetMeta.sessionless;
-        }
+    else {
+        ensureFunctionMetadata(state, funcName, fullRoute, funcInitializer, checker, extracted.isHelper);
     }
     // The route's own `auth`, falling back to the group's. Recorded on the meta
     // below so an audit can answer "is this route open?" without re-reading the
@@ -175,12 +180,11 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
     }
     const input = fnMeta.inputs?.[0] || null;
     const getRouteInputKeys = () => {
-        const targetFuncName = refAddonTarget ?? funcName;
-        const inputTypes = state.typesLookup.get(targetFuncName);
+        const inputTypes = state.typesLookup.get(funcName);
         if (inputTypes && inputTypes.length > 0) {
             return extractTypeKeys(inputTypes[0]);
         }
-        const targetMeta = resolveFunctionMeta(state, targetFuncName);
+        const targetMeta = resolveFunctionMeta(state, funcName);
         if (targetMeta?.inputSchemaName) {
             const schema = state.schemas[targetMeta.inputSchemaName];
             const properties = schema?.properties;
@@ -203,7 +207,7 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
                 const missingParams = params.filter((p) => !inputKeys.includes(p));
                 if (missingParams.length > 0) {
                     logger.critical(ErrorCode.ROUTE_PARAM_MISMATCH, `Route '${fullRoute}' has path parameter(s) [${missingParams.join(', ')}] ` +
-                        `not found in function '${refAddonTarget ?? funcName}' input type. ` +
+                        `not found in function '${funcName}' input type. ` +
                         `Input type has: [${inputKeys.join(', ')}]`);
                     return;
                 }
@@ -213,7 +217,7 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
                 const missingQuery = query.filter((q) => !inputKeys.includes(q));
                 if (missingQuery.length > 0) {
                     logger.critical(ErrorCode.ROUTE_QUERY_MISMATCH, `Route '${fullRoute}' has query parameter(s) [${missingQuery.join(', ')}] ` +
-                        `not found in function '${refAddonTarget ?? funcName}' input type. ` +
+                        `not found in function '${funcName}' input type. ` +
                         `Input type has: [${inputKeys.join(', ')}]`);
                     return;
                 }
@@ -227,9 +231,6 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
     // Resolve permissions
     const permissions = resolvePermissions(state, obj, tags, checker);
     state.serviceAggregation.usedFunctions.add(funcName);
-    if (refAddonTarget) {
-        state.serviceAggregation.usedFunctions.add(refAddonTarget);
-    }
     extractWireNames(middleware).forEach((name) => state.serviceAggregation.usedMiddleware.add(name));
     extractWireNames(permissions).forEach((name) => state.serviceAggregation.usedPermissions.add(name));
     // Check for SSE
@@ -240,7 +241,6 @@ export function registerHTTPRoute({ obj, state, checker, logger, sourceFile, bas
     state.http.files.add(sourceFile.fileName);
     state.http.meta[method][fullRoute] = {
         pikkuFuncId: funcName,
-        ...(refAddonTarget && { refTarget: refAddonTarget }),
         ...(packageName && { packageName }),
         route: fullRoute,
         sourceFile: sourceFile.fileName,

package/dist/add/add-keyed-wiring.d.ts

@@ -4,6 +4,8 @@ export interface KeyedWiringConfig {
     idField: string;
     label: string;
     schemaPrefix: string;
+    /** Boolean property carrying this wiring kind's deploy-gate opt-in/opt-out. */
+    flagField: string;
     getState: (state: InspectorState) => {
         definitions: any[];
         files: Set<string>;

package/dist/add/add-keyed-wiring.js

@@ -2,7 +2,7 @@ import * as ts from 'typescript';
 import { getPropertyValue, getArrayPropertyValue, assertStringLiteralProperty, } from '../utils/get-property-value.js';
 import { ErrorCode } from '../error-codes.js';
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
-import { parseDurationString } from '@pikku/core';
+import { parseDurationString } from '@pikku/core/utils';
 export const createAddKeyedWiring = (config) => {
     return (logger, node, checker, state, _options) => {
         if (!ts.isCallExpression(node)) {
@@ -29,6 +29,7 @@ export const createAddKeyedWiring = (config) => {
             const docsUrlValue = getPropertyValue(obj, 'docsUrl');
             const allowedHostsValue = getArrayPropertyValue(obj, 'allowedHosts');
             const idValue = getPropertyValue(obj, config.idField);
+            const flagValue = getPropertyValue(obj, config.flagField) === true;
             let schemaVariableName = null;
             let schemaSourceFile = null;
             let schemaIdentifier = null;
@@ -107,6 +108,7 @@ export const createAddKeyedWiring = (config) => {
                 docsUrl: docsUrlValue || undefined,
                 allowedHosts: allowedHostsValue || undefined,
                 [config.idField]: idValue,
+                [config.flagField]: flagValue || undefined,
                 schema: schemaLookupName,
                 sourceFile,
             });

package/dist/add/add-middleware.js

@@ -508,12 +508,12 @@ export const addMiddleware = (logger, node, checker, state) => {
         logger.debug(`• Found channel middleware factory with services: ${services.services.join(', ')}`);
         return;
     }
-    if (expression.text === 'pikkuAIMiddleware') {
+    if (expression.text === 'pikkuAgentMiddleware') {
         const arg = args[0];
         if (!arg)
             return;
         if (!ts.isObjectLiteralExpression(arg)) {
-            logger.error(`• pikkuAIMiddleware() requires an object literal argument.`);
+            logger.error(`• pikkuAgentMiddleware() requires an object literal argument.`);
             return;
         }
         const allServices = new Set();
@@ -542,12 +542,12 @@ export const addMiddleware = (logger, node, checker, state) => {
                 pikkuFuncId = node.parent.name.text;
             }
             else {
-                logger.error(`• pikkuAIMiddleware() must be assigned to a variable or object property. ` +
-                    `Extract it to a const: const myMiddleware = pikkuAIMiddleware(...)`);
+                logger.error(`• pikkuAgentMiddleware() must be assigned to a variable or object property. ` +
+                    `Extract it to a const: const myMiddleware = pikkuAgentMiddleware(...)`);
                 return;
             }
         }
-        state.aiMiddleware.definitions[pikkuFuncId] = {
+        state.agentMiddleware.definitions[pikkuFuncId] = {
             services,
             sourceFile: node.getSourceFile().fileName,
             position: node.getStart(),

package/dist/add/add-personas.js

@@ -192,6 +192,9 @@ export const addPersonas = (logger, node, _checker, state) => {
         const personality = stringProperty(config, 'personality');
         if (personality !== undefined)
             persona.personality = personality;
+        const app = stringProperty(config, 'app');
+        if (app !== undefined)
+            persona.app = app;
         if (disposition !== undefined) {
             persona.disposition = disposition;
         }

package/dist/add/add-secret.js

@@ -4,5 +4,6 @@ export const addSecret = createAddKeyedWiring({
     idField: 'secretId',
     label: 'Secret',
     schemaPrefix: 'SecretSchema',
+    flagField: 'optional',
     getState: (state) => state.secrets,
 });

package/dist/add/add-variable.js

@@ -4,5 +4,6 @@ export const addVariable = createAddKeyedWiring({
     idField: 'variableId',
     label: 'Variable',
     schemaPrefix: 'VariableSchema',
+    flagField: 'required',
     getState: (state) => state.variables,
 });

package/dist/add/add-wire-remote-addon.js

@@ -38,7 +38,8 @@ export function addWireRemoteAddon(node, state, logger) {
             ts.isObjectLiteralExpression(prop.initializer)) {
             hasAuth = true;
             for (const authProp of prop.initializer.properties) {
-                if (!ts.isPropertyAssignment(authProp) || !ts.isIdentifier(authProp.name))
+                if (!ts.isPropertyAssignment(authProp) ||
+                    !ts.isIdentifier(authProp.name))
                     continue;
                 if (authProp.name.text === 'credentialId' &&
                     ts.isStringLiteral(authProp.initializer)) {

package/dist/add/add-workflow-graph.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral } from '../utils/extract-node-value.js';
-function extractAstValue(expr, refParamName, templateParamName) {
+function extractAstValue(expr, refParamName, templateParamName, itemParamName) {
     // `'GET' as const` / parenthesised values wrap the real initializer — see
     // through them or the whole property is silently dropped from the meta.
     while (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr)) {
@@ -31,6 +31,11 @@ function extractAstValue(expr, refParamName, templateParamName) {
                 const path = args[1] && ts.isStringLiteral(args[1]) ? args[1].text : undefined;
                 return { $ref: nodeId, path };
             }
+            if (itemParamName && callee.text === itemParamName) {
+                const pathArg = expr.arguments[0];
+                const path = pathArg && ts.isStringLiteral(pathArg) ? pathArg.text : undefined;
+                return { $ref: '$item', path };
+            }
             if (templateParamName && callee.text === templateParamName) {
                 const templateStr = expr.arguments[0] && ts.isStringLiteral(expr.arguments[0])
                     ? expr.arguments[0].text
@@ -39,7 +44,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
                 const refs = [];
                 if (refsArg && ts.isArrayLiteralExpression(refsArg)) {
                     for (const el of refsArg.elements) {
-                        const resolved = extractAstValue(el, refParamName, templateParamName);
+                        const resolved = extractAstValue(el, refParamName, templateParamName, itemParamName);
                         if (typeof resolved === 'object' &&
                             resolved !== null &&
                             '$ref' in resolved) {
@@ -64,7 +69,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
         }
     }
     if (ts.isArrayLiteralExpression(expr)) {
-        return expr.elements.map((el) => extractAstValue(el, refParamName, templateParamName));
+        return expr.elements.map((el) => extractAstValue(el, refParamName, templateParamName, itemParamName));
     }
     if (ts.isObjectLiteralExpression(expr)) {
         const obj = {};
@@ -78,7 +83,7 @@ function extractAstValue(expr, refParamName, templateParamName) {
                     : null;
             if (!key)
                 continue;
-            obj[key] = extractAstValue(prop.initializer, refParamName, templateParamName);
+            obj[key] = extractAstValue(prop.initializer, refParamName, templateParamName, itemParamName);
         }
         return obj;
     }
@@ -125,6 +130,11 @@ function extractInputMapping(node, _checker) {
     const templateParamName = node.parameters.length > 1 && ts.isIdentifier(node.parameters[1].name)
         ? node.parameters[1].name.text
         : 'template';
+    // `$item` is appended after `template` so neither existing arrow shape —
+    // `(ref) => ...` nor `(ref, template) => ...` — shifts a parameter.
+    const itemParamName = node.parameters.length > 2 && ts.isIdentifier(node.parameters[2].name)
+        ? node.parameters[2].name.text
+        : undefined;
     const input = {};
     for (const prop of bodyObj.properties) {
         if (!ts.isPropertyAssignment(prop))
@@ -136,13 +146,48 @@ function extractInputMapping(node, _checker) {
                 : null;
         if (!key)
             continue;
-        const value = extractAstValue(prop.initializer, refParamName, templateParamName);
+        const value = extractAstValue(prop.initializer, refParamName, templateParamName, itemParamName);
         if (value !== undefined) {
             input[key] = value;
         }
     }
     return input;
 }
+/**
+ * Extract a `forEach` source, authored either as a bare node id (`'listRows'`)
+ * or as a callback returning a ref (`(ref) => ref('listRows', 'rows')`).
+ */
+function extractForEachConfig(node) {
+    while (ts.isAsExpression(node) || ts.isParenthesizedExpression(node)) {
+        node = node.expression;
+    }
+    if (ts.isStringLiteral(node)) {
+        return { $ref: node.text };
+    }
+    if (ts.isArrowFunction(node)) {
+        const refParamName = node.parameters.length > 0 && ts.isIdentifier(node.parameters[0].name)
+            ? node.parameters[0].name.text
+            : 'ref';
+        let body = node.body;
+        if (ts.isBlock(body)) {
+            for (const stmt of body.statements) {
+                if (ts.isReturnStatement(stmt) && stmt.expression) {
+                    body = stmt.expression;
+                }
+            }
+        }
+        if (!ts.isExpression(body))
+            return undefined;
+        const value = extractAstValue(body, refParamName, undefined);
+        if (typeof value === 'object' &&
+            value !== null &&
+            '$ref' in value &&
+            typeof value.$ref === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
 /**
  * Extract next config (string, array, or record)
  */
@@ -301,6 +346,8 @@ function extractGraphFromNewFormat(nodesNode, configNode, checker, state) {
             nodeId,
             rpcName,
             input: {},
+            forEach: undefined,
+            mode: undefined,
             next: undefined,
             onError: undefined,
             retries: undefined,
@@ -326,6 +373,8 @@ function extractGraphFromNewFormat(nodesNode, configNode, checker, state) {
                     nodes[nodeId].next = nodeConfig.next;
                     nodes[nodeId].onError = nodeConfig.onError;
                     nodes[nodeId].input = nodeConfig.input;
+                    nodes[nodeId].forEach = nodeConfig.forEach;
+                    nodes[nodeId].mode = nodeConfig.mode;
                     nodes[nodeId].retries = nodeConfig.retries;
                     nodes[nodeId].retryDelay = nodeConfig.retryDelay;
                     nodes[nodeId].notes = nodeConfig.notes;
@@ -342,6 +391,8 @@ function extractNodeConfigFromObject(obj, checker) {
     let next = undefined;
     let onError = undefined;
     let input = {};
+    let forEach = undefined;
+    let mode = undefined;
     let retries = undefined;
     let retryDelay = undefined;
     let notes = undefined;
@@ -358,6 +409,12 @@ function extractNodeConfigFromObject(obj, checker) {
         else if (propName === 'input') {
             input = extractInputMapping(prop.initializer, checker);
         }
+        else if (propName === 'forEach') {
+            forEach = extractForEachConfig(prop.initializer);
+        }
+        else if (propName === 'mode') {
+            mode = extractStringLiteral(prop.initializer, checker);
+        }
         else if (propName === 'retries') {
             if (ts.isNumericLiteral(prop.initializer)) {
                 retries = Number(prop.initializer.text);
@@ -375,7 +432,7 @@ function extractNodeConfigFromObject(obj, checker) {
             notes = extractStringLiteral(prop.initializer, checker);
         }
     }
-    return { next, onError, input, retries, retryDelay, notes };
+    return { next, onError, input, forEach, mode, retries, retryDelay, notes };
 }
 /**
  * Inspector for pikkuWorkflowGraph() calls

package/dist/error-codes.d.ts

@@ -20,7 +20,7 @@ export declare enum ErrorCode {
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
     SCENARIO_HAS_SERVICES = "PKU673",
     EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
-    SCENARIO_BROWSER_STEP_NEEDS_ACTOR = "PKU677",
+    SCENARIO_STEP_NEEDS_ACTOR = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
     SCENARIO_HAS_NO_ASSERTION = "PKU680",
@@ -30,6 +30,7 @@ export declare enum ErrorCode {
     COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
+    ADDON_NOT_INSTALLED = "PKU340",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -70,6 +71,7 @@ export declare enum ErrorCode {
     DUPLICATE_CORE_VERSION = "PKU717",
     CORE_VERSION_SKEW = "PKU718",
     SPLIT_TYPE_IDENTITY = "PKU719",
+    SINGLETON_SERVICES_TYPE_UNRESOLVED = "PKU724",
     PII_IN_OUTPUT = "PKU910",
     ADDON_WIRING_NOT_ALLOWED = "PKU920",
     ADDON_CONTRACT_HANDLERS_NOT_ALLOWED = "PKU921",

package/dist/error-codes.js

@@ -22,7 +22,7 @@ export var ErrorCode;
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
     ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
     ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
-    ErrorCode["SCENARIO_BROWSER_STEP_NEEDS_ACTOR"] = "PKU677";
+    ErrorCode["SCENARIO_STEP_NEEDS_ACTOR"] = "PKU677";
     ErrorCode["SCENARIO_STEP_TARGET_NOT_STATIC"] = "PKU678";
     ErrorCode["SCENARIO_NOT_EXTRACTABLE"] = "PKU679";
     ErrorCode["SCENARIO_HAS_NO_ASSERTION"] = "PKU680";
@@ -33,6 +33,7 @@ export var ErrorCode;
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
+    ErrorCode["ADDON_NOT_INSTALLED"] = "PKU340";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -91,6 +92,7 @@ export var ErrorCode;
     ErrorCode["DUPLICATE_CORE_VERSION"] = "PKU717";
     ErrorCode["CORE_VERSION_SKEW"] = "PKU718";
     ErrorCode["SPLIT_TYPE_IDENTITY"] = "PKU719";
+    ErrorCode["SINGLETON_SERVICES_TYPE_UNRESOLVED"] = "PKU724";
     // Data classification errors
     ErrorCode["PII_IN_OUTPUT"] = "PKU910";
     // Addon authoring errors

package/dist/index.d.ts

@@ -12,9 +12,11 @@ export type { SerializableInspectorState } from './utils/serialize-inspector-sta
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
+export type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export type { ContractEntry, VersionHashEntry, VersionValidateError, 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 { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { serializeInspectorState, deserializeInspectorState, } from './utils/ser
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';
 export { generateCustomTypes, sanitizeTypeName, } from './utils/custom-types-generator.js';
+export { unresolvedSchemaReferences } from './utils/post-process.js';
 export { createEmptyManifest, serializeManifest, } from './utils/contract-hashes.js';
 export { serializeMCPJson } from './utils/serialize-mcp-json.js';
 export { deserializeDslWorkflow, deserializeGraphWorkflow, deserializeAllDslWorkflows, } from './utils/workflow/dsl/index.js';

package/dist/inspector.js

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { performance } from 'perf_hooks';
-import { dirname, resolve } from 'path';
+import { dirname, relative, resolve } from 'path';
 import { visitSetup, visitFunctions, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
@@ -11,12 +11,13 @@ import { validateExposedFunctionsGated } from './utils/validate-exposed-function
 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/ecosystem';
+import { pikkuState } from '@pikku/core/state';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js';
 import { finalizeWorkflowHelperTypes, 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 { accumulateSurfaceUsage, surfaceUsageArea, } from './utils/extract-surface-usage.js';
 import { loadAddonFunctionsMeta, loadAddonSchemas, } from './utils/load-addon-functions-meta.js';
 import { computeContractHashes, extractContractsFromMeta, updateManifest, createEmptyManifest, validateContracts, } from './utils/contract-hashes.js';
 /**
@@ -142,6 +143,7 @@ export function getInitialInspectorState(rootDir) {
             files: new Set(),
             usage: new Map(),
         },
+        surfaceUsage: {},
         credentials: {
             definitions: [],
             files: new Set(),
@@ -177,7 +179,7 @@ export function getInitialInspectorState(rootDir) {
             instances: {},
             tagMiddleware: new Map(),
         },
-        aiMiddleware: {
+        agentMiddleware: {
             definitions: {},
         },
         permissions: {
@@ -299,11 +301,19 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         .sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
     logger.debug(`Got source files in ${(performance.now() - startSourceFiles).toFixed(2)}ms`);
     const state = getInitialInspectorState(rootDir);
+    const surfaceAreaCache = new Map();
     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);
         }
+        // Counted in the sweep that already has this file open. The public surface
+        // is documentation, and documentation may not cost a project a second pass
+        // over its source.
+        accumulateSurfaceUsage(sourceFile, {
+            area: surfaceUsageArea(sourceFile.fileName, rootDir, surfaceAreaCache),
+            file: relative(rootDir, sourceFile.fileName),
+        }, state.surfaceUsage);
     }
     // First sweep: add all functions
     const startSetup = performance.now();

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type * as ts from 'typescript';
 import type { SecretUsage } from './utils/extract-secret-usage.js';
+import type { SurfaceUsageCounts } from './utils/extract-surface-usage.js';
 import type { ChannelMessageMeta, ChannelsMeta } from '@pikku/core/channel';
 import type { GatewaysMeta } from '@pikku/core/gateway';
 import type { HTTPWiringsMeta } from '@pikku/core/http';
@@ -8,8 +9,8 @@ import type { TriggerMeta, TriggerSourceMeta } from '@pikku/core/trigger';
 import type { QueueWorkersMeta } from '@pikku/core/queue';
 import type { WorkflowsMeta } from '@pikku/core/workflow';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
-import type { AIAgentMeta } from '@pikku/core/ai-agent';
-import type { ScorerMeta } from '@pikku/core/ai-scorer';
+import type { AgentsMeta } from '@pikku/core/agent';
+import type { ScorerMeta } from '@pikku/core/agent-scorer';
 import type { CLIMeta } from '@pikku/core/cli';
 import type { CLICommandMeta } from '@pikku/core/cli';
 import type { NodesMeta } from '@pikku/core/node';
@@ -20,7 +21,9 @@ 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 { FunctionsMeta, FunctionServicesMeta, FunctionWiresMeta, JSONValue } from '@pikku/core';
+import type { FunctionsMeta } from '@pikku/core/services';
+import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/function';
+import type { JSONValue } from '@pikku/core/utils';
 import type { OpenAPISpecInfo } from './utils/serialize-openapi-json.js';
 import type { ErrorCode, CodedDiagnostic } from './error-codes.js';
 import type { VersionManifest, VersionValidateError } from './utils/contract-hashes.js';
@@ -545,7 +548,7 @@ export interface InspectorState {
         files: Set<string>;
     };
     agents: {
-        agentsMeta: AIAgentMeta;
+        agentsMeta: AgentsMeta;
         files: Map<string, {
             path: string;
             exportedName: string;
@@ -592,6 +595,8 @@ export interface InspectorState {
         /** Secret reads found per source file, keyed by absolute path. */
         usage: Map<string, SecretUsage>;
     };
+    /** How often each `#pikku/*` export is imported, and from where. */
+    surfaceUsage: SurfaceUsageCounts;
     credentials: {
         definitions: CredentialDefinitions;
         files: Set<string>;
@@ -619,7 +624,7 @@ export interface InspectorState {
     };
     middleware: InspectorMiddlewareState;
     channelMiddleware: InspectorChannelMiddlewareState;
-    aiMiddleware: InspectorAIMiddlewareState;
+    agentMiddleware: InspectorAIMiddlewareState;
     permissions: InspectorPermissionState;
     serviceAggregation: {
         requiredServices: Set<string>;

package/dist/utils/annotate-http-route-auth.js

@@ -1,3 +1,4 @@
+import { resolveFunctionMeta } from './resolve-function-meta.js';
 /**
  * Resolve, per HTTP route, whether reaching it requires a session.
  *
@@ -22,7 +23,7 @@ export function annotateHttpRouteAuth(state) {
     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];
+            const meta = resolveFunctionMeta(state, route.pikkuFuncId);
             route.requiresSession =
                 // A pikkuFunc always requires a session, on every path.
                 meta?.sessionless === false ||

package/dist/utils/check-secret-sinks.js

@@ -38,7 +38,8 @@ const SINKS = [
 export function findRevealedSecretSinks(checker, handler) {
     const violations = [];
     const visit = (node) => {
-        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
             const sink = describeSink(checker, node.expression);
             if (sink) {
                 for (const arg of node.arguments) {

package/dist/utils/compute-required-schemas.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '@pikku/core';
+import type { FunctionsMeta } from '@pikku/core/services';
 import type { TypesMap } from '../types-map.js';
 import type { SchemaRef } from '../types.js';
 export declare function computeRequiredSchemas(functionsMeta: FunctionsMeta, typesMap: TypesMap, additionalTypes?: string[], schemaLookup?: Map<string, SchemaRef>): Set<string>;

package/dist/utils/contract-hashes.d.ts

@@ -1,4 +1,5 @@
-import type { FunctionsMeta, JSONValue } from '@pikku/core';
+import type { FunctionsMeta } from '@pikku/core/services';
+import type { JSONValue } from '@pikku/core/utils';
 import type { TypesMap } from '../types-map.js';
 import { ErrorCode } from '../error-codes.js';
 export type ContractEntry = {

package/dist/utils/contract-hashes.js

@@ -1,4 +1,4 @@
-import { parseVersionedId } from '@pikku/core';
+import { parseVersionedId } from '@pikku/core/utils';
 import { ErrorCode } from '../error-codes.js';
 import { canonicalJSON, hashString } from './hash.js';
 function isHashEntry(v) {

package/dist/utils/extract-function-name.js

@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { createHash } from 'crypto';
 import { relative } from 'path';
-import { formatVersionedId } from '@pikku/core';
+import { formatVersionedId } from '@pikku/core/utils';
 /**
  * Deterministic placeholder id for an anonymous/unnamed pikku function or
  * permission. Derived from the call expression's source location (relative path

package/dist/utils/extract-services.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core';
+import type { FunctionServicesMeta, FunctionWiresMeta } from '@pikku/core/function';
 /**
  * Extract services from a function's first parameter destructuring pattern
  */

package/dist/utils/extract-surface-usage.d.ts

@@ -0,0 +1,29 @@
+import ts from 'typescript';
+/**
+ * How often each `#pikku/*` export is imported, the source areas it was
+ * imported from, and the files those imports are written in. Counters only:
+ * this is accumulated during the sweep that already visits every source file,
+ * so nothing here may retain a node.
+ */
+export type SurfaceUsageCounts = Record<string, Record<string, {
+    imports: number;
+    seenIn: string[];
+    files: string[];
+}>>;
+/**
+ * A label a person recognises: the workspace package a file belongs to, or the
+ * top-level source directory it sits under when the project is one package.
+ * The root package is skipped deliberately — naming it would label every file
+ * in a single-package project identically.
+ */
+export declare const surfaceUsageArea: (fileName: string, rootDir: string, cache: Map<string, string | null>) => string;
+/**
+ * Counts the `#pikku/*` imports of one file into `into`. Only the file's own
+ * top-level statements are looked at — an import declaration can appear nowhere
+ * else — so this costs a single pass over the statement list and retains
+ * nothing.
+ */
+export declare const accumulateSurfaceUsage: (sourceFile: ts.SourceFile, { area, file }: {
+    area: string;
+    file: string;
+}, into: SurfaceUsageCounts) => void;