@pikku/core 0.11.2 → 0.12.1

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

@@ -0,0 +1,328 @@
+import type {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from '../../function/functions.types.js'
+import type {
+  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>
+  needsApproval?: boolean
+}
+
+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[] }
+
+  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 = {
+  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[]
+  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>[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+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 }
+  | {
+      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,39 @@
+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,
+  ToolApprovalRequired,
+} from './ai-agent-prepare.js'
+export {
+  addAIAgent,
+  approveAIAgent,
+  getAIAgents,
+  getAIAgentsMeta,
+} from './ai-agent-registry.js'
+export type {
+  AIAgentInput,
+  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 { CoreChannel, ChannelMessageMeta } from './channel.types.js'
+import type {
+  CoreSingletonServices,
+  CorePikkuMiddleware,
+  PikkuWire,
+  MiddlewareMetadata,
+} from '../../types/core.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 {
+  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

@@ -1,16 +1,21 @@
-import {
+import type {
   CoreServices,
   JSONValue,
   CoreUserSession,
 } from '../../types/core.types.js'
-import {
+import type {
   ChannelMessageMeta,
   CoreChannel,
   PikkuChannelHandler,
 } 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 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]
+}
 
 const getRouteMeta = (
   channelName: string,
@@ -74,7 +79,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'
@@ -87,7 +98,7 @@ export const processMessageHandlers = (
     }
 
     const {
-      pikkuFuncName,
+      pikkuFuncId,
       middleware: routeInheritedMiddleware,
       permissions: inheritedPermissions,
     } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
@@ -122,17 +133,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)),
       },
     })
   }
@@ -146,7 +163,7 @@ export const processMessageHandlers = (
       let messageData: any
       try {
         messageData = JSON.parse(rawData)
-      } catch (error) {
+      } catch {
         // Most likely a json error.. ignore
       }
 
@@ -188,7 +205,7 @@ export const processMessageHandlers = (
       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

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,
+    },
+  }
+}