@pikku/inspector 0.12.86 → 0.12.87

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## 0.12.87
+
+### Patch Changes
+
+- a95179a: An AI agent's `providerOptions` now reaches the generated metadata.
+
+  The inspector read `model`, `temperature`, `maxSteps` and `toolChoice` off an agent declaration but never `providerOptions`, so `agentsMeta` always showed an agent with no provider configuration — even though the type says it carries one. Runs were unaffected, since the runner takes the value from the live agent object, which is exactly why the gap went unnoticed by everything except what reads the compiled meta: the console's agent view and `infra.json`.
+
+  The value is read as an object literal of strings, numbers, booleans, arrays and nested objects, all-or-nothing. A computed one is reported as `PKU156` rather than silently dropped.
+
+- 145b32b: Generated type aliases are deterministic
+
+  A type name that collided across files got a `Math.random()` suffix, so every
+  `pikku all` emitted different names into `pikku-agent-map.gen.d.ts` and
+  `pikku-workflow-map.gen.d.ts`. Those files sit in the schema generator's
+  dependency closure, so rewriting them invalidated the schema cache partway
+  through the same run and forced a full `ts-json-schema-generator` pass each
+  time. The suffix now comes from the declaring file's path.
+
+- 42b7ac3: The app decides which of an addon's functions `rpc.exposed` reaches
+
+  `wireAddon` takes `expose?: boolean | string[]`, mirroring `mcp`. Unset or
+  `true` keeps the functions the addon declared `expose: true`; `false` exposes
+  none of the instance's functions; a list names exactly the functions to expose,
+  whether or not the addon declared them, typed against the addon's function
+  names. A listed name the addon does not publish fails the build with PKU343, a value that is not written inline fails it with
+  PKU344,
+  and the deploy analyzer's per-addon unit carries only what the wiring exposes.
+
+- Updated dependencies [4a9dcd2]
+- Updated dependencies [5ab24ad]
+- Updated dependencies [42b7ac3]
+  - @pikku/core@0.12.120
+
 ## 0.12.86
 
 ### Patch Changes

package/dist/add/add-agent.d.ts

@@ -1,4 +1,14 @@
 import * as ts from 'typescript';
 import type { AddWiring, InspectorLogger } from '../types.js';
+/**
+ * Reads `providerOptions` off the declaration so it survives into `agentsMeta`.
+ *
+ * The runner takes the value from the live agent object, so an in-process run
+ * honours it either way — but everything that reads the compiled meta instead
+ * (the console's agent view, `infra.json`, the deploy analyzer) saw an agent
+ * with no provider configuration at all. A computed value is reported rather
+ * than dropped, because that is the case nobody notices.
+ */
+export declare function resolveProviderOptions(obj: ts.ObjectLiteralExpression, agentName: string, logger: InspectorLogger): Record<string, Record<string, unknown>> | null;
 export declare function resolveWorkflowReferences(obj: ts.ObjectLiteralExpression, checker: ts.TypeChecker, agentName: string, logger: InspectorLogger): string[] | null;
 export declare const addAgent: AddWiring;

package/dist/add/add-agent.js

@@ -4,8 +4,33 @@ import { extractWireNames } from '../utils/post-process.js';
 import { extractFunctionName, funcIdToTypeName, } from '../utils/extract-function-name.js';
 import { resolveMiddleware, resolveChannelMiddleware, resolveAgentMiddleware, } from '../utils/middleware.js';
 import { resolvePermissions } from '../utils/permissions.js';
+import { getProperty, jsonObjectProperty } from '../utils/literal-properties.js';
 import { ErrorCode } from '../error-codes.js';
 import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js';
+/**
+ * Reads `providerOptions` off the declaration so it survives into `agentsMeta`.
+ *
+ * The runner takes the value from the live agent object, so an in-process run
+ * honours it either way — but everything that reads the compiled meta instead
+ * (the console's agent view, `infra.json`, the deploy analyzer) saw an agent
+ * with no provider configuration at all. A computed value is reported rather
+ * than dropped, because that is the case nobody notices.
+ */
+export function resolveProviderOptions(obj, agentName, logger) {
+    if (!getProperty(obj, 'providerOptions')) {
+        return null;
+    }
+    const providerOptions = jsonObjectProperty(obj, 'providerOptions');
+    if (!providerOptions) {
+        logger.diagnostic({
+            severity: 'warn',
+            code: ErrorCode.AGENT_PROVIDER_OPTIONS_UNREADABLE,
+            message: `AI agent '${agentName}' has a 'providerOptions' the inspector cannot read statically, so it is missing from the generated metadata. Inline it as an object literal of strings, numbers, booleans, arrays and nested objects.`,
+        });
+        return null;
+    }
+    return providerOptions;
+}
 function resolveToolReferences(obj, checker, agentName, logger) {
     const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
         ts.isIdentifier(p.name) &&
@@ -267,6 +292,7 @@ export const addAgent = (logger, node, checker, state, options) => {
         const maxStepsValue = getPropertyValue(obj, 'maxSteps');
         const temperatureValue = getPropertyValue(obj, 'temperature');
         const toolChoiceValue = getPropertyValue(obj, 'toolChoice');
+        const providerOptionsValue = resolveProviderOptions(obj, nameValue || '', logger);
         const scorersValue = resolveScorerNames(obj, nameValue || '', logger);
         const toolsValue = resolveToolReferences(obj, checker, nameValue || '', logger);
         if (toolsValue) {
@@ -410,6 +436,9 @@ export const addAgent = (logger, node, checker, state, options) => {
             ...(toolChoiceValue !== null && {
                 toolChoice: toolChoiceValue,
             }),
+            ...(providerOptionsValue !== null && {
+                providerOptions: providerOptionsValue,
+            }),
             ...(toolsValue !== null && { tools: toolsValue }),
             ...(agentsValue !== null && { agents: agentsValue }),
             ...(workflowsValue !== null && { workflows: workflowsValue }),

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

@@ -1,4 +1,5 @@
 import * as ts from 'typescript';
+import { ErrorCode } from '../error-codes.js';
 function parseStringArray(node) {
     if (!ts.isArrayLiteralExpression(node))
         return undefined;
@@ -95,6 +96,7 @@ export function addWireAddon(node, state, logger) {
     let pkg;
     let rpcEndpoint;
     let mcp;
+    let expose;
     let mcpEndpoint;
     let auth;
     let tags;
@@ -126,6 +128,18 @@ export function addWireAddon(node, state, logger) {
                     ? prop.initializer.kind === ts.SyntaxKind.TrueKeyword
                     : parseStringArray(prop.initializer);
         }
+        else if (key === 'expose') {
+            expose =
+                prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                    prop.initializer.kind === ts.SyntaxKind.FalseKeyword
+                    ? prop.initializer.kind === ts.SyntaxKind.TrueKeyword
+                    : parseStringArray(prop.initializer);
+            // Read as unset, the deploy analyzer would build this addon's unit from
+            // the addon's own declarations while the runtime follows the real list.
+            if (expose === undefined) {
+                logger.critical(ErrorCode.ADDON_EXPOSE_NOT_STATIC, `wireAddon's expose must be true, false or an array of string literals, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'mcpEndpoint') {
             if (ts.isStringLiteral(prop.initializer)) {
                 mcpEndpoint = prop.initializer.text;
@@ -186,6 +200,7 @@ export function addWireAddon(node, state, logger) {
         rpcEndpoint,
         mcp,
         mcpEndpoint,
+        expose,
         auth,
         tags,
         scopes,

package/dist/error-codes.d.ts

@@ -34,6 +34,8 @@ export declare enum ErrorCode {
     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",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",
@@ -67,6 +69,7 @@ export declare enum ErrorCode {
     AGENT_TOOL_NOT_FOUND = "PKU153",
     AGENT_TOOL_MISSING_DESCRIPTION = "PKU154",
     AGENT_SCORER_NOT_FOUND = "PKU155",
+    AGENT_PROVIDER_OPTIONS_UNREADABLE = "PKU156",
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
     SCHEMA_TRANSFORM_NOT_SUPPORTED = "PKU491",
     SERVICES_NOT_DESTRUCTURED = "PKU410",

package/dist/error-codes.js

@@ -37,6 +37,8 @@ export var ErrorCode;
     ErrorCode["REMOTE_ADDON_AUTH_UNRESOLVED"] = "PKU339";
     ErrorCode["ADDON_NOT_INSTALLED"] = "PKU340";
     ErrorCode["ADDON_MCP_FUNCTION_NOT_FOUND"] = "PKU341";
+    ErrorCode["ADDON_EXPOSE_FUNCTION_NOT_FOUND"] = "PKU343";
+    ErrorCode["ADDON_EXPOSE_NOT_STATIC"] = "PKU344";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";
@@ -85,6 +87,8 @@ export var ErrorCode;
     ErrorCode["AGENT_TOOL_MISSING_DESCRIPTION"] = "PKU154";
     // Agent scorer reference errors
     ErrorCode["AGENT_SCORER_NOT_FOUND"] = "PKU155";
+    // Agent provider configuration errors
+    ErrorCode["AGENT_PROVIDER_OPTIONS_UNREADABLE"] = "PKU156";
     // File structure errors
     ErrorCode["SCHEMA_AND_WIRING_COLOCATED"] = "PKU490";
     // Schema authoring errors

package/dist/types-map.d.ts

@@ -6,6 +6,13 @@ export declare class TypesMap {
     }>;
     addCustomType(name: string, type: string, references: string[]): void;
     addType(originalName: string, path: string): void;
+    /**
+     * A pure function of the path, with no dependence on insertion order: the
+     * alias lands in generated `.d.ts` maps, and anything that varies between
+     * runs rewrites those files, which invalidates the schema cache mid-`pikku
+     * all` and costs a full ts-json-schema-generator pass each time. A counter
+     * over already-taken names would reintroduce that through traversal order.
+     */
     addUniqueType(originalName: string, path: string): string;
     getUniqueName(name: string): string;
     getTypeMeta(name: string): {

package/dist/types-map.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 export class TypesMap {
     map = new Map();
     customTypes = new Map();
@@ -7,8 +8,16 @@ export class TypesMap {
     addType(originalName, path) {
         this.map.set(originalName, { originalName, path });
     }
+    /**
+     * A pure function of the path, with no dependence on insertion order: the
+     * alias lands in generated `.d.ts` maps, and anything that varies between
+     * runs rewrites those files, which invalidates the schema cache mid-`pikku
+     * all` and costs a full ts-json-schema-generator pass each time. A counter
+     * over already-taken names would reintroduce that through traversal order.
+     */
     addUniqueType(originalName, path) {
-        const uniqueName = `${originalName}_${Math.random().toString(36).substring(7)}`;
+        const digest = createHash('sha256').update(path).digest('hex').slice(0, 12);
+        const uniqueName = `${originalName}_${digest}`;
         this.map.set(uniqueName, { originalName, path });
         return uniqueName;
     }

package/dist/types.d.ts

@@ -609,6 +609,13 @@ export interface InspectorState {
              * endpoint, which is where they have always been.
              */
             mcpEndpoint?: boolean | string;
+            /**
+             * Which functions `rpc.exposed` may call under `<name>:<function>`.
+             * Unset or `true` keeps what the addon declared `expose: true`; `false`
+             * exposes none; a list names exactly the functions to expose, whatever
+             * the addon declared.
+             */
+            expose?: boolean | string[];
             /**
              * The addon's own gates. `runPikkuFunc` applies these to every function
              * in the package, on every wiring path — not just `namespace:function`.

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

@@ -20,3 +20,14 @@ export declare const booleanProperty: (config: ts.ObjectLiteralExpression, name:
 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;
+/**
+ * Reads a property whose value is a JSON-shaped object literal — nested
+ * objects, arrays, strings, numbers, booleans and `null`.
+ *
+ * All-or-nothing for the same reason as `stringArrayProperty`, and then some:
+ * these values are handed to a provider verbatim, so a half-read
+ * `providerOptions` would send the model a *different* configuration from the
+ * one in source rather than none. `undefined` for anything computed lets the
+ * caller say so instead of guessing.
+ */
+export declare const jsonObjectProperty: (config: ts.ObjectLiteralExpression, name: string) => Record<string, unknown> | undefined;

package/dist/utils/literal-properties.js

@@ -67,3 +67,82 @@ export const stringArrayProperty = (config, name) => {
 export const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
     ? unwrapAs(node.expression)
     : node;
+/**
+ * Reads a property whose value is a JSON-shaped object literal — nested
+ * objects, arrays, strings, numbers, booleans and `null`.
+ *
+ * All-or-nothing for the same reason as `stringArrayProperty`, and then some:
+ * these values are handed to a provider verbatim, so a half-read
+ * `providerOptions` would send the model a *different* configuration from the
+ * one in source rather than none. `undefined` for anything computed lets the
+ * caller say so instead of guessing.
+ */
+export const jsonObjectProperty = (config, name) => {
+    const value = getProperty(config, name);
+    if (!value) {
+        return undefined;
+    }
+    const read = readJsonValue(value);
+    return read.ok && isPlainRecord(read.value) ? read.value : undefined;
+};
+const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const UNREADABLE = { ok: false };
+const readJsonValue = (node) => {
+    const value = unwrapAs(node);
+    if (ts.isStringLiteralLike(value)) {
+        return { ok: true, value: value.text };
+    }
+    if (ts.isNumericLiteral(value)) {
+        return { ok: true, value: Number(value.text) };
+    }
+    if (ts.isPrefixUnaryExpression(value) &&
+        value.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(value.operand)) {
+        return { ok: true, value: -Number(value.operand.text) };
+    }
+    if (value.kind === ts.SyntaxKind.TrueKeyword) {
+        return { ok: true, value: true };
+    }
+    if (value.kind === ts.SyntaxKind.FalseKeyword) {
+        return { ok: true, value: false };
+    }
+    if (value.kind === ts.SyntaxKind.NullKeyword) {
+        return { ok: true, value: null };
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+        const entries = [];
+        for (const element of value.elements) {
+            const read = readJsonValue(element);
+            if (!read.ok) {
+                return UNREADABLE;
+            }
+            entries.push(read.value);
+        }
+        return { ok: true, value: entries };
+    }
+    if (ts.isObjectLiteralExpression(value)) {
+        const record = {};
+        for (const property of value.properties) {
+            if (!ts.isPropertyAssignment(property)) {
+                return UNREADABLE;
+            }
+            const key = ts.isIdentifier(property.name)
+                ? property.name.text
+                : ts.isStringLiteralLike(property.name)
+                    ? property.name.text
+                    : ts.isNumericLiteral(property.name)
+                        ? property.name.text
+                        : null;
+            if (key === null) {
+                return UNREADABLE;
+            }
+            const read = readJsonValue(property.initializer);
+            if (!read.ok) {
+                return UNREADABLE;
+            }
+            record[key] = read.value;
+        }
+        return { ok: true, value: record };
+    }
+    return UNREADABLE;
+};

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

@@ -188,6 +188,15 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     }
                 }
             }
+            // Same reasoning as mcp: a listed name the addon does not publish is a
+            // function the app believes callable and never is.
+            if (Array.isArray(decl.expose)) {
+                for (const funcName of decl.expose) {
+                    if (!Object.hasOwn(meta, funcName)) {
+                        logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} publishes no such function.`);
+                    }
+                }
+            }
             // Load addon secrets meta
             try {
                 const secretsMetaPath = require.resolve(`${decl.package}/.pikku/secrets/pikku-secrets-meta.gen.json`);

package/dist/utils/validate-exposed-functions-gated.js

@@ -16,28 +16,32 @@ export function validateExposedFunctionsGated(logger, state) {
     for (const [funcName, meta] of Object.entries(state.functions.meta)) {
         if (!meta.expose)
             continue;
-        // A pikkuFunc always requires a session, on every path.
-        if (meta.sessionless === false)
+        if (gatesItself(meta))
             continue;
-        // Scenario steps are refused by rpcExposed regardless of `expose`.
-        if (meta.scenarioStep)
-            continue;
-        // The author declared that the body authorizes its own callers — a gate
-        // this check has no way to see. Taking the claim at face value is the
-        // point: without it the warning fires forever on functions that are fine,
-        // and a warning that is usually wrong stops being read.
-        if (meta.permissionsInBody === true)
-            continue;
-        // The function gates itself.
-        if (meta.auth === true)
+        if (isGatedByItsAddon(state, meta.packageName))
             continue;
-        if (meta.scopes && meta.scopes.length > 0)
+        ungated.push(funcName);
+    }
+    // A `wireAddon` expose list can open an addon function its author never
+    // exposed, so the app that listed it is the one to tell. The namespaced call
+    // is governed by that instance's config alone.
+    //
+    // knowledge: decisions/security/wire-addon-expose-selects-the-rpc-surface.md
+    for (const [namespace, declaration] of state.rpc?.wireAddonDeclarations ??
+        []) {
+        if (!Array.isArray(declaration.expose))
             continue;
-        if (meta.permissions && meta.permissions.length > 0)
+        if (declaration.auth === true)
             continue;
-        if (isGatedByItsAddon(state, meta.packageName))
+        if (declaration.scopes && declaration.scopes.length > 0)
             continue;
-        ungated.push(funcName);
+        const addonMeta = state.addonFunctions?.[namespace] ?? {};
+        for (const funcName of declaration.expose) {
+            const meta = addonMeta[funcName];
+            if (!meta || gatesItself(meta))
+                continue;
+            ungated.push(`${namespace}:${funcName}`);
+        }
     }
     if (ungated.length === 0)
         return;
@@ -64,6 +68,19 @@ export function validateExposedFunctionsGated(logger, state) {
             `${one ? 'it was' : 'they were'} not meant to be callable from outside.`,
     });
 }
+const gatesItself = (meta) => 
+// A pikkuFunc always requires a session, on every path.
+meta.sessionless === false ||
+    // Scenario steps are refused by rpcExposed regardless of `expose`.
+    meta.scenarioStep === true ||
+    // The author declared that the body authorizes its own callers — a gate
+    // this check has no way to see. Taking the claim at face value is the
+    // point: without it the warning fires forever on functions that are fine,
+    // and a warning that is usually wrong stops being read.
+    meta.permissionsInBody === true ||
+    meta.auth === true ||
+    (meta.scopes?.length ?? 0) > 0 ||
+    (meta.permissions?.length ?? 0) > 0;
 /**
  * Whether every function in this package is already gated by its `wireAddon`.
  * Those gates are applied by `runPikkuFunc` on every wiring path, so a function

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.86",
+  "version": "0.12.87",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -55,10 +55,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.118"
+    "@pikku/core": "^0.12.120"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.118",
+    "@pikku/core": "^0.12.120",
     "@types/node": "^24.13.3"
   },
   "engines": {