@pikku/core 0.12.0 → 0.12.2

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

@@ -1,8 +1,8 @@
-import {
+import type {
   CorePermissionGroup,
   CorePikkuPermission,
 } from '../../function/functions.types.js'
-import {
+import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -19,6 +19,17 @@ export interface AIThread {
   updatedAt: Date
 }
 
+export type AIContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data?: string; url?: string; mediaType?: string }
+  | {
+      type: 'file'
+      data?: string
+      url?: string
+      mediaType: string
+      filename?: string
+    }
+
 export interface AIToolCall {
   id: string
   name: string
@@ -34,7 +45,7 @@ export interface AIToolResult {
 export interface AIMessage {
   id: string
   role: 'system' | 'user' | 'assistant' | 'tool'
-  content?: string
+  content?: string | AIContentPart[]
   toolCalls?: AIToolCall[]
   toolResults?: AIToolResult[]
   createdAt: Date
@@ -45,10 +56,19 @@ export interface AIAgentStep {
   toolCalls?: { name: string; args: Record<string, unknown>; result: string }[]
 }
 
+export interface AIAgentInputAttachment {
+  type: 'image' | 'file'
+  data?: string
+  url?: string
+  mediaType?: string
+  filename?: string
+}
+
 export interface AIAgentInput {
   message: string
   threadId: string
   resourceId: string
+  attachments?: AIAgentInputAttachment[]
 }
 
 export interface AIAgentOutput {
@@ -65,6 +85,7 @@ export interface AIAgentToolDef {
   description: string
   inputSchema: Record<string, unknown>
   execute: (input: unknown) => Promise<unknown>
+  needsApproval?: boolean
 }
 
 export interface PikkuAIMiddlewareHooks<
@@ -85,7 +106,11 @@ export interface PikkuAIMiddlewareHooks<
       allEvents: readonly AIStreamEvent[]
       state: State
     }
-  ) => Promise<AIStreamEvent | null> | AIStreamEvent | null
+  ) =>
+    | Promise<AIStreamEvent | AIStreamEvent[] | null>
+    | AIStreamEvent
+    | AIStreamEvent[]
+    | null
 
   modifyOutput?: (
     services: Services,
@@ -97,6 +122,50 @@ export interface PikkuAIMiddlewareHooks<
   ) =>
     | Promise<{ text: string; messages: AIMessage[] }>
     | { text: string; messages: AIMessage[] }
+
+  beforeToolCall?: (
+    services: Services,
+    ctx: {
+      toolName: string
+      toolCallId: string
+      args: Record<string, unknown>
+    }
+  ) =>
+    | Promise<{ args: Record<string, unknown> } | void>
+    | { args: Record<string, unknown> }
+    | void
+
+  afterToolCall?: (
+    services: Services,
+    ctx: {
+      toolName: string
+      toolCallId: string
+      args: Record<string, unknown>
+      result: unknown
+      durationMs: number
+    }
+  ) => Promise<{ result: unknown } | void> | { result: unknown } | void
+
+  afterStep?: (
+    services: Services,
+    ctx: {
+      stepNumber: number
+      text: string
+      toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
+      toolResults: { toolCallId: string; toolName: string; result: unknown }[]
+      usage: { inputTokens: number; outputTokens: number }
+      finishReason: string
+    }
+  ) => Promise<void> | void
+
+  onError?: (
+    services: Services,
+    ctx: {
+      error: Error
+      stepNumber: number
+      messages: AIMessage[]
+    }
+  ) => Promise<void> | void
 }
 
 export type AIAgentMemoryConfig = {
@@ -126,6 +195,15 @@ export type CoreAIAgent<
   input?: unknown
   output?: unknown
   tags?: string[]
+  protocol?: 'ui-message-stream'
+  prepareStep?: (ctx: {
+    stepNumber: number
+    messages: AIMessage[]
+    tools: AIAgentToolDef[]
+    toolChoice: 'auto' | 'required' | 'none'
+    model: string
+    stop: () => void
+  }) => void | Promise<void>
   middleware?: PikkuMiddleware[]
   channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
   aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[]
@@ -133,6 +211,7 @@ export type CoreAIAgent<
 }
 
 export type AIStreamEvent =
+  | { type: 'step-start'; stepNumber: number; agent?: string; session?: string }
   | { type: 'text-delta'; text: string; agent?: string; session?: string }
   | { type: 'reasoning-delta'; text: string; agent?: string; session?: string }
   | {
@@ -180,6 +259,14 @@ export type AIStreamEvent =
       session?: string
     }
   | { type: 'error'; message: string; agent?: string; session?: string }
+  | {
+      type: 'audio-delta'
+      data: string
+      format: string
+      agent?: string
+      session?: string
+    }
+  | { type: 'audio-done'; agent?: string; session?: string }
   | {
       type: 'suspended'
       reason: 'rpc-missing'

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

@@ -1,5 +1,15 @@
+export {
+  agent,
+  agentStream,
+  agentResume,
+  agentApprove,
+} from './ai-agent-helpers.js'
 export { runAIAgent } from './ai-agent-runner.js'
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js'
+export {
+  createAssistantUIChannel,
+  parseAssistantUIInput,
+} from './ai-agent-assistant-ui.js'
 export {
   type RunAIAgentParams,
   type StreamAIAgentOptions,
@@ -12,9 +22,12 @@ export {
   getAIAgentsMeta,
 } from './ai-agent-registry.js'
 export type {
+  AIAgentInput,
+  AIAgentInputAttachment,
   AIAgentMeta,
   AIAgentMemoryConfig,
   AIAgentStep,
+  AIContentPart,
   AgentRunRow,
   AgentRunService,
   AgentRunState,

package/src/wirings/channel/channel-common.ts

@@ -1,10 +1,10 @@
-import {
+import type {
   CoreSingletonServices,
   CorePikkuMiddleware,
   PikkuWire,
   MiddlewareMetadata,
 } from '../../types/core.types.js'
-import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
+import type { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { runPikkuFuncDirectly } from '../../function/function-runner.js'
 import {

package/src/wirings/channel/channel-handler.ts

@@ -1,19 +1,18 @@
-import {
+import type {
   CoreServices,
   JSONValue,
   CoreUserSession,
 } from '../../types/core.types.js'
-import {
+import type {
+  BinaryData,
   ChannelMessageMeta,
   CoreChannel,
   PikkuChannelHandler,
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
-import {
-  SessionService,
-  createMiddlewareSessionWireProps,
-} from '../../services/user-session-service.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 
 const getChannelMeta = (channelName: string) => {
   return pikkuState(null, 'channel', 'meta')[channelName]
@@ -81,7 +80,13 @@ export const processMessageHandlers = (
     routingProperty?: string,
     routerValue?: string
   ): Promise<unknown> => {
-    if (!validateAuth(requiresSession, channelHandler, onMessage)) {
+    if (
+      !validateAuth(
+        requiresSession,
+        userSession?.get() as CoreUserSession | undefined,
+        onMessage
+      )
+    ) {
       const routeMessage = routingProperty
         ? `route '${routingProperty}:${routerValue}'`
         : 'the default message route'
@@ -150,7 +155,7 @@ export const processMessageHandlers = (
     })
   }
 
-  return async (rawData): Promise<unknown> => {
+  const onMessage = async (rawData: unknown): Promise<unknown> => {
     let result: unknown
     let processed = false
 
@@ -159,7 +164,7 @@ export const processMessageHandlers = (
       let messageData: any
       try {
         messageData = JSON.parse(rawData)
-      } catch (error) {
+      } catch {
         // Most likely a json error.. ignore
       }
 
@@ -194,16 +199,43 @@ export const processMessageHandlers = (
     // Default handler if no routes matched and json data wasn't parsed
     if (!processed && channelConfig.onMessage) {
       processed = true
-      result = await processMessage(rawData, channelConfig.onMessage)
+      result = await processMessage(
+        rawData as JSONValue,
+        channelConfig.onMessage
+      )
     }
 
     if (!processed) {
       logger.error(
         `No handler found for message in channel ${channelConfig.name} for ${JSON.stringify(rawData)}`
       )
-      logger.error(`Channel ${JSON.stringify(channelConfig)}`)
+      logger.error(`Channel config name: ${channelConfig.name}`)
     }
 
     return result
   }
+
+  const onBinaryMessage = channelConfig.onBinaryMessage
+    ? async (data: BinaryData): Promise<BinaryData | void> => {
+        if (
+          !validateAuth(
+            requiresSession,
+            userSession?.get() as CoreUserSession | undefined,
+            channelConfig
+          )
+        ) {
+          logger.error(
+            `Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for binary message`
+          )
+          return
+        }
+        return channelConfig.onBinaryMessage!(
+          services,
+          data,
+          channelHandler.getChannel()
+        )
+      }
+    : undefined
+
+  return { onMessage, onBinaryMessage }
 }

package/src/wirings/channel/channel-middleware-runner.ts

@@ -114,6 +114,7 @@ export function wrapChannelWithMiddleware<Out>(
     channel: {
       ...channel,
       send: ((data: Out) => dispatch(0, data)) as typeof channel.send,
+      sendBinary: channel.sendBinary,
     },
   }
 }

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

@@ -1,12 +1,12 @@
 import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
 import { addFunction } from '../../function/function-runner.js'
-import { CorePikkuPermission } from '../../function/functions.types.js'
-import { pikkuState } from '../../pikku-state.js'
+import type { CorePikkuPermission } from '../../function/functions.types.js'
+import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import { SessionService } from '../../services/user-session-service.js'
-import { CorePikkuMiddleware } from '../../types/core.types.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
-import {
+import type {
   ChannelMeta,
   CoreChannel,
   RunChannelOptions,
@@ -122,7 +122,6 @@ const getMatchingChannelConfig = (path: string) => {
 
 export const openChannel = async ({
   route,
-  singletonServices,
   coerceDataFromSchema = true,
   request,
 }: Pick<CoreChannel<unknown, string>, 'route'> &
@@ -133,6 +132,7 @@ export const openChannel = async ({
   channelConfig: CoreChannel<unknown, any>
   meta: ChannelMeta
 }> => {
+  const singletonServices = getSingletonServices()
   const matchingChannel = getMatchingChannelConfig(route)
   if (!matchingChannel) {
     singletonServices.logger.info(`Channel not found: ${route}`)

package/src/wirings/channel/channel-store.ts

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../../types/core.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
 
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
   channelId: string

package/src/wirings/channel/channel.types.ts

@@ -1,17 +1,17 @@
-import { PikkuError } from '../../errors/error-handler.js'
-import {
+import type { PikkuError } from '../../errors/error-handler.js'
+import type {
   HTTPFunctionMetaInputTypes,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
 } from '../http/http.types.js'
-import {
-  CoreSingletonServices,
-  CreateWireServices,
+import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
 } from '../../types/core.types.js'
 
+export type BinaryData = ArrayBuffer | Uint8Array
+
 export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (
   services: Services,
   event: Event,
@@ -23,7 +23,7 @@ export type CorePikkuChannelMiddlewareFactory<
   Services = any,
   Event = unknown,
 > = (input: In) => CorePikkuChannelMiddleware<Services, Event>
-import {
+import type {
   CorePermissionGroup,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
@@ -41,10 +41,8 @@ export type RunChannelOptions = Partial<{
 
 export type RunChannelParams<ChannelData> = {
   channelId: string
-  singletonServices: CoreSingletonServices
   request?: PikkuHTTPRequest<ChannelData>
   response?: PikkuHTTPResponse
-  createWireServices?: CreateWireServices
 }
 
 export interface ChannelMessageMeta {
@@ -68,6 +66,7 @@ export interface ChannelMeta {
   disconnect: ChannelMessageMeta | null
   message: ChannelMessageMeta | null
   messageWirings: Record<string, Record<string, ChannelMessageMeta>>
+  binary?: boolean | null
   summary?: string
   description?: string
   errors?: string[]
@@ -136,6 +135,12 @@ export type CoreChannel<
   >
   permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
+  binary?: boolean | null
+  onBinaryMessage?: (
+    services: any,
+    data: BinaryData,
+    channel: PikkuChannel<ChannelData, any>
+  ) => Promise<BinaryData | void> | BinaryData | void
   docs?: Partial<{
     description: string
     response: string
@@ -153,6 +158,7 @@ export interface PikkuChannel<OpeningData, out Out> {
   openingData: OpeningData
   // The data to send. This will fail is the stream has been closed.
   send(data: Out, isBinary?: boolean): Promise<void> | void
+  sendBinary(data: BinaryData): Promise<void> | void
   // This will close the channel.
   close(): Promise<void> | void
   // The current state of the channel
@@ -161,6 +167,7 @@ export interface PikkuChannel<OpeningData, out Out> {
 
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
   send(message: Out, isBinary?: boolean): Promise<void> | void
+  sendBinary(data: BinaryData): Promise<void> | void
   getChannel(): PikkuChannel<OpeningData, Out>
 }
 

package/src/wirings/channel/index.ts

@@ -11,6 +11,7 @@ export { ChannelStore } from './channel-store.js'
 export type { Channel } from './channel-store.js'
 export { EventHubStore } from './eventhub-store.js'
 export type {
+  BinaryData,
   ChannelsMeta,
   CoreChannel,
   CorePikkuChannelMiddleware,

package/src/wirings/channel/local/local-channel-handler.ts

@@ -1,3 +1,4 @@
+import type { BinaryData } from '../channel.types.js'
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js'
 
 export class PikkuLocalChannelHandler<
@@ -5,9 +6,11 @@ export class PikkuLocalChannelHandler<
   Out = unknown,
 > extends PikkuAbstractChannelHandler<OpeningData, Out> {
   private onMessageCallback?: (message: unknown) => void
+  private onBinaryMessageCallback?: (data: BinaryData) => void
   private openCallBack?: () => void
   private closeCallback?: () => void
   private sendCallback?: (message: Out, isBinary?: boolean) => void
+  private sendBinaryCallback?: (data: BinaryData) => void
 
   public registerOnOpen(callback: () => void): void {
     this.openCallBack = callback
@@ -28,6 +31,18 @@ export class PikkuLocalChannelHandler<
     return this.onMessageCallback?.(data)
   }
 
+  public registerOnBinaryMessage(
+    callback: (
+      data: BinaryData
+    ) => Promise<BinaryData | void> | BinaryData | void
+  ): void {
+    this.onBinaryMessageCallback = callback
+  }
+
+  public async binaryMessage(data: BinaryData): Promise<BinaryData | void> {
+    return this.onBinaryMessageCallback?.(data)
+  }
+
   public registerOnClose(callback: () => void): void {
     this.closeCallback = callback
   }
@@ -50,4 +65,15 @@ export class PikkuLocalChannelHandler<
     }
     return this.sendCallback?.(message, isBinary)
   }
+
+  public registerOnSendBinary(send: (data: BinaryData) => void) {
+    this.sendBinaryCallback = send
+  }
+
+  public sendBinary(data: BinaryData): void {
+    if (!this.sendBinaryCallback) {
+      throw new Error('No sendBinary callback registered')
+    }
+    this.sendBinaryCallback(data)
+  }
 }

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -3,13 +3,13 @@ import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
 import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
 import { wireChannel } from '../channel-runner.js'
-import {
+import type {
   HTTPMethod,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
   PikkuQuery,
 } from '../../http/http.types.js'
-import { SerializeOptions } from 'cookie'
+import type { SerializeOptions } from 'cookie'
 import { httpRouter } from '../../http/routers/http-router.js'
 
 /**
@@ -102,6 +102,10 @@ const mockCreateWireServices = async () => ({
 beforeEach(() => {
   resetPikkuState()
   httpRouter.reset()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 })
 
 afterEach(() => {
@@ -113,11 +117,9 @@ test('runChannel should return undefined and 404 if no matching channel is found
   const mockResponse = new PikkuMockResponse()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/non-existent-channel', 'get'),
     response: mockResponse,
-    createWireServices: mockCreateWireServices,
   })
 
   assert.equal(
@@ -131,6 +133,10 @@ test('runChannel should return undefined and 404 if no matching channel is found
 
 test('runChannel should return a channel handler if channel matches and no auth required', async () => {
   resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 
   pikkuState(null, 'channel', 'meta', {
     test: {
@@ -148,12 +154,10 @@ test('runChannel should return a channel handler if channel matches and no auth
   httpRouter.initialize()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/test-channel', 'get'),
     response: new PikkuMockResponse(),
     route: '/test-channel',
-    createWireServices: mockCreateWireServices,
   })
 
   assert.ok(result, 'Should return a PikkuChannelHandler instance')
@@ -164,6 +168,7 @@ test('runChannel should return a channel handler if channel matches and no auth
 
 test('runChannel should close wire services once when channel closes', async () => {
   resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
   let closeCount = 0
 
   pikkuState(null, 'channel', 'meta', {
@@ -180,12 +185,7 @@ test('runChannel should close wire services once when channel closes', async ()
 
   httpRouter.initialize()
 
-  const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
-    channelId: 'test-channel-id',
-    request: new PikkuMockRequest('/test-channel', 'get'),
-    response: new PikkuMockResponse(),
-    route: '/test-channel',
+  pikkuState(null, 'package', 'factories', {
     createWireServices: async () => ({
       tracked: {
         close: async () => {
@@ -193,6 +193,13 @@ test('runChannel should close wire services once when channel closes', async ()
         },
       },
     }),
+  } as any)
+
+  const result = await runLocalChannel({
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/test-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/test-channel',
   })
 
   assert.ok(result)

package/src/wirings/channel/local/local-channel-runner.ts

@@ -2,36 +2,43 @@ import { openChannel } from '../channel-runner.js'
 import { createHTTPWire } from '../../http/http-runner.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
-import {
-  CoreChannel,
-  RunChannelOptions,
-  RunChannelParams,
-} from '../channel.types.js'
+import type { CoreChannel, RunChannelOptions } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../../services/user-session-service.js'
-import { PikkuHTTP } from '../../http/http.types.js'
+import type {
+  PikkuHTTP,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+} from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../../pikku-state.js'
 
 export const runLocalChannel = async ({
-  singletonServices,
   channelId,
   request,
   response,
   route,
-  createWireServices,
   skipUserSession = false,
   respondWith404 = true,
   coerceDataFromSchema = true,
   logWarningsForStatusCodes = [],
   bubbleErrors = false,
 }: Partial<Pick<CoreChannel<unknown, any>, 'route'>> &
-  RunChannelOptions &
-  RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
+  RunChannelOptions & {
+    channelId: string
+    request?: PikkuHTTPRequest
+    response?: PikkuHTTPResponse
+  }): Promise<PikkuLocalChannelHandler | void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices<typeof singletonServices> | undefined
   let closedWireServices = false
 
@@ -48,12 +55,10 @@ export const runLocalChannel = async ({
   try {
     ;({ openingData, channelConfig, meta } = await openChannel({
       channelId,
-      createWireServices,
       respondWith404,
       request,
       response,
       route,
-      singletonServices,
       skipUserSession,
       coerceDataFromSchema,
       userSession,
@@ -142,7 +147,7 @@ export const runLocalChannel = async ({
         await closeServices()
       })
 
-      const onMessage = processMessageHandlers(
+      const { onMessage, onBinaryMessage } = processMessageHandlers(
         services,
         channelConfig as any,
         channelHandler,
@@ -157,6 +162,20 @@ export const runLocalChannel = async ({
           channel.send({ error: e.message || 'Unknown error' })
         }
       })
+      if (onBinaryMessage) {
+        channelHandler.registerOnBinaryMessage(async (data) => {
+          try {
+            const result = await onBinaryMessage(data)
+            if (result) {
+              await channel.sendBinary(result)
+            }
+          } catch (e) {
+            singletonServices.logger.error(
+              `Error handling binary message: ${e.message}`
+            )
+          }
+        })
+      }
     } catch (e: any) {
       handleHTTPError(
         e,