@pikku/inspector 0.12.74 → 0.12.81

package/src/add/add-agent.ts

@@ -1,638 +0,0 @@
-import * as ts from 'typescript'
-import {
-  getPropertyValue,
-  getCommonWireMetaData,
-} from '../utils/get-property-value.js'
-import { extractWireNames } from '../utils/post-process.js'
-import type { AddWiring, InspectorLogger, SchemaRef } from '../types.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 { ErrorCode } from '../error-codes.js'
-import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
-
-function resolveToolReferences(
-  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 === 'tools'
-  )
-
-  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}' tools array contains a string literal '${element.text}'. ` +
-          `Use a function reference instead (e.g., import the pikkuFunc variable).`
-      )
-      continue
-    }
-
-    if (ts.isCallExpression(element) && ts.isIdentifier(element.expression)) {
-      const calleeName = element.expression.text
-
-      if (calleeName === 'workflow') {
-        const [firstArg] = element.arguments
-        if (firstArg && ts.isStringLiteral(firstArg)) {
-          resolved.push(`workflow:${firstArg.text}`)
-          continue
-        }
-      }
-
-      if (calleeName === 'ref') {
-        const [firstArg] = element.arguments
-        if (firstArg && ts.isStringLiteral(firstArg)) {
-          resolved.push(firstArg.text)
-          continue
-        }
-      }
-    }
-
-    if (ts.isIdentifier(element)) {
-      const rpcName = resolveIdentifierToRpcName(element, checker)
-      if (rpcName) {
-        resolved.push(rpcName)
-        continue
-      }
-
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `AI agent '${agentName}' tools array contains identifier '${element.text}' ` +
-          `that could not be resolved to a pikkuFunc.`
-      )
-    }
-  }
-
-  return resolved.length > 0 ? resolved : null
-}
-
-function resolveAgentReferences(
-  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 === 'agents'
-  )
-
-  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}' agents array contains a string literal '${element.text}'. ` +
-          `Use an agent reference instead (e.g., import the pikkuAgent variable).`
-      )
-      continue
-    }
-
-    if (ts.isIdentifier(element)) {
-      const name = resolveIdentifierToAgentName(element, checker)
-      if (name) {
-        resolved.push(name)
-        continue
-      }
-
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `AI agent '${agentName}' agents array contains identifier '${element.text}' ` +
-          `that could not be resolved to a pikkuAgent.`
-      )
-    }
-  }
-
-  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
-): 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)
-    ) {
-      const callName = decl.initializer.expression.text
-      if (
-        callName === 'pikkuFunc' ||
-        callName === 'pikkuSessionlessFunc' ||
-        callName === 'pikkuVoidFunc'
-      ) {
-        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 === 'override' &&
-              ts.isStringLiteral(prop.initializer)
-            ) {
-              return prop.initializer.text
-            }
-          }
-        }
-
-        if (ts.isIdentifier(decl.name)) {
-          return decl.name.text
-        }
-      }
-    }
-  }
-
-  return null
-}
-
-function resolveIdentifierToAgentName(
-  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 === 'pikkuAgent'
-    ) {
-      if (ts.isIdentifier(decl.name)) {
-        return decl.name.text
-      }
-    }
-  }
-
-  return null
-}
-
-/**
- * The scorers an agent asks to be graded by, which are plain names rather than
- * references: a scorer is resolved out of the registry at grading time, not
- * imported by the agent, so nothing here has a declaration to chase.
- */
-function resolveScorerNames(
-  obj: ts.ObjectLiteralExpression,
-  agentName: string,
-  logger: InspectorLogger
-): string[] | null {
-  const property = obj.properties.find(
-    (p) =>
-      ts.isPropertyAssignment(p) &&
-      ts.isIdentifier(p.name) &&
-      p.name.text === 'scorers'
-  )
-  if (!property || !ts.isPropertyAssignment(property)) return null
-  if (!ts.isArrayLiteralExpression(property.initializer)) return null
-
-  const names: string[] = []
-  for (const element of property.initializer.elements) {
-    if (!ts.isStringLiteral(element)) {
-      logger.critical(
-        ErrorCode.INVALID_VALUE,
-        `AI agent '${agentName}' lists a scorer that is not an inline string: \`${element.getText()}\`. A scorer is named, not imported, so the name has to be readable from source.`
-      )
-      continue
-    }
-    names.push(element.text)
-  }
-  return names.length > 0 ? names : null
-}
-
-export const addAgent: AddWiring = (logger, node, checker, state, options) => {
-  if (!ts.isCallExpression(node)) {
-    return
-  }
-
-  const args = node.arguments
-  const firstArg = args[0]
-  const expression = node.expression
-
-  if (!ts.isIdentifier(expression) || expression.text !== 'pikkuAgent') {
-    return
-  }
-
-  if (!firstArg) {
-    return
-  }
-
-  const { exportedName } = extractFunctionName(node, checker, state.rootDir)
-
-  if (ts.isObjectLiteralExpression(firstArg)) {
-    const obj = firstArg
-
-    const nameValue = getPropertyValue(obj, 'name') as string | null
-    const { disabled, tags, summary, description, errors } =
-      getCommonWireMetaData(obj, 'AI agent', nameValue, logger, checker)
-
-    if (disabled) return
-
-    const modelValue = getPropertyValue(obj, 'model') as string | null
-
-    const roleValue = getPropertyValue(obj, 'role') as string | null
-    const personalityValue = getPropertyValue(obj, 'personality') as
-      string | null
-    const goalValue = getPropertyValue(obj, 'goal') as string | null
-
-    const maxStepsValue = getPropertyValue(obj, 'maxSteps') as number | null
-    const temperatureValue = getPropertyValue(obj, 'temperature') as
-      number | null
-    const toolChoiceValue = getPropertyValue(obj, 'toolChoice') as string | null
-    const scorersValue = resolveScorerNames(obj, nameValue || '', logger)
-    const toolsValue = resolveToolReferences(
-      obj,
-      checker,
-      nameValue || '',
-      logger
-    )
-
-    if (toolsValue) {
-      for (const toolName of toolsValue) {
-        if (toolName.startsWith('workflow:') || toolName.includes(':')) continue
-        const funcFile = state.functions.files.get(toolName)
-        if (funcFile && !state.rpc.internalFiles.has(toolName)) {
-          state.rpc.internalFiles.set(toolName, funcFile)
-        }
-      }
-    }
-
-    const agentsValue = resolveAgentReferences(
-      obj,
-      checker,
-      nameValue || '',
-      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,
-        "AI agent is missing the required 'name' property."
-      )
-      return
-    }
-
-    const agentKey = exportedName || nameValue
-
-    if (!description) {
-      logger.critical(
-        ErrorCode.MISSING_DESCRIPTION,
-        `AI agent '${nameValue}' is missing a description.`
-      )
-      return
-    }
-
-    const resolveSchemaRef = (
-      identifier: ts.Identifier,
-      context: string
-    ): SchemaRef | null => {
-      const symbol = checker.getSymbolAtLocation(identifier)
-      if (!symbol) return null
-
-      const decl = symbol.valueDeclaration || symbol.declarations?.[0]
-      if (!decl) return null
-
-      let sourceFile: string
-
-      if (ts.isImportSpecifier(decl)) {
-        const aliasedSymbol = checker.getAliasedSymbol(symbol)
-        if (aliasedSymbol) {
-          const aliasedDecl =
-            aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
-          if (aliasedDecl) {
-            sourceFile = aliasedDecl.getSourceFile().fileName
-          } else {
-            return null
-          }
-        } else {
-          return null
-        }
-      } else {
-        sourceFile = decl.getSourceFile().fileName
-      }
-
-      const vendor = detectSchemaVendorOrError(
-        identifier,
-        checker,
-        logger,
-        context,
-        sourceFile
-      )
-      if (!vendor) return null
-
-      return {
-        variableName: identifier.text,
-        sourceFile,
-        vendor,
-      }
-    }
-
-    let inputSchema: string | null = null
-    let outputSchema: string | null = null
-    let workingMemorySchema: string | null = null
-    const capitalizedName = funcIdToTypeName(agentKey)
-
-    for (const prop of obj.properties) {
-      if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
-        const propName = prop.name.text
-        if (propName === 'input' || propName === 'output') {
-          if (ts.isIdentifier(prop.initializer)) {
-            const context = `AI agent '${nameValue}' ${propName}`
-            const ref = resolveSchemaRef(prop.initializer, context)
-            if (ref) {
-              const schemaName = `${capitalizedName}${propName.charAt(0).toUpperCase() + propName.slice(1)}`
-              state.schemaLookup.set(schemaName, ref)
-              state.functions.typesMap.addCustomType(schemaName, 'unknown', [])
-              if (propName === 'input') {
-                inputSchema = schemaName
-              } else {
-                outputSchema = schemaName
-              }
-            }
-          } else if (ts.isCallExpression(prop.initializer)) {
-            const schemaName = `${capitalizedName}${propName.charAt(0).toUpperCase() + propName.slice(1)}`
-            logger.critical(
-              ErrorCode.INLINE_SCHEMA,
-              `Inline schemas are not supported for '${propName}' in AI agent '${nameValue}'.\n` +
-                `  Extract to an exported variable:\n` +
-                `    export const ${schemaName} = ${prop.initializer.getText()}\n` +
-                `  Then use: ${propName}: ${schemaName}`
-            )
-          }
-        } else if (
-          propName === 'memory' &&
-          ts.isObjectLiteralExpression(prop.initializer)
-        ) {
-          for (const memProp of prop.initializer.properties) {
-            if (
-              ts.isPropertyAssignment(memProp) &&
-              ts.isIdentifier(memProp.name) &&
-              memProp.name.text === 'workingMemory' &&
-              ts.isIdentifier(memProp.initializer)
-            ) {
-              const context = `AI agent '${nameValue}' workingMemory`
-              const ref = resolveSchemaRef(memProp.initializer, context)
-              if (ref) {
-                const schemaName = `${capitalizedName}WorkingMemory`
-                state.schemaLookup.set(schemaName, ref)
-                state.functions.typesMap.addCustomType(
-                  schemaName,
-                  'unknown',
-                  []
-                )
-                workingMemorySchema = schemaName
-              }
-            }
-          }
-        }
-      }
-    }
-
-    const middleware = resolveMiddleware(state, obj, tags, checker)
-    const channelMiddleware = resolveChannelMiddleware(
-      state,
-      obj,
-      tags,
-      checker
-    )
-    const agentMiddleware = resolveAgentMiddleware(state, obj, checker)
-    const permissions = resolvePermissions(state, obj, tags, checker)
-
-    state.serviceAggregation.usedFunctions.add(agentKey)
-    extractWireNames(middleware).forEach((name) =>
-      state.serviceAggregation.usedMiddleware.add(name)
-    )
-    extractWireNames(permissions).forEach((name) =>
-      state.serviceAggregation.usedPermissions.add(name)
-    )
-
-    if (exportedName) {
-      state.agents.files.set(agentKey, {
-        path: node.getSourceFile().fileName,
-        exportedName,
-      })
-    }
-
-    state.agents.agentsMeta[agentKey] = {
-      name: nameValue,
-      description,
-      role: roleValue || undefined,
-      personality: personalityValue || undefined,
-      goal: goalValue || '',
-      model: modelValue || '',
-      summary,
-      errors,
-      sourceFile: node.getSourceFile().fileName,
-      exportedName: exportedName || undefined,
-      ...(maxStepsValue !== null && { maxSteps: maxStepsValue }),
-      ...(temperatureValue !== null && { temperature: temperatureValue }),
-      ...(toolChoiceValue !== null && {
-        toolChoice: toolChoiceValue as 'auto' | 'required' | 'none',
-      }),
-      ...(toolsValue !== null && { tools: toolsValue }),
-      ...(agentsValue !== null && { agents: agentsValue }),
-      ...(workflowsValue !== null && { workflows: workflowsValue }),
-      ...(scorersValue !== null && { scorers: scorersValue }),
-      tags,
-      inputSchema,
-      outputSchema,
-      workingMemorySchema,
-      middleware,
-      channelMiddleware,
-      agentMiddleware,
-      permissions,
-    }
-
-    // AI agent functions require platform services that aren't visible
-    // through parameter destructuring
-    const funcMeta = state.functions.meta[agentKey]
-    if (funcMeta?.services) {
-      for (const svc of [
-        'agentStorage',
-        'agentRunState',
-        'agentRunService',
-        'agentRunner',
-      ]) {
-        if (!funcMeta.services.services.includes(svc)) {
-          funcMeta.services.services.push(svc)
-        }
-      }
-    }
-  }
-}

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

@@ -1,76 +0,0 @@
-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(', ')}`
-  )
-}