@pikku/inspector 0.12.102 → 0.12.106

package/dist/add/add-workflow.js

@@ -1,11 +1,12 @@
 import * as ts from 'typescript';
+import { relative } from 'node:path';
 import { extractFunctionName } from '../utils/extract-function-name.js';
 import { extractFunctionNode } from '../utils/extract-function-node.js';
 import { ErrorCode } from '../error-codes.js';
 import { extractStringLiteral, isStringLike, isFunctionLike, extractDescription, extractDuration, } from '../utils/extract-node-value.js';
 import { getCommonWireMetaData, getPropertyValue, } from '../utils/get-property-value.js';
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js';
-import { getSourceText, extractActorFromOptions, } from '../utils/workflow/dsl/patterns.js';
+import { getSourceText, extractVirtualUserFromOptions, } from '../utils/workflow/dsl/patterns.js';
 /**
  * Extract a workflow step's display name without letting a non-static name
  * (e.g. a function call) abort the scan. The step name is cosmetic, so a
@@ -141,7 +142,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             type: 'rpc',
                             stepName,
                             rpcName,
-                            actor: extractActorFromOptions(optionsArg),
+                            virtualUser: extractVirtualUserFromOptions(optionsArg),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -164,7 +165,7 @@ function getWorkflowInvocations(node, checker, state, workflowName, steps) {
                             stepName,
                             rpcName,
                             expectEventually: true,
-                            actor: extractActorFromOptions(args.length >= 5 ? args[4] : undefined),
+                            virtualUser: extractVirtualUserFromOptions(args.length >= 5 ? args[4] : undefined),
                         });
                         state.rpc.invokedFunctions.add(rpcName);
                     }
@@ -229,7 +230,7 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         wrapperType = 'complex';
     }
     else if (expression.text === 'pikkuScenario') {
-        // A scenario is a complex workflow whose steps run as actors over the
+        // A scenario is a complex workflow whose steps run as virtual users over the
         // real transport — same extraction rules as complex, distinct meta.
         wrapperType = 'scenario';
     }
@@ -243,7 +244,10 @@ export const addWorkflow = (logger, node, checker, state, options) => {
     const { pikkuFuncId, name, exportedName } = extractFunctionName(node, checker, state.rootDir);
     const workflowName = exportedName || name;
     if (!workflowName) {
-        logger.critical(ErrorCode.MISSING_NAME, `Could not determine workflow name from export.`);
+        const sourceFile = node.getSourceFile();
+        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        logger.critical(ErrorCode.MISSING_NAME, `Could not determine workflow name from export at ${relative(state.rootDir, sourceFile.fileName)}:${line + 1}. ` +
+            `Assign the \`${expression.text}(...)\` call to an exported const; that name is how it is registered.`);
         return;
     }
     // Extract the function node (either direct function or from config.func)
@@ -358,11 +362,11 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         const sink = steps.length > 0 ? [] : steps;
         getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink);
     }
-    // Actor names the flow's steps run as (scenarios) — powers the console
-    // personas view and the Scenario graph badges.
-    const actorNames = [
+    // Virtual user names the flow's steps run as (scenarios) — powers the console
+    // virtual users view and the Scenario graph badges.
+    const virtualUserNames = [
         ...new Set(steps
-            .map((s) => ('actor' in s ? s.actor : undefined))
+            .map((s) => ('virtualUser' in s ? s.virtualUser : undefined))
             .filter((a) => typeof a === 'string')),
     ];
     state.workflows.meta[workflowName] = {
@@ -380,7 +384,7 @@ export const addWorkflow = (logger, node, checker, state, options) => {
         skip,
         scenario: wrapperType === 'scenario' ? true : undefined,
         asserts,
-        actors: actorNames.length > 0 ? actorNames : undefined,
+        virtualUsers: virtualUserNames.length > 0 ? virtualUserNames : undefined,
     };
     // The scenario "logger/config only" rule (PKU673) and the implicit
     // workflow platform-service injection both used to live here, reading

package/dist/error-codes.d.ts

@@ -20,22 +20,28 @@ export declare enum ErrorCode {
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
     SCENARIO_HAS_SERVICES = "PKU673",
     EXPECT_EVENTUALLY_SCENARIO_ONLY = "PKU675",
-    SCENARIO_STEP_NEEDS_ACTOR = "PKU677",
+    SCENARIO_STEP_NEEDS_VIRTUAL_USER = "PKU677",
     SCENARIO_STEP_TARGET_NOT_STATIC = "PKU678",
     SCENARIO_NOT_EXTRACTABLE = "PKU679",
     SCENARIO_HAS_NO_ASSERTION = "PKU680",
-    SCENARIO_STEP_PROSE_NAMES_ACTOR = "PKU681",
+    SCENARIO_STEP_PROSE_NAMES_VIRTUAL_USER = "PKU681",
     SCENARIO_HAS_NO_FEATURE = "PKU682",
     WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     INVALID_DSL_WORKFLOW = "PKU641",
     WORKFLOW_GRAPH_ADDON_NOT_WIRED = "PKU642",
     COMPLEX_WORKFLOW_NOT_ALLOWED = "PKU643",
+    SINGLE_STEP_WORKFLOW = "PKU644",
     REMOTE_ADDON_NOT_DEV_DEPENDENCY = "PKU338",
     REMOTE_ADDON_AUTH_UNRESOLVED = "PKU339",
     ADDON_NOT_INSTALLED = "PKU340",
     ADDON_MCP_FUNCTION_NOT_FOUND = "PKU341",
     ADDON_EXPOSE_FUNCTION_NOT_FOUND = "PKU343",
     ADDON_EXPOSE_NOT_STATIC = "PKU344",
+    ADDON_SCREENS_NOT_STATIC = "PKU345",
+    ADDON_UI_HAS_NO_SCREENS = "PKU346",
+    ADDON_USES_NOT_WIRED = "PKU347",
+    ADDON_NEEDS_NOT_MAPPED = "PKU348",
+    ADDON_CONTENT_GRANT_INVALID = "PKU349",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -48,7 +54,7 @@ export declare enum ErrorCode {
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     DUPLICATE_AUTH_DEFINITION = "PKU581",
     AUTH_NOT_EXPORTED = "PKU582",
-    DUPLICATE_PERSONAS_DEFINITION = "PKU585",
+    DUPLICATE_VIRTUAL_USERS_DEFINITION = "PKU585",
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",

package/dist/error-codes.js

@@ -22,16 +22,17 @@ export var ErrorCode;
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
     ErrorCode["SCENARIO_HAS_SERVICES"] = "PKU673";
     ErrorCode["EXPECT_EVENTUALLY_SCENARIO_ONLY"] = "PKU675";
-    ErrorCode["SCENARIO_STEP_NEEDS_ACTOR"] = "PKU677";
+    ErrorCode["SCENARIO_STEP_NEEDS_VIRTUAL_USER"] = "PKU677";
     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["SCENARIO_STEP_PROSE_NAMES_VIRTUAL_USER"] = "PKU681";
     ErrorCode["SCENARIO_HAS_NO_FEATURE"] = "PKU682";
     ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     ErrorCode["INVALID_DSL_WORKFLOW"] = "PKU641";
     ErrorCode["WORKFLOW_GRAPH_ADDON_NOT_WIRED"] = "PKU642";
     ErrorCode["COMPLEX_WORKFLOW_NOT_ALLOWED"] = "PKU643";
+    ErrorCode["SINGLE_STEP_WORKFLOW"] = "PKU644";
     // Remote addon (wireRemoteAddon) validation
     ErrorCode["REMOTE_ADDON_NOT_DEV_DEPENDENCY"] = "PKU338";
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
@@ -39,6 +40,11 @@ export var ErrorCode;
     ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
     ErrorCode["ADDON_EXPOSE_FUNCTION_NOT_FOUND"] = "PKU343";
     ErrorCode["ADDON_EXPOSE_NOT_STATIC"] = "PKU344";
+    ErrorCode["ADDON_SCREENS_NOT_STATIC"] = "PKU345";
+    ErrorCode["ADDON_UI_HAS_NO_SCREENS"] = "PKU346";
+    ErrorCode["ADDON_USES_NOT_WIRED"] = "PKU347";
+    ErrorCode["ADDON_NEEDS_NOT_MAPPED"] = "PKU348";
+    ErrorCode["ADDON_CONTENT_GRANT_INVALID"] = "PKU349";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -60,7 +66,7 @@ export var ErrorCode;
     // scopes and roles held this rule until the generated `admin` tree made it
     // unsatisfiable, and get it back once `admin` is a default scope nobody
     // declares. Do not reuse those two numbers for anything else.
-    ErrorCode["DUPLICATE_PERSONAS_DEFINITION"] = "PKU585";
+    ErrorCode["DUPLICATE_VIRTUAL_USERS_DEFINITION"] = "PKU585";
     // HTTP Route errors
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, ScreensManifestMeta, AddonScreenMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';

package/dist/inspector.js

@@ -9,9 +9,10 @@ import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
 import { toProgramPath } from './utils/program-path.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateAddonUses, validateAddonContentGrants, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validateVirtualUserRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateScenarioFeatures, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
+import { validateSingleStepWorkflows } from './utils/validate-single-step-workflows.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/state';
@@ -169,7 +170,7 @@ export function getInitialInspectorState(rootDir) {
             definitions: [],
             files: new Set(),
         },
-        personas: {
+        virtualUsers: {
             definitions: [],
             files: new Set(),
         },
@@ -408,6 +409,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);
         validateWorkflowGraphAddons(logger, state);
+        validateSingleStepWorkflows(logger, state);
         validateScenarioServices(logger, state);
         validateScenarioSteps(logger, state);
         validateScenarioFeatures(logger, state);
@@ -427,12 +429,14 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         validateSecretOverrides(logger, state);
         validateVariableOverrides(logger, state);
         validateCredentialOverrides(logger, state);
+        validateAddonUses(logger, state);
+        validateAddonContentGrants(logger, state);
         validateRemoteAddonDependencies(logger, state);
         validateRemoteAddonAuth(logger, state);
         applyDeclaredScopes(state);
         validateScopeReferences(logger, state);
         validateSystemRoleScopes(logger, state);
-        validatePersonaRoles(logger, state);
+        validateVirtualUserRoles(logger, state);
         logger.endValidationPass?.();
     }
     const cpu = process.cpuUsage(cpuStart);

package/dist/types.d.ts

@@ -19,7 +19,7 @@ import type { CredentialDefinitions } from '@pikku/core/credential';
 import type { ScopeDefinitions } from '@pikku/core/scope';
 import type { SystemRoleDefinitions } from '@pikku/core/role';
 import type { FeatureFlagDefinitions } from '@pikku/core/flag';
-import type { PersonaDefinitions } from '@pikku/core/persona';
+import type { VirtualUserDefinitions } from '@pikku/core/virtual-user';
 import type { VariableDefinitions } from '@pikku/core/variable';
 import type { TypesMap } from './types-map.js';
 import type { FunctionsMeta } from '@pikku/core/services';
@@ -491,7 +491,38 @@ export type CredentialOverrideMeta = string | {
     name?: string;
     mode?: 'singleton' | 'wire';
 };
+/** A screen of an addon as `defineScreens` declares it, read statically. */
+export type AddonScreenMeta = {
+    path: string;
+    title: string;
+    nav?: boolean;
+    scopes?: string[];
+} & ({
+    component: string;
+    app?: undefined;
+} | {
+    app: string;
+    component?: undefined;
+});
+export type ScreensManifestMeta = {
+    title: string;
+    icon?: string;
+    /** The source file whose `defineScreens` call declared this manifest. */
+    file: string;
+    screens: AddonScreenMeta[];
+    /**
+     * The addon's role: every scope its own functions require, derived by
+     * `pikku all` and never declared. Absent from the raw `defineScreens` read.
+     * On a wired instance it also carries the host's `wireAddon` scopes, which
+     * the runner demands of every function in the package.
+     */
+    scopes?: string[];
+};
 export interface InspectorState {
+    /** Set when this package calls `defineScreens`: the screens it ships. */
+    screensManifest?: ScreensManifestMeta;
+    /** The screens of the addons this project wires with `ui: true`, by namespace. */
+    addonScreens?: Record<string, ScreensManifestMeta>;
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
     wireServicesTypeImportMap: PathToNameAndType;
@@ -605,7 +636,11 @@ export interface InspectorState {
             package: string;
             /** The app source file whose `wireAddon` call declared this instance. */
             file?: string;
+            /** Declared with `ui: true`: the package must ship screens, and the host mounts them. */
+            ui?: boolean;
             rpcEndpoint?: string;
+            /** The other addons this instance may call: package -> the name it is wired under. */
+            uses?: Record<string, string>;
             /**
              * `true` offers every function the addon declared `mcp: true`; a list
              * names the functions to offer, whatever the addon declared. Absent
@@ -660,6 +695,13 @@ export interface InspectorState {
              * `CredentialService` instead of one scoped to its declared credentials.
              */
             globalCredentials?: string;
+            contentBucket?: string;
+            contentGrants?: Record<string, string>;
+            /**
+             * The app's stated reason for handing this instance the whole
+             * `ContentService` instead of one scoped to its own folder.
+             */
+            globalContent?: string;
         }>;
         wireAddonFiles: Set<string>;
     };
@@ -742,8 +784,8 @@ export interface InspectorState {
         definitions: FeatureFlagDefinitions;
         files: Set<string>;
     };
-    personas: {
-        definitions: PersonaDefinitions;
+    virtualUsers: {
+        definitions: VirtualUserDefinitions;
         files: Set<string>;
     };
     variables: {

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

@@ -30,7 +30,7 @@ export function funcIdToTypeName(id) {
 }
 /**
  * The step wrappers, whichever kind of subject acts in them. A scenario calls a
- * platform or addon step by name exactly as it calls a persona one.
+ * platform or addon step by name exactly as it calls a virtual user one.
  */
 const SCENARIO_STEP_WRAPPERS = new Set([
     'pikkuScenarioStep',

package/dist/utils/get-property-value.js

@@ -102,7 +102,7 @@ export const assertStringLiteralProperty = (obj, propertyName, wiringType, logge
  * that anything written as an expression comes through raw: a `description`
  * split across lines as `'Fetch the thing ' + 'from upstream'` reaches
  * `infra.json` with the quotes and the `+` still in it, and is rendered that
- * way in the fabric console.
+ * way in the cloud console.
  *
  * Deliberately checker-free, unlike `extractStringLiteral`. Every value this
  * resolves is a literal in the same expression, so no symbol resolution is

package/dist/utils/load-addon-functions-meta.d.ts

@@ -8,11 +8,6 @@ export declare const describeMissingAddonMeta: (namespace: string, packageName:
  * Every source starts off: the app turns one on at runtime.
  */
 export declare const namespaceAddonWebhookSources: (sources: WebhookSourcesMeta, namespace: string) => WebhookSourcesMeta;
-/**
- * After the setup sweep discovers wireAddon() declarations, load each addon
- * package's function metadata so that wiring handlers (channels, HTTP routes,
- * schedules, etc.) can look up addon function types during the routes sweep.
- */
 export declare function loadAddonFunctionsMeta(logger: InspectorLogger, state: InspectorState): Promise<void>;
 /**
  * Load addon schemas into state.schemas. Called after generateAllSchemas

package/dist/utils/load-addon-functions-meta.js

@@ -45,6 +45,7 @@ const applyPackageToCLICommands = (commands, packageName, namespace) => {
             }
             if (namespace &&
                 typeof command.pikkuFuncId === 'string' &&
+                command.pikkuFuncId !== '' &&
                 !command.pikkuFuncId.includes(':')) {
                 command.pikkuFuncId = `${namespace}:${command.pikkuFuncId}`;
             }
@@ -181,6 +182,27 @@ export const namespaceAddonWebhookSources = (sources, namespace) => {
  * package's function metadata so that wiring handlers (channels, HTTP routes,
  * schedules, etc.) can look up addon function types during the routes sweep.
  */
+const loadScreensManifest = async (require, packageName) => {
+    const path = resolveAddonMeta(require, packageName, 'screens/pikku-screens-meta');
+    if (!path)
+        return null;
+    return JSON.parse(await readFile(path, 'utf-8'));
+};
+const readAddonNeeds = async (dirs, packageName) => {
+    const dir = findInstalledPackageDir(dirs, packageName);
+    if (!dir)
+        return [];
+    try {
+        const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
+        const uses = pkg?.pikku?.uses;
+        return Array.isArray(uses)
+            ? uses.filter((u) => typeof u === 'string')
+            : [];
+    }
+    catch {
+        return [];
+    }
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -194,6 +216,37 @@ export async function loadAddonFunctionsMeta(logger, state) {
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
+            for (const needed of await readAddonNeeds(dirs, decl.package)) {
+                if (!decl.uses?.[needed]) {
+                    logger.critical(ErrorCode.ADDON_NEEDS_NOT_MAPPED, `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
+                }
+            }
+            if (decl.ui) {
+                let manifest;
+                let unreadable = false;
+                try {
+                    manifest = await loadScreensManifest(require, decl.package);
+                }
+                catch (e) {
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${decl.package} could not be read: ${e instanceof Error ? e.message : e}`);
+                    unreadable = true;
+                }
+                if (unreadable) {
+                    // reported above; the addon's functions and scopes still load
+                }
+                else if (!manifest || manifest.screens.length === 0) {
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a defineScreens call to the package, or drop ui.`);
+                }
+                else {
+                    ;
+                    (state.addonScreens ??= {})[namespace] = {
+                        ...manifest,
+                        scopes: [
+                            ...new Set([...(manifest.scopes ?? []), ...(decl.scopes ?? [])]),
+                        ].sort(),
+                    };
+                }
+            }
             // Verbose first. `description` is one of the fields stripped from the
             // minimal copy, and it is what an addon's function is offered to a model
             // under — both as an MCP tool below and as an agent tool. Read the minimal

package/dist/utils/post-process.d.ts

@@ -1,7 +1,7 @@
-import type { InspectorState, InspectorLogger, InspectorOptions } from "../types.js";
-import type { PermissionMetadata } from "@pikku/core/function";
-import type { MiddlewareMetadata } from "@pikku/core/middleware";
-import type ts from "typescript";
+import type { InspectorState, InspectorLogger, InspectorOptions } from '../types.js';
+import type { PermissionMetadata } from '@pikku/core/function';
+import type { MiddlewareMetadata } from '@pikku/core/middleware';
+import type ts from 'typescript';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -15,7 +15,7 @@ import type ts from "typescript";
  * onto the handler meta. Re-derived every inspect and ordered BEFORE
  * `aggregateRequiredServices` so it flows into `requiredServices`.
  */
-export declare function stampAuthHandlerServices(state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function stampAuthHandlerServices(state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
  * Only extracts type:'wire' variants (individual middleware/permissions).
@@ -29,10 +29,12 @@ export declare function extractWireNames(list?: Array<MiddlewareMetadata | Permi
  * Note: usedFunctions, usedMiddleware, and usedPermissions are tracked directly
  * in the add-* methods during AST traversal for efficiency.
  */
-export declare function aggregateRequiredServices(state: InspectorState | Omit<InspectorState, "typesLookup">): void;
-export declare function validateSecretOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
-export declare function validateCredentialOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
-export declare function validateVariableOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function aggregateRequiredServices(state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateSecretOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateAddonUses(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateAddonContentGrants(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateCredentialOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateVariableOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Every wired addon must be installed, in the bucket matching how it is used.
  *
@@ -56,14 +58,14 @@ export declare function validateVariableOverrides(logger: InspectorLogger, state
  * up in `dependencies`. Asking the resolver is the only question that matches
  * what the loader will actually do.
  */
-export declare function validateRemoteAddonDependencies(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateRemoteAddonDependencies(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * The auth a `wireRemoteAddon` consumer binds must reference a slot the consumer
  * actually declares: a `credentialId` must be a wired credential, a `secretId`
  * a wired secret. A custom `resolve()` and a public (omitted) surface are not
  * statically checkable and are left to runtime.
  */
-export declare function validateRemoteAddonAuth(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateRemoteAddonAuth(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function computeResolvedIOTypes(state: InspectorState): void;
 export declare function computeMiddlewareGroupsMeta(state: InspectorState): void;
 export declare function computePermissionsGroupsMeta(state: InspectorState): void;
@@ -88,11 +90,11 @@ export declare function validateSchemaReferences(logger: InspectorLogger, state:
  * A model is either concrete (`provider/model`) or an alias, which must appear
  * in the `models` table from pikku.config.json.
  */
-export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">, modelAliases?: Record<string, string>): void;
+export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>, modelAliases?: Record<string, string>): void;
 /**
  * Scenarios are pure stories of remote RPCs (same rule as client-side CLI
  * renderers): the func may only destructure logger/config — everything else
- * must go through actor steps so the flow runs against the TARGET
+ * must go through virtual user steps so the flow runs against the TARGET
  * environment, never local services.
  *
  * This runs in post-processing rather than in `addWorkflow` because
@@ -100,17 +102,17 @@ export declare function validateAgentModels(logger: InspectorLogger, state: Insp
  * `addFunctions` (`visitFunctions`) has populated `state.functions.meta` — so
  * the check read `undefined` there and never fired.
  */
-export declare function validateScenarioServices(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+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?
+ * Does this step's prose open by naming the virtual user who is already its subject?
  *
- * `composeStepProse` renders the actor as the sentence's subject, so a step
+ * `composeStepProse` renders the virtual user 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
+ * client". Only the subject position counts: a virtual user 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;
+export declare const proseOpensWithVirtualUser: (prose: string, virtualUser: 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
@@ -118,9 +120,9 @@ export declare const proseOpensWithActor: (prose: string, actor: string) => bool
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a step that runs as a persona must be given one (PKU677) — declared by
- *   `actor: true`, or implied by a `browser` binding, since the browser context
- *   signs in as that persona. It is checked statically even though a browser
+ * - a step that runs as a virtual user must be given one (PKU677) — declared by
+ *   `virtualUser: true`, or implied by a `browser` binding, since the browser context
+ *   signs in as that virtual user. It is checked statically even though a browser
  *   binding only runs on a browser run: a step that can never be driven by a
  *   human is a latent failure, not a passing default run.
  * - a scenario written as a step ladder must assert something (PKU680).
@@ -128,7 +130,7 @@ export declare const proseOpensWithActor: (prose: string, actor: string) => bool
  * It also marks the step's function as used, so `scenario run` boots the
  * singletons the step actually needs.
  */
-export declare function validateScenarioSteps(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateScenarioSteps(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Reports scenarios that no `pikkuFeature` lists.
  *
@@ -153,7 +155,7 @@ export declare function validateScenarioSteps(logger: InspectorLogger, state: In
  * the check reports it then and downgrades to a warn naming both sides, rather
  * than accusing a scenario that may well be in that array.
  */
-export declare function validateScenarioFeatures(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateScenarioFeatures(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
  * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never
@@ -178,7 +180,7 @@ export declare function validateSchemaWiringSeparation(logger: InspectorLogger,
  * a name the omit does not cover. A name-based rule misses this; the type does
  * not.
  */
-export declare function validateNoSecretAliasServices(logger: InspectorLogger, checker: ts.TypeChecker, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateNoSecretAliasServices(logger: InspectorLogger, checker: ts.TypeChecker, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Reports secret reads the catalogue does not account for.
  *
@@ -191,8 +193,8 @@ export declare function validateNoSecretAliasServices(logger: InspectorLogger, c
  * deployment is asked for the client id and secret every connect flow needs
  * without an author restating a shape the runtime already fixes.
  */
-export declare function registerDerivedOAuth2AppSecrets(state: InspectorState | Omit<InspectorState, "typesLookup">): void;
-export declare function validateSecretUsage(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function registerDerivedOAuth2AppSecrets(state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+export declare function validateSecretUsage(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function computeDiagnostics(state: InspectorState): void;
 /**
  * Validates that every scope referenced by a function is declared via
@@ -201,7 +203,7 @@ export declare function computeDiagnostics(state: InspectorState): void;
  * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
  * to be declared, and grants its whole subtree.
  */
-export declare function validateScopeReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateScopeReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Resolves every `tools:` entry on every agent and reports the ones that do not
  * land on a real function, or that land on one with nothing to tell the model.
@@ -218,7 +220,7 @@ export declare function validateScopeReferences(logger: InspectorLogger, state:
  * quality loss rather than a failure. A title deliberately does not satisfy it —
  * a title labels a tool in a UI, it does not tell a model when to reach for it.
  */
-export declare function validateAgentToolReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">, options?: InspectorOptions): void;
+export declare function validateAgentToolReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>, options?: InspectorOptions): void;
 /**
  * Validates that every scorer an agent asks to be graded by exists.
  *
@@ -226,7 +228,7 @@ export declare function validateAgentToolReferences(logger: InspectorLogger, sta
  * that has already answered the user — which means a typo would otherwise cost
  * nothing visible and simply grade nothing, forever.
  */
-export declare function validateAgentScorerReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateAgentScorerReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Validates that every scope granted by a system role is declared via
  * `defineScope`. Runs after all visitors, so declaration order does not matter.
@@ -234,21 +236,21 @@ export declare function validateAgentScorerReferences(logger: InspectorLogger, s
  * The same rule functions get, for a sharper reason: a role granting an
  * undeclared scope is not merely useless, it is *invisibly* useless. No
  * function checks the scope, so the role appears to work — every call a
- * persona holding it makes succeeds or fails for unrelated reasons, and the
+ * virtual user holding it makes succeeds or fails for unrelated reasons, and the
  * authorization boundary it was written to describe is never exercised.
  *
  * A `*` suffix grants a subtree; the node it hangs off must exist.
  */
-export declare function validateSystemRoleScopes(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateSystemRoleScopes(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
- * Validates that every role a persona names is declared with
+ * Validates that every role a virtual user names is declared with
  * `defineSystemRole`. Runs after all visitors, so declaration order does not
  * matter.
  *
  * Custom roles are refused rather than tolerated. A role composed in the
  * console does not exist at build time and can be deleted after it, so a
- * persona pinned to one silently stops testing what it claims to — and the
+ * virtual user pinned to one silently stops testing what it claims to — and the
  * symptom is a scatter of 403s that read like authorization findings rather
  * than like a deleted role.
  */
-export declare function validatePersonaRoles(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, "typesLookup">): void;
+export declare function validateVirtualUserRoles(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;