@pikku/core 0.11.1 → 0.12.0

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

@@ -0,0 +1,273 @@
+import {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from '../../function/functions.types.js'
+import {
+  CorePikkuMiddleware,
+  MiddlewareMetadata,
+  PermissionMetadata,
+} from '../../types/core.types.js'
+import type { PikkuChannel } from '../channel/channel.types.js'
+import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js'
+
+export interface AIThread {
+  id: string
+  resourceId: string
+  title?: string
+  metadata?: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface AIToolCall {
+  id: string
+  name: string
+  args: Record<string, unknown>
+}
+
+export interface AIToolResult {
+  id: string
+  name: string
+  result: string
+}
+
+export interface AIMessage {
+  id: string
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content?: string
+  toolCalls?: AIToolCall[]
+  toolResults?: AIToolResult[]
+  createdAt: Date
+}
+
+export interface AIAgentStep {
+  usage: { inputTokens: number; outputTokens: number }
+  toolCalls?: { name: string; args: Record<string, unknown>; result: string }[]
+}
+
+export interface AIAgentInput {
+  message: string
+  threadId: string
+  resourceId: string
+}
+
+export interface AIAgentOutput {
+  runId: string
+  text: string
+  object?: unknown
+  threadId: string
+  steps: AIAgentStep[]
+  usage: { inputTokens: number; outputTokens: number }
+}
+
+export interface AIAgentToolDef {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  execute: (input: unknown) => Promise<unknown>
+}
+
+export interface PikkuAIMiddlewareHooks<
+  State extends Record<string, unknown> = Record<string, unknown>,
+  Services = any,
+> {
+  modifyInput?: (
+    services: Services,
+    ctx: { messages: AIMessage[]; instructions: string }
+  ) =>
+    | Promise<{ messages: AIMessage[]; instructions: string }>
+    | { messages: AIMessage[]; instructions: string }
+
+  modifyOutputStream?: (
+    services: Services,
+    ctx: {
+      event: AIStreamEvent
+      allEvents: readonly AIStreamEvent[]
+      state: State
+    }
+  ) => Promise<AIStreamEvent | null> | AIStreamEvent | null
+
+  modifyOutput?: (
+    services: Services,
+    ctx: {
+      text: string
+      messages: AIMessage[]
+      usage: { inputTokens: number; outputTokens: number }
+    }
+  ) =>
+    | Promise<{ text: string; messages: AIMessage[] }>
+    | { text: string; messages: AIMessage[] }
+}
+
+export type AIAgentMemoryConfig = {
+  storage?: string
+  vector?: string
+  embedder?: string
+  lastMessages?: number
+  workingMemory?: unknown
+}
+
+export type CoreAIAgent<
+  PikkuPermission = CorePikkuPermission<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
+> = {
+  name: string
+  description: string
+  summary?: string
+  errors?: string[]
+  instructions: string | string[]
+  model: string
+  temperature?: number
+  tools?: unknown[]
+  agents?: unknown[]
+  memory?: AIAgentMemoryConfig
+  maxSteps?: number
+  toolChoice?: 'auto' | 'required' | 'none'
+  input?: unknown
+  output?: unknown
+  tags?: string[]
+  middleware?: PikkuMiddleware[]
+  channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
+  aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+export type AIStreamEvent =
+  | { type: 'text-delta'; text: string; agent?: string; session?: string }
+  | { type: 'reasoning-delta'; text: string; agent?: string; session?: string }
+  | {
+      type: 'tool-call'
+      toolCallId: string
+      toolName: string
+      args: unknown
+      agent?: string
+      session?: string
+    }
+  | {
+      type: 'tool-result'
+      toolCallId: string
+      toolName: string
+      result: unknown
+      agent?: string
+      session?: string
+    }
+  | {
+      type: 'agent-call'
+      agentName: string
+      session: string
+      input: unknown
+    }
+  | {
+      type: 'agent-result'
+      agentName: string
+      session: string
+      result: unknown
+    }
+  | {
+      type: 'approval-request'
+      toolCallId: string
+      toolName: string
+      args: unknown
+      reason?: string
+      agent?: string
+      session?: string
+    }
+  | {
+      type: 'usage'
+      tokens: { input: number; output: number }
+      model: string
+      agent?: string
+      session?: string
+    }
+  | { type: 'error'; message: string; agent?: string; session?: string }
+  | {
+      type: 'suspended'
+      reason: 'rpc-missing'
+      missingRpcs: string[]
+    }
+  | { type: 'done' }
+
+export interface AIStreamChannel extends PikkuChannel<unknown, AIStreamEvent> {}
+
+export type PendingApproval =
+  | {
+      type: 'tool-call'
+      toolCallId: string
+      toolName: string
+      args: unknown
+    }
+  | {
+      type: 'agent-call'
+      toolCallId: string
+      agentName: string
+      agentRunId: string
+      displayToolName: string
+      displayArgs: unknown
+    }
+
+export interface AgentRunState {
+  runId: string
+  agentName: string
+  threadId: string
+  resourceId: string
+  status: 'running' | 'suspended' | 'completed' | 'failed'
+  suspendReason?: 'approval' | 'rpc-missing'
+  missingRpcs?: string[]
+  pendingApprovals?: PendingApproval[]
+  usage: { inputTokens: number; outputTokens: number; model: string }
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface AgentRunRow {
+  runId: string
+  agentName: string
+  threadId: string
+  resourceId: string
+  status: string
+  suspendReason?: string
+  missingRpcs?: string[]
+  usageInputTokens: number
+  usageOutputTokens: number
+  usageModel: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface AgentRunService {
+  listThreads(options?: {
+    agentName?: string
+    limit?: number
+    offset?: number
+  }): Promise<AIThread[]>
+  getThread(threadId: string): Promise<AIThread | null>
+  getThreadMessages(threadId: string): Promise<AIMessage[]>
+  getThreadRuns(threadId: string): Promise<AgentRunRow[]>
+  deleteThread(threadId: string): Promise<boolean>
+  getDistinctAgentNames(): Promise<string[]>
+}
+
+export type AIAgentMeta = Record<
+  string,
+  Omit<
+    CoreAIAgent,
+    | 'input'
+    | 'output'
+    | 'tools'
+    | 'agents'
+    | 'middleware'
+    | 'channelMiddleware'
+    | 'aiMiddleware'
+    | 'permissions'
+  > & {
+    tools?: string[]
+    agents?: string[]
+    inputSchema: string | null
+    outputSchema: string | null
+    workingMemorySchema: string | null
+    middleware?: MiddlewareMetadata[]
+    channelMiddleware?: MiddlewareMetadata[]
+    aiMiddleware?: MiddlewareMetadata[]
+    permissions?: PermissionMetadata[]
+  }
+>

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

@@ -0,0 +1,28 @@
+export { runAIAgent } from './ai-agent-runner.js'
+export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js'
+export {
+  type RunAIAgentParams,
+  type StreamAIAgentOptions,
+  ToolApprovalRequired,
+} from './ai-agent-prepare.js'
+export {
+  addAIAgent,
+  approveAIAgent,
+  getAIAgents,
+  getAIAgentsMeta,
+} from './ai-agent-registry.js'
+export type {
+  AIAgentMeta,
+  AIAgentMemoryConfig,
+  AIAgentStep,
+  AgentRunRow,
+  AgentRunService,
+  AgentRunState,
+  AIMessage,
+  AIStreamChannel,
+  AIStreamEvent,
+  AIThread,
+  CoreAIAgent,
+  PendingApproval,
+  PikkuAIMiddlewareHooks,
+} from './ai-agent.types.js'

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

@@ -1,7 +1,16 @@
-import { CoreServices, CorePikkuMiddleware } from '../../types/core.types.js'
+import {
+  CoreSingletonServices,
+  CorePikkuMiddleware,
+  PikkuWire,
+  MiddlewareMetadata,
+} from '../../types/core.types.js'
 import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { runPikkuFuncDirectly } from '../../function/function-runner.js'
+import {
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from './channel-middleware-runner.js'
 
 /**
  * Runs a channel lifecycle function (onConnect or onDisconnect) with proper middleware handling.
@@ -9,7 +18,8 @@ import { runPikkuFuncDirectly } from '../../function/function-runner.js'
  * This function:
  * 1. Extracts inline middleware from the lifecycle config if present
  * 2. Combines metadata middleware with inline middleware using combineMiddleware()
- * 3. Runs the lifecycle function with middleware support
+ * 3. Wraps the channel with channel middleware if present
+ * 4. Runs the lifecycle function with middleware support
  *
  * @param channelConfig - The channel configuration
  * @param meta - Metadata for the lifecycle function (connect or disconnect)
@@ -18,6 +28,7 @@ import { runPikkuFuncDirectly } from '../../function/function-runner.js'
  * @param services - All services (singleton + session)
  * @param channel - The channel instance
  * @param data - Optional data to pass to the lifecycle function (for onConnect)
+ * @param channelMiddlewareMeta - Optional channel middleware metadata for wrapping channel.send()
  * @returns Promise<unknown> - Result from the lifecycle function (if any)
  */
 export const runChannelLifecycleWithMiddleware = async ({
@@ -28,22 +39,22 @@ export const runChannelLifecycleWithMiddleware = async ({
   services,
   channel,
   data,
+  channelMiddlewareMeta,
 }: {
   channelConfig: CoreChannel<unknown, any>
   meta: ChannelMessageMeta
   lifecycleConfig: any
   lifecycleType: 'connect' | 'disconnect'
-  services: CoreServices
+  services: CoreSingletonServices
   channel: any
   data?: unknown
+  channelMiddlewareMeta?: MiddlewareMetadata[]
 }): Promise<unknown> => {
-  // Extract middleware if lifecycle config is an object
   const lifecycleMiddleware =
     typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
       ? (lifecycleConfig.middleware as CorePikkuMiddleware[]) || []
       : []
 
-  // Use combineMiddleware to properly resolve metadata + inline middleware
   const allMiddleware = combineMiddleware(
     'channel',
     `${channelConfig.name}:${lifecycleType}`,
@@ -53,24 +64,26 @@ export const runChannelLifecycleWithMiddleware = async ({
     }
   )
 
-  // Run the lifecycle function
+  const allChannelMiddleware = combineChannelMiddleware(
+    'channel',
+    `${channelConfig.name}:${lifecycleType}:cm`,
+    {
+      wireInheritedChannelMiddleware: channelMiddlewareMeta,
+      wireChannelMiddleware: channelConfig.channelMiddleware as any,
+    }
+  )
+
+  let wire: PikkuWire = { channel }
+  if (allChannelMiddleware.length > 0) {
+    wire = wrapChannelWithMiddleware(wire, services, allChannelMiddleware)
+  }
+
   const runLifecycle = async () => {
-    return await runPikkuFuncDirectly(
-      meta.pikkuFuncName,
-      services,
-      { channel },
-      data
-    )
+    return await runPikkuFuncDirectly(meta.pikkuFuncId, services, wire, data)
   }
 
-  // Run with middleware if any
   if (allMiddleware.length > 0) {
-    return await runMiddleware(
-      services,
-      { channel },
-      allMiddleware,
-      runLifecycle
-    )
+    return await runMiddleware(services, wire, allMiddleware, runLifecycle)
   } else {
     return await runLifecycle()
   }

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

@@ -10,14 +10,21 @@ import {
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
-import { SessionService } from '../../services/user-session-service.js'
+import {
+  SessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
+
+const getChannelMeta = (channelName: string) => {
+  return pikkuState(null, 'channel', 'meta')[channelName]
+}
 
 const getRouteMeta = (
   channelName: string,
   routingProperty?: string,
   routerValue?: string
 ): ChannelMessageMeta => {
-  const channelMeta = pikkuState('channel', 'meta')[channelName]
+  const channelMeta = pikkuState(null, 'channel', 'meta')[channelName]
   if (!channelMeta) {
     throw new Error(`Channel ${channelName} not found`)
   }
@@ -87,7 +94,7 @@ export const processMessageHandlers = (
     }
 
     const {
-      pikkuFuncName,
+      pikkuFuncId,
       middleware: routeInheritedMiddleware,
       permissions: inheritedPermissions,
     } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
@@ -122,17 +129,23 @@ export const processMessageHandlers = (
       ? `${channelConfig.name}:${routingProperty}:${routerValue}`
       : `${channelConfig.name}:default`
 
-    return await runPikkuFunc('channel', cacheKey, pikkuFuncName, {
+    const channelMeta = getChannelMeta(channelConfig.name)
+    const wireChannelMiddleware = channelConfig.channelMiddleware || []
+
+    return await runPikkuFunc('channel', cacheKey, pikkuFuncId, {
       singletonServices: services,
       data: () => data,
       inheritedMiddleware,
       wireMiddleware,
+      inheritedChannelMiddleware: channelMeta?.channelMiddleware,
+      wireChannelMiddleware: wireChannelMiddleware as any,
       inheritedPermissions,
       wirePermissions,
       tags: channelConfig.tags,
+      sessionService: userSession,
       wire: {
         channel: channelHandler.getChannel(),
-        session: userSession,
+        ...(userSession && createMiddlewareSessionWireProps(userSession)),
       },
     })
   }

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

@@ -0,0 +1,119 @@
+import type {
+  CoreSingletonServices,
+  MiddlewareMetadata,
+  PikkuWire,
+} from '../../types/core.types.js'
+import type { CorePikkuChannelMiddleware } from './channel.types.js'
+import { pikkuState } from '../../pikku-state.js'
+import { freezeDedupe, getTagGroups } from '../../utils.js'
+
+export const addChannelMiddleware = (
+  tag: string,
+  middleware: CorePikkuChannelMiddleware[],
+  packageName: string | null = null
+): CorePikkuChannelMiddleware[] => {
+  const tagGroups = pikkuState(packageName, 'channelMiddleware', 'tagGroup')
+  tagGroups[tag] = middleware
+  return middleware
+}
+
+const getChannelMiddlewareByName = (
+  name: string
+): CorePikkuChannelMiddleware | undefined => {
+  const store = pikkuState(null, 'misc', 'channelMiddleware')
+  const middleware = store[name]
+  return middleware?.[0]
+}
+
+const channelMiddlewareCache: Record<
+  string,
+  readonly CorePikkuChannelMiddleware[]
+> = {}
+
+export const combineChannelMiddleware = (
+  wireType: string,
+  uid: string,
+  {
+    wireInheritedChannelMiddleware,
+    wireChannelMiddleware,
+    packageName = null,
+  }: {
+    wireInheritedChannelMiddleware?: MiddlewareMetadata[]
+    wireChannelMiddleware?: CorePikkuChannelMiddleware[]
+    packageName?: string | null
+  } = {}
+): readonly CorePikkuChannelMiddleware[] => {
+  const cacheKey = `${wireType}:${uid}`
+  if (channelMiddlewareCache[cacheKey]) {
+    return channelMiddlewareCache[cacheKey]
+  }
+
+  const resolved: CorePikkuChannelMiddleware[] = []
+
+  if (wireInheritedChannelMiddleware) {
+    for (const meta of wireInheritedChannelMiddleware) {
+      if (meta.type === 'tag') {
+        const groups = getTagGroups(
+          pikkuState(packageName, 'channelMiddleware', 'tagGroup'),
+          meta.tag
+        )
+        for (const group of groups) {
+          resolved.push(...group)
+        }
+      } else if (meta.type === 'wire') {
+        const middleware = getChannelMiddlewareByName(meta.name)
+        if (middleware) {
+          resolved.push(middleware)
+        }
+      }
+    }
+  }
+
+  if (wireChannelMiddleware) {
+    resolved.push(...wireChannelMiddleware)
+  }
+
+  channelMiddlewareCache[cacheKey] = freezeDedupe(
+    resolved
+  ) as readonly CorePikkuChannelMiddleware[]
+
+  return channelMiddlewareCache[cacheKey]
+}
+
+export function wrapChannelWithMiddleware<Out>(
+  wire: PikkuWire,
+  services: CoreSingletonServices,
+  middlewares: readonly CorePikkuChannelMiddleware[]
+): PikkuWire {
+  if (middlewares.length === 0 || !wire.channel) return wire
+
+  const channel = wire.channel
+  const originalSend = channel.send.bind(channel)
+
+  const dispatch = async (index: number, event: Out): Promise<void> => {
+    if (index >= middlewares.length) {
+      await originalSend(event)
+      return
+    }
+
+    const middleware = middlewares[index]!
+    await middleware(services, event, async (result: any) => {
+      if (result === null || result === undefined) return
+      if (Array.isArray(result)) {
+        for (const item of result) {
+          await dispatch(index + 1, item)
+        }
+      } else {
+        await dispatch(index + 1, result)
+      }
+    })
+  }
+
+  return {
+    ...wire,
+    channel: {
+      ...channel,
+      send: ((data: Out) => dispatch(0, data)) as typeof channel.send,
+    },
+  }
+}

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

@@ -1,4 +1,4 @@
-import { NotFoundError } from '../../errors/errors.js'
+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'
@@ -33,31 +33,30 @@ export const wireChannel = <
   >
 ) => {
   // Get the channel metadata
-  const channelsMeta = pikkuState('channel', 'meta')
+  const channelsMeta = pikkuState(null, 'channel', 'meta')
   const channelMeta = channelsMeta[channel.name]
   if (!channelMeta) {
-    throw new Error(`Channel metadata not found for channel: ${channel.name}`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for channel '${channel.name}'`
+    )
   }
 
-  pikkuState('channel', 'channels').set(channel.name, channel as any)
+  pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
-    addFunction(channelMeta.connect.pikkuFuncName, channel.onConnect as any)
+    addFunction(channelMeta.connect.pikkuFuncId, channel.onConnect as any)
   }
 
   // Register onDisconnect function if provided
   if (channel.onDisconnect && channelMeta.disconnect) {
-    addFunction(
-      channelMeta.disconnect.pikkuFuncName,
-      channel.onDisconnect as any
-    )
+    addFunction(channelMeta.disconnect.pikkuFuncId, channel.onDisconnect as any)
   }
 
   // Register onMessage function if provided
-  if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
+  if (channel.onMessage && channelMeta.message?.pikkuFuncId) {
     addFunction(
-      channelMeta.message.pikkuFuncName,
+      channelMeta.message.pikkuFuncId,
       (channel.onMessage as any).func instanceof Function
         ? channel.onMessage
         : (channel.onMessage as any).func
@@ -79,7 +78,7 @@ export const wireChannel = <
         // Register the function using the pikku name from metadata
         // It could be a FuncConfig or a wiring override with a funcConfig
         addFunction(
-          wiringMeta.pikkuFuncName,
+          wiringMeta.pikkuFuncId,
           (handler as any).func instanceof Function
             ? handler
             : (handler as any).func
@@ -89,7 +88,7 @@ export const wireChannel = <
   }
 
   // Store the channel configuration
-  pikkuState('channel', 'channels').set(channel.name, channel as any)
+  pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 }
 
 const getMatchingChannelConfig = (path: string) => {
@@ -98,7 +97,7 @@ const getMatchingChannelConfig = (path: string) => {
     return null
   }
 
-  const meta = pikkuState('channel', 'meta')
+  const meta = pikkuState(null, 'channel', 'meta')
   const channelMeta = Object.values(meta).find(
     (channelConfig) => channelConfig.route === matchedPath.route
   )
@@ -106,7 +105,7 @@ const getMatchingChannelConfig = (path: string) => {
     return null
   }
 
-  const channels = pikkuState('channel', 'channels')
+  const channels = pikkuState(null, 'channel', 'channels')
   const channelConfig = channels.get(channelMeta.name)
   if (!channelConfig) {
     return null

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

@@ -11,6 +11,18 @@ import {
   MiddlewareMetadata,
   PermissionMetadata,
 } from '../../types/core.types.js'
+
+export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (
+  services: Services,
+  event: Event,
+  next: (event: Event | Event[] | null) => Promise<void> | void
+) => Promise<void> | void
+
+export type CorePikkuChannelMiddlewareFactory<
+  In = any,
+  Services = any,
+  Event = unknown,
+> = (input: In) => CorePikkuChannelMiddleware<Services, Event>
 import {
   CorePermissionGroup,
   CorePikkuFunction,
@@ -36,7 +48,7 @@ export type RunChannelParams<ChannelData> = {
 }
 
 export interface ChannelMessageMeta {
-  pikkuFuncName: string
+  pikkuFuncId: string
   summary?: string
   description?: string
   errors?: string[]
@@ -62,6 +74,7 @@ export interface ChannelMeta {
   tags?: string[]
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
   permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  channelMiddleware?: MiddlewareMetadata[]
 }
 
 export type ChannelsMeta = Record<string, ChannelMeta>
@@ -118,6 +131,9 @@ export type CoreChannel<
     >
   >
   middleware?: PikkuMiddleware[]
+  channelMiddleware?: Array<
+    CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
+  >
   permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
   docs?: Partial<{