@pikku/core 0.12.84 → 0.12.88

package/src/wirings/agent/agent-memory.test.ts

@@ -74,6 +74,72 @@ describe('agent-memory', () => {
     })
   })
 
+  test('deepMergeWorkingMemory replaces an array re-emitted in full', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [{ id: 1 }, { id: 2 }], other: 'kept' },
+      { steps: [{ id: 1 }, { id: 2 }, { id: 3 }] }
+    )
+
+    assert.deepEqual(result, {
+      steps: [{ id: 1 }, { id: 2 }, { id: 3 }],
+      other: 'kept',
+    })
+  })
+
+  test('deepMergeWorkingMemory replaces rather than appends a partial array', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [{ id: 1 }, { id: 2 }] },
+      { steps: [{ id: 3 }] }
+    )
+
+    assert.deepEqual(result, { steps: [{ id: 3 }] })
+  })
+
+  test('deepMergeWorkingMemory clears an array field set to null', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [1, 2, 3], city: 'Berlin' },
+      {
+        steps: null,
+      }
+    )
+
+    assert.deepEqual(result, { city: 'Berlin' })
+  })
+
+  test('deepMergeWorkingMemory replaces arrays nested inside merged objects', () => {
+    const result = deepMergeWorkingMemory(
+      {
+        profile: {
+          name: 'Yasser',
+          tags: ['a', 'b'],
+        },
+      },
+      {
+        profile: {
+          tags: ['c'],
+        },
+      }
+    )
+
+    assert.deepEqual(result, {
+      profile: {
+        name: 'Yasser',
+        tags: ['c'],
+      },
+    })
+  })
+
+  test('deepMergeWorkingMemory replaces across array and object shape changes', () => {
+    assert.deepEqual(
+      deepMergeWorkingMemory({ value: { a: 1 } }, { value: [1, 2] }),
+      { value: [1, 2] }
+    )
+    assert.deepEqual(
+      deepMergeWorkingMemory({ value: [1, 2] }, { value: { a: 1 } }),
+      { value: { a: 1 } }
+    )
+  })
+
   test('deepMergeWorkingMemory ignores prototype-polluting keys', () => {
     const before = ({} as any).isAdmin
     deepMergeWorkingMemory(
@@ -107,6 +173,13 @@ describe('agent-memory', () => {
     assert.match(prompt, /<working_memory>/)
   })
 
+  test('buildWorkingMemoryPrompt tells the model arrays are replaced whole', () => {
+    const prompt = buildWorkingMemoryPrompt({ steps: [1] })
+
+    assert.match(prompt, /Arrays are replaced, not merged/)
+    assert.match(prompt, /repeat every item you want to keep/)
+  })
+
   test('buildWorkingMemoryPrompt marks empty memory explicitly', () => {
     const prompt = buildWorkingMemoryPrompt(null)
     assert.match(prompt, /Current working memory: \(empty\)/)

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

@@ -39,6 +39,17 @@ export function isWorkingMemoryEnabled(
   return !!memoryConfig?.workingMemory && !!storage
 }
 
+/**
+ * Merges a model-emitted working memory update into the stored state.
+ *
+ * Objects merge key by key, and `null` deletes a key. Arrays are replaced
+ * wholesale — deliberately, not as a side effect of the object guard below.
+ * The full state is echoed back to the model every turn by
+ * {@link buildWorkingMemoryPrompt}, so it can always re-emit an array in full,
+ * and appending instead would duplicate every item each time it did.
+ * `buildWorkingMemoryPrompt` states this contract to the model; the two must
+ * stay in agreement.
+ */
 export function deepMergeWorkingMemory(
   existing: Record<string, unknown>,
   updates: Record<string, unknown>
@@ -51,9 +62,10 @@ export function deepMergeWorkingMemory(
     const value = updates[key]
     if (value === null) {
       delete result[key]
+    } else if (Array.isArray(value)) {
+      result[key] = value
     } else if (
       typeof value === 'object' &&
-      !Array.isArray(value) &&
       typeof result[key] === 'object' &&
       result[key] !== null &&
       !Array.isArray(result[key])
@@ -100,7 +112,9 @@ export function buildWorkingMemoryPrompt(
     'When you learn new information, output a partial JSON update in <working_memory> tags. ' +
       'Only include durable facts you have actually derived or the user has confirmed. ' +
       'Do not output templates, placeholders, or narration. ' +
-      'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it.'
+      'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it. ' +
+      'Arrays are replaced, not merged: to change one, repeat every item you want to keep alongside the new ones, ' +
+      'because any item you leave out is deleted.'
   )
 
   return parts.join('\n\n')

package/src/wirings/agent/agent-middleware.types.test.ts

@@ -0,0 +1,41 @@
+// Type-checked via tsconfig.type-tests.json; no runtime assertions.
+
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
+import type { PikkuAgentMiddlewareHooks } from './agent.types.js'
+
+const _singletonServicesCompile = pikkuAgentMiddleware<{ count: number }>({
+  modifyInput: async ({ logger }, { messages, instructions }) => {
+    logger.info(`agent input: ${messages.length} messages`)
+    return { messages, instructions }
+  },
+  modifyOutputStream: async ({ logger }, { event, state }) => {
+    state.count = (state.count ?? 0) + 1
+    logger.info(`event: ${event.type}`)
+    return event
+  },
+  afterStep: async ({ variables }, { stepNumber }) => {
+    variables.get(`STEP_${stepNumber}`)
+  },
+  onError: async ({ logger }, { error }) => {
+    logger.error(error.message)
+  },
+})
+void _singletonServicesCompile
+
+const _wireServiceIsNotAvailable: PikkuAgentMiddlewareHooks = {
+  // @ts-expect-error — `http` is a wire service, and an agent run has no wire
+  modifyInput: async ({ http }, { messages, instructions }) => {
+    void http
+    return { messages, instructions }
+  },
+}
+void _wireServiceIsNotAvailable
+
+const _wireServiceIsNotAvailableToTheFactory = pikkuAgentMiddleware({
+  // @ts-expect-error — `channel` is a wire service, and an agent run has no wire
+  afterToolCall: async ({ channel }, { result }) => {
+    void channel
+    return { result }
+  },
+})
+void _wireServiceIsNotAvailableToTheFactory

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

@@ -1,4 +1,8 @@
-import type { PikkuRawWire, CoreUserSession } from '../../types/core.types.js'
+import type {
+  PikkuRawWire,
+  CoreUserSession,
+  GetCredential,
+} from '../../types/core.types.js'
 import type {
   CoreAgent,
   AgentInput,
@@ -31,7 +35,7 @@ import {
   resolveNamespace,
   ContextAwareRPCService,
 } from '../../wirings/rpc/rpc-runner.js'
-import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js'
+import { getOrCreatePackageSingletonServices } from '../../wirings/addon/addon-runner.js'
 import {
   resolveMemoryServices,
   loadContextMessages,
@@ -42,7 +46,7 @@ import { resolveModelConfig } from './agent-model-config.js'
 export type RunAgentParams = {
   sessionService?: SessionService<CoreUserSession>
   /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
-  getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>
+  getCredential?: GetCredential
   /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
   anonymousOwnerResourceId?: string
 }
@@ -542,8 +546,7 @@ export async function buildToolDefs(
         (approvalPolicy === 'explicit' && fnMeta?.approvalRequired)
 
       let approvalDescriptionFn:
-        | ((input: unknown) => Promise<string>)
-        | undefined
+        ((input: unknown) => Promise<string>) | undefined
       if (needsApproval && pikkuFuncId) {
         const funcConfig = pikkuState(resolvedPkg, 'function', 'functions').get(
           pikkuFuncId

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

@@ -56,7 +56,7 @@ import {
 } from './agent-finalize.js'
 import { resolveModelConfig } from './agent-model-config.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
-import { randomUUID } from './agent-utils.js'
+import { deniedToolResult, randomUUID } from './agent-utils.js'
 
 function stripNulls(obj: unknown): unknown {
   if (obj === null) return undefined
@@ -484,8 +484,7 @@ export async function resumeAgentSync(
     let toolError: string | undefined
 
     if (rejectedIds.has(toolCallId)) {
-      resultStr =
-        'The user explicitly declined this action. Inform them that it was declined and do not retry.'
+      resultStr = deniedToolResult()
     } else if (approvedIds.has(toolCallId)) {
       const matchingTool = tools.find((t) => t.name === pending.toolName)
       if (!matchingTool) {

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

@@ -0,0 +1,381 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import { streamAgent, resumeAgent } from './agent-stream.js'
+import type {
+  CoreAgent,
+  AgentStreamChannel,
+  AgentStreamEvent,
+} from './agent.types.js'
+import type {
+  AgentStepResult,
+  AgentRunnerParams,
+} from '../../services/agent-runner-service.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const registerAgent = (
+  name: string,
+  overrides: Partial<CoreAgent> = {},
+  metaOverrides: Record<string, unknown> = {}
+) => {
+  const agent: CoreAgent = {
+    name,
+    description: `${name} agent`,
+    instructions: name,
+    model: 'test/test-model',
+    ...overrides,
+  }
+
+  pikkuState(null, 'agent', 'agentsMeta')[name] = {
+    ...agent,
+    inputSchema: null,
+    outputSchema: null,
+    workingMemorySchema: null,
+    ...metaOverrides,
+  } as any
+  pikkuState(null, 'agent', 'agents').set(name, agent)
+  return agent
+}
+
+const makeStepResult = (
+  overrides?: Partial<AgentStepResult>
+): AgentStepResult => ({
+  text: '',
+  toolCalls: [],
+  toolResults: [],
+  usage: { inputTokens: 0, outputTokens: 0 },
+  finishReason: 'stop',
+  ...overrides,
+})
+
+const recordingChannel = (channelId: string) => {
+  const events: AgentStreamEvent[] = []
+  const channel = {
+    channelId,
+    openingData: undefined,
+    state: 'open',
+    send: (event: AgentStreamEvent) => {
+      events.push(event)
+    },
+    sendBinary: () => {},
+    setState: () => {},
+    close: () => {},
+  } as unknown as AgentStreamChannel
+  return { channel, events }
+}
+
+const parentTextOf = (events: AgentStreamEvent[]) =>
+  events
+    .filter((e) => e.type === 'text-delta' && !(e as any).agent)
+    .map((e) => (e as any).text as string)
+    .join('')
+
+/**
+ * A parent that speaks either side of a hand-off to a specialist — the shape
+ * the issue describes, with the model's text made deterministic so the
+ * plumbing can be observed without a live call.
+ */
+const delegatingRunner = (
+  script: { preHandoff: string; postHandoff: string } = {
+    preHandoff: 'Planning. ',
+    postHandoff: 'Handed off. <working_memory>{"phase":"two"}</working_memory>',
+  }
+) => {
+  let parentStep = 0
+  return {
+    stream: async (params: AgentRunnerParams, channel: AgentStreamChannel) => {
+      const subTool = params.tools.find((t) => t.name === 'sub')
+      if (!subTool) {
+        channel.send({ type: 'text-delta', text: 'specialist output' })
+        channel.send({
+          type: 'usage',
+          tokens: { input: 1, output: 1 },
+        } as AgentStreamEvent)
+        return makeStepResult({ text: 'specialist output' })
+      }
+
+      if (parentStep++ === 0) {
+        channel.send({ type: 'text-delta', text: script.preHandoff })
+
+        await subTool.execute!({ message: 'do phase two', session: 's1' })
+
+        channel.send({ type: 'text-delta', text: script.postHandoff })
+        channel.send({
+          type: 'usage',
+          tokens: { input: 1, output: 1 },
+        } as AgentStreamEvent)
+        return makeStepResult({
+          text: 'Planning. Handed off.',
+          toolCalls: [
+            {
+              toolCallId: 'call-1',
+              toolName: 'sub',
+              args: { message: 'do phase two', session: 's1' },
+            },
+          ],
+          toolResults: [
+            {
+              toolCallId: 'call-1',
+              toolName: 'sub',
+              result: 'specialist output',
+            },
+          ],
+          finishReason: 'tool-calls',
+        })
+      }
+
+      channel.send({
+        type: 'text-delta',
+        text: 'Done. <working_memory>{"phase":"three"}</working_memory>',
+      })
+      channel.send({
+        type: 'usage',
+        tokens: { input: 1, output: 1 },
+      } as AgentStreamEvent)
+      return makeStepResult({ text: 'Done.' })
+    },
+  }
+}
+
+const makeServices = (
+  runner: { stream: any },
+  savedWorkingMemory: unknown[],
+  savedMessages: any[] = []
+) => {
+  let stored: Record<string, unknown> = {}
+  return {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    agentRunner: runner,
+    agentRunState: {
+      createRun: async () => 'run-1',
+      updateRun: async () => {},
+    },
+    agentStorage: {
+      createThread: async () => {},
+      getMessages: async () => [],
+      saveMessages: async (threadId: string, messages: any[]) => {
+        savedMessages.push(
+          ...messages.map((message) => ({ threadId, message }))
+        )
+      },
+      getWorkingMemory: async () => stored,
+      saveWorkingMemory: async (
+        threadId: string,
+        scope: string,
+        value: any
+      ) => {
+        stored = value
+        savedWorkingMemory.push({ threadId, scope, value })
+      },
+    },
+  } as any
+}
+
+const wireDelegatingPair = (agentMode: 'delegate' | 'supervise') => {
+  registerAgent('sub', { instructions: 'sub' })
+  registerAgent(
+    'parent',
+    {
+      instructions: 'parent',
+      agentMode,
+      memory: { workingMemory: true } as any,
+    },
+    { agents: ['sub'] }
+  )
+}
+
+const runParent = async (script?: {
+  preHandoff: string
+  postHandoff: string
+}) => {
+  const savedWorkingMemory: unknown[] = []
+  const savedMessages: any[] = []
+  pikkuState(
+    null,
+    'package',
+    'singletonServices',
+    makeServices(delegatingRunner(script), savedWorkingMemory, savedMessages)
+  )
+  const { channel, events } = recordingChannel('c1')
+  const fullText = await streamAgent(
+    'parent',
+    { message: 'go', threadId: 't1', resourceId: 'r1' },
+    channel,
+    {}
+  )
+  return { savedWorkingMemory, savedMessages, events, fullText }
+}
+
+describe('delegate mode and working memory', () => {
+  test('collects working memory the parent writes after a hand-off', async () => {
+    wireDelegatingPair('delegate')
+    const { savedWorkingMemory } = await runParent()
+
+    assert.deepEqual(
+      savedWorkingMemory.map((s: any) => s.value.phase),
+      ['two', 'three']
+    )
+  })
+
+  test('still collects working memory written before the hand-off', async () => {
+    wireDelegatingPair('delegate')
+    const { savedWorkingMemory } = await runParent({
+      preHandoff: 'Planning. <working_memory>{"phase":"one"}</working_memory>',
+      postHandoff: 'Handed off. ',
+    })
+
+    assert.deepEqual(
+      savedWorkingMemory.map((s: any) => s.value.phase),
+      ['one', 'three']
+    )
+  })
+
+  test('the client receives no parent text after the hand-off', async () => {
+    wireDelegatingPair('delegate')
+    const { events } = await runParent()
+
+    assert.equal(parentTextOf(events), 'Planning. ')
+  })
+
+  test('the parent assistant text persisted stays suppressed', async () => {
+    wireDelegatingPair('delegate')
+    const { fullText, savedMessages } = await runParent()
+
+    assert.equal(fullText, 'Planning. ')
+    const assistantText = savedMessages
+      .filter(
+        ({ threadId, message }: any) =>
+          threadId === 't1' && message.role === 'assistant'
+      )
+      .map(({ message }: any) =>
+        typeof message.content === 'string'
+          ? message.content
+          : (message.content ?? [])
+              .filter((part: any) => part.type === 'text')
+              .map((part: any) => part.text)
+              .join('')
+      )
+      .join('')
+    assert.equal(assistantText, 'Planning. ')
+  })
+
+  test('supervise mode streams every parent delta and collects every update', async () => {
+    wireDelegatingPair('supervise')
+    const { events, savedWorkingMemory } = await runParent()
+
+    assert.equal(parentTextOf(events), 'Planning. Handed off. Done. ')
+    assert.deepEqual(
+      savedWorkingMemory.map((s: any) => s.value.phase),
+      ['two', 'three']
+    )
+  })
+
+  test('user channel middleware sees exactly the deltas the client sees', async () => {
+    wireDelegatingPair('delegate')
+    const seen: string[] = []
+    const agent = pikkuState(null, 'agent', 'agents').get('parent')!
+    agent.channelMiddleware = [
+      async (_services: any, event: any, next: any) => {
+        if (event.type === 'text-delta') seen.push(event.text)
+        await next(event)
+      },
+    ] as any
+    pikkuState(null, 'agent', 'agents').set('parent', agent)
+
+    const { events } = await runParent({
+      preHandoff: 'Planning. <working_memory>{"phase":"one"}</working_memory>',
+      postHandoff: 'Handed off. ',
+    })
+
+    const clientDeltas = events
+      .filter((e) => e.type === 'text-delta' && !(e as any).agent)
+      .map((e) => (e as any).text as string)
+
+    assert.deepEqual(seen, clientDeltas)
+    assert.deepEqual(seen, ['Planning. '])
+  })
+
+  test('the raw text a delegating parent speaks still reaches afterStep', async () => {
+    wireDelegatingPair('delegate')
+
+    const stepTexts: string[] = []
+    const agent = pikkuState(null, 'agent', 'agents').get('parent')!
+    agent.agentMiddleware = [
+      {
+        afterStep: async (_services: any, ctx: any) => {
+          stepTexts.push(ctx.text)
+        },
+      },
+    ] as any
+    pikkuState(null, 'agent', 'agents').set('parent', agent)
+
+    await runParent()
+
+    assert.deepEqual(stepTexts, ['Planning. Handed off.', 'Done.'])
+  })
+})
+
+describe('delegate mode on the resume path', () => {
+  test('suppresses parent text after a hand-off and still collects working memory', async () => {
+    wireDelegatingPair('delegate')
+
+    const savedWorkingMemory: unknown[] = []
+    const services = makeServices(delegatingRunner(), savedWorkingMemory)
+    let pendingApprovals: unknown[] = [
+      {
+        type: 'tool-call',
+        toolCallId: 'tc-1',
+        toolName: 'sub',
+        args: { message: 'approved hand-off', session: 's0' },
+        runId: 'run-1',
+      },
+    ]
+    services.agentRunState = {
+      createRun: async () => 'run-1',
+      updateRun: async () => {},
+      resolveApproval: async () => {
+        pendingApprovals = []
+        return true
+      },
+      getRun: async () => ({
+        runId: 'run-1',
+        id: 'run-1',
+        agentName: 'parent',
+        threadId: 't1',
+        resourceId: 'r1',
+        status: 'suspended',
+        pendingApprovals,
+        messages: [],
+      }),
+    }
+    pikkuState(null, 'package', 'singletonServices', services)
+
+    const { channel, events } = recordingChannel('c1')
+    await resumeAgent(
+      { runId: 'run-1', toolCallId: 'tc-1', approved: true },
+      channel,
+      {
+        sessionService: {
+          get: () => ({ userId: 'r1' }),
+          setInitial: () => {},
+          sessionChanged: false,
+        },
+      } as any
+    )
+
+    assert.equal(parentTextOf(events), 'Planning. ')
+    assert.deepEqual(
+      savedWorkingMemory.map((s: any) => s.value.phase),
+      ['two', 'three']
+    )
+  })
+})