@pikku/core 0.12.2 → 0.12.3

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -11,16 +11,17 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import {
-  pikkuState,
-  getSingletonServices,
-  getCreateWireServices,
-} from '../../pikku-state.js'
-import { runPikkuFunc } from '../../function/function-runner.js'
+import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
 import { randomUUID } from 'crypto'
-
+import { streamAIAgent } from './ai-agent-stream.js'
+import { runAIAgent } from './ai-agent-runner.js'
+import {
+  resolveNamespace,
+  ContextAwareRPCService,
+} from '../../wirings/rpc/rpc-runner.js'
+import { buildDynamicWorkflowInstructions, buildWorkflowTools } from './agent-dynamic-workflow.js'
 import {
   resolveMemoryServices,
   loadContextMessages,
@@ -40,7 +41,7 @@ export class ToolApprovalRequired extends PikkuError {
   public readonly toolCallId: string
   public readonly toolName: string
   public readonly args: unknown
-  public readonly reason?: string
+  public reason?: string
   public readonly displayToolName?: string
   public readonly displayArgs?: unknown
   public readonly agentRunId?: string
@@ -68,6 +69,7 @@ export class ToolApprovalRequired extends PikkuError {
 export type StreamContext = {
   channel: AIStreamChannel
   options?: StreamAIAgentOptions
+  delegateState?: { delegated: boolean }
 }
 
 export const resolveAgent = (
@@ -82,7 +84,7 @@ export const resolveAgent = (
   if (colonIndex !== -1) {
     const namespace = agentName.substring(0, colonIndex)
     const localName = agentName.substring(colonIndex + 1)
-    const addons = pikkuState(null, 'rpc', 'addons')
+    const addons = pikkuState(null, 'addons', 'packages')
     const pkgConfig = addons.get(namespace)
     if (pkgConfig) {
       const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(
@@ -101,31 +103,38 @@ export const resolveAgent = (
   throw new Error(`AI agent not found: ${agentName}`)
 }
 
-export function buildInstructions(
+export async function buildInstructions(
   agentName: string,
   packageName: string | null
-): string {
+): Promise<string> {
   const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
-  const instructions = meta?.instructions ?? ''
-  const baseInstructions = Array.isArray(instructions)
-    ? instructions.join('\n')
-    : instructions
-
-  return meta?.agents?.length
-    ? baseInstructions +
-        '\n\nWhen calling a sub-agent, provide a short session name that describes the task. ' +
-        'Use the same session name to continue a previous conversation with that agent. ' +
-        'Use a new session name for a new independent task.'
-    : baseInstructions
+  const rawInstructions = meta?.instructions ?? ''
+  let instructions = Array.isArray(rawInstructions)
+    ? rawInstructions.join('\n')
+    : rawInstructions
+
+  if (meta?.agents?.length) {
+    instructions +=
+      '\n\nWhen calling a sub-agent, provide a short session name that describes the task. ' +
+      'Use the same session name to continue a previous conversation with that agent. ' +
+      'Use a new session name for a new independent task. ' +
+      'When a request involves multiple actions for the same domain, combine them into a single sub-agent call rather than making separate calls.'
+  }
+
+  if (meta?.dynamicWorkflows && meta.tools?.length) {
+    instructions += buildDynamicWorkflowInstructions(meta.tools, meta.dynamicWorkflows)
+  }
+
+  return instructions
 }
 
 export type ScopedChannel = AIStreamChannel & {
-  approval: {
+  approvals: Array<{
     toolCallId: string
     toolName: string
     args: unknown
     runId: string
-  } | null
+  }>
 }
 
 export function createScopedChannel(
@@ -133,7 +142,7 @@ export function createScopedChannel(
   agentName: string,
   session: string
 ): ScopedChannel {
-  let capturedApproval: ScopedChannel['approval'] = null
+  const capturedApprovals: ScopedChannel['approvals'] = []
 
   return {
     channelId: `${parent.channelId}:${agentName}:${session}`,
@@ -141,20 +150,20 @@ export function createScopedChannel(
     get state() {
       return parent.state
     },
-    get approval() {
-      return capturedApproval
+    get approvals() {
+      return capturedApprovals
     },
     close: () => {},
     sendBinary: (data) => parent.sendBinary(data),
     send: (event: AIStreamEvent) => {
       if (event.type === 'done') return
       if (event.type === 'approval-request') {
-        capturedApproval = {
+        capturedApprovals.push({
           toolCallId: event.toolCallId,
           toolName: event.toolName,
           args: event.args,
           runId: (event as any).runId,
-        }
+        })
         return
       }
       if (
@@ -164,7 +173,8 @@ export function createScopedChannel(
         event.type === 'tool-call' ||
         event.type === 'tool-result' ||
         event.type === 'usage' ||
-        event.type === 'error'
+        event.type === 'error' ||
+        event.type === 'workflow-created'
       ) {
         parent.send({ ...event, agent: agentName, session } as AIStreamEvent)
       } else {
@@ -174,15 +184,16 @@ export function createScopedChannel(
   }
 }
 
-export function buildToolDefs(
+export async function buildToolDefs(
   params: RunAIAgentParams,
   agentSessionMap: Map<string, string>,
   resourceId: string,
   agentName: string,
   packageName: string | null,
   streamContext?: StreamContext,
-  aiMiddlewares?: PikkuAIMiddlewareHooks[]
-): { tools: AIAgentToolDef[]; missingRpcs: string[] } {
+  aiMiddlewares?: PikkuAIMiddlewareHooks[],
+  agentMode?: 'delegate' | 'supervise'
+): Promise<{ tools: AIAgentToolDef[]; missingRpcs: string[] }> {
   const singletonServices = getSingletonServices()
   const tools: AIAgentToolDef[] = []
   const missingRpcs: string[] = []
@@ -196,18 +207,38 @@ export function buildToolDefs(
   const metaAgents = meta.agents
 
   if (metaTools?.length) {
-    const functionMeta = pikkuState(null, 'function', 'meta')
-    const schemas = pikkuState(null, 'misc', 'schemas')
-
     for (const toolName of metaTools) {
-      const rpcMeta = pikkuState(null, 'rpc', 'meta')
-      const pikkuFuncId = rpcMeta[toolName]
-      if (!pikkuFuncId) {
+      let fnMeta: any
+      let resolvedPkg: string | null = null
+      let schemas: Map<string, any>
+
+      const resolved = toolName.includes(':')
+        ? resolveNamespace(toolName)
+        : null
+
+      let pikkuFuncId: string | undefined
+
+      if (resolved) {
+        resolvedPkg = resolved.package
+        pikkuFuncId = resolved.function
+        fnMeta = pikkuState(resolvedPkg, 'function', 'meta')[pikkuFuncId]
+        schemas = pikkuState(resolvedPkg, 'misc', 'schemas')
+      } else {
+        const rpcMeta = pikkuState(null, 'rpc', 'meta')
+        pikkuFuncId = rpcMeta[toolName]
+        if (!pikkuFuncId) {
+          missingRpcs.push(toolName)
+          continue
+        }
+        fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
+        schemas = pikkuState(null, 'misc', 'schemas')
+      }
+
+      if (!fnMeta) {
         missingRpcs.push(toolName)
         continue
       }
 
-      const fnMeta = functionMeta[pikkuFuncId]
       const inputSchemaName = fnMeta?.inputSchemaName
       let inputSchema = inputSchemaName
         ? schemas.get(inputSchemaName)
@@ -223,24 +254,52 @@ export function buildToolDefs(
 
       const needsApproval =
         approvalPolicy === 'all' ||
-        (approvalPolicy === 'explicit' && fnMeta?.requiresApproval)
+        (approvalPolicy === 'explicit' && fnMeta?.approvalRequired)
+
+      // Build approvalDescriptionFn if the function has an approvalDescription configured
+      let approvalDescriptionFn:
+        | ((input: unknown) => Promise<string>)
+        | undefined
+      if (needsApproval && pikkuFuncId) {
+        const funcConfig = pikkuState(resolvedPkg, 'function', 'functions').get(
+          pikkuFuncId
+        )
+        if (funcConfig?.approvalDescription) {
+          const descFn = funcConfig.approvalDescription
+          const capturedPkg = resolvedPkg
+          approvalDescriptionFn = async (input: unknown) => {
+            let services = singletonServices
+            if (capturedPkg) {
+              const pkgServices = pikkuState(
+                capturedPkg,
+                'package',
+                'singletonServices'
+              )
+              if (pkgServices) {
+                services = pkgServices
+              }
+            }
+            return descFn(services, input)
+          }
+        }
+      }
 
       tools.push({
-        name: pikkuFuncId,
+        name: toolName.replaceAll(':', '__'),
         description: fnMeta?.description || fnMeta?.title || toolName,
         inputSchema,
         needsApproval: needsApproval || undefined,
+        approvalDescriptionFn,
         execute: async (toolInput: unknown) => {
           const wire: PikkuWire = params.sessionService
             ? { ...createMiddlewareSessionWireProps(params.sessionService) }
             : {}
-          return runPikkuFunc('agent', `tool:${pikkuFuncId}`, pikkuFuncId, {
+          const rpcService = new ContextAwareRPCService(
             singletonServices,
-            createWireServices: getCreateWireServices(),
-            data: () => toolInput,
             wire,
-            sessionService: params.sessionService,
-          })
+            { sessionService: params.sessionService }
+          )
+          return rpcService.rpc(toolName, toolInput)
         },
       })
     }
@@ -280,12 +339,15 @@ export function buildToolDefs(
           const sessionKey = `${subAgentName}::${session}`
           let threadId = agentSessionMap.get(sessionKey)
           if (!threadId) {
-            threadId = `${subAgentName}-${session}-${Date.now()}`
+            threadId = randomUUID()
             agentSessionMap.set(sessionKey, threadId)
           }
 
           if (streamContext) {
-            const { streamAIAgent } = await import('./ai-agent-stream.js')
+            const isDelegate = agentMode !== 'supervise'
+            if (isDelegate && streamContext.delegateState) {
+              streamContext.delegateState.delegated = true
+            }
             const { channel } = streamContext
             channel.send({
               type: 'agent-call',
@@ -298,34 +360,48 @@ export function buildToolDefs(
               subAgentName,
               session
             )
-            await streamAIAgent(
+            // In supervise mode, suppress sub-agent text from reaching the client.
+            // Approvals still flow through normally.
+            const effectiveChannel = isDelegate
+              ? subChannel
+              : {
+                  ...subChannel,
+                  send: (event: AIStreamEvent) => {
+                    if (
+                      event.type === 'text-delta' ||
+                      event.type === 'reasoning-delta'
+                    )
+                      return
+                    subChannel.send(event)
+                  },
+                }
+            const resultText = await streamAIAgent(
               subAgentName,
               { message, threadId, resourceId },
-              subChannel,
+              effectiveChannel,
               params,
               agentSessionMap,
               streamContext.options
             )
-            if (subChannel.approval) {
+            if (subChannel.approvals.length > 0) {
               return {
                 __approvalRequired: true,
                 toolName: subAgentName,
                 args: toolInput,
-                displayToolName: subChannel.approval.toolName,
-                displayArgs: subChannel.approval.args,
-                agentRunId: subChannel.approval.runId,
+                agentRunId: subChannel.approvals[0].runId,
+                subApprovals: subChannel.approvals,
               }
             }
             channel.send({
               type: 'agent-result',
               agentName: subAgentName,
               session,
-              result: null,
+              result: resultText,
             })
-            return null
+            return resultText
           }
 
-          const { runAIAgent } = await import('./ai-agent-runner.js')
+          // No stream context: sub-agent runs non-streaming
           const result = await runAIAgent(
             subAgentName,
             { message, threadId, resourceId },
@@ -338,6 +414,18 @@ export function buildToolDefs(
     }
   }
 
+  if (meta.dynamicWorkflows) {
+    const workflowTools = buildWorkflowTools(
+      agentName,
+      packageName,
+      meta.tools ?? [],
+      meta.dynamicWorkflows,
+      streamContext,
+      params.sessionService
+    )
+    tools.push(...workflowTools)
+  }
+
   const hasToolHooks = aiMiddlewares?.some(
     (mw) => mw.beforeToolCall || mw.afterToolCall
   )
@@ -412,6 +500,19 @@ export async function prepareAgentRun(
     throw new Error('AIAgentRunnerService not available in singletonServices')
   }
 
+  if (agent.dynamicWorkflows && singletonServices.workflowService) {
+    const persisted =
+      await singletonServices.workflowService.getAIGeneratedWorkflows(
+        resolvedName
+      )
+    const allMeta = pikkuState(null, 'workflows', 'meta')
+    for (const wf of persisted) {
+      if (!allMeta[wf.workflowName]) {
+        allMeta[wf.workflowName] = wf.graph
+      }
+    }
+  }
+
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
   const threadId = input.threadId
@@ -478,19 +579,32 @@ export async function prepareAgentRun(
 
   const aiMiddlewares: PikkuAIMiddlewareHooks[] = agent.aiMiddleware ?? []
 
-  const { tools, missingRpcs } = buildToolDefs(
+  const { tools, missingRpcs } = await buildToolDefs(
     params,
     agentSessionMap,
     input.resourceId,
     resolvedName,
     packageName,
     streamContext,
-    aiMiddlewares
+    aiMiddlewares,
+    agent.agentMode
   )
 
-  const instructions = buildInstructions(resolvedName, packageName)
+  const instructions = await buildInstructions(resolvedName, packageName)
 
   const resolved = resolveModelConfig(resolvedName, agent)
+
+  // Per-request overrides
+  if (input.model) {
+    resolved.model = resolveModelConfig(resolvedName, {
+      ...agent,
+      model: input.model,
+    }).model
+  }
+  if (input.temperature !== undefined) {
+    resolved.temperature = input.temperature
+  }
+
   const maxSteps = resolved.maxSteps ?? 10
 
   const runnerParams: AIAgentRunnerParams = {

package/src/wirings/ai-agent/ai-agent-runner.test.ts

@@ -84,7 +84,9 @@ describe('runAIAgent', () => {
       expectedError
     )
 
-    assert.deepEqual(updates, [{ status: 'failed' }])
+    assert.deepEqual(updates, [
+      { status: 'failed', errorMessage: 'runner failed' },
+    ])
   })
 
   test('loops through multiple steps and accumulates usage', async () => {