@pikku/inspector 0.12.49 → 0.12.52

package/dist/utils/literal-properties.d.ts

@@ -0,0 +1,22 @@
+import * as ts from 'typescript';
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+export declare const getProperty: (config: ts.ObjectLiteralExpression, name: string) => ts.Expression | undefined;
+export declare const stringProperty: (config: ts.ObjectLiteralExpression, name: string) => string | undefined;
+export declare const numberProperty: (config: ts.ObjectLiteralExpression, name: string) => number | undefined;
+export declare const booleanProperty: (config: ts.ObjectLiteralExpression, name: string) => boolean | undefined;
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+export declare const stringArrayProperty: (config: ts.ObjectLiteralExpression, name: string) => string[] | undefined;
+/** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
+export declare const unwrapAs: (node: ts.Expression) => ts.Expression;

package/dist/utils/literal-properties.js

@@ -0,0 +1,69 @@
+import * as ts from 'typescript';
+/**
+ * Readers for object-literal properties that must be statically knowable.
+ *
+ * Declarations extracted this way are never evaluated — the CLI reads them from
+ * source and writes them to JSON that a deployed stage carries without the app.
+ * So a computed value is not "unsupported", it is unreadable, and every reader
+ * here returns `undefined` for one rather than guessing.
+ */
+export const getProperty = (config, name) => {
+    const property = config.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === name);
+    return property && ts.isPropertyAssignment(property)
+        ? property.initializer
+        : undefined;
+};
+export const stringProperty = (config, name) => {
+    const value = getProperty(config, name);
+    return value && ts.isStringLiteralLike(value) ? value.text : undefined;
+};
+export const numberProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    // `-1` parses as a unary minus over a literal, not as a literal. Reading it
+    // rather than ignoring it is what lets a negative be *rejected* by the caller
+    // instead of silently dropped and defaulted.
+    if (ts.isPrefixUnaryExpression(value) &&
+        value.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(value.operand)) {
+        return -Number(value.operand.text);
+    }
+    return ts.isNumericLiteral(value) ? Number(value.text) : undefined;
+};
+export const booleanProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    if (value.kind === ts.SyntaxKind.TrueKeyword) {
+        return true;
+    }
+    if (value.kind === ts.SyntaxKind.FalseKeyword) {
+        return false;
+    }
+    return undefined;
+};
+/**
+ * All-or-nothing: an array with one computed entry reads as unreadable rather
+ * than as the entries that happened to be literals. A half-read `roles` or
+ * `scopes` array is worse than none — it typechecks, runs, and grants less
+ * than the source says.
+ */
+export const stringArrayProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value || !ts.isArrayLiteralExpression(value)) {
+        return undefined;
+    }
+    const values = value.elements
+        .filter(ts.isStringLiteralLike)
+        .map((e) => e.text);
+    return values.length === value.elements.length ? values : undefined;
+};
+/** Unwraps `x as const` / `x satisfies T` so a cast is still extracted. */
+export const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;

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

@@ -69,6 +69,25 @@ const applyPackageToChannelContracts = (contracts, packageName, namespace) => {
         }
     }
 };
+/**
+ * Resolves an addon's generated metadata, preferring the verbose copy.
+ *
+ * An addon publishes both: the minimal one its own bootstrap imports, and the
+ * verbose one for anything that needs the fields stripped out of it. A consumer
+ * is squarely in the second category — it is reading the addon to describe it,
+ * not to run it.
+ */
+const resolveAddonMeta = (require, packageName, baseName) => {
+    for (const suffix of ['-verbose.gen.json', '.gen.json']) {
+        try {
+            return require.resolve(`${packageName}/.pikku/${baseName}${suffix}`);
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+};
 /**
  * After the setup sweep discovers wireAddon() declarations, load each addon
  * package's function metadata so that wiring handlers (channels, HTTP routes,
@@ -86,7 +105,13 @@ export async function loadAddonFunctionsMeta(logger, state) {
         if (decl.remote)
             continue;
         try {
-            const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
+            // 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
+            // one and every addon function looks undescribed.
+            const metaPath = resolveAddonMeta(require, decl.package, 'function/pikku-functions-meta');
+            if (!metaPath)
+                throw new Error('no function metadata');
             const raw = await readFile(metaPath, 'utf-8');
             const meta = JSON.parse(raw);
             state.addonFunctions[namespace] = meta;

package/dist/utils/permissions.js

@@ -42,6 +42,14 @@ export function extractPermissionPikkuNames(node, checker, rootDir) {
             if (ts.isPropertyAssignment(prop)) {
                 extractFromElement(prop.initializer);
             }
+            else if (ts.isShorthandPropertyAssignment(prop)) {
+                // `permissions: { canAdminOrg }`. The runtime resolves this exactly
+                // like the longhand form — `verifyPermissions` has a non-array branch —
+                // so dropping it here reported a guarded function as having no
+                // permissions at all, which is the most dangerous direction to be wrong
+                // in: an audit reading meta sees an open door where one is shut.
+                extractFromElement(prop.name);
+            }
         }
     }
     return names;

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

@@ -1,5 +1,6 @@
 import type { InspectorState, InspectorLogger, InspectorOptions } from '../types.js';
 import type { MiddlewareMetadata, PermissionMetadata } from '@pikku/core';
+import type ts from 'typescript';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -69,8 +70,11 @@ export declare function validateScenarioServices(logger: InspectorLogger, state:
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a `browser: true` step must be given an actor (PKU677), since the browser
- *   context signs in as that persona.
+ * - a step declaring a `browser` binding must be given an actor (PKU677), since
+ *   the browser context signs in as that persona. It is checked statically even
+ *   though the 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).
  *
  * It also marks the step's function as used, so `scenario run` boots the
  * singletons the step actually needs.
@@ -92,12 +96,73 @@ export declare function validateWorkflowGraphAddons(logger: InspectorLogger, sta
  * because the pikku state metadata doesn't exist in the CLI context.
  */
 export declare function validateSchemaWiringSeparation(logger: InspectorLogger, state: InspectorState): void;
+/** Marks the functions that keep the full `SecretService`. */
+export declare function computeSecretBrokers(state: InspectorState): void;
+/**
+ * Refuses a singleton service that is a `SecretService` under another name.
+ *
+ * `secrets` is omitted from every function-facing services type, but
+ * `pikkuServices(async ({ secrets }) => ({ cfg: secrets }))` re-exposes it under
+ * 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;
+/**
+ * Reports secret reads the catalogue does not account for.
+ *
+ * `getSecret('X')` with no matching `defineSecret` is a value that will be missing
+ * at first request rather than at deploy; a non-literal key is a read the
+ * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
+ */
+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
- * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
  *
  * 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;
+/**
+ * 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.
+ *
+ * `ref('todos:listTodos')` is a bare string to the inspector — `ref` is not
+ * resolved, only unwrapped — so until now a reference to a function that never
+ * existed generated cleanly and failed at agent-run time. Addon namespaces come
+ * from `wireAddon`, and each addon's generated metadata is read off disk, which
+ * is the only view of it this project has.
+ *
+ * The description check is separate and opt-in (`--strict-meta`), because the
+ * description is what the model is told the tool does: without one, the tool is
+ * offered to it under its own name (`ai-agent-prepare.ts`), which is a silent
+ * 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;
+/**
+ * Validates that every scope granted by a system role is declared via
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * 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
+ * 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;
+/**
+ * Validates that every role a persona 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
+ * 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;

package/dist/utils/post-process.js

@@ -2,6 +2,9 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
+import { isSecretBrokerFunction } from './secret-brokers.js';
+import { findSecretAliasServices } from './secret-alias-services.js';
+import { relative } from 'node:path';
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 import { DYNAMIC_SCENARIO_STEP_TARGET } from './workflow/dsl/patterns.js';
@@ -484,6 +487,9 @@ const serializeGroupMap = (groupMap) => {
             count: meta.count,
             instanceIds: meta.instanceIds,
             isFactory: meta.isFactory,
+            ...(meta.additionalRegistrations && {
+                additionalRegistrations: meta.additionalRegistrations,
+            }),
         };
     }
     return result;
@@ -594,16 +600,21 @@ export function validateScenarioServices(logger, state) {
  *
  * - the step target must be a static string literal (PKU678) — otherwise it
  *   can't be bundled, typed or drawn;
- * - a `browser: true` step must be given an actor (PKU677), since the browser
- *   context signs in as that persona.
+ * - a step declaring a `browser` binding must be given an actor (PKU677), since
+ *   the browser context signs in as that persona. It is checked statically even
+ *   though the 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).
  *
  * It also marks the step's function as used, so `scenario run` boots the
  * singletons the step actually needs.
  */
 export function validateScenarioSteps(logger, state) {
+    const phasesSeen = new Set();
     const visit = (workflowName, steps) => {
         for (const step of steps) {
             if (step.type === 'scenarioStep') {
+                phasesSeen.add(step.phase);
                 if (step.stepFunc === DYNAMIC_SCENARIO_STEP_TARGET) {
                     logger.critical(ErrorCode.SCENARIO_STEP_TARGET_NOT_STATIC, `Scenario '${workflowName}' calls step '${step.stepName}' with a target that isn't a string literal. ` +
                         `A step target must be statically resolvable so it can be bundled, typed and drawn — ` +
@@ -612,8 +623,9 @@ export function validateScenarioSteps(logger, state) {
                 }
                 state.serviceAggregation.usedFunctions.add(step.stepFunc);
                 const stepMeta = state.functions.meta[step.stepFunc];
-                if (stepMeta?.scenarioStepBrowser && !step.actor) {
-                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls browser step '${step.stepFunc}' without an actor. ` +
+                if (stepMeta?.scenarioStepSurfaces?.includes('browser') &&
+                    !step.actor) {
+                    logger.critical(ErrorCode.SCENARIO_BROWSER_STEP_NEEDS_ACTOR, `Scenario '${workflowName}' calls step '${step.stepFunc}', which declares a browser binding, without an actor. ` +
                         `Pass { actor: actors.<name> } so the browser context signs in as that persona.`);
                 }
                 continue;
@@ -641,7 +653,17 @@ export function validateScenarioSteps(logger, state) {
         }
     };
     for (const [workflowName, meta] of Object.entries(state.workflows.meta)) {
+        phasesSeen.clear();
         visit(workflowName, meta.steps ?? []);
+        // A scenario written as a step ladder but with no `then` proves only that
+        // nothing threw. It is also invisible to witness coverage — it contributes
+        // 0/0, so it can never lower the number — which makes an assertion-free
+        // flow the cheapest way to make a suite look better covered than it is.
+        if (phasesSeen.size > 0 && !phasesSeen.has('then')) {
+            logger.critical(ErrorCode.SCENARIO_HAS_NO_ASSERTION, `Scenario '${workflowName}' has ${[...phasesSeen].join('/')} steps but never asserts. ` +
+                `Add a scenario.then(...) naming what the actor should now see — a flow with no 'then' ` +
+                `only proves nothing threw, and contributes nothing to witness coverage.`);
+        }
     }
 }
 /**
@@ -692,13 +714,18 @@ export function validateSchemaWiringSeparation(logger, state) {
     for (const file of state.http.files) {
         wiringFiles.add(file);
     }
-    // Middleware wirings (addHTTPMiddleware calls)
-    for (const meta of state.http.routeMiddleware.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
-    for (const meta of state.middleware.tagMiddleware.values()) {
-        wiringFiles.add(meta.sourceFile);
-    }
+    // Middleware wirings (addHTTPMiddleware calls). A group can be registered
+    // from more than one file, and every one of them is a wiring file.
+    const addGroupFiles = (groups) => {
+        for (const meta of groups.values()) {
+            wiringFiles.add(meta.sourceFile);
+            for (const registration of meta.additionalRegistrations ?? []) {
+                wiringFiles.add(registration.sourceFile);
+            }
+        }
+    };
+    addGroupFiles(state.http.routeMiddleware);
+    addGroupFiles(state.middleware.tagMiddleware);
     // Check for overlap
     for (const file of schemaFiles) {
         if (wiringFiles.has(file)) {
@@ -711,6 +738,85 @@ export function validateSchemaWiringSeparation(logger, state) {
         }
     }
 }
+/** Marks the functions that keep the full `SecretService`. */
+export function computeSecretBrokers(state) {
+    for (const [id, meta] of Object.entries(state.functions.meta)) {
+        if (isSecretBrokerFunction(meta.pikkuFuncId ?? id)) {
+            meta.secretBroker = true;
+        }
+    }
+}
+/**
+ * Refuses a singleton service that is a `SecretService` under another name.
+ *
+ * `secrets` is omitted from every function-facing services type, but
+ * `pikkuServices(async ({ secrets }) => ({ cfg: secrets }))` re-exposes it under
+ * a name the omit does not cover. A name-based rule misses this; the type does
+ * not.
+ */
+export function validateNoSecretAliasServices(logger, checker, state) {
+    if (!('typesLookup' in state)) {
+        return;
+    }
+    const singletonServicesTypes = state.typesLookup.get('SingletonServices');
+    if (!singletonServicesTypes?.length) {
+        return;
+    }
+    const aliases = findSecretAliasServices(singletonServicesTypes[0], checker);
+    if (aliases.length === 0) {
+        return;
+    }
+    const report = (kind, id, services) => {
+        const used = services.filter((service) => aliases.includes(service));
+        if (used.length === 0) {
+            return;
+        }
+        logger.critical(ErrorCode.SECRET_SERVICE_ALIASED, `${kind} '${id}' receives ${used.map((s) => `'${s}'`).join(', ')}, which ${used.length === 1 ? 'is' : 'are'} a SecretService under another name. ` +
+            `SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret value when you construct it and expose only what the function needs.`);
+    };
+    for (const [id, meta] of Object.entries(state.functions.meta)) {
+        if (meta.secretBroker) {
+            continue;
+        }
+        report('Function', id, meta.services?.services ?? []);
+    }
+    for (const [id, def] of Object.entries(state.permissions.definitions)) {
+        report('Permission', id, def.services?.services ?? []);
+    }
+}
+/**
+ * Reports secret reads the catalogue does not account for.
+ *
+ * `getSecret('X')` with no matching `defineSecret` is a value that will be missing
+ * at first request rather than at deploy; a non-literal key is a read the
+ * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
+ */
+export function validateSecretUsage(logger, state) {
+    const declared = new Set(state.secrets.definitions.map((d) => d.secretId));
+    for (const definition of state.secrets.definitions) {
+        if (definition.oauth2?.tokenSecretId) {
+            declared.add(definition.oauth2.tokenSecretId);
+        }
+    }
+    for (const [file, usage] of state.secrets.usage) {
+        const relativeFile = relative(state.rootDir, file);
+        const undeclared = usage.keys.filter((key) => !declared.has(key));
+        if (undeclared.length > 0) {
+            logger.diagnostic({
+                severity: 'warn',
+                code: ErrorCode.SECRET_NOT_DECLARED,
+                message: `${relativeFile} reads ${undeclared.map((k) => `'${k}'`).join(', ')}, which no defineSecret declares. Declare it so it is validated at deploy time and shown to whoever has to provision it.`,
+            });
+        }
+        if (usage.dynamic.length > 0) {
+            logger.diagnostic({
+                severity: 'warn',
+                code: ErrorCode.SECRET_KEY_NOT_STATIC,
+                message: `${relativeFile} reads a secret with a non-literal key (${usage.dynamic.join(', ')}). The deployment cannot narrow its secret scope around a key it cannot see.`,
+            });
+        }
+    }
+}
 export function computeDiagnostics(state) {
     const diagnostics = [];
     for (const [id, meta] of Object.entries(state.functions.meta)) {
@@ -787,7 +893,7 @@ export function computeDiagnostics(state) {
 }
 /**
  * Validates that every scope referenced by a function is declared via
- * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
  *
  * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
  * to be declared, and grants its whole subtree.
@@ -806,7 +912,131 @@ export function validateScopeReferences(logger, state) {
             }
             if (!declared.has(declaredForm)) {
                 const available = Array.from(declared);
-                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with wireScope. Available scopes: ${available.join(', ') || 'none'}`);
+                logger.critical(ErrorCode.INVALID_VALUE, `Function '${funcName}' requires scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
+            }
+        }
+    }
+}
+/**
+ * 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.
+ *
+ * `ref('todos:listTodos')` is a bare string to the inspector — `ref` is not
+ * resolved, only unwrapped — so until now a reference to a function that never
+ * existed generated cleanly and failed at agent-run time. Addon namespaces come
+ * from `wireAddon`, and each addon's generated metadata is read off disk, which
+ * is the only view of it this project has.
+ *
+ * The description check is separate and opt-in (`--strict-meta`), because the
+ * description is what the model is told the tool does: without one, the tool is
+ * offered to it under its own name (`ai-agent-prepare.ts`), which is a silent
+ * 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 function validateAgentToolReferences(logger, state, options = {}) {
+    const agents = Object.entries(state.agents.agentsMeta);
+    if (agents.length === 0)
+        return;
+    const { wireAddonDeclarations } = state.rpc;
+    for (const [agentKey, agent] of agents) {
+        const where = agent.sourceFile ? ` (${agent.sourceFile})` : '';
+        for (const tool of agent.tools ?? []) {
+            // A workflow reference is resolved against the workflow map, not here.
+            if (tool.startsWith('workflow:'))
+                continue;
+            const separator = tool.indexOf(':');
+            let meta;
+            if (separator === -1) {
+                const funcId = state.rpc.internalMeta[tool] ?? tool;
+                meta = state.functions.meta[funcId];
+                if (!meta) {
+                    logger.critical(ErrorCode.AGENT_TOOL_NOT_FOUND, `AI agent '${agentKey}'${where} references tool '${tool}', which is not a function in this project.`);
+                    continue;
+                }
+            }
+            else {
+                const namespace = tool.slice(0, separator);
+                const funcName = tool.slice(separator + 1);
+                const addon = wireAddonDeclarations?.get(namespace);
+                if (!addon) {
+                    const known = Array.from(wireAddonDeclarations?.keys() ?? []);
+                    logger.critical(ErrorCode.AGENT_TOOL_UNKNOWN_NAMESPACE, `AI agent '${agentKey}'${where} references tool '${tool}', but no addon is wired under the namespace '${namespace}'. ` +
+                        `Wired namespaces: ${known.join(', ') || 'none'}.`);
+                    continue;
+                }
+                // An addon that has not been built yet contributed no metadata, which
+                // is not the same as one whose function is missing.
+                const addonMeta = state.addonFunctions[namespace];
+                if (!addonMeta)
+                    continue;
+                meta = addonMeta[funcName];
+                if (!meta) {
+                    logger.critical(ErrorCode.AGENT_TOOL_NOT_FOUND, `AI agent '${agentKey}'${where} references tool '${tool}', but addon '${namespace}' ('${addon.package}') exposes no function '${funcName}'.`);
+                    continue;
+                }
+            }
+            if (options.strictMeta && !meta.description) {
+                logger.critical(ErrorCode.AGENT_TOOL_MISSING_DESCRIPTION, `AI agent '${agentKey}'${where} uses tool '${tool}', which has no description. ` +
+                    `An agent tool's description is what the model is told it does; without one it is offered the tool under its own name. ` +
+                    `Add a 'description' to '${tool}'${meta.title ? " (a 'title' does not count — it labels the tool, it does not explain it)" : ''}.`);
+            }
+        }
+    }
+}
+/**
+ * Validates that every scope granted by a system role is declared via
+ * `defineScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * 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
+ * authorization boundary it was written to describe is never exercised.
+ *
+ * A `*` suffix grants a subtree; the node it hangs off must exist.
+ */
+export function validateSystemRoleScopes(logger, state) {
+    if (!state.systemRoles.definitions.length) {
+        return;
+    }
+    const declared = new Set(flattenScopeDefinitions(state.scopes.definitions).map((s) => s.id));
+    for (const role of state.systemRoles.definitions) {
+        for (const scope of role.scopes) {
+            if (scope === '*') {
+                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants the bare wildcard scope '*'. Grant the roots it should cover instead — '*' hides what the role actually confers.`);
+                continue;
+            }
+            const declaredForm = scope.endsWith(':*') ? scope.slice(0, -2) : scope;
+            if (!declared.has(declaredForm)) {
+                const available = Array.from(declared);
+                logger.critical(ErrorCode.INVALID_VALUE, `System role '${role.name}' grants scope '${scope}' which is not declared. Declare it with defineScope. Available scopes: ${available.join(', ') || 'none'}`);
+            }
+        }
+    }
+}
+/**
+ * Validates that every role a persona 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
+ * symptom is a scatter of 403s that read like authorization findings rather
+ * than like a deleted role.
+ */
+export function validatePersonaRoles(logger, state) {
+    if (!state.personas.definitions.length) {
+        return;
+    }
+    const declared = new Set(state.systemRoles.definitions.map((r) => r.name));
+    for (const persona of state.personas.definitions) {
+        for (const role of persona.roles) {
+            if (!declared.has(role)) {
+                const available = Array.from(declared).sort();
+                logger.critical(ErrorCode.INVALID_VALUE, `Persona '${persona.id}' holds role '${role}', which is not declared with defineSystemRole. ` +
+                    `A persona may only name a system role — a role composed in the console can be deleted, and the persona would go on claiming to test it. ` +
+                    `Declared roles: ${available.join(', ') || 'none'}`);
             }
         }
     }

package/dist/utils/schema-generator.d.ts

@@ -1,5 +1,29 @@
 import type { JSONValue } from '@pikku/core';
 import type { InspectorLogger, InspectorState } from '../types.js';
+/** One file the generated schemas were derived from, as of when they were generated. */
+export type SchemaDep = {
+    path: string;
+    mtimeMs: number;
+    size: number;
+};
+export declare function readDiskTSSchemas(logger: InspectorLogger, cacheDir: string, key: string): {
+    schemas: Record<string, JSONValue>;
+    deps: SchemaDep[];
+} | null;
+export declare function writeDiskTSSchemas(logger: InspectorLogger, cacheDir: string, key: string, schemas: Record<string, JSONValue>, deps: SchemaDep[]): void;
+/**
+ * Where the RUNTIME value of a schema lives, given where TypeScript resolved it.
+ *
+ * A schema imported from a built workspace package resolves to that package's
+ * declaration file, and importing a `.d.ts` yields a module with no exports at
+ * all — every one of them is a type. The value is in the emitted JS beside it, so
+ * that is what gets imported.
+ *
+ * Falls back to the original path when no sibling JS exists, which keeps the
+ * "could not find exported schema" error pointing at the file the developer
+ * actually wrote.
+ */
+export declare const schemaRuntimeFile: (sourceFile: string) => string;
 export declare function generateAllSchemas(logger: InspectorLogger, config: {
     tsconfig: string;
     schemasFromTypes?: string[];