@pikku/inspector 0.12.42 → 0.12.44

package/dist/utils/workflow/graph/finalize-workflows.d.ts

@@ -1,2 +1,9 @@
+import type { SerializedWorkflowGraph } from './workflow-graph.types.js';
 import type { InspectorState } from '../../../types.js';
 export declare function finalizeWorkflows(state: InspectorState): void;
+/**
+ * Hash of graph topology only. `notes` (node- and graph-level) is deliberately
+ * excluded so editing documentation never changes the hash / marks the workflow
+ * as a new version.
+ */
+export declare function computeGraphHash(graph: SerializedWorkflowGraph): string;

package/dist/utils/workflow/graph/finalize-workflows.js

@@ -80,11 +80,20 @@ function computeStepHashes(graph, functionsMeta) {
         node.stepHash = hashString(`${node.nodeId}:${meta?.contractHash ?? ''}`, 12);
     }
 }
-function computeGraphHash(graph) {
+/**
+ * Hash of graph topology only. `notes` (node- and graph-level) is deliberately
+ * excluded so editing documentation never changes the hash / marks the workflow
+ * as a new version.
+ */
+export function computeGraphHash(graph) {
+    const nodesForHash = Object.fromEntries(Object.entries(graph.nodes).map(([nodeId, node]) => {
+        const { notes: _notes, ...rest } = node;
+        return [nodeId, rest];
+    }));
     return hashString(canonicalJSON({
         source: graph.source,
         context: graph.context,
-        nodes: graph.nodes,
+        nodes: nodesForHash,
         entryNodeIds: graph.entryNodeIds,
     }), 12);
 }

package/dist/utils/workflow/graph/serialize-workflow-graph.d.ts

@@ -14,10 +14,12 @@ export declare function serializeWorkflowGraph(definition: {
         input?: (ref: any) => Record<string, unknown>;
         next?: string | string[] | Record<string, string | string[]>;
         onError?: string | string[];
+        notes?: string;
     }>;
 }, options?: {
     description?: string;
     tags?: string[];
+    notes?: string[];
 }): SerializedWorkflowGraph;
 /**
  * Deserialize a workflow graph from JSON to runtime format

package/dist/utils/workflow/graph/serialize-workflow-graph.js

@@ -108,6 +108,9 @@ export function serializeWorkflowGraph(definition, options) {
             next: serializeNext(node.next),
             onError: node.onError,
         };
+        if (node.notes !== undefined) {
+            funcNode.notes = node.notes;
+        }
         nodes[nodeId] = funcNode;
         // Entry nodes have no incoming edges
         if (!hasIncomingEdge.has(nodeId)) {
@@ -120,6 +123,7 @@ export function serializeWorkflowGraph(definition, options) {
         source: 'graph',
         description: options?.description,
         tags: options?.tags,
+        notes: options?.notes,
         nodes,
         entryNodeIds,
     };

package/dist/utils/workflow/graph/workflow-graph.types.d.ts

@@ -51,22 +51,22 @@ export type SerializedNext = string | string[] | {
     conditions: BranchCondition[];
     /** Default target if no conditions match */
     default?: string | string[];
-};
+} | Record<string, string | string[]>;
 /**
  * Node execution options
  */
 export interface NodeOptions {
     /** Number of retry attempts on failure */
     retries?: number;
-    /** Delay between retries (e.g., '1s', '5s') */
-    retryDelay?: string;
+    /** Delay between retries (e.g., '1s', '5s', or a number of milliseconds) */
+    retryDelay?: string | number;
     /** Timeout for node execution (e.g., '30s', '5m') */
     timeout?: string;
 }
 /**
  * Flow node types for control flow (no RPC call)
  */
-export type FlowType = 'sleep' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
+export type FlowType = 'sleep' | 'suspend' | 'approval' | 'branch' | 'parallel' | 'fanout' | 'inline' | 'switch' | 'filter' | 'arrayPredicate' | 'return' | 'cancel' | 'set';
 import type { ContextVariable, WorkflowContext, WorkflowPlannedStep } from '@pikku/core/workflow';
 export type { ContextVariable, WorkflowContext };
 /**
@@ -83,6 +83,8 @@ interface BaseNode {
     onError?: string | string[];
     /** Execution options */
     options?: NodeOptions;
+    /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+    notes?: string;
 }
 /**
  * Function node - calls an RPC
@@ -154,6 +156,8 @@ export interface SerializedWorkflowGraph {
     context?: WorkflowContext;
     /** Serialized nodes */
     nodes: Record<string, SerializedGraphNode>;
+    /** Graph-level free-text notes (e.g. imported sticky notes). Non-semantic — excluded from graphHash. */
+    notes?: string[];
     /** Entry node(s) - first nodes to execute */
     entryNodeIds: string[];
     /** Hash of graph topology (nodes, edges, input mappings) */

package/dist/visit.js

@@ -15,12 +15,14 @@ import { addChannel } from './add/add-channel.js';
 import { addGateway } from './add/add-gateway.js';
 import { addRPCInvocations } from './add/add-rpc-invocations.js';
 import { addWireAddon } from './add/add-wire-addon.js';
+import { addWireRemoteAddon } from './add/add-wire-remote-addon.js';
 import { addMiddleware } from './add/add-middleware.js';
 import { addPermission } from './add/add-permission.js';
 import { addCLI, addCLIRenderers } from './add/add-cli.js';
 import { addAuth } from './add/add-auth.js';
 import { addSecret } from './add/add-secret.js';
 import { addCredential } from './add/add-credential.js';
+import { addScope } from './add/add-scope.js';
 import { addVariable } from './add/add-variable.js';
 import { addWorkflowGraph } from './add/add-workflow-graph.js';
 import { addAIAgent } from './add/add-ai-agent.js';
@@ -36,6 +38,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addFileWithFactory(node, checker, state.serverLifecycleFactories, 'ServerLifecycle');
     addRPCInvocations(node, state, logger);
     addWireAddon(node, state, logger);
+    addWireRemoteAddon(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
     addPermission(logger, node, checker, state, options);
     addApprovalDescription(logger, node, checker, state, options);
@@ -64,6 +67,7 @@ export const visitRoutes = (logger, checker, node, state, options) => {
     addAuth(logger, node, checker, state, nextOptions);
     addSecret(logger, node, checker, state, nextOptions);
     addCredential(logger, node, checker, state, nextOptions);
+    addScope(logger, node, checker, state, nextOptions);
     addVariable(logger, node, checker, state, nextOptions);
     addHTTPRoute(logger, node, checker, state, nextOptions);
     addHTTPRoutes(logger, node, checker, state, nextOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.42",
+  "version": "0.12.44",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -44,10 +44,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.61"
+    "@pikku/core": "^0.12.65"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.61",
+    "@pikku/core": "^0.12.65",
     "@types/node": "^24.11.0"
   },
   "engines": {

package/run-tests.sh

@@ -38,7 +38,7 @@ if [ ${#files[@]} -eq 0 ]; then
 fi
 
 # Construct the node command
-node_cmd=(node --import tsx --test)
+node_cmd=(node --import tsx --expose-gc --test)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then

package/src/add/add-addon-bans.ts

@@ -9,6 +9,7 @@ import { ErrorCode } from '../error-codes.js'
  */
 const BANNED_WIRINGS = new Set([
   'wireAddon',
+  'wireRemoteAddon',
   'wireChannel',
   'wireCLI',
   'wireGateway',

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

@@ -0,0 +1,87 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import * as ts from 'typescript'
+
+import { resolveWorkflowReferences } from './add-ai-agent.js'
+import type { InspectorLogger } from '../types.js'
+
+function createSourceFile(code: string): ts.SourceFile {
+  return ts.createSourceFile('test.ts', code, ts.ScriptTarget.ESNext, true)
+}
+
+function getObjectLiteral(
+  sourceFile: ts.SourceFile
+): ts.ObjectLiteralExpression {
+  let result: ts.ObjectLiteralExpression | undefined
+  ts.forEachChild(sourceFile, function visit(node) {
+    if (ts.isObjectLiteralExpression(node) && !result) {
+      result = node
+    }
+    ts.forEachChild(node, visit)
+  })
+  if (!result) throw new Error('No object literal found')
+  return result
+}
+
+function createLogger(): {
+  logger: InspectorLogger
+  criticals: Array<{ code: unknown; message: string }>
+} {
+  const criticals: Array<{ code: unknown; message: string }> = []
+  const logger = {
+    info: () => {},
+    error: () => {},
+    warn: () => {},
+    debug: () => {},
+    diagnostic: () => {},
+    critical: (code: unknown, message: string) =>
+      criticals.push({ code, message }),
+    hasCriticalErrors: () => criticals.length > 0,
+  } as unknown as InspectorLogger
+  return { logger, criticals }
+}
+
+describe('resolveWorkflowReferences', () => {
+  test('returns null when no workflows property exists', () => {
+    const obj = getObjectLiteral(createSourceFile('const x = { name: "a" }'))
+    const { logger } = createLogger()
+    assert.strictEqual(
+      resolveWorkflowReferences(obj, {} as any, 'a', logger),
+      null
+    )
+  })
+
+  test('returns null for an empty workflows array', () => {
+    const obj = getObjectLiteral(
+      createSourceFile('const x = { workflows: [] }')
+    )
+    const { logger } = createLogger()
+    assert.strictEqual(
+      resolveWorkflowReferences(obj, {} as any, 'a', logger),
+      null
+    )
+  })
+
+  test('resolves ref() and workflow() string-literal references', () => {
+    const obj = getObjectLiteral(
+      createSourceFile(
+        `const x = { workflows: [ref('buildReport'), workflow('country_capitals')] }`
+      )
+    )
+    const { logger, criticals } = createLogger()
+    const result = resolveWorkflowReferences(obj, {} as any, 'planner', logger)
+    assert.deepStrictEqual(result, ['buildReport', 'country_capitals'])
+    assert.strictEqual(criticals.length, 0)
+  })
+
+  test('flags a raw string literal as a critical error', () => {
+    const obj = getObjectLiteral(
+      createSourceFile(`const x = { workflows: ['buildReport'] }`)
+    )
+    const { logger, criticals } = createLogger()
+    const result = resolveWorkflowReferences(obj, {} as any, 'planner', logger)
+    assert.strictEqual(result, null)
+    assert.strictEqual(criticals.length, 1)
+    assert.match(criticals[0].message, /string literal/)
+  })
+})

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

@@ -142,6 +142,114 @@ function resolveAgentReferences(
   return resolved.length > 0 ? resolved : null
 }
 
+export function resolveWorkflowReferences(
+  obj: ts.ObjectLiteralExpression,
+  checker: ts.TypeChecker,
+  agentName: string,
+  logger: InspectorLogger
+): string[] | null {
+  const property = obj.properties.find(
+    (p) =>
+      ts.isPropertyAssignment(p) &&
+      ts.isIdentifier(p.name) &&
+      p.name.text === 'workflows'
+  )
+
+  if (!property || !ts.isPropertyAssignment(property)) {
+    return null
+  }
+
+  const initializer = property.initializer
+  if (!ts.isArrayLiteralExpression(initializer)) {
+    return null
+  }
+
+  const resolved: string[] = []
+
+  for (const element of initializer.elements) {
+    if (ts.isStringLiteral(element)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `AI agent '${agentName}' workflows array contains a string literal '${element.text}'. ` +
+          `Use a workflow reference instead (e.g., ref('<workflowName>') or import the pikkuWorkflowGraph variable).`
+      )
+      continue
+    }
+
+    if (ts.isCallExpression(element) && ts.isIdentifier(element.expression)) {
+      const calleeName = element.expression.text
+      if (calleeName === 'ref' || calleeName === 'workflow') {
+        const [firstArg] = element.arguments
+        if (firstArg && ts.isStringLiteral(firstArg)) {
+          resolved.push(firstArg.text)
+          continue
+        }
+      }
+    }
+
+    if (ts.isIdentifier(element)) {
+      const name = resolveIdentifierToWorkflowName(element, checker)
+      if (name) {
+        resolved.push(name)
+        continue
+      }
+
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `AI agent '${agentName}' workflows array contains identifier '${element.text}' ` +
+          `that could not be resolved to a pikkuWorkflowGraph.`
+      )
+    }
+  }
+
+  return resolved.length > 0 ? resolved : null
+}
+
+function resolveIdentifierToWorkflowName(
+  identifier: ts.Identifier,
+  checker: ts.TypeChecker
+): string | null {
+  const symbol = checker.getSymbolAtLocation(identifier)
+  if (!symbol) return null
+
+  let resolved = symbol
+  if (resolved.flags & ts.SymbolFlags.Alias) {
+    resolved = checker.getAliasedSymbol(resolved) ?? resolved
+  }
+
+  const decl = resolved.valueDeclaration ?? resolved.declarations?.[0]
+  if (!decl) return null
+
+  if (ts.isVariableDeclaration(decl) && decl.initializer) {
+    if (
+      ts.isCallExpression(decl.initializer) &&
+      ts.isIdentifier(decl.initializer.expression) &&
+      (decl.initializer.expression.text === 'pikkuWorkflowGraph' ||
+        decl.initializer.expression.text === 'pikkuWorkflow' ||
+        decl.initializer.expression.text === 'pikkuWorkflowComplex')
+    ) {
+      const firstArg = decl.initializer.arguments[0]
+      if (firstArg && ts.isObjectLiteralExpression(firstArg)) {
+        for (const prop of firstArg.properties) {
+          if (
+            ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === 'name' &&
+            ts.isStringLiteral(prop.initializer)
+          ) {
+            return prop.initializer.text
+          }
+        }
+      }
+      if (ts.isIdentifier(decl.name)) {
+        return decl.name.text
+      }
+    }
+  }
+
+  return null
+}
+
 function resolveIdentifierToRpcName(
   identifier: ts.Identifier,
   checker: ts.TypeChecker
@@ -293,6 +401,19 @@ export const addAIAgent: AddWiring = (
       logger
     )
 
+    const workflowsValue = resolveWorkflowReferences(
+      obj,
+      checker,
+      nameValue || '',
+      logger
+    )
+
+    if (workflowsValue) {
+      for (const workflowName of workflowsValue) {
+        state.workflows.invokedWorkflows.add(workflowName)
+      }
+    }
+
     if (!nameValue) {
       logger.critical(
         ErrorCode.MISSING_NAME,
@@ -460,6 +581,7 @@ export const addAIAgent: AddWiring = (
       }),
       ...(toolsValue !== null && { tools: toolsValue }),
       ...(agentsValue !== null && { agents: agentsValue }),
+      ...(workflowsValue !== null && { workflows: workflowsValue }),
       tags,
       inputSchema,
       outputSchema,

package/src/add/add-credential.ts

@@ -2,6 +2,7 @@ import * as ts from 'typescript'
 import {
   getPropertyValue,
   getArrayPropertyValue,
+  getRecordPropertyValue,
   assertStringLiteralProperty,
 } from '../utils/get-property-value.js'
 import type { AddWiring } from '../types.js'
@@ -44,6 +45,7 @@ export const addCredential: AddWiring = (
       | string
       | null
     const typeValue = getPropertyValue(obj, 'type') as string | null
+    const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
 
     if (!nameValue) {
       logger.critical(
@@ -133,6 +135,10 @@ export const addCredential: AddWiring = (
       const tokenUrl = getPropertyValue(oauth2Obj, 'tokenUrl') as string | null
       const scopes = getArrayPropertyValue(oauth2Obj, 'scopes')
       const pkce = getPropertyValue(oauth2Obj, 'pkce') as boolean | null
+      const additionalParams = getRecordPropertyValue(
+        oauth2Obj,
+        'additionalParams'
+      )
 
       if (appCredentialSecretId && authorizationUrl && tokenUrl && scopes) {
         oauth2 = {
@@ -142,6 +148,7 @@ export const addCredential: AddWiring = (
           tokenUrl,
           scopes,
           pkce: pkce || undefined,
+          additionalParams: additionalParams || undefined,
         }
       }
     }
@@ -173,6 +180,7 @@ export const addCredential: AddWiring = (
       displayName: displayNameValue,
       description: descriptionValue || undefined,
       type: typeValue as 'singleton' | 'wire',
+      docsUrl: docsUrlValue || undefined,
       schema: schemaLookupName,
       oauth2,
       sourceFile,

package/src/add/add-functions.ts

@@ -12,6 +12,7 @@ import type { FunctionServicesMeta } from '@pikku/core'
 import { formatVersionedId, parseVersionedId } from '@pikku/core'
 import {
   getPropertyValue,
+  getArrayPropertyValue,
   getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { canonicalJSON, hashString } from '../utils/hash.js'
@@ -426,6 +427,7 @@ export const addFunctions: AddWiring = (
   let workflowQueued: boolean | undefined
   let workflowRetries: number | undefined
   let workflowTimeout: string | undefined
+  let scopes: string[] | undefined
   let version: number | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
   let nodeDisplayName: string | null = null
@@ -530,6 +532,7 @@ export const addFunctions: AddWiring = (
     workflowTimeout = getPropertyValue(firstArg, 'workflowTimeout') as
       | string
       | undefined
+    scopes = getArrayPropertyValue(firstArg, 'scopes') ?? undefined
 
     // Extract approvalDescription identifier reference
     for (const prop of firstArg.properties) {
@@ -1029,17 +1032,6 @@ export const addFunctions: AddWiring = (
     if (newMiddleware.length > 0) {
       middleware = [...(middleware || []), ...newMiddleware]
     }
-    const existingPermissionTags = new Set(
-      (permissions || [])
-        .filter((p) => p.type === 'tag')
-        .map((p) => (p as any).tag)
-    )
-    const newPermissions = tagEntries.filter(
-      (e) => !existingPermissionTags.has(e.tag)
-    )
-    if (newPermissions.length > 0) {
-      permissions = [...(permissions || []), ...newPermissions]
-    }
   }
 
   const implementationHash = computeImplementationHash({
@@ -1094,6 +1086,7 @@ export const addFunctions: AddWiring = (
     workflowQueued: workflowQueued === true ? true : undefined,
     workflowRetries: workflowRetries ?? undefined,
     workflowTimeout: workflowTimeout ?? undefined,
+    scopes: scopes ?? undefined,
     implementationHash,
     version,
     title,
@@ -1147,7 +1140,6 @@ export const addFunctions: AddWiring = (
       inputSchema: inputNames[0] ?? null,
       outputSchema: outputNames[0] ?? null,
       middleware,
-      permissions,
     }
     state.serviceAggregation.usedFunctions.add(pikkuFuncId)
     extractWireNames(middleware).forEach((n) =>
@@ -1192,6 +1184,12 @@ export const addFunctions: AddWiring = (
 
     if (remote) {
       state.rpc.invokedFunctions.add(pikkuFuncId)
+      // The consumer-facing surface a wireRemoteAddon imports (mirrors exposedMeta)
+      state.rpc.remoteMeta[name] = pikkuFuncId
+      state.rpc.remoteFiles.set(name, {
+        path: node.getSourceFile().fileName,
+        exportedName,
+      })
     }
 
     if (expose) {

package/src/add/add-gateway.ts

@@ -9,6 +9,7 @@ import {
   makeContextBasedId,
 } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
+import { ensureInlineWiringFunction } from '../utils/ensure-function-metadata.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
@@ -83,6 +84,16 @@ export const addGateway: AddWiring = (
     return
   }
 
+  // Register metadata for a func inlined into the wiring (see helper).
+  ensureInlineWiringFunction(
+    state,
+    pikkuFuncId,
+    nameValue,
+    funcInitializer,
+    checker,
+    extracted.isHelper
+  )
+
   const middleware = resolveMiddleware(state, obj, tags, checker)
 
   state.serviceAggregation.usedFunctions.add(pikkuFuncId)

package/src/add/add-http-route.ts

@@ -19,7 +19,7 @@ import type {
   InspectorState,
 } from '../types.js'
 import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
-import { resolveHTTPPermissionsFromObject } from '../utils/permissions.js'
+import { resolvePermissions } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
@@ -381,13 +381,7 @@ export function registerHTTPRoute({
   )
 
   // Resolve permissions
-  const permissions = resolveHTTPPermissionsFromObject(
-    state,
-    fullRoute,
-    obj,
-    tags,
-    checker
-  )
+  const permissions = resolvePermissions(state, obj, tags, checker)
 
   state.serviceAggregation.usedFunctions.add(funcName)
   if (refAddonTarget) {

package/src/add/add-keyed-wiring.ts

@@ -56,6 +56,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
       const rotationPeriodValue = getPropertyValue(obj, 'rotationPeriod') as
         | string
         | null
+      const docsUrlValue = getPropertyValue(obj, 'docsUrl') as string | null
       const idValue = getPropertyValue(obj, config.idField) as string | null
 
       let schemaVariableName: string | null = null
@@ -165,6 +166,7 @@ export const createAddKeyedWiring = (config: KeyedWiringConfig): AddWiring => {
         displayName: displayNameValue,
         description: descriptionValue || undefined,
         rotationPeriod: rotationPeriodValue || undefined,
+        docsUrl: docsUrlValue || undefined,
         [config.idField]: idValue,
         schema: schemaLookupName,
         sourceFile,

package/src/add/add-mcp-prompt.ts

@@ -152,7 +152,6 @@ export const addMCPPrompt: AddWiring = (
       outputSchema,
       arguments: [], // Will be populated by CLI during serialization
       middleware,
-      permissions,
     }
   }
 }

package/src/add/add-mcp-resource.ts

@@ -170,7 +170,6 @@ export const addMCPResource: AddWiring = (
       inputSchema,
       outputSchema,
       middleware,
-      permissions,
     }
   }
 }