@pikku/inspector 0.12.2 → 0.12.3

package/dist/types.d.ts

@@ -73,6 +73,7 @@ export interface InspectorFunctionState {
         path: string;
         exportedName: string;
     }>;
+    approvalDescriptions: Record<string, InspectorApprovalDescriptionDefinition>;
 }
 export interface InspectorChannelState {
     meta: ChannelsMeta;
@@ -108,6 +109,13 @@ export interface InspectorChannelMiddlewareState {
 export interface InspectorAIMiddlewareState {
     definitions: Record<string, InspectorMiddlewareDefinition>;
 }
+export interface InspectorApprovalDescriptionDefinition {
+    services: FunctionServicesMeta;
+    wires?: FunctionWiresMeta;
+    sourceFile: string;
+    position: number;
+    exportedName: string | null;
+}
 export interface InspectorPermissionDefinition {
     services: FunctionServicesMeta;
     wires?: FunctionWiresMeta;
@@ -309,6 +317,7 @@ export interface InspectorState {
         wireAddonDeclarations: Map<string, {
             package: string;
             rpcEndpoint?: string;
+            mcp?: boolean;
             secretOverrides?: Record<string, string>;
             variableOverrides?: Record<string, string>;
         }>;
@@ -383,4 +392,5 @@ export interface InspectorState {
     requiredSchemas: Set<string>;
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
+    addonFunctions: Record<string, FunctionsMeta>;
 }

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

@@ -0,0 +1,12 @@
+import type { InspectorState, InspectorLogger } from '../types.js';
+/**
+ * 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
+ * to ensure addon schemas aren't overwritten.
+ */
+export declare function loadAddonSchemas(logger: InspectorLogger, state: InspectorState): Promise<void>;

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

@@ -0,0 +1,76 @@
+import { readFile, readdir } from 'fs/promises';
+import { createRequire } from 'module';
+import { join, dirname } from 'path';
+/**
+ * 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 async function loadAddonFunctionsMeta(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (wireAddonDeclarations.size === 0)
+        return;
+    const require = createRequire(join(state.rootDir, 'package.json'));
+    for (const [namespace, decl] of wireAddonDeclarations) {
+        try {
+            const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
+            const raw = await readFile(metaPath, 'utf-8');
+            const meta = JSON.parse(raw);
+            state.addonFunctions[namespace] = meta;
+            logger.debug(`Loaded ${Object.keys(meta).length} addon functions for '${namespace}' from ${decl.package}`);
+            // If wireAddon has mcp: true, expose addon functions with mcp: true as MCP tools
+            if (decl.mcp) {
+                for (const [funcName, funcMeta] of Object.entries(meta)) {
+                    if (funcMeta.mcp) {
+                        const toolName = `${namespace}:${funcName}`;
+                        state.mcpEndpoints.toolsMeta[toolName] = {
+                            pikkuFuncId: `${namespace}:${funcName}`,
+                            name: toolName,
+                            description: funcMeta.description || funcMeta.title || funcName,
+                            inputSchema: funcMeta.inputSchemaName ?? null,
+                            outputSchema: funcMeta.outputSchemaName ?? null,
+                            tags: funcMeta.tags,
+                        };
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.warn(`Failed to load addon function metadata for '${namespace}' (${decl.package}): ${error.message}`);
+        }
+    }
+}
+/**
+ * Load addon schemas into state.schemas. Called after generateAllSchemas
+ * to ensure addon schemas aren't overwritten.
+ */
+export async function loadAddonSchemas(logger, state) {
+    const { wireAddonDeclarations } = state.rpc;
+    if (wireAddonDeclarations.size === 0)
+        return;
+    const require = createRequire(join(state.rootDir, 'package.json'));
+    for (const [namespace, decl] of wireAddonDeclarations) {
+        try {
+            const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
+            const schemasDir = join(dirname(metaPath), '..', 'schemas', 'schemas');
+            try {
+                const schemaFiles = await readdir(schemasDir);
+                for (const file of schemaFiles) {
+                    if (!file.endsWith('.schema.json'))
+                        continue;
+                    const schemaName = file.replace('.schema.json', '');
+                    if (!state.schemas[schemaName]) {
+                        const schemaRaw = await readFile(join(schemasDir, file), 'utf-8');
+                        state.schemas[schemaName] = JSON.parse(schemaRaw);
+                    }
+                }
+            }
+            catch {
+                // No schemas directory — that's fine
+            }
+        }
+        catch (error) {
+            logger.warn(`Failed to load addon schemas for '${namespace}' (${decl.package}): ${error.message}`);
+        }
+    }
+}

package/dist/utils/post-process.js

@@ -217,6 +217,32 @@ export function computeResolvedIOTypes(state) {
             }
         }
         state.resolvedIOTypes[pikkuFuncId] = { inputType, outputType };
+        if (meta.inputSchemaName && inputType !== 'null') {
+            meta.inputSchemaName = inputType;
+        }
+        if (meta.outputSchemaName && outputType !== 'null') {
+            meta.outputSchemaName = outputType;
+        }
+        if (meta.inputs) {
+            meta.inputs = meta.inputs.map((name) => {
+                try {
+                    return functions.typesMap.getTypeMeta(name).uniqueName;
+                }
+                catch {
+                    return name;
+                }
+            });
+        }
+        if (meta.outputs) {
+            meta.outputs = meta.outputs.map((name) => {
+                try {
+                    return functions.typesMap.getTypeMeta(name).uniqueName;
+                }
+                catch {
+                    return name;
+                }
+            });
+        }
     }
 }
 const serializeGroupMap = (groupMap) => {

package/dist/utils/resolve-function-meta.d.ts

@@ -0,0 +1,11 @@
+import type { FunctionMeta, FunctionsMeta } from '@pikku/core';
+/**
+ * Look up function metadata by pikkuFuncId, checking both local functions
+ * and addon functions. Addon functions use namespaced IDs like 'namespace:funcName'.
+ */
+export declare function resolveFunctionMeta(state: {
+    functions: {
+        meta: FunctionsMeta;
+    };
+    addonFunctions: Record<string, FunctionsMeta>;
+}, pikkuFuncId: string): FunctionMeta | undefined;

package/dist/utils/resolve-function-meta.js

@@ -0,0 +1,17 @@
+/**
+ * Look up function metadata by pikkuFuncId, checking both local functions
+ * and addon functions. Addon functions use namespaced IDs like 'namespace:funcName'.
+ */
+export function resolveFunctionMeta(state, pikkuFuncId) {
+    // Check local functions first
+    const local = state.functions.meta[pikkuFuncId];
+    if (local)
+        return local;
+    // Check addon functions (namespaced like 'swaggerPetstore:addPet')
+    const colonIndex = pikkuFuncId.indexOf(':');
+    if (colonIndex === -1)
+        return undefined;
+    const namespace = pikkuFuncId.substring(0, colonIndex);
+    const funcName = pikkuFuncId.substring(colonIndex + 1);
+    return state.addonFunctions[namespace]?.[funcName];
+}

package/dist/utils/serialize-inspector-state.d.ts

@@ -100,6 +100,7 @@ export interface SerializableInspectorState {
             path: string;
             exportedName: string;
         }]>;
+        approvalDescriptions: InspectorState['functions']['approvalDescriptions'];
     };
     http: {
         metaInputTypes: Array<[
@@ -253,6 +254,7 @@ export interface SerializableInspectorState {
     requiredSchemas: string[];
     openAPISpec: Record<string, any> | null;
     diagnostics: InspectorDiagnostic[];
+    addonFunctions: InspectorState['addonFunctions'];
 }
 /**
  * Serializes InspectorState to a JSON-compatible format

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

@@ -32,6 +32,7 @@ export function serializeInspectorState(state) {
             typesMap: serializeTypesMap(state.functions.typesMap),
             meta: state.functions.meta,
             files: Array.from(state.functions.files.entries()),
+            approvalDescriptions: state.functions.approvalDescriptions,
         },
         http: {
             metaInputTypes: Array.from(state.http.metaInputTypes.entries()),
@@ -137,6 +138,7 @@ export function serializeInspectorState(state) {
         requiredSchemas: Array.from(state.requiredSchemas),
         openAPISpec: state.openAPISpec,
         diagnostics: state.diagnostics,
+        addonFunctions: state.addonFunctions,
     };
 }
 /**
@@ -173,6 +175,7 @@ export function deserializeInspectorState(data) {
             typesMap: deserializeTypesMap(data.functions.typesMap),
             meta: data.functions.meta,
             files: new Map(data.functions.files),
+            approvalDescriptions: data.functions.approvalDescriptions || {},
         },
         http: {
             metaInputTypes: new Map(data.http.metaInputTypes),
@@ -288,5 +291,6 @@ export function deserializeInspectorState(data) {
         requiredSchemas: new Set(data.requiredSchemas || []),
         openAPISpec: data.openAPISpec || null,
         diagnostics: data.diagnostics || [],
+        addonFunctions: data.addonFunctions || {},
     };
 }

package/dist/utils/serialize-mcp-json.js

@@ -1,6 +1,7 @@
+import { resolveFunctionMeta } from './resolve-function-meta.js';
 export const serializeMCPJson = (logger, state) => {
     const { mcpEndpoints, functions, schemas } = state;
-    const { meta: functionsMeta, typesMap } = functions;
+    const { typesMap } = functions;
     const { resourcesMeta, toolsMeta, promptsMeta } = mcpEndpoints;
     const tools = [];
     const resources = [];
@@ -19,9 +20,14 @@ export const serializeMCPJson = (logger, state) => {
             ].includes(typeName)) {
             return undefined;
         }
-        const uniqueName = typesMap.getUniqueName(typeName);
-        if (!uniqueName) {
-            return undefined;
+        // Try local typesMap first, fall back to direct schema lookup (for addon types)
+        let uniqueName;
+        try {
+            uniqueName = typesMap.getUniqueName(typeName);
+        }
+        catch {
+            // Type not in local typesMap — try direct schema lookup (addon schemas)
+            uniqueName = typeName;
         }
         const schema = schemas[uniqueName];
         if (!schema) {
@@ -31,7 +37,7 @@ export const serializeMCPJson = (logger, state) => {
         return schema;
     };
     for (const [name, endpointMeta] of Object.entries(resourcesMeta)) {
-        const functionMeta = functionsMeta[endpointMeta.pikkuFuncId];
+        const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId);
         if (!functionMeta) {
             logger.warn(`Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping resource ${name}.`);
             continue;
@@ -50,7 +56,7 @@ export const serializeMCPJson = (logger, state) => {
         });
     }
     for (const [name, endpointMeta] of Object.entries(toolsMeta)) {
-        const functionMeta = functionsMeta[endpointMeta.pikkuFuncId];
+        const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId);
         if (!functionMeta) {
             logger.warn(`Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping tool ${name}.`);
             continue;
@@ -68,7 +74,7 @@ export const serializeMCPJson = (logger, state) => {
         });
     }
     for (const [name, endpointMeta] of Object.entries(promptsMeta)) {
-        const functionMeta = functionsMeta[endpointMeta.pikkuFuncId];
+        const functionMeta = resolveFunctionMeta(state, endpointMeta.pikkuFuncId);
         if (!functionMeta) {
             logger.warn(`Function ${endpointMeta.pikkuFuncId} not found in functionsMeta. Skipping prompt ${name}.`);
             continue;

package/dist/visit.js

@@ -21,6 +21,7 @@ import { addSecret, addOAuth2Credential } from './add/add-secret.js';
 import { addVariable } from './add/add-variable.js';
 import { addWorkflowGraph } from './add/add-workflow-graph.js';
 import { addAIAgent } from './add/add-ai-agent.js';
+import { addApprovalDescription } from './add/add-approval-description.js';
 export const visitSetup = (logger, checker, node, state, options) => {
     addFileExtendsCoreType(node, checker, state.singletonServicesTypeImportMap, 'CoreSingletonServices', state);
     addFileExtendsCoreType(node, checker, state.wireServicesTypeImportMap, 'CoreServices', state);
@@ -33,6 +34,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addWireAddon(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
     addPermission(logger, node, checker, state, options);
+    addApprovalDescription(logger, node, checker, state, options);
     addWorkflow(logger, node, checker, state, options);
     ts.forEachChild(node, (child) => visitSetup(logger, checker, child, state, options));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.2",
+    "@pikku/core": "^0.12.3",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",

package/src/add/add-ai-agent.ts

@@ -268,6 +268,9 @@ export const addAIAgent: AddWiring = (
       | number
       | null
     const toolChoiceValue = getPropertyValue(obj, 'toolChoice') as string | null
+    const dynamicWorkflowsValue = getPropertyValue(obj, 'dynamicWorkflows') as
+      | string
+      | null
     const toolsValue = resolveToolReferences(
       obj,
       checker,
@@ -455,6 +458,9 @@ export const addAIAgent: AddWiring = (
       }),
       ...(toolsValue !== null && { tools: toolsValue }),
       ...(agentsValue !== null && { agents: agentsValue }),
+      ...(dynamicWorkflowsValue !== null && {
+        dynamicWorkflows: dynamicWorkflowsValue as 'read' | 'always' | 'ask',
+      }),
       tags,
       inputSchema,
       outputSchema,

package/src/add/add-approval-description.ts

@@ -0,0 +1,76 @@
+import * as ts from 'typescript'
+import type { AddWiring } from '../types.js'
+import { extractFunctionName } from '../utils/extract-function-name.js'
+import {
+  extractServicesFromFunction,
+  extractUsedWires,
+} from '../utils/extract-services.js'
+
+/**
+ * Inspect pikkuApprovalDescription() calls and extract metadata
+ */
+export const addApprovalDescription: AddWiring = (
+  logger,
+  node,
+  checker,
+  state
+) => {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+
+  if (!ts.isIdentifier(expression)) return
+  if (expression.text !== 'pikkuApprovalDescription') return
+
+  const arg = args[0]
+  if (!arg) return
+
+  let actualHandler: ts.ArrowFunction | ts.FunctionExpression
+
+  if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) {
+    actualHandler = arg
+  } else {
+    logger.error(`• Handler for pikkuApprovalDescription is not a function.`)
+    return
+  }
+
+  const services = extractServicesFromFunction(actualHandler)
+  const wires = extractUsedWires(actualHandler, 1)
+  let { pikkuFuncId, exportedName } = extractFunctionName(
+    node,
+    checker,
+    state.rootDir
+  )
+
+  if (pikkuFuncId.startsWith('__temp_')) {
+    if (
+      ts.isVariableDeclaration(node.parent) &&
+      ts.isIdentifier(node.parent.name)
+    ) {
+      pikkuFuncId = node.parent.name.text
+    } else if (
+      ts.isPropertyAssignment(node.parent) &&
+      ts.isIdentifier(node.parent.name)
+    ) {
+      pikkuFuncId = node.parent.name.text
+    } else {
+      logger.error(
+        `• pikkuApprovalDescription() must be assigned to a variable or object property. ` +
+          `Extract it to a const: const myApproval = pikkuApprovalDescription(...)`
+      )
+      return
+    }
+  }
+
+  state.functions.approvalDescriptions[pikkuFuncId] = {
+    services,
+    wires: wires.wires.length > 0 || !wires.optimized ? wires : undefined,
+    sourceFile: node.getSourceFile().fileName,
+    position: node.getStart(),
+    exportedName,
+  }
+
+  logger.debug(
+    `• Found approval description '${pikkuFuncId}' with services: ${services.services.join(', ')}`
+  )
+}

package/src/add/add-channel.ts

@@ -18,6 +18,8 @@ import {
 } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { resolveIdentifier } from '../utils/resolve-identifier.js'
+import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
+import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
 
 /**
@@ -92,6 +94,13 @@ function getHandlerNameFromExpression(
 
   // Handle call expressions
   if (ts.isCallExpression(expr)) {
+    // Handle addon('namespace:funcName') calls
+    if (ts.isIdentifier(expr.expression) && expr.expression.text === 'addon') {
+      const [firstArg] = expr.arguments
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        return firstArg.text
+      }
+    }
     const { pikkuFuncId } = extractFunctionName(expr, checker, rootDir)
     return pikkuFuncId
   }
@@ -460,11 +469,11 @@ export function addMessagesRoutes(
         continue
       }
 
-      const fnMeta = state.functions.meta[handlerName]
+      const fnMeta = resolveFunctionMeta(state, handlerName)
       if (!fnMeta) {
         logger.critical(
           ErrorCode.FUNCTION_METADATA_NOT_FOUND,
-          `No function metadata found for handler '${handlerName}'`
+          `No function metadata found for channel handler '${handlerName}' on route '${routeKey}'. If this is an inline function, it must be exported for the inspector to discover it.`
         )
         continue
       }
@@ -478,8 +487,17 @@ export function addMessagesRoutes(
         ? resolveMiddleware(state, init, routeTags, checker)
         : undefined
 
+      // Resolve package name for addon functions (e.g. 'swaggerPetstore:addPet')
+      const colonIdx = handlerName.indexOf(':')
+      const addonNs =
+        colonIdx !== -1 ? handlerName.substring(0, colonIdx) : null
+      const packageName = addonNs
+        ? state.rpc.wireAddonDeclarations.get(addonNs)?.package
+        : undefined
+
       result[channelKey]![routeKey] = {
         pikkuFuncId: handlerName,
+        packageName,
         middleware: routeMiddleware,
       }
     }
@@ -564,8 +582,12 @@ export const addChannel: AddWiring = (
       )
       return
     }
+    const msgPackageName = ts.isIdentifier(onMsgProp)
+      ? resolveAddonName(onMsgProp, checker, state.rpc.wireAddonDeclarations)
+      : null
     message = {
       pikkuFuncId: msgFuncId,
+      ...(msgPackageName && { packageName: msgPackageName }),
     }
   }
 
@@ -579,15 +601,20 @@ export const addChannel: AddWiring = (
   // --- track used functions/middleware for service aggregation ---
   // Track connect/disconnect/message handlers
   let connectFuncId: string | undefined
+  let connectPackageName: string | null = null
   if (connect) {
     const extracted = extractFunctionName(connect, checker, state.rootDir)
     connectFuncId = extracted.pikkuFuncId.startsWith('__temp_')
       ? makeContextBasedId('channel', name, 'connect')
       : extracted.pikkuFuncId
+    connectPackageName = ts.isIdentifier(connect)
+      ? resolveAddonName(connect, checker, state.rpc.wireAddonDeclarations)
+      : null
     state.serviceAggregation.usedFunctions.add(connectFuncId)
   }
 
   let disconnectFuncId: string | undefined
+  let disconnectPackageName: string | null = null
   if (disconnect) {
     const extracted = extractFunctionName(
       disconnect as any,
@@ -597,6 +624,9 @@ export const addChannel: AddWiring = (
     disconnectFuncId = extracted.pikkuFuncId.startsWith('__temp_')
       ? makeContextBasedId('channel', name, 'disconnect')
       : extracted.pikkuFuncId
+    disconnectPackageName = ts.isIdentifier(disconnect)
+      ? resolveAddonName(disconnect, checker, state.rpc.wireAddonDeclarations)
+      : null
     state.serviceAggregation.usedFunctions.add(disconnectFuncId)
   }
 
@@ -634,8 +664,18 @@ export const addChannel: AddWiring = (
     input: null,
     params: params.length ? params : undefined,
     query: query?.length ? query : undefined,
-    connect: connectFuncId ? { pikkuFuncId: connectFuncId } : null,
-    disconnect: disconnectFuncId ? { pikkuFuncId: disconnectFuncId } : null,
+    connect: connectFuncId
+      ? {
+          pikkuFuncId: connectFuncId,
+          ...(connectPackageName && { packageName: connectPackageName }),
+        }
+      : null,
+    disconnect: disconnectFuncId
+      ? {
+          pikkuFuncId: disconnectFuncId,
+          ...(disconnectPackageName && { packageName: disconnectPackageName }),
+        }
+      : null,
     message,
     messageWirings,
     binary: binary === undefined ? undefined : binary,