@pikku/core 0.12.0 → 0.12.2

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

@@ -0,0 +1,152 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import {
+  agent,
+  agentStream,
+  agentResume,
+  agentApprove,
+} from './ai-agent-helpers.js'
+
+describe('agent helpers', () => {
+  describe('agent', () => {
+    test('should return an object with func', () => {
+      const a = agent('myAgent')
+      assert.strictEqual(typeof a.func, 'function')
+    })
+
+    test('func should call rpc.agent.run', async () => {
+      const a = agent('myAgent')
+      let calledWith: any
+      const rpc = {
+        agent: {
+          run: async (...args: any[]) => {
+            calledWith = args
+            return {
+              runId: 'run-1',
+              result: 'done',
+              usage: { inputTokens: 10, outputTokens: 20 },
+            }
+          },
+        },
+      }
+      const input = { message: 'hello', threadId: 't1', resourceId: 'r1' }
+      const result = await a.func({}, input, { rpc })
+      assert.strictEqual(calledWith[0], 'myAgent')
+      assert.deepStrictEqual(calledWith[1], input)
+      assert.strictEqual(result.runId, 'run-1')
+    })
+  })
+
+  describe('agentStream', () => {
+    test('should return an object with func', () => {
+      const a = agentStream('myAgent')
+      assert.strictEqual(typeof a.func, 'function')
+    })
+
+    test('func should call rpc.agent.stream with bound name', async () => {
+      const a = agentStream('myAgent')
+      let calledWith: any
+      const rpc = {
+        agent: {
+          stream: async (...args: any[]) => {
+            calledWith = args
+          },
+        },
+      }
+      const input = { message: 'hello', threadId: 't1', resourceId: 'r1' }
+      await a.func({}, input, { rpc })
+      assert.strictEqual(calledWith[0], 'myAgent')
+      assert.deepStrictEqual(calledWith[1], input)
+    })
+
+    test('func should extract agentName from data when no name bound', async () => {
+      const a = agentStream()
+      let calledWith: any
+      const rpc = {
+        agent: {
+          stream: async (...args: any[]) => {
+            calledWith = args
+          },
+        },
+      }
+      const input = {
+        agentName: 'dynamicAgent',
+        message: 'hello',
+        threadId: 't1',
+        resourceId: 'r1',
+      }
+      await a.func({}, input, { rpc })
+      assert.strictEqual(calledWith[0], 'dynamicAgent')
+      assert.deepStrictEqual(calledWith[1], {
+        message: 'hello',
+        threadId: 't1',
+        resourceId: 'r1',
+      })
+    })
+
+    test('func should throw when no name bound and no agentName in data', async () => {
+      const a = agentStream()
+      const rpc = { agent: { stream: async () => {} } }
+      await assert.rejects(() => a.func({}, { message: 'hello' }, { rpc }), {
+        message:
+          'agentStream requires an agentName either as a parameter or in the input data',
+      })
+    })
+  })
+
+  describe('agentResume', () => {
+    test('should return an object with func', () => {
+      const a = agentResume()
+      assert.strictEqual(typeof a.func, 'function')
+    })
+
+    test('func should call rpc.agent.resume', async () => {
+      const a = agentResume()
+      let calledWith: any
+      const rpc = {
+        agent: {
+          resume: async (...args: any[]) => {
+            calledWith = args
+          },
+        },
+      }
+      const data = { runId: 'run-1', toolCallId: 'tc1', approved: true }
+      await a.func({}, data, { rpc })
+      assert.strictEqual(calledWith[0], 'run-1')
+      assert.deepStrictEqual(calledWith[1], {
+        toolCallId: 'tc1',
+        approved: true,
+      })
+    })
+  })
+
+  describe('agentApprove', () => {
+    test('should return an object with func', () => {
+      const a = agentApprove('myAgent')
+      assert.strictEqual(typeof a.func, 'function')
+    })
+
+    test('func should call rpc.agent.approve', async () => {
+      const a = agentApprove('myAgent')
+      let calledWith: any
+      const rpc = {
+        agent: {
+          approve: async (...args: any[]) => {
+            calledWith = args
+            return { approved: true }
+          },
+        },
+      }
+      const data = {
+        runId: 'run-1',
+        approvals: [{ toolCallId: 'tc1', approved: true }],
+      }
+      const result = await a.func({}, data, { rpc })
+      assert.strictEqual(calledWith[0], 'run-1')
+      assert.deepStrictEqual(calledWith[1], [
+        { toolCallId: 'tc1', approved: true },
+      ])
+      assert.deepStrictEqual(result, { approved: true })
+    })
+  })
+})

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

@@ -0,0 +1,76 @@
+export function agent<TAgentMap extends Record<string, { output: any }>>(
+  agentName: string & keyof TAgentMap
+): { func: (services: any, data: any, wire: any) => Promise<any> } {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      return rpc.agent.run(agentName, data)
+    },
+  }
+}
+
+export function agentStream<TAgentMap extends Record<string, { output: any }>>(
+  agentName?: string & keyof TAgentMap
+): { func: (services: any, data: any, wire: any) => Promise<void> } {
+  return {
+    func: async (_services: any, data: any, { rpc }: any) => {
+      if (agentName) {
+        await rpc.agent.stream(agentName, data)
+      } else {
+        const { agentName: name, ...rest } = data
+        if (!name) {
+          throw new Error(
+            'agentStream requires an agentName either as a parameter or in the input data'
+          )
+        }
+        await rpc.agent.stream(name, rest)
+      }
+    },
+  }
+}
+
+export function agentResume(): {
+  func: (
+    services: any,
+    data: { runId: string; toolCallId: string; approved: boolean },
+    wire: any
+  ) => Promise<void>
+} {
+  return {
+    func: async (
+      _services: any,
+      data: { runId: string; toolCallId: string; approved: boolean },
+      { rpc }: any
+    ) => {
+      await rpc.agent.resume(data.runId, {
+        toolCallId: data.toolCallId,
+        approved: data.approved,
+      })
+    },
+  }
+}
+
+export function agentApprove<TAgentMap extends Record<string, { output: any }>>(
+  _agentName: string & keyof TAgentMap
+): {
+  func: (
+    services: any,
+    data: {
+      runId: string
+      approvals: { toolCallId: string; approved: boolean }[]
+    },
+    wire: any
+  ) => Promise<any>
+} {
+  return {
+    func: async (
+      _services: any,
+      data: {
+        runId: string
+        approvals: { toolCallId: string; approved: boolean }[]
+      },
+      { rpc }: any
+    ) => {
+      return rpc.agent.approve(data.runId, data.approvals)
+    },
+  }
+}

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

@@ -277,7 +277,16 @@ function sanitizeToolMessages(messages: AIMessage[]): AIMessage[] {
 
 function estimateTokens(msg: AIMessage): number {
   let chars = 0
-  if (msg.content) chars += msg.content.length
+  if (msg.content) {
+    if (typeof msg.content === 'string') {
+      chars += msg.content.length
+    } else {
+      for (const part of msg.content) {
+        if (part.type === 'text') chars += part.text.length
+        else chars += 1000
+      }
+    }
+  }
   if (msg.toolCalls) chars += JSON.stringify(msg.toolCalls).length
   if (msg.toolResults) chars += JSON.stringify(msg.toolResults).length
   return Math.ceil(chars / 4)

package/src/wirings/ai-agent/ai-agent-model-config.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { resolveModelConfig } from './ai-agent-model-config.js'
+import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('resolveModelConfig', () => {
+  test('should return agent model when no config', () => {
+    const result = resolveModelConfig('testAgent', {
+      model: 'anthropic/claude-3',
+      temperature: 0.7,
+    })
+    assert.strictEqual(result.model, 'anthropic/claude-3')
+    assert.strictEqual(result.temperature, 0.7)
+  })
+
+  test('should resolve model alias to string', () => {
+    pikkuState(null, 'models', 'config', {
+      models: { fast: 'anthropic/claude-haiku' },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', { model: 'fast' })
+    assert.strictEqual(result.model, 'anthropic/claude-haiku')
+  })
+
+  test('should resolve model alias with temperature and maxSteps', () => {
+    pikkuState(null, 'models', 'config', {
+      models: {
+        smart: {
+          model: 'anthropic/claude-opus',
+          temperature: 0.3,
+          maxSteps: 10,
+        },
+      },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', { model: 'smart' })
+    assert.strictEqual(result.model, 'anthropic/claude-opus')
+    assert.strictEqual(result.temperature, 0.3)
+    assert.strictEqual(result.maxSteps, 10)
+  })
+
+  test('should throw for unknown model alias', () => {
+    pikkuState(null, 'models', 'config', {
+      models: {},
+    } as any)
+
+    assert.throws(() => resolveModelConfig('testAgent', { model: 'unknown' }), {
+      message: "Unknown model alias 'unknown'.",
+    })
+  })
+
+  test('should pass through model with slash (not an alias)', () => {
+    pikkuState(null, 'models', 'config', {
+      models: {},
+    } as any)
+
+    const result = resolveModelConfig('testAgent', { model: 'openai/gpt-4' })
+    assert.strictEqual(result.model, 'openai/gpt-4')
+  })
+
+  test('should use agent override model', () => {
+    pikkuState(null, 'models', 'config', {
+      models: { fast: 'anthropic/haiku' },
+      agentOverrides: { testAgent: { model: 'fast' } },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', {
+      model: 'anthropic/default',
+    })
+    assert.strictEqual(result.model, 'anthropic/haiku')
+  })
+
+  test('should use agent override temperature over alias', () => {
+    pikkuState(null, 'models', 'config', {
+      models: { smart: { model: 'anthropic/opus', temperature: 0.5 } },
+      agentOverrides: { testAgent: { model: 'smart', temperature: 0.1 } },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', {
+      model: 'anthropic/default',
+    })
+    assert.strictEqual(result.temperature, 0.1)
+  })
+
+  test('should use agentDefaults as fallback', () => {
+    pikkuState(null, 'models', 'config', {
+      models: {},
+      agentDefaults: { temperature: 0.5, maxSteps: 20 },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', {
+      model: 'anthropic/claude-3',
+    })
+    assert.strictEqual(result.temperature, 0.5)
+    assert.strictEqual(result.maxSteps, 20)
+  })
+
+  test('should prioritize: override > alias > defaults > agent', () => {
+    pikkuState(null, 'models', 'config', {
+      models: { fast: { model: 'anthropic/haiku', temperature: 0.3 } },
+      agentDefaults: { temperature: 0.5 },
+      agentOverrides: { testAgent: { temperature: 0.1 } },
+    } as any)
+
+    const result = resolveModelConfig('testAgent', {
+      model: 'fast',
+      temperature: 0.9,
+    })
+    assert.strictEqual(result.temperature, 0.1)
+  })
+})

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

@@ -1,21 +1,21 @@
-import {
-  type CoreSingletonServices,
-  type CoreServices,
-  type CoreUserSession,
-  type CreateWireServices,
-  PikkuWire,
-} from '../../types/core.types.js'
+import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
 import type {
   CoreAIAgent,
   AIAgentInput,
   AIAgentToolDef,
+  AIContentPart,
   AIMessage,
   AIStreamChannel,
   AIStreamEvent,
+  PikkuAIMiddlewareHooks,
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import { pikkuState } from '../../pikku-state.js'
+import {
+  pikkuState,
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
@@ -29,13 +29,7 @@ import {
 import { resolveModelConfig } from './ai-agent-model-config.js'
 
 export type RunAIAgentParams = {
-  singletonServices: CoreSingletonServices
   sessionService?: SessionService<CoreUserSession>
-  createWireServices?: CreateWireServices<
-    CoreSingletonServices,
-    CoreServices<CoreSingletonServices>,
-    CoreUserSession
-  >
 }
 
 export type StreamAIAgentOptions = {
@@ -88,8 +82,8 @@ export const resolveAgent = (
   if (colonIndex !== -1) {
     const namespace = agentName.substring(0, colonIndex)
     const localName = agentName.substring(colonIndex + 1)
-    const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
-    const pkgConfig = externalPackages.get(namespace)
+    const addons = pikkuState(null, 'rpc', 'addons')
+    const pkgConfig = addons.get(namespace)
     if (pkgConfig) {
       const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(
         localName
@@ -151,6 +145,7 @@ export function createScopedChannel(
       return capturedApproval
     },
     close: () => {},
+    sendBinary: (data) => parent.sendBinary(data),
     send: (event: AIStreamEvent) => {
       if (event.type === 'done') return
       if (event.type === 'approval-request') {
@@ -163,6 +158,7 @@ export function createScopedChannel(
         return
       }
       if (
+        event.type === 'step-start' ||
         event.type === 'text-delta' ||
         event.type === 'reasoning-delta' ||
         event.type === 'tool-call' ||
@@ -179,14 +175,15 @@ export function createScopedChannel(
 }
 
 export function buildToolDefs(
-  singletonServices: CoreSingletonServices,
   params: RunAIAgentParams,
   agentSessionMap: Map<string, string>,
   resourceId: string,
   agentName: string,
   packageName: string | null,
-  streamContext?: StreamContext
+  streamContext?: StreamContext,
+  aiMiddlewares?: PikkuAIMiddlewareHooks[]
 ): { tools: AIAgentToolDef[]; missingRpcs: string[] } {
+  const singletonServices = getSingletonServices()
   const tools: AIAgentToolDef[] = []
   const missingRpcs: string[] = []
   const approvalPolicy =
@@ -228,39 +225,18 @@ export function buildToolDefs(
         approvalPolicy === 'all' ||
         (approvalPolicy === 'explicit' && fnMeta?.requiresApproval)
 
-      if (needsApproval) {
-        inputSchema = {
-          ...inputSchema,
-          properties: {
-            ...((inputSchema.properties as Record<string, unknown>) || {}),
-            toolApprovalReason: {
-              type: 'string',
-              description: 'Brief explanation of why this action is needed',
-            },
-          },
-        }
-      }
-
       tools.push({
         name: pikkuFuncId,
         description: fnMeta?.description || fnMeta?.title || toolName,
         inputSchema,
+        needsApproval: needsApproval || undefined,
         execute: async (toolInput: unknown) => {
-          if (needsApproval) {
-            const { toolApprovalReason, ...cleanArgs } = toolInput as any
-            return {
-              __approvalRequired: true,
-              toolName: pikkuFuncId,
-              args: cleanArgs,
-              reason: toolApprovalReason,
-            }
-          }
           const wire: PikkuWire = params.sessionService
             ? { ...createMiddlewareSessionWireProps(params.sessionService) }
             : {}
           return runPikkuFunc('agent', `tool:${pikkuFuncId}`, pikkuFuncId, {
             singletonServices,
-            createWireServices: params.createWireServices,
+            createWireServices: getCreateWireServices(),
             data: () => toolInput,
             wire,
             sessionService: params.sessionService,
@@ -362,6 +338,62 @@ export function buildToolDefs(
     }
   }
 
+  const hasToolHooks = aiMiddlewares?.some(
+    (mw) => mw.beforeToolCall || mw.afterToolCall
+  )
+  if (hasToolHooks) {
+    for (const tool of tools) {
+      const originalExecute = tool.execute
+      tool.execute = async (toolInput: unknown) => {
+        const toolCallId = randomUUID()
+        let args = (toolInput ?? {}) as Record<string, unknown>
+
+        for (const mw of aiMiddlewares!) {
+          if (mw.beforeToolCall) {
+            const beforeResult = await mw.beforeToolCall(singletonServices, {
+              toolName: tool.name,
+              toolCallId,
+              args,
+            })
+            if (beforeResult && 'args' in beforeResult) {
+              args = beforeResult.args
+            }
+          }
+        }
+
+        const startTime = Date.now()
+        let result: unknown
+        let execError: unknown
+        try {
+          result = await originalExecute(args)
+        } catch (err) {
+          execError = err
+          result = err instanceof Error ? err.message : String(err)
+        }
+        const durationMs = Date.now() - startTime
+
+        for (let i = aiMiddlewares!.length - 1; i >= 0; i--) {
+          const mw = aiMiddlewares![i]
+          if (mw.afterToolCall) {
+            const afterResult = await mw.afterToolCall(singletonServices, {
+              toolName: tool.name,
+              toolCallId,
+              args,
+              result,
+              durationMs,
+            })
+            if (afterResult && 'result' in afterResult) {
+              result = afterResult.result
+            }
+          }
+        }
+
+        if (execError) throw execError
+        return result
+      }
+    }
+  }
+
   return { tools, missingRpcs }
 }
 
@@ -372,7 +404,7 @@ export async function prepareAgentRun(
   agentSessionMap: Map<string, string>,
   streamContext?: StreamContext
 ) {
-  const { singletonServices } = params
+  const singletonServices = getSingletonServices()
   const { agent, packageName, resolvedName } = resolveAgent(agentName)
 
   const agentRunner = singletonServices.aiAgentRunner
@@ -418,29 +450,48 @@ export async function prepareAgentRun(
     workingMemoryJsonSchema
   )
 
+  const userContent: AIMessage['content'] = input.attachments?.length
+    ? [
+        { type: 'text' as const, text: input.message },
+        ...input.attachments.map(
+          (a) =>
+            ({
+              type: a.type,
+              data: a.data,
+              url: a.url,
+              mediaType: a.mediaType,
+              ...(a.filename ? { filename: a.filename } : {}),
+            }) as AIContentPart
+        ),
+      ]
+    : input.message
+
   const userMessage: AIMessage = {
     id: randomUUID(),
     role: 'user',
-    content: input.message,
+    content: userContent,
     createdAt: new Date(),
   }
 
   const allMessages = [...contextMessages, ...messages, userMessage]
   const trimmedMessages = trimMessages(allMessages)
 
+  const aiMiddlewares: PikkuAIMiddlewareHooks[] = agent.aiMiddleware ?? []
+
   const { tools, missingRpcs } = buildToolDefs(
-    singletonServices,
     params,
     agentSessionMap,
     input.resourceId,
     resolvedName,
     packageName,
-    streamContext
+    streamContext,
+    aiMiddlewares
   )
 
   const instructions = buildInstructions(resolvedName, packageName)
 
   const resolved = resolveModelConfig(resolvedName, agent)
+  const maxSteps = resolved.maxSteps ?? 10
 
   const runnerParams: AIAgentRunnerParams = {
     model: resolved.model,
@@ -448,7 +499,7 @@ export async function prepareAgentRun(
     instructions,
     messages: trimmedMessages,
     tools,
-    maxSteps: resolved.maxSteps ?? 10,
+    maxSteps: 1,
     toolChoice: agent.toolChoice ?? 'auto',
     outputSchema,
   }
@@ -463,6 +514,7 @@ export async function prepareAgentRun(
     threadId,
     userMessage,
     runnerParams,
+    maxSteps,
     missingRpcs,
     workingMemoryJsonSchema,
     workingMemorySchemaName,

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

@@ -1,6 +1,6 @@
 import type { CoreAIAgent, AgentRunState } from './ai-agent.types.js'
 import { pikkuState } from '../../pikku-state.js'
-import { AIRunStateService } from '../../services/ai-run-state-service.js'
+import type { AIRunStateService } from '../../services/ai-run-state-service.js'
 import { PikkuMissingMetaError } from '../../errors/errors.js'
 
 export const addAIAgent = (