@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,382 @@
+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 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
+  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 | AIContentPart[]
+  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 AIAgentInputAttachment {
+  type: 'image' | 'file'
+  data?: string
+  url?: string
+  mediaType?: string
+  filename?: string
+}
+
+export interface AIAgentInput {
+  message: string
+  threadId: string
+  resourceId: string
+  attachments?: AIAgentInputAttachment[]
+  model?: string
+  temperature?: number
+}
+
+export interface AIAgentOutput {
+  runId: string
+  text: string
+  object?: unknown
+  threadId: string
+  steps: AIAgentStep[]
+  usage: { inputTokens: number; outputTokens: number }
+  status?: 'completed' | 'suspended'
+  pendingApprovals?: Array<{
+    toolCallId: string
+    toolName: string
+    args: unknown
+    reason?: string
+    runId: string
+  }>
+}
+
+export interface AIAgentToolDef {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+  execute: (input: unknown) => Promise<unknown>
+  needsApproval?: boolean
+  approvalDescriptionFn?: (input: unknown) => Promise<string>
+}
+
+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 | AIStreamEvent[] | null>
+    | AIStreamEvent
+    | 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[]
+  agentMode?: 'delegate' | 'supervise'
+  memory?: AIAgentMemoryConfig
+  maxSteps?: number
+  toolChoice?: 'auto' | 'required' | 'none'
+  dynamicWorkflows?: 'read' | 'always' | 'ask'
+  input?: unknown
+  output?: unknown
+  tags?: string[]
+  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: 'audio-delta'
+      data: string
+      format: string
+      agent?: string
+      session?: string
+    }
+  | { type: 'audio-done'; agent?: string; session?: string }
+  | {
+      type: 'workflow-created'
+      workflowName: string
+      graph: any
+      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'
+  errorMessage?: string
+  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
+  errorMessage?: 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[]
+    dynamicWorkflows?: 'read' | 'always' | 'ask'
+  }
+>

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

@@ -0,0 +1,37 @@
+export {
+  agent,
+  agentStream,
+  agentResume,
+  agentApprove,
+} from './ai-agent-helpers.js'
+export { runAIAgent, resumeAIAgentSync } 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 {
+  AIAgentInput,
+  AIAgentInputAttachment,
+  AIAgentMeta,
+  AIAgentMemoryConfig,
+  AIAgentStep,
+  AIContentPart,
+  AgentRunRow,
+  AgentRunService,
+  AgentRunState,
+  AIMessage,
+  AIStreamChannel,
+  AIStreamEvent,
+  AIThread,
+  CoreAIAgent,
+  PendingApproval,
+  PikkuAIMiddlewareHooks,
+} from './ai-agent.types.js'

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

@@ -0,0 +1,90 @@
+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.
+ *
+ * This function:
+ * 1. Extracts inline middleware from the lifecycle config if present
+ * 2. Combines metadata middleware with inline middleware using combineMiddleware()
+ * 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)
+ * @param lifecycleConfig - The onConnect or onDisconnect config (can be function or object with middleware)
+ * @param lifecycleType - Type of lifecycle for cache key ('connect' or 'disconnect')
+ * @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 ({
+  channelConfig,
+  meta,
+  lifecycleConfig,
+  lifecycleType,
+  services,
+  channel,
+  data,
+  channelMiddlewareMeta,
+}: {
+  channelConfig: CoreChannel<unknown, any>
+  meta: ChannelMessageMeta
+  lifecycleConfig: any
+  lifecycleType: 'connect' | 'disconnect'
+  services: CoreSingletonServices
+  channel: any
+  data?: unknown
+  channelMiddlewareMeta?: MiddlewareMetadata[]
+}): Promise<unknown> => {
+  const lifecycleMiddleware =
+    typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
+      ? (lifecycleConfig.middleware as CorePikkuMiddleware[]) || []
+      : []
+
+  const allMiddleware = combineMiddleware(
+    'channel',
+    `${channelConfig.name}:${lifecycleType}`,
+    {
+      wireInheritedMiddleware: meta.middleware,
+      wireMiddleware: lifecycleMiddleware,
+    }
+  )
+
+  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.pikkuFuncId, services, wire, data)
+  }
+
+  if (allMiddleware.length > 0) {
+    return await runMiddleware(services, wire, allMiddleware, runLifecycle)
+  } else {
+    return await runLifecycle()
+  }
+}