@pikku/core 0.12.84 → 0.12.88

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

@@ -14,12 +14,14 @@ import { finalizeAgentRun, lastUserMessageText } from './agent-finalize.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { applyInputMiddleware } from './agent-turn.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
-import { randomUUID } from './agent-utils.js'
+import { deniedToolResult, randomUUID } from './agent-utils.js'
 import { SPOKEN_TRANSCRIPT } from './voice-input.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../channel/channel-middleware-runner.js'
+import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js'
+import type { CoreSingletonServices } from '../../types/core.types.js'
 import type { AgentStorageService } from '../../services/agent-storage-service.js'
 import type {
   AgentRunnerParams,
@@ -300,6 +302,64 @@ async function postStreamCleanup(
   })
 }
 
+/**
+ * Adapts `modifyOutputStream` hooks to channel middleware, one closure per
+ * hook so each keeps its own `state` and event log for the whole run.
+ */
+const toChannelStreamMiddleware = (
+  hooks: PikkuAgentMiddlewareHooks[],
+  sharedNotes: Record<string, unknown>,
+  signal: AbortSignal
+) =>
+  hooks
+    .filter((mw) => mw.modifyOutputStream)
+    .map((mw) => {
+      const state: Record<string, unknown> = {}
+      const allEvents: AgentStreamEvent[] = []
+      return async (services: any, event: any, next: any) => {
+        allEvents.push(event)
+        const result = await mw.modifyOutputStream!(services, {
+          event,
+          allEvents,
+          state,
+          shared: sharedNotes,
+          // Sends downstream directly, so a hook can hand back the fast event
+          // now and push the slow one when it is ready.
+          emit: next,
+          signal,
+        })
+        if (result == null) return
+        if (Array.isArray(result)) {
+          for (const r of result) await next(r)
+        } else {
+          await next(result)
+        }
+      }
+    })
+
+/**
+ * The branch a delegating parent's own spoken text is routed down once it has
+ * handed off: the same working-memory hook instances as the main chain, so the
+ * in-band `<working_memory>` blocks are still collected, ending in a sink so
+ * neither the client, the thread history, nor user channel middleware sees
+ * text the parent was supposed to keep to itself.
+ *
+ * Routing at ingress rather than dropping further down the chain keeps the
+ * decision synchronous with the send: the working-memory hook is async, so a
+ * hand-off landing mid-flight would otherwise retroactively suppress text the
+ * parent spoke before it.
+ */
+const createWorkingMemoryOnlyChannel = (
+  channel: AgentStreamChannel,
+  services: CoreSingletonServices,
+  workingMemoryMiddleware: readonly CorePikkuChannelMiddleware[]
+): AgentStreamChannel =>
+  wrapChannelWithMiddleware(
+    { channel: { ...channel, send: () => {} } as AgentStreamChannel },
+    services,
+    workingMemoryMiddleware
+  ).channel as AgentStreamChannel
+
 type StepLoopParams = {
   agent: CoreAgent
   runnerParams: AgentRunnerParams
@@ -720,13 +780,18 @@ export async function streamAgent(
     return ''
   }
 
-  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
-    ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+  const workingMemoryMiddleware = getWorkingMemoryMiddleware(
+    memoryConfig,
+    storage,
+    {
       threadId,
       workingMemorySchemaName,
       logger: singletonServices.logger,
       schemaService: singletonServices.schema,
-    }),
+    }
+  )
+  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
+    ...workingMemoryMiddleware,
     ...(agent.agentMiddleware ?? []),
   ]
 
@@ -785,45 +850,36 @@ export async function streamAgent(
     singletonServices.logger
   )
 
-  const streamMiddleware = agentMiddlewares
-    .filter((mw) => mw.modifyOutputStream)
-    .map((mw) => {
-      const state: Record<string, unknown> = {}
-      const allEvents: AgentStreamEvent[] = []
-      return async (services: any, event: any, next: any) => {
-        allEvents.push(event)
-        const result = await mw.modifyOutputStream!(services, {
-          event,
-          allEvents,
-          state,
-          shared: sharedNotes,
-          // Sends downstream directly, so a hook can hand back the fast event
-          // now and push the slow one when it is ready.
-          emit: next,
-          signal: interruptHandle.signal,
-        })
-        if (result == null) return
-        if (Array.isArray(result)) {
-          for (const r of result) await next(r)
-        } else {
-          await next(result)
-        }
-      }
-    })
+  const workingMemoryStreamMiddleware = toChannelStreamMiddleware(
+    workingMemoryMiddleware,
+    sharedNotes,
+    interruptHandle.signal
+  )
+  const streamMiddleware = toChannelStreamMiddleware(
+    agent.agentMiddleware ?? [],
+    sharedNotes,
+    interruptHandle.signal
+  )
 
   const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
   const meta = agentsMeta[resolvedName]
-  const allChannelMiddleware = combineChannelMiddleware(
-    'agent',
-    `stream:${agentName}`,
-    {
+
+  const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length
+  const delegateState = { delegated: false }
+  if (isDelegateMode) {
+    streamContext.delegateState = delegateState
+  }
+
+  const allChannelMiddleware = [
+    ...workingMemoryStreamMiddleware,
+    ...combineChannelMiddleware('agent', `stream:${agentName}`, {
       wireInheritedChannelMiddleware: meta?.channelMiddleware,
       wireChannelMiddleware: [
         ...(agent.channelMiddleware ?? []),
         ...streamMiddleware,
       ],
-    }
-  )
+    }),
+  ]
 
   const persistingChannel = createPersistingChannel(
     channel,
@@ -857,23 +913,27 @@ export async function streamAgent(
     },
   }
 
-  const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length
-  const delegateState = { delegated: false }
-  if (isDelegateMode) {
-    streamContext.delegateState = delegateState
-  }
-  const outputChannel = isDelegateMode
+  const workingMemoryOnlyChannel =
+    isDelegateMode && workingMemoryStreamMiddleware.length > 0
+      ? createWorkingMemoryOnlyChannel(
+          channel,
+          singletonServices,
+          workingMemoryStreamMiddleware
+        )
+      : undefined
+
+  const outputChannel: AgentStreamChannel = isDelegateMode
     ? {
         ...credentialFilteredChannel,
         send: (event: AgentStreamEvent) => {
           if (
             delegateState.delegated &&
             (event.type === 'text-delta' || event.type === 'reasoning-delta')
-          )
-            return
+          ) {
+            return workingMemoryOnlyChannel?.send(event)
+          }
           return credentialFilteredChannel.send(event)
         },
-        delegateState,
       }
     : credentialFilteredChannel
 
@@ -1099,8 +1159,7 @@ export async function resumeAgent(
       await agentRunState.updateRun(pending.agentRunId, { status: 'failed' })
     }
 
-    const denialResult =
-      'The user explicitly declined this action. Inform them that it was declined and do not retry.'
+    const denialResult = deniedToolResult()
 
     if (storage) {
       await storage.saveMessages(run.threadId, [
@@ -1351,13 +1410,18 @@ async function continueAfterToolResult(
 
   const instructions = await buildInstructions(resolvedName, packageName)
 
-  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
-    ...getWorkingMemoryMiddleware(memoryConfig, storage, {
+  const workingMemoryMiddleware = getWorkingMemoryMiddleware(
+    memoryConfig,
+    storage,
+    {
       threadId: run.threadId,
       workingMemorySchemaName,
       logger: singletonServices.logger,
       schemaService: singletonServices.schema,
-    }),
+    }
+  )
+  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
+    ...workingMemoryMiddleware,
     ...(agent.agentMiddleware ?? []),
   ]
   // One bag per run, shared by every middleware — see PikkuAgentMiddlewareHooks.
@@ -1380,43 +1444,27 @@ async function continueAfterToolResult(
     singletonServices.logger
   )
 
-  const streamMiddleware = agentMiddlewares
-    .filter((mw) => mw.modifyOutputStream)
-    .map((mw) => {
-      const state: Record<string, unknown> = {}
-      const allEvents: AgentStreamEvent[] = []
-      return async (services: any, event: any, next: any) => {
-        allEvents.push(event)
-        const result = await mw.modifyOutputStream!(services, {
-          event,
-          allEvents,
-          state,
-          shared: sharedNotes,
-          // Sends downstream directly, so a hook can hand back the fast event
-          // now and push the slow one when it is ready.
-          emit: next,
-          signal: interruptHandle.signal,
-        })
-        if (result == null) return
-        if (Array.isArray(result)) {
-          for (const r of result) await next(r)
-        } else {
-          await next(result)
-        }
-      }
-    })
+  const workingMemoryStreamMiddleware = toChannelStreamMiddleware(
+    workingMemoryMiddleware,
+    sharedNotes,
+    interruptHandle.signal
+  )
+  const streamMiddleware = toChannelStreamMiddleware(
+    agent.agentMiddleware ?? [],
+    sharedNotes,
+    interruptHandle.signal
+  )
 
-  const allChannelMiddleware = combineChannelMiddleware(
-    'agent',
-    `stream:${run.agentName}`,
-    {
+  const allChannelMiddleware = [
+    ...workingMemoryStreamMiddleware,
+    ...combineChannelMiddleware('agent', `stream:${run.agentName}`, {
       wireInheritedChannelMiddleware: meta?.channelMiddleware,
       wireChannelMiddleware: [
         ...(agent.channelMiddleware ?? []),
         ...streamMiddleware,
       ],
-    }
-  )
+    }),
+  ]
 
   const persistingChannel = createPersistingChannel(
     channel,
@@ -1434,7 +1482,38 @@ async function continueAfterToolResult(
         ).channel as AgentStreamChannel)
       : persistingChannel
 
+  const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length
+  const delegateState = { delegated: false }
+
   const streamContext: StreamContext = { channel, options }
+  if (isDelegateMode) {
+    streamContext.delegateState = delegateState
+  }
+
+  const workingMemoryOnlyChannel =
+    isDelegateMode && workingMemoryStreamMiddleware.length > 0
+      ? createWorkingMemoryOnlyChannel(
+          channel,
+          singletonServices,
+          workingMemoryStreamMiddleware
+        )
+      : undefined
+
+  const outputChannel: AgentStreamChannel = isDelegateMode
+    ? {
+        ...wrappedChannel,
+        send: (event: AgentStreamEvent) => {
+          if (
+            delegateState.delegated &&
+            (event.type === 'text-delta' || event.type === 'reasoning-delta')
+          ) {
+            return workingMemoryOnlyChannel?.send(event)
+          }
+          return wrappedChannel.send(event)
+        },
+      }
+    : wrappedChannel
+
   const resumeTools = (
     await buildToolDefs(
       params,
@@ -1473,7 +1552,7 @@ async function continueAfterToolResult(
       runnerParams,
       maxSteps,
       agentRunner,
-      streamChannel: wrappedChannel,
+      streamChannel: outputChannel,
       persistingChannel,
       channel,
       agentMiddlewares,

package/src/wirings/agent/agent-utils.ts

@@ -1 +1,20 @@
 export const randomUUID = (): string => globalThis.crypto.randomUUID()
+
+/**
+ * The tool result stored and streamed when a user denies an approval.
+ *
+ * Two readers, one string. The model needs the sentence — it has to tell the
+ * user the action was declined and not retry it. A client needs to know a
+ * denial when it sees one, so it can render the call as denied rather than as
+ * a successful call that happened to return prose; that is what `approved`
+ * carries, and it is the same flag a client sets optimistically the moment the
+ * deny button is clicked. Emitting only the sentence made the two disagree:
+ * live the call showed denied, and on any re-render from storage the same call
+ * came back green.
+ */
+export const deniedToolResult = (): string =>
+  JSON.stringify({
+    approved: false,
+    message:
+      'The user explicitly declined this action. Inform them that it was declined and do not retry.',
+  })

package/src/wirings/agent/agent.types.ts

@@ -5,8 +5,9 @@ import type {
 import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
-  PermissionMetadata,
-} from '../../types/core.types.js'
+} from '../../middleware/middleware.types.js'
+import type { CoreSingletonServices } from '../../types/core.types.js'
+import type { PermissionMetadata } from '../../function/function-meta.types.js'
 import type { AIProviderOptions } from '../../services/agent-runner-service.js'
 import type { PikkuChannel } from '../channel/channel.types.js'
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js'
@@ -180,10 +181,10 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
 
 export interface PikkuAgentMiddlewareHooks<
   State extends Record<string, unknown> = Record<string, unknown>,
-  Services = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
 > {
   modifyInput?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       messages: AgentMessage[]
       instructions: string
@@ -210,7 +211,7 @@ export interface PikkuAgentMiddlewareHooks<
     | { messages: AgentMessage[]; instructions: string }
 
   modifyOutputStream?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       event: AgentStreamEvent
       allEvents: readonly AgentStreamEvent[]
@@ -262,7 +263,7 @@ export interface PikkuAgentMiddlewareHooks<
    * leaves them untouched.
    */
   modifyOutput?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       text: string
       messages: AgentMessage[]
@@ -282,7 +283,7 @@ export interface PikkuAgentMiddlewareHooks<
       }
 
   beforeToolCall?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       toolName: string
       toolCallId: string
@@ -294,7 +295,7 @@ export interface PikkuAgentMiddlewareHooks<
     | void
 
   afterToolCall?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       toolName: string
       toolCallId: string
@@ -305,7 +306,7 @@ export interface PikkuAgentMiddlewareHooks<
   ) => Promise<{ result: unknown } | void> | { result: unknown } | void
 
   afterStep?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       stepNumber: number
       text: string
@@ -323,7 +324,7 @@ export interface PikkuAgentMiddlewareHooks<
   ) => Promise<void> | void
 
   onError?: (
-    services: Services,
+    services: SingletonServices,
     ctx: {
       error: Error
       stepNumber: number
@@ -423,7 +424,7 @@ export type CoreAgent<
    * which OR together, a scope can only narrow access.
    *
    * Narrowed to the generated `ScopeId` union in a project's own
-   * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+   * `#pikku/scopes`, so an undeclared scope is a compile error.
    */
   scopes?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>

package/src/wirings/agent/index.ts

@@ -20,6 +20,7 @@ export {
   unspeakableScripts,
   voiceForText,
   type SpeakableScripts,
+  type VoiceOutputState,
 } from './voice-output.js'
 export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js'
 export type {

package/src/wirings/agent/voice-input.ts

@@ -1,5 +1,5 @@
 import type { AgentRunnerService } from '../../services/agent-runner-service.js'
-import { pikkuAgentMiddleware } from '../../types/core.types.js'
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
 import { safeFetch } from '../../utils/safe-fetch.js'
 import type { AgentContentPart } from './agent.types.js'
 

package/src/wirings/agent/voice-output.test.ts

@@ -233,8 +233,7 @@ describe('voiceOutput', () => {
 
     assert.deepEqual(asked, [], 'nothing should have been sent for synthesis')
     const notice = stream.out.find((event) => event.type === 'data') as
-      | { name: string; data: { scripts: string[] } }
-      | undefined
+      { name: string; data: { scripts: string[] } } | undefined
     assert.equal(notice?.name, 'voice-unsupported')
     assert.deepEqual(notice?.data.scripts, ['arabic'])
   })
@@ -424,8 +423,7 @@ describe('voiceOutput', () => {
 
     assert.deepEqual(asked, [])
     const notice = stream.out.find((event) => event.type === 'data') as
-      | { name: string; data: { scripts: string[] } }
-      | undefined
+      { name: string; data: { scripts: string[] } } | undefined
     assert.deepEqual(notice?.data.scripts, ['arabic'])
   })
 

package/src/wirings/agent/voice-output.ts

@@ -1,5 +1,5 @@
 import type { AgentRunnerService } from '../../services/agent-runner-service.js'
-import { pikkuAgentMiddleware } from '../../types/core.types.js'
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
 import { SPOKEN_TURN } from './voice-input.js'
 
 export type VoiceOutputState = {

package/src/wirings/agent-scorer/agent-scorer-judge.test.ts

@@ -55,6 +55,151 @@ describe('buildJudgePrompt', () => {
     assert.match(prompt, /Grade helpfulness\./)
   })
 
+  test('shows which tools ran, so an answer is distinguishable from a guess', () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({
+        toolCalls: [
+          { name: 'listTodos', args: {}, result: { todos: ['Buy groceries'] } },
+        ],
+      })
+    )
+
+    assert.match(prompt, /Tools the assistant ran:\n- listTodos/)
+  })
+
+  test('the default disclosure sends the judge no arguments and no results', () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({
+        toolCalls: [
+          {
+            name: 'lookupCustomer',
+            args: { email: 'ada@example.com' },
+            result: { address: '12 Mill Lane' },
+          },
+        ],
+      })
+    )
+
+    assert.doesNotMatch(prompt, /ada@example\.com/)
+    assert.doesNotMatch(prompt, /Mill Lane/)
+  })
+
+  test('a run that called nothing gets no tool section rather than an empty one', () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+    })
+
+    assert.doesNotMatch(buildJudgePrompt(scorer.judge!, input()), /Tools the/)
+  })
+
+  test('a failed call is shown as failed, which is not the same as no call', () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({
+        toolCalls: [
+          {
+            name: 'listTodos',
+            args: {},
+            error: 'no such user ada@example.com',
+          },
+        ],
+      })
+    )
+
+    assert.match(prompt, /- listTodos \(failed\)/)
+    assert.doesNotMatch(prompt, /ada@example\.com/)
+  })
+
+  test("'full' shows the arguments and results, for a judge that grades against them", () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+      toolCalls: 'full',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({
+        toolCalls: [
+          { name: 'listTodos', args: {}, result: { todos: ['Buy groceries'] } },
+          { name: 'save', args: {}, error: 'store unreachable' },
+        ],
+      })
+    )
+
+    assert.match(
+      prompt,
+      /listTodos\(\{\}\) returned \{"todos":\["Buy groceries"\]\}/
+    )
+    assert.match(prompt, /save\(\{\}\) failed: store unreachable/)
+  })
+
+  test("'off' withholds the trajectory entirely, even from a run that used tools", () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+      toolCalls: 'off',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({ toolCalls: [{ name: 'listTodos', args: {}, result: {} }] })
+    )
+
+    assert.doesNotMatch(prompt, /Tools the/)
+    assert.doesNotMatch(prompt, /listTodos/)
+  })
+
+  test('a large tool result is truncated rather than crowding out the answer', () => {
+    const scorer = pikkuAgentJudge({
+      name: 'helpfulness',
+      description: 'Is the answer useful',
+      model: 'claude-opus-5',
+      goal: 'Grade helpfulness.',
+      toolCalls: 'full',
+    })
+
+    const prompt = buildJudgePrompt(
+      scorer.judge!,
+      input({
+        toolCalls: [{ name: 'search', args: {}, result: 'x'.repeat(5000) }],
+      })
+    )
+
+    assert.match(prompt, /… \(truncated\)/)
+    assert.ok(prompt.length < 1500, `prompt was ${prompt.length} characters`)
+  })
+
   test('a scorer that supplies its own prompt replaces the framing entirely', () => {
     const scorer = pikkuAgentJudge({
       name: 'custom',