@pikku/core 0.12.2 → 0.12.3

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

@@ -94,7 +94,12 @@ describe('streamAIAgent', () => {
       {}
     )
 
-    assert.deepEqual(updates, [{ runId: 'run-1', patch: { status: 'failed' } }])
+    assert.deepEqual(updates, [
+      {
+        runId: 'run-1',
+        patch: { status: 'failed', errorMessage: 'stream failed' },
+      },
+    ])
     assert.deepEqual(
       events.map((event) => event.type),
       ['step-start', 'error', 'done']
@@ -198,7 +203,7 @@ describe('streamAIAgent', () => {
     pikkuState(null, 'rpc', 'meta')['tool-x'] = 'tool-x'
     pikkuState(null, 'function', 'meta')['tool-x'] = {
       description: 'test tool',
-      requiresApproval: true,
+      approvalRequired: true,
     }
     pikkuState(null, 'misc', 'schemas').set('ToolXInput', {
       type: 'object',
@@ -260,6 +265,208 @@ describe('streamAIAgent', () => {
     )
   })
 
+  test('suspends run when multiple tool calls need approval (explicit policy)', async () => {
+    addTestAgent('multi-approval-agent')
+
+    const updates: Array<{ runId: string; patch: unknown }> = []
+    const events: AIStreamEvent[] = []
+
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        stream: async (): Promise<AIAgentStepResult> => {
+          // Simulate LLM returning 3 addTodo calls in one step
+          return makeStepResult({
+            toolCalls: [
+              {
+                toolCallId: 'tc-1',
+                toolName: 'todos__addTodo',
+                args: { title: 'todo 1' },
+              },
+              {
+                toolCallId: 'tc-2',
+                toolName: 'todos__addTodo',
+                args: { title: 'todo 2' },
+              },
+              {
+                toolCallId: 'tc-3',
+                toolName: 'todos__addTodo',
+                args: { title: 'todo 3' },
+              },
+            ],
+            // No toolResults since tools have no execute (needsApproval)
+          })
+        },
+      },
+      aiRunState: {
+        createRun: async () => 'run-multi-approval',
+        updateRun: async (runId: string, patch: unknown) => {
+          updates.push({ runId, patch })
+        },
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    const agentName = 'multi-approval-agent'
+    pikkuState(null, 'agent', 'agentsMeta')[agentName].tools = [
+      'todos__addTodo',
+    ]
+    pikkuState(null, 'rpc', 'meta')['todos__addTodo'] = 'addTodo'
+    pikkuState(null, 'function', 'meta')['addTodo'] = {
+      description: 'Add a todo',
+      approvalRequired: true,
+      inputSchemaName: 'AddTodoInput',
+    }
+    pikkuState(null, 'misc', 'schemas').set('AddTodoInput', {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+    })
+
+    await streamAIAgent(
+      agentName,
+      {
+        message: 'create 3 todos',
+        threadId: 'thread-multi-approval',
+        resourceId: 'resource-multi-approval',
+      },
+      {
+        channelId: 'channel-multi-approval',
+        openingData: undefined,
+        state: 'open',
+        send: (event: AIStreamEvent) => {
+          events.push(event)
+        },
+        close: () => {},
+      },
+      {}
+      // No options → defaults to requiresToolApproval: 'explicit'
+    )
+
+    // Should suspend on first tool call
+    const approvalEvent = events.find(
+      (e) => e.type === 'approval-request'
+    ) as any
+    assert.ok(approvalEvent, 'Should have an approval-request event')
+    assert.equal(approvalEvent.toolCallId, 'tc-1')
+    assert.equal(approvalEvent.toolName, 'todos__addTodo')
+
+    // Run should be suspended
+    assert.ok(
+      updates.some((u) => (u.patch as any).status === 'suspended'),
+      'Run should be suspended for approval'
+    )
+
+    assert.ok(events.some((e) => e.type === 'done'))
+  })
+
+  test('suspends run for addon tools using namespaced resolution (explicit policy)', async () => {
+    addTestAgent('addon-approval-agent')
+
+    const updates: Array<{ runId: string; patch: unknown }> = []
+    const events: AIStreamEvent[] = []
+
+    const mockServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        stream: async (params: any): Promise<AIAgentStepResult> => {
+          // Verify the tool was built with needsApproval
+          const addTodoTool = params.tools.find(
+            (t: any) => t.name === 'todos__addTodo'
+          )
+          assert.ok(addTodoTool, 'Tool todos__addTodo should exist')
+          assert.equal(
+            addTodoTool.needsApproval,
+            true,
+            'Tool should have needsApproval=true'
+          )
+
+          // Simulate LLM calling the tool
+          return makeStepResult({
+            toolCalls: [
+              {
+                toolCallId: 'tc-1',
+                toolName: 'todos__addTodo',
+                args: { title: 'new todo' },
+              },
+            ],
+          })
+        },
+      },
+      aiRunState: {
+        createRun: async () => 'run-addon-approval',
+        updateRun: async (runId: string, patch: unknown) => {
+          updates.push({ runId, patch })
+        },
+      },
+    } as any
+
+    pikkuState(null, 'package', 'singletonServices', mockServices)
+
+    // Register addon package
+    pikkuState(null, 'addons', 'packages').set('todos', {
+      package: '@test/addon-todos',
+    })
+
+    // Set up addon package's function metadata
+    pikkuState('@test/addon-todos', 'function', 'meta')['addTodo'] = {
+      description: 'Add a todo',
+      approvalRequired: true,
+      inputSchemaName: 'AddTodoInput',
+    }
+    pikkuState('@test/addon-todos', 'misc', 'schemas').set('AddTodoInput', {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+    })
+
+    // Set up agent with namespaced tool
+    const agentName = 'addon-approval-agent'
+    pikkuState(null, 'agent', 'agentsMeta')[agentName].tools = ['todos:addTodo']
+
+    await streamAIAgent(
+      agentName,
+      {
+        message: 'add a todo',
+        threadId: 'thread-addon-approval',
+        resourceId: 'resource-addon-approval',
+      },
+      {
+        channelId: 'channel-addon-approval',
+        openingData: undefined,
+        state: 'open',
+        send: (event: AIStreamEvent) => {
+          events.push(event)
+        },
+        close: () => {},
+      },
+      {}
+    )
+
+    // Should suspend on the tool call
+    const approvalEvent = events.find(
+      (e) => e.type === 'approval-request'
+    ) as any
+    assert.ok(approvalEvent, 'Should have an approval-request event')
+    assert.equal(approvalEvent.toolCallId, 'tc-1')
+    assert.equal(approvalEvent.toolName, 'todos__addTodo')
+
+    // Run should be suspended
+    assert.ok(
+      updates.some((u) => (u.patch as any).status === 'suspended'),
+      'Run should be suspended for approval'
+    )
+  })
+
   test('suspends with agent-call type when sub-agent returns approval sentinel', async () => {
     addTestAgent('parent-agent')
 

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

@@ -39,10 +39,6 @@ import {
   type StreamAIAgentOptions,
   type StreamContext,
 } from './ai-agent-prepare.js'
-import {
-  createAssistantUIChannel,
-  parseAssistantUIInput,
-} from './ai-agent-assistant-ui.js'
 import { resolveModelConfig } from './ai-agent-model-config.js'
 import type { AIRunStateService } from '../../services/ai-run-state-service.js'
 import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
@@ -238,7 +234,7 @@ type StepLoopParams = {
 
 type StepLoopResult =
   | { outcome: 'done' }
-  | { outcome: 'approval'; approval: ToolApprovalRequired }
+  | { outcome: 'approval'; approvals: ToolApprovalRequired[] }
 
 async function runStreamStepLoop(
   params: StepLoopParams
@@ -291,13 +287,26 @@ async function runStreamStepLoop(
 
     if (stepResult.toolCalls.length === 0) break
 
-    const approvalNeeded = checkForApproval(
+    const approvalsNeeded = checkForApprovals(
       stepResult,
       runnerParams.tools,
       runId
     )
-    if (approvalNeeded) {
-      return { outcome: 'approval', approval: approvalNeeded }
+    if (approvalsNeeded.length > 0) {
+      // For each approval, call approvalDescriptionFn if available
+      for (const approval of approvalsNeeded) {
+        const toolDef = runnerParams.tools.find(
+          (t) => t.name === approval.toolName
+        )
+        if (toolDef?.approvalDescriptionFn && !approval.reason) {
+          try {
+            approval.reason = await toolDef.approvalDescriptionFn(approval.args)
+          } catch {
+            // If description generation fails, continue without it
+          }
+        }
+      }
+      return { outcome: 'approval', approvals: approvalsNeeded }
     }
 
     appendStepMessages(runnerParams, stepResult)
@@ -306,16 +315,20 @@ async function runStreamStepLoop(
   return { outcome: 'done' }
 }
 
-function checkForApproval(
+export function checkForApprovals(
   stepResult: AIAgentStepResult,
   tools: AIAgentRunnerParams['tools'],
   runId: string
-): ToolApprovalRequired | null {
+): ToolApprovalRequired[] {
+  const approvals: ToolApprovalRequired[] = []
   for (const tc of stepResult.toolCalls) {
     const toolDef = tools.find((t) => t.name === tc.toolName)
 
     if (toolDef?.needsApproval) {
-      return new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args)
+      approvals.push(
+        new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args)
+      )
+      continue
     }
 
     const tr = stepResult.toolResults.find(
@@ -333,22 +346,46 @@ function checkForApproval(
         displayToolName?: string
         displayArgs?: unknown
         agentRunId?: string
+        subApprovals?: Array<{
+          toolCallId: string
+          toolName: string
+          args: unknown
+          runId: string
+        }>
+      }
+      if (r.subApprovals?.length) {
+        for (const sub of r.subApprovals) {
+          approvals.push(
+            new ToolApprovalRequired(
+              sub.toolCallId,
+              r.toolName,
+              r.args,
+              undefined,
+              sub.toolName,
+              sub.args,
+              r.agentRunId
+            )
+          )
+        }
+      } else {
+        approvals.push(
+          new ToolApprovalRequired(
+            tc.toolCallId,
+            r.toolName,
+            r.args,
+            r.reason,
+            r.displayToolName,
+            r.displayArgs,
+            r.agentRunId
+          )
+        )
       }
-      return new ToolApprovalRequired(
-        tc.toolCallId,
-        r.toolName,
-        r.args,
-        r.reason,
-        r.displayToolName,
-        r.displayArgs,
-        r.agentRunId
-      )
     }
   }
-  return null
+  return approvals
 }
 
-function appendStepMessages(
+export function appendStepMessages(
   runnerParams: AIAgentRunnerParams,
   stepResult: AIAgentStepResult
 ): void {
@@ -384,8 +421,8 @@ function appendStepMessages(
   }
 }
 
-function handleApproval(
-  err: ToolApprovalRequired,
+function handleApprovals(
+  approvals: ToolApprovalRequired[],
   runId: string,
   channel: AIStreamChannel,
   aiRunState: AIRunStateService,
@@ -394,37 +431,41 @@ function handleApproval(
   return (async () => {
     await persistingChannel.flush()
 
-    const pendingApproval = err.agentRunId
-      ? {
-          type: 'agent-call' as const,
-          toolCallId: err.toolCallId,
-          agentName: err.toolName,
-          agentRunId: err.agentRunId,
-          displayToolName: err.displayToolName ?? err.toolName,
-          displayArgs: err.displayArgs ?? err.args,
-        }
-      : {
-          type: 'tool-call' as const,
-          toolCallId: err.toolCallId,
-          toolName: err.toolName,
-          args: err.args,
-        }
+    const pendingApprovals = approvals.map((err) =>
+      err.agentRunId
+        ? {
+            type: 'agent-call' as const,
+            toolCallId: err.toolCallId,
+            agentName: err.toolName,
+            agentRunId: err.agentRunId,
+            displayToolName: err.displayToolName ?? err.toolName,
+            displayArgs: err.displayArgs ?? err.args,
+          }
+        : {
+            type: 'tool-call' as const,
+            toolCallId: err.toolCallId,
+            toolName: err.toolName,
+            args: err.args,
+          }
+    )
 
     await aiRunState.updateRun(runId, {
       status: 'suspended',
       suspendReason: 'approval',
-      pendingApprovals: [pendingApproval],
+      pendingApprovals,
     })
 
-    const approvalEvent = {
-      type: 'approval-request' as const,
-      toolCallId: err.toolCallId,
-      toolName: err.displayToolName ?? err.toolName,
-      args: err.displayArgs ?? err.args,
-      reason: err.reason,
-      runId,
+    for (const err of approvals) {
+      const approvalEvent = {
+        type: 'approval-request' as const,
+        toolCallId: err.toolCallId,
+        toolName: err.displayToolName ?? err.toolName,
+        args: err.displayArgs ?? err.args,
+        reason: err.reason,
+        runId,
+      }
+      channel.send(approvalEvent as any)
     }
-    channel.send(approvalEvent as any)
     channel.send({ type: 'done' })
     channel.close()
   })()
@@ -432,34 +473,24 @@ function handleApproval(
 
 export async function streamAIAgent(
   agentName: string,
-  input:
-    | { message: string; threadId: string; resourceId: string }
-    | Record<string, unknown>,
+  input: {
+    message: string
+    threadId: string
+    resourceId: string
+    model?: string
+    temperature?: number
+  },
   channel: AIStreamChannel,
   params: RunAIAgentParams,
   agentSessionMap?: Map<string, string>,
   options?: StreamAIAgentOptions
-): Promise<void> {
+): Promise<string> {
   const sessionMap = agentSessionMap ?? new Map<string, string>()
 
-  const { agent: resolvedAgentForProtocol } = resolveAgent(agentName)
-  const inputRecord = input as Record<string, unknown>
-  const useUIMessageStream =
-    resolvedAgentForProtocol.protocol === 'ui-message-stream' ||
-    Array.isArray(inputRecord.messages)
-  let normalizedInput: { message: string; threadId: string; resourceId: string }
-  if (useUIMessageStream) {
-    normalizedInput = parseAssistantUIInput(inputRecord)
-    channel = createAssistantUIChannel(channel)
-  } else {
-    normalizedInput = input as {
-      message: string
-      threadId: string
-      resourceId: string
-    }
-  }
+  const normalizedInput = input
 
   const streamContext: StreamContext = { channel, options }
+  // delegateState is attached after prepareAgentRun resolves the agent config
 
   const {
     agent,
@@ -502,7 +533,7 @@ export async function streamAIAgent(
     })
     channel.send({ type: 'suspended', reason: 'rpc-missing', missingRpcs })
     channel.send({ type: 'done' })
-    return
+    return ''
   }
 
   const aiMiddlewares: PikkuAIMiddlewareHooks[] = agent.aiMiddleware ?? []
@@ -580,8 +611,32 @@ export async function streamAIAgent(
         ).channel as AIStreamChannel)
       : channel
 
+  // In delegate mode (default), suppress parent's text from reaching the client
+  // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
+  // its text goes through normally. Sub-agent text bypasses this path entirely
+  // (goes through subChannel → channel directly).
+  const isDelegateMode = agent.agentMode !== 'supervise' && meta.agents?.length
+  const delegateState = { delegated: false }
+  if (isDelegateMode) {
+    streamContext.delegateState = delegateState
+  }
+  const outputChannel = isDelegateMode
+    ? {
+        ...wrappedChannel,
+        send: (event: AIStreamEvent) => {
+          if (
+            delegateState.delegated &&
+            (event.type === 'text-delta' || event.type === 'reasoning-delta')
+          )
+            return
+          wrappedChannel.send(event)
+        },
+        delegateState,
+      }
+    : wrappedChannel
+
   const persistingChannel = createPersistingChannel(
-    wrappedChannel,
+    outputChannel,
     storage,
     threadId
   )
@@ -599,14 +654,14 @@ export async function streamAIAgent(
     })
 
     if (loopResult.outcome === 'approval') {
-      await handleApproval(
-        loopResult.approval,
+      await handleApprovals(
+        loopResult.approvals,
         runId,
         channel,
         aiRunState,
         persistingChannel
       )
-      return
+      return persistingChannel.fullText
     }
 
     await postStreamCleanup(
@@ -624,6 +679,7 @@ export async function streamAIAgent(
 
     channel.send({ type: 'done' })
     channel.close()
+    return persistingChannel.fullText
   } catch (err) {
     for (const mw of aiMiddlewares) {
       if (mw.onError) {
@@ -638,13 +694,17 @@ export async function streamAIAgent(
         }
       }
     }
-    await aiRunState.updateRun(runId, { status: 'failed' })
+    await aiRunState.updateRun(runId, {
+      status: 'failed',
+      errorMessage: err instanceof Error ? err.message : String(err),
+    })
     channel.send({
       type: 'error',
       message: err instanceof Error ? err.message : String(err),
     })
     channel.send({ type: 'done' })
     channel.close()
+    return persistingChannel.fullText
   }
 }
 
@@ -696,7 +756,8 @@ export async function resumeAIAgent(
       await aiRunState.updateRun(pending.agentRunId, { status: 'failed' })
     }
 
-    const denialResult = 'Tool call was not approved by the user'
+    const denialResult =
+      'The user explicitly declined this action. Inform them that it was declined and do not retry.'
 
     if (storage) {
       await storage.saveMessages(run.threadId, [
@@ -718,6 +779,17 @@ export async function resumeAIAgent(
       ])
     }
 
+    // Check remaining pending approvals
+    const updatedRun = await aiRunState.getRun(run.runId)
+    const remaining = updatedRun?.pendingApprovals ?? []
+
+    if (remaining.length > 0) {
+      // Still waiting for more approvals - don't continue step loop
+      channel.send({ type: 'done' })
+      channel.close()
+      return
+    }
+
     await aiRunState.updateRun(run.runId, { status: 'running' })
 
     await continueAfterToolResult(
@@ -741,7 +813,9 @@ export async function resumeAIAgent(
     if (!subRun) {
       throw new Error(`Sub-agent run not found: ${pending.agentRunId}`)
     }
-    const subPending = subRun.pendingApprovals?.[0]
+    const subPending =
+      subRun.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId) ??
+      subRun.pendingApprovals?.[0]
     if (!subPending) {
       throw new Error(
         `No pending approval on sub-agent run ${pending.agentRunId}`
@@ -797,7 +871,7 @@ export async function resumeAIAgent(
     }
     const aiMiddlewaresForResume: PikkuAIMiddlewareHooks[] =
       agent.aiMiddleware ?? []
-    const { tools } = buildToolDefs(
+    const { tools } = await buildToolDefs(
       params,
       new Map<string, string>(),
       run.resourceId,
@@ -818,10 +892,12 @@ export async function resumeAIAgent(
       typeof pending.args === 'string' ? JSON.parse(pending.args) : pending.args
 
     let toolResult: unknown
+    let isError = false
     try {
       toolResult = await matchingTool.execute(toolArgs)
     } catch (execErr) {
       toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`
+      isError = true
     }
 
     const resultStr =
@@ -848,9 +924,21 @@ export async function resumeAIAgent(
       toolCallId: input.toolCallId,
       toolName: pending.toolName,
       result: toolResult,
+      ...(isError ? { isError: true } : {}),
     })
   }
 
+  // Check remaining pending approvals after processing this one
+  const updatedRun = await aiRunState.getRun(run.runId)
+  const remaining = updatedRun?.pendingApprovals ?? []
+
+  if (remaining.length > 0) {
+    // Still waiting for more approvals - don't continue step loop
+    channel.send({ type: 'done' })
+    channel.close()
+    return
+  }
+
   await aiRunState.updateRun(run.runId, { status: 'running' })
 
   await continueAfterToolResult(
@@ -906,7 +994,7 @@ async function continueAfterToolResult(
   const allMessages = [...contextMessages, ...messages]
   const trimmedMessages = trimMessages(allMessages)
 
-  const instructions = buildInstructions(resolvedName, packageName)
+  const instructions = await buildInstructions(resolvedName, packageName)
 
   const aiMiddlewares: PikkuAIMiddlewareHooks[] = agent.aiMiddleware ?? []
   let modifiedMessages = trimmedMessages
@@ -971,14 +1059,16 @@ async function continueAfterToolResult(
   )
 
   const streamContext: StreamContext = { channel, options }
-  const resumeTools = buildToolDefs(
-    params,
-    new Map<string, string>(),
-    run.resourceId,
-    resolvedName,
-    packageName,
-    streamContext,
-    aiMiddlewares
+  const resumeTools = (
+    await buildToolDefs(
+      params,
+      new Map<string, string>(),
+      run.resourceId,
+      resolvedName,
+      packageName,
+      streamContext,
+      aiMiddlewares
+    )
   ).tools
 
   const resolved = resolveModelConfig(resolvedName, agent)
@@ -1010,8 +1100,8 @@ async function continueAfterToolResult(
     })
 
     if (loopResult.outcome === 'approval') {
-      await handleApproval(
-        loopResult.approval,
+      await handleApprovals(
+        loopResult.approvals,
         run.runId,
         channel,
         aiRunState,
@@ -1049,7 +1139,10 @@ async function continueAfterToolResult(
         }
       }
     }
-    await aiRunState.updateRun(run.runId, { status: 'failed' })
+    await aiRunState.updateRun(run.runId, {
+      status: 'failed',
+      errorMessage: err instanceof Error ? err.message : String(err),
+    })
     channel.send({
       type: 'error',
       message: err instanceof Error ? err.message : String(err),