@pikku/core 0.12.79 → 0.12.82

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

@@ -1,6 +1,7 @@
 import type {
   AIStreamChannel,
   AIStreamEvent,
+  AIAgentStep,
   AIMessage,
   AIToolCall,
   AIToolResult,
@@ -9,7 +10,12 @@ import type {
   CoreAIAgent,
   AIAgentMemoryConfig,
 } from './ai-agent.types.js'
+import {
+  finalizeAgentRun,
+  lastUserMessageText,
+} from './ai-agent-finalize.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
+import { applyInputMiddleware } from './ai-agent-turn.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { randomUUID } from './ai-agent-utils.js'
 import { SPOKEN_TRANSCRIPT } from './voice-input.js'
@@ -67,6 +73,8 @@ type PersistingChannel = AIStreamChannel & {
   fullText: string
   flush: (opts?: { interrupted?: boolean }) => Promise<void>
   totalUsage: { inputTokens: number; outputTokens: number; model?: string }
+  /** Every tool the run called, kept for the whole run rather than per step. */
+  runToolCalls: NonNullable<AIAgentStep['toolCalls']>
 }
 
 function createPersistingChannel(
@@ -88,6 +96,9 @@ function createPersistingChannel(
     inputTokens: 0,
     outputTokens: 0,
   }
+  // Survives the per-step flush below, which clears its own buffers: the run
+  // record needs every call the run made, not just the last step's.
+  const runToolCalls: NonNullable<AIAgentStep['toolCalls']> = []
 
   const flushStep = async (opts?: { interrupted?: boolean }) => {
     if (!storage) return
@@ -136,6 +147,8 @@ function createPersistingChannel(
     })
   }
 
+  const runToolCallIndex = new Map<string, number>()
+
   const channel: PersistingChannel = {
     channelId: parent.channelId,
     openingData: parent.openingData,
@@ -148,6 +161,9 @@ function createPersistingChannel(
     get totalUsage() {
       return totalUsage
     },
+    get runToolCalls() {
+      return runToolCalls
+    },
     flush: flushStep,
     close: () => parent.close(),
     sendBinary: (data) => parent.sendBinary(data),
@@ -156,6 +172,26 @@ function createPersistingChannel(
       // the client was streamed, and an interrupted run has to be able to
       // report the fragment it got through even with persistence turned off.
       if (event.type === 'text-delta') fullText += event.text
+      if (event.type === 'tool-call') {
+        runToolCallIndex.set(event.toolCallId, runToolCalls.length)
+        runToolCalls.push({
+          name: event.toolName,
+          args: event.args as Record<string, unknown>,
+          result: '',
+        })
+      }
+      if (event.type === 'tool-result') {
+        const index = runToolCallIndex.get(event.toolCallId)
+        const result =
+          typeof event.result === 'string'
+            ? event.result
+            : JSON.stringify(event.result)
+        const call = index === undefined ? undefined : runToolCalls[index]
+        if (call) {
+          call.result = result
+          if (event.error) call.error = event.error
+        }
+      }
       if (storage) {
         switch (event.type) {
           case 'text-delta':
@@ -176,6 +212,7 @@ function createPersistingChannel(
                 typeof event.result === 'string'
                   ? event.result
                   : JSON.stringify(event.result),
+              ...(event.error ? { error: event.error } : {}),
             })
             break
           case 'generative-ui':
@@ -202,44 +239,67 @@ function createPersistingChannel(
   return channel
 }
 
+/**
+ * Agents already warned about, so a per-request hook does not become a
+ * per-request log line.
+ */
+const warnedUnstreamedOutputHooks = new Set<string>()
+
+/**
+ * `modifyOutput` does not run on a streamed run at all. Nothing here could act
+ * on what it returns — the text has already reached the client, and
+ * `createPersistingChannel` flushes each step to storage as it goes, so by the
+ * time the run ends the transcript is already written.
+ *
+ * Rewriting on this path belongs to `modifyOutputStream`, which genuinely
+ * works: the stream middleware wraps the persisting channel, so what is stored
+ * and accumulated is already what the client was sent. A middleware that
+ * rewrites in `modifyOutput` only — a redaction hook, typically — is therefore
+ * silently ineffective when the agent is streamed, and is told so once.
+ */
+const warnUnstreamedOutputHooks = (
+  agentName: string,
+  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  logger?: { warn: (...args: any[]) => void }
+) => {
+  if (warnedUnstreamedOutputHooks.has(agentName)) return
+  const unstreamed = aiMiddlewares.some(
+    (mw) => mw.modifyOutput && !mw.modifyOutputStream
+  )
+  if (!unstreamed) return
+  warnedUnstreamedOutputHooks.add(agentName)
+  logger?.warn(
+    `Agent '${agentName}' has AI middleware with modifyOutput but no modifyOutputStream — modifyOutput does not apply to streamed runs. Implement modifyOutputStream to affect a streamed reply.`
+  )
+}
+
 async function postStreamCleanup(
   persistingChannel: PersistingChannel,
-  aiMiddlewares: PikkuAIMiddlewareHooks[],
-  singletonServices: any,
-  messages: AIMessage[],
   aiRunState: AIRunStateService,
-  runId: string
-): Promise<void> {
-  const usage = persistingChannel.totalUsage
-  let outputText = persistingChannel.fullText
-  let outputMessages = messages
-  for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-    const mw = aiMiddlewares[i]
-    if (mw.modifyOutput) {
-      const result = await mw.modifyOutput(singletonServices, {
-        text: outputText,
-        messages: outputMessages,
-        usage: {
-          inputTokens: usage.inputTokens,
-          outputTokens: usage.outputTokens,
-        },
-      })
-      outputText = result.text
-      outputMessages = result.messages
-    }
+  runId: string,
+  run: {
+    agentName: string
+    threadId: string
+    resourceId?: string
+    input: string
   }
-
-  await aiRunState.updateRun(runId, {
-    status: 'completed',
-    ...(usage.model
-      ? {
-          usage: {
-            inputTokens: usage.inputTokens,
-            outputTokens: usage.outputTokens,
-            model: usage.model,
-          },
-        }
-      : {}),
+): Promise<void> {
+  await finalizeAgentRun(aiRunState, {
+    runId,
+    agentName: run.agentName,
+    threadId: run.threadId,
+    resourceId: run.resourceId,
+    input: run.input,
+    // Already what the client received: the stream middleware wraps the
+    // persisting channel, so both were accumulated post-rewrite.
+    text: persistingChannel.fullText,
+    steps: [
+      {
+        usage: persistingChannel.totalUsage,
+        toolCalls: persistingChannel.runToolCalls,
+      },
+    ],
+    usage: persistingChannel.totalUsage,
   })
 }
 
@@ -676,38 +736,26 @@ export async function streamAIAgent(
   // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
   const sharedNotes: Record<string, unknown> = {}
 
-  let modifiedMessages = runnerParams.messages
-  let modifiedInstructions = runnerParams.instructions
-  for (const mw of aiMiddlewares) {
-    if (mw.modifyInput) {
-      const result = await mw.modifyInput(singletonServices, {
-        messages: modifiedMessages,
-        instructions: modifiedInstructions,
-        shared: sharedNotes,
-      })
-      modifiedMessages = result.messages
-      modifiedInstructions = result.instructions
-    }
-  }
+  const { messages: modifiedMessages, instructions: modifiedInstructions } =
+    await applyInputMiddleware(
+      aiMiddlewares,
+      singletonServices,
+      {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+      },
+      sharedNotes
+    )
   runnerParams.messages = modifiedMessages
   runnerParams.instructions = modifiedInstructions
 
-  // Sent on the raw channel, ahead of the run. A voice client sent audio and so
-  // has no idea what it said; until this arrives its own message is a blank
-  // bubble. Ahead of the run rather than alongside it because the answer starts
-  // streaming within a few hundred milliseconds, and a question that appears
-  // after its answer reads as the wrong question.
+  // knowledge: decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md
   const transcript = sharedNotes[SPOKEN_TRANSCRIPT]
   if (typeof transcript === 'string') {
     channel.send({ type: 'transcript', text: transcript })
   }
 
-  // What goes into thread history is what the model was actually asked. For a
-  // spoken turn that is not what arrived over the wire: the wire carried a
-  // base64 audio blob, and persisting it would write megabytes of unreadable
-  // data into the history while losing the only readable record of the turn.
-  // Identity-checked rather than assumed — a middleware is free to rewrite the
-  // message list into something with no relation to the turn.
+  // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
   const lastModified = modifiedMessages[modifiedMessages.length - 1]
   const persistedUserMessage =
     lastModified?.id === userMessage.id ? lastModified : userMessage
@@ -734,6 +782,8 @@ export async function streamAIAgent(
     await storage.saveMessages(threadId, [persistedUserMessage])
   }
 
+  warnUnstreamedOutputHooks(agentName, aiMiddlewares, singletonServices.logger)
+
   const streamMiddleware = aiMiddlewares
     .filter((mw) => mw.modifyOutputStream)
     .map((mw) => {
@@ -768,7 +818,7 @@ export async function streamAIAgent(
     {
       wireInheritedChannelMiddleware: meta?.channelMiddleware,
       wireChannelMiddleware: [
-        ...((agent.channelMiddleware as any[]) ?? []),
+        ...(agent.channelMiddleware ?? []),
         ...streamMiddleware,
       ],
     }
@@ -792,10 +842,7 @@ export async function streamAIAgent(
 
   const credentialFilteredChannel: AIStreamChannel = {
     ...wrappedChannel,
-    // Returns what the inner send returns. Middleware runs asynchronously, so
-    // swallowing the promise here makes every `await channel.send(...)` upstream
-    // a no-op — including the one that waits for a buffering hook to flush
-    // before the channel closes.
+    // knowledge: decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md
     send: (event: AIStreamEvent) => {
       if (
         event.type === 'tool-result' &&
@@ -863,20 +910,14 @@ export async function streamAIAgent(
       return persistingChannel.fullText
     }
 
-    await postStreamCleanup(
-      persistingChannel,
-      aiMiddlewares,
-      singletonServices,
-      runnerParams.messages,
-      aiRunState,
-      runId
-    )
+    await postStreamCleanup(persistingChannel, aiRunState, runId, {
+      agentName,
+      threadId,
+      resourceId: input.resourceId,
+      input: lastUserMessageText(runnerParams.messages),
+    })
 
-    // Through the middleware rather than straight at the channel, and awaited.
-    // `done` is the only signal a stream hook gets that the reply is over, and
-    // the ones that buffer need it: `voiceOutput` speaks a trailing fragment
-    // that never reached a full stop, and waits for audio it has already paid
-    // to synthesize. Sent raw, that work is discarded by the `close()` below.
+    // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
     await outputChannel.send({ type: 'done' })
     channel.close()
     return persistingChannel.fullText
@@ -979,12 +1020,7 @@ export async function interruptAIAgent(
     reason: input.reason ?? 'user',
   })
 
-  // A run still marked `running` that this process cannot abort is executing on
-  // another instance. Returning a bare `false` there is indistinguishable from
-  // "it already finished", so the one deployment shape this registry does not
-  // cover fails silently — an agent that simply refuses to shut up, with nothing
-  // in the logs. Say so instead. See `signalRunInterrupt` for the fix (fan the
-  // interrupt out over eventHub so every instance tries locally).
+  // knowledge: decisions/internals/an-agent-run-owned-by-another-instance-says-so.md
   if (!stopped && run.status === 'running') {
     logger?.warn(
       `Could not interrupt run ${input.runId}: it is running in another process. ` +
@@ -1037,10 +1073,18 @@ export async function resumeAIAgent(
 
   await assertAgentAuthorized(agent, params, packageName)
 
-  await aiRunState.resolveApproval(
+  // The read above is not a claim — concurrent resumes all see the same pending
+  // approval. `resolveApproval` is the claim, and the loser must not go on to
+  // run the tool a second time.
+  const claimed = await aiRunState.resolveApproval(
     input.toolCallId,
     input.approved ? 'approved' : 'denied'
   )
+  if (!claimed) {
+    throw new Error(
+      `Approval for toolCallId ${input.toolCallId} was already resolved by another caller`
+    )
+  }
 
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
@@ -1199,16 +1243,17 @@ export async function resumeAIAgent(
       typeof pending.args === 'string' ? JSON.parse(pending.args) : pending.args
 
     let toolResult: unknown
-    let isError = false
+    let toolError: string | undefined
     try {
       toolResult = await matchingTool.execute(toolArgs)
     } catch (execErr: any) {
       if (execErr?.payload?.error === 'missing_credential') {
         toolResult = execErr.payload
+        toolError = 'missing_credential'
       } else {
-        toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`
+        toolError = execErr instanceof Error ? execErr.message : String(execErr)
+        toolResult = `Error: ${toolError}`
       }
-      isError = true
     }
 
     const resultStr =
@@ -1235,7 +1280,7 @@ export async function resumeAIAgent(
       toolCallId: input.toolCallId,
       toolName: pending.toolName,
       result: toolResult,
-      ...(isError ? { isError: true } : {}),
+      ...(toolError ? { error: toolError } : {}),
     })
   }
 
@@ -1317,26 +1362,23 @@ async function continueAfterToolResult(
   // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
   const sharedNotes: Record<string, unknown> = {}
 
-  let modifiedMessages = trimmedMessages
-  let modifiedInstructions = instructions
-  for (const mw of aiMiddlewares) {
-    if (mw.modifyInput) {
-      const result = await mw.modifyInput(singletonServices, {
-        messages: modifiedMessages,
-        instructions: modifiedInstructions,
-        shared: sharedNotes,
-      })
-      modifiedMessages = result.messages
-      modifiedInstructions = result.instructions
-    }
-  }
+  const { messages: modifiedMessages, instructions: modifiedInstructions } =
+    await applyInputMiddleware(
+      aiMiddlewares,
+      singletonServices,
+      { messages: trimmedMessages, instructions: instructions },
+      sharedNotes
+    )
 
-  // Resuming is as interruptible as the first turn. It is the same person
-  // listening to the same voice, and after an approval it is where most of the
-  // reply actually gets spoken — an approved delete is followed by the agent
-  // talking about it, and that is a normal thing to talk over.
+  // knowledge: decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md
   const interruptHandle = registerInterruptibleRun(run.runId)
 
+  warnUnstreamedOutputHooks(
+    run.agentName,
+    aiMiddlewares,
+    singletonServices.logger
+  )
+
   const streamMiddleware = aiMiddlewares
     .filter((mw) => mw.modifyOutputStream)
     .map((mw) => {
@@ -1369,7 +1411,7 @@ async function continueAfterToolResult(
     {
       wireInheritedChannelMiddleware: meta?.channelMiddleware,
       wireChannelMiddleware: [
-        ...((agent.channelMiddleware as any[]) ?? []),
+        ...(agent.channelMiddleware ?? []),
         ...streamMiddleware,
       ],
     }
@@ -1458,19 +1500,12 @@ async function continueAfterToolResult(
       return
     }
 
-    await postStreamCleanup(
-      persistingChannel,
-      aiMiddlewares,
-      singletonServices,
-      runnerParams.messages,
-      aiRunState,
-      run.runId
-    )
+    await postStreamCleanup(persistingChannel, aiRunState, run.runId, {
+      ...run,
+      input: lastUserMessageText(runnerParams.messages),
+    })
 
-    // Through the middleware, for the same reason as the first turn — and it
-    // matters more here. After an approval, most of what gets spoken is the
-    // agent talking about what it just did, so this is the half of the reply a
-    // dropped flush would silence.
+    // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
     await wrappedChannel.send({ type: 'done' })
     channel.close()
   } catch (err) {

package/src/wirings/ai-agent/ai-agent-thread-ownership.test.ts

@@ -114,7 +114,7 @@ const createHarness = (
         ],
         messages: [],
       }),
-      resolveApproval: async () => {},
+      resolveApproval: async () => true,
     },
   } as any)
 

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

@@ -0,0 +1,67 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { toAccumulatedStep } from './ai-agent-turn.js'
+import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+
+const stepResult = (
+  overrides?: Partial<AIAgentStepResult>
+): AIAgentStepResult => ({
+  text: '',
+  toolCalls: [],
+  toolResults: [],
+  usage: { inputTokens: 0, outputTokens: 0 },
+  finishReason: 'stop',
+  ...overrides,
+})
+
+describe('toAccumulatedStep', () => {
+  test('carries a tool failure as its own field, not only as rendered text', () => {
+    const step = toAccumulatedStep(
+      stepResult({
+        toolCalls: [
+          { toolCallId: 'call-1', toolName: 'lookupOrder', args: { id: 7 } },
+        ],
+        toolResults: [
+          {
+            toolCallId: 'call-1',
+            toolName: 'lookupOrder',
+            result: 'Error: order service unreachable',
+            error: 'order service unreachable',
+          },
+        ],
+      })
+    )
+
+    assert.deepEqual(step.toolCalls, [
+      {
+        name: 'lookupOrder',
+        args: { id: 7 },
+        result: 'Error: order service unreachable',
+        error: 'order service unreachable',
+      },
+    ])
+  })
+
+  test('leaves error unset on a tool that returned normally, even if it says Error', () => {
+    // A tool is allowed to return the word "Error" — which is exactly why
+    // "did this fail" cannot be answered by matching on the result text.
+    const step = toAccumulatedStep(
+      stepResult({
+        toolCalls: [
+          { toolCallId: 'call-1', toolName: 'searchLogs', args: { q: 'x' } },
+        ],
+        toolResults: [
+          {
+            toolCallId: 'call-1',
+            toolName: 'searchLogs',
+            result: 'Error: connection refused (1 match)',
+          },
+        ],
+      })
+    )
+
+    assert.equal(step.toolCalls[0].error, undefined)
+    assert.ok(!('error' in step.toolCalls[0]))
+  })
+})

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

@@ -0,0 +1,122 @@
+import type { CoreSingletonServices } from '../../types/core.types.js'
+import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js'
+
+/** Exactly what `modifyInput` accepts and returns, taken from the hook itself. */
+type TurnInput = Pick<
+  Parameters<NonNullable<PikkuAIMiddlewareHooks['modifyInput']>>[1],
+  'messages' | 'instructions'
+>
+
+/**
+ * Run every `modifyInput` hook in order, threading each result into the next.
+ *
+ * Shared by the four places a turn starts — first turn and resume, on both the
+ * streaming and non-streaming paths. `sharedNotes` is one bag per run that the
+ * caller keeps, because hooks use it to pass things forward (`voiceInput`
+ * leaves the transcript there for `voiceOutput`).
+ */
+export const applyInputMiddleware = async (
+  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  singletonServices: CoreSingletonServices,
+  input: TurnInput,
+  sharedNotes: Record<string, unknown>
+): Promise<TurnInput> => {
+  let { messages, instructions } = input
+  for (const mw of aiMiddlewares) {
+    if (!mw.modifyInput) continue
+    const result = await mw.modifyInput(singletonServices, {
+      messages,
+      instructions,
+      shared: sharedNotes,
+    })
+    messages = result.messages
+    instructions = result.instructions
+  }
+  return { messages, instructions }
+}
+
+/** The step fields both agent paths hand to `afterStep`, taken from the hook. */
+type StepResult = Omit<
+  Parameters<NonNullable<PikkuAIMiddlewareHooks['afterStep']>>[1],
+  'stepNumber'
+>
+
+/**
+ * Notify every `afterStep` hook. The payload is the step verbatim plus its
+ * ordinal — a hook that wants the run's totals accumulates them itself.
+ */
+export const notifyAfterStep = async (
+  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  singletonServices: CoreSingletonServices,
+  stepNumber: number,
+  stepResult: StepResult
+): Promise<void> => {
+  for (const mw of aiMiddlewares) {
+    if (!mw.afterStep) continue
+    await mw.afterStep(singletonServices, {
+      stepNumber,
+      text: stepResult.text,
+      toolCalls: stepResult.toolCalls,
+      toolResults: stepResult.toolResults,
+      usage: stepResult.usage,
+      finishReason: stepResult.finishReason,
+    })
+  }
+}
+
+/**
+ * The step shape kept on the run: each tool call paired with its result.
+ *
+ * A result is stringified unless it already is a string, because this is what
+ * gets persisted and read back as history — an object there is unreadable.
+ */
+export const toAccumulatedStep = (stepResult: StepResult) => ({
+  usage: stepResult.usage,
+  toolCalls: stepResult.toolCalls.map((tc) => {
+    const tr = stepResult.toolResults.find(
+      (r) => r.toolCallId === tc.toolCallId
+    )
+    return {
+      name: tc.toolName,
+      args: tc.args as Record<string, unknown>,
+      result:
+        typeof tr?.result === 'string'
+          ? tr.result
+          : JSON.stringify(tr?.result ?? ''),
+      ...(tr?.error ? { error: tr.error } : {}),
+    }
+  }),
+})
+
+type PendingApproval = {
+  toolName: string
+  args: unknown
+  reason?: string
+}
+
+type ToolDef = {
+  name: string
+  approvalDescriptionFn?: (args: any) => Promise<string> | string
+}
+
+/**
+ * Fill in each approval's human-readable reason from the tool's own
+ * `approvalDescriptionFn`, where it did not supply one.
+ *
+ * A description that throws is swallowed: the approval still has to be raised,
+ * and a gate that disappears because its label failed to render is the worst
+ * available outcome.
+ */
+export const describeApprovals = async (
+  approvals: PendingApproval[],
+  tools: ToolDef[]
+): Promise<void> => {
+  for (const approval of approvals) {
+    if (approval.reason) continue
+    const toolDef = tools.find((t) => t.name === approval.toolName)
+    if (!toolDef?.approvalDescriptionFn) continue
+    try {
+      approval.reason = await toolDef.approvalDescriptionFn(approval.args)
+    } catch {}
+  }
+}