@pikku/core 0.11.2 → 0.12.0

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

@@ -0,0 +1,470 @@
+import {
+  type CoreSingletonServices,
+  type CoreServices,
+  type CoreUserSession,
+  type CreateWireServices,
+  PikkuWire,
+} from '../../types/core.types.js'
+import type {
+  CoreAIAgent,
+  AIAgentInput,
+  AIAgentToolDef,
+  AIMessage,
+  AIStreamChannel,
+  AIStreamEvent,
+} 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 { runPikkuFunc } from '../../function/function-runner.js'
+import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import { randomUUID } from 'crypto'
+
+import {
+  resolveMemoryServices,
+  loadContextMessages,
+  trimMessages,
+} from './ai-agent-memory.js'
+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 = {
+  requiresToolApproval?: 'all' | 'explicit' | false
+}
+
+export class ToolApprovalRequired extends PikkuError {
+  public readonly toolCallId: string
+  public readonly toolName: string
+  public readonly args: unknown
+  public readonly reason?: string
+  public readonly displayToolName?: string
+  public readonly displayArgs?: unknown
+  public readonly agentRunId?: string
+
+  constructor(
+    toolCallId: string,
+    toolName: string,
+    args: unknown,
+    reason?: string,
+    displayToolName?: string,
+    displayArgs?: unknown,
+    agentRunId?: string
+  ) {
+    super(`Tool '${displayToolName ?? toolName}' requires approval`)
+    this.toolCallId = toolCallId
+    this.toolName = toolName
+    this.args = args
+    this.reason = reason
+    this.displayToolName = displayToolName
+    this.displayArgs = displayArgs
+    this.agentRunId = agentRunId
+  }
+}
+
+export type StreamContext = {
+  channel: AIStreamChannel
+  options?: StreamAIAgentOptions
+}
+
+export const resolveAgent = (
+  agentName: string
+): { agent: CoreAIAgent; packageName: string | null; resolvedName: string } => {
+  const mainAgent = pikkuState(null, 'agent', 'agents').get(agentName)
+  if (mainAgent) {
+    return { agent: mainAgent, packageName: null, resolvedName: agentName }
+  }
+
+  const colonIndex = agentName.indexOf(':')
+  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)
+    if (pkgConfig) {
+      const extAgent = pikkuState(pkgConfig.package, 'agent', 'agents').get(
+        localName
+      )
+      if (extAgent) {
+        return {
+          agent: extAgent,
+          packageName: pkgConfig.package,
+          resolvedName: localName,
+        }
+      }
+    }
+  }
+
+  throw new Error(`AI agent not found: ${agentName}`)
+}
+
+export function buildInstructions(
+  agentName: string,
+  packageName: string | null
+): string {
+  const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
+  const instructions = meta?.instructions ?? ''
+  const baseInstructions = Array.isArray(instructions)
+    ? instructions.join('\n')
+    : instructions
+
+  return meta?.agents?.length
+    ? baseInstructions +
+        '\n\nWhen calling a sub-agent, provide a short session name that describes the task. ' +
+        'Use the same session name to continue a previous conversation with that agent. ' +
+        'Use a new session name for a new independent task.'
+    : baseInstructions
+}
+
+export type ScopedChannel = AIStreamChannel & {
+  approval: {
+    toolCallId: string
+    toolName: string
+    args: unknown
+    runId: string
+  } | null
+}
+
+export function createScopedChannel(
+  parent: AIStreamChannel,
+  agentName: string,
+  session: string
+): ScopedChannel {
+  let capturedApproval: ScopedChannel['approval'] = null
+
+  return {
+    channelId: `${parent.channelId}:${agentName}:${session}`,
+    openingData: parent.openingData,
+    get state() {
+      return parent.state
+    },
+    get approval() {
+      return capturedApproval
+    },
+    close: () => {},
+    send: (event: AIStreamEvent) => {
+      if (event.type === 'done') return
+      if (event.type === 'approval-request') {
+        capturedApproval = {
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          args: event.args,
+          runId: (event as any).runId,
+        }
+        return
+      }
+      if (
+        event.type === 'text-delta' ||
+        event.type === 'reasoning-delta' ||
+        event.type === 'tool-call' ||
+        event.type === 'tool-result' ||
+        event.type === 'usage' ||
+        event.type === 'error'
+      ) {
+        parent.send({ ...event, agent: agentName, session } as AIStreamEvent)
+      } else {
+        parent.send(event)
+      }
+    },
+  }
+}
+
+export function buildToolDefs(
+  singletonServices: CoreSingletonServices,
+  params: RunAIAgentParams,
+  agentSessionMap: Map<string, string>,
+  resourceId: string,
+  agentName: string,
+  packageName: string | null,
+  streamContext?: StreamContext
+): { tools: AIAgentToolDef[]; missingRpcs: string[] } {
+  const tools: AIAgentToolDef[] = []
+  const missingRpcs: string[] = []
+  const approvalPolicy =
+    streamContext?.options?.requiresToolApproval ?? 'explicit'
+
+  const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
+  if (!meta) return { tools, missingRpcs }
+
+  const metaTools = meta.tools
+  const metaAgents = meta.agents
+
+  if (metaTools?.length) {
+    const functionMeta = pikkuState(null, 'function', 'meta')
+    const schemas = pikkuState(null, 'misc', 'schemas')
+
+    for (const toolName of metaTools) {
+      const rpcMeta = pikkuState(null, 'rpc', 'meta')
+      const pikkuFuncId = rpcMeta[toolName]
+      if (!pikkuFuncId) {
+        missingRpcs.push(toolName)
+        continue
+      }
+
+      const fnMeta = functionMeta[pikkuFuncId]
+      const inputSchemaName = fnMeta?.inputSchemaName
+      let inputSchema = inputSchemaName
+        ? schemas.get(inputSchemaName)
+        : undefined
+      if (
+        !inputSchema ||
+        (typeof inputSchema === 'object' &&
+          inputSchema.type === 'object' &&
+          !inputSchema.properties)
+      ) {
+        inputSchema = { type: 'object', properties: {} }
+      }
+
+      const needsApproval =
+        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,
+        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,
+            data: () => toolInput,
+            wire,
+            sessionService: params.sessionService,
+          })
+        },
+      })
+    }
+  }
+
+  if (metaAgents?.length) {
+    const allAgentsMeta = pikkuState(null, 'agent', 'agentsMeta')
+
+    for (const subAgentName of metaAgents) {
+      const subMeta = allAgentsMeta[subAgentName]
+      if (!subMeta) {
+        singletonServices.logger.warn(
+          `Sub-agent '${subAgentName}' not found in agent registry`
+        )
+        continue
+      }
+
+      tools.push({
+        name: subAgentName,
+        description: subMeta.description,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            message: { type: 'string' },
+            session: {
+              type: 'string',
+              description: 'Short session label for thread continuity',
+            },
+          },
+          required: ['message', 'session'],
+        },
+        execute: async (toolInput: unknown) => {
+          const { message, session } = toolInput as {
+            message: string
+            session: string
+          }
+          const sessionKey = `${subAgentName}::${session}`
+          let threadId = agentSessionMap.get(sessionKey)
+          if (!threadId) {
+            threadId = `${subAgentName}-${session}-${Date.now()}`
+            agentSessionMap.set(sessionKey, threadId)
+          }
+
+          if (streamContext) {
+            const { streamAIAgent } = await import('./ai-agent-stream.js')
+            const { channel } = streamContext
+            channel.send({
+              type: 'agent-call',
+              agentName: subAgentName,
+              session,
+              input: message,
+            })
+            const subChannel = createScopedChannel(
+              channel,
+              subAgentName,
+              session
+            )
+            await streamAIAgent(
+              subAgentName,
+              { message, threadId, resourceId },
+              subChannel,
+              params,
+              agentSessionMap,
+              streamContext.options
+            )
+            if (subChannel.approval) {
+              return {
+                __approvalRequired: true,
+                toolName: subAgentName,
+                args: toolInput,
+                displayToolName: subChannel.approval.toolName,
+                displayArgs: subChannel.approval.args,
+                agentRunId: subChannel.approval.runId,
+              }
+            }
+            channel.send({
+              type: 'agent-result',
+              agentName: subAgentName,
+              session,
+              result: null,
+            })
+            return null
+          }
+
+          const { runAIAgent } = await import('./ai-agent-runner.js')
+          const result = await runAIAgent(
+            subAgentName,
+            { message, threadId, resourceId },
+            params,
+            agentSessionMap
+          )
+          return result.object ?? result.text
+        },
+      })
+    }
+  }
+
+  return { tools, missingRpcs }
+}
+
+export async function prepareAgentRun(
+  agentName: string,
+  input: AIAgentInput,
+  params: RunAIAgentParams,
+  agentSessionMap: Map<string, string>,
+  streamContext?: StreamContext
+) {
+  const { singletonServices } = params
+  const { agent, packageName, resolvedName } = resolveAgent(agentName)
+
+  const agentRunner = singletonServices.aiAgentRunner
+  if (!agentRunner) {
+    throw new Error('AIAgentRunnerService not available in singletonServices')
+  }
+
+  const { storage } = resolveMemoryServices(agent, singletonServices)
+  const memoryConfig = agent.memory
+  const threadId = input.threadId
+
+  const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
+  const meta = agentsMeta[resolvedName]
+  const outputSchemaName = meta?.outputSchema
+  const outputSchema = outputSchemaName
+    ? pikkuState(packageName, 'misc', 'schemas').get(outputSchemaName)
+    : undefined
+
+  const workingMemorySchemaName = meta?.workingMemorySchema ?? null
+  const workingMemoryJsonSchema = workingMemorySchemaName
+    ? pikkuState(packageName, 'misc', 'schemas').get(workingMemorySchemaName)
+    : undefined
+
+  if (storage) {
+    try {
+      await storage.getThread(threadId)
+    } catch {
+      await storage.createThread(input.resourceId, { threadId })
+    }
+  }
+
+  let messages: AIMessage[] = []
+  if (storage) {
+    messages = await storage.getMessages(threadId, {
+      lastN: memoryConfig?.lastMessages ?? 20,
+    })
+  }
+
+  const contextMessages = await loadContextMessages(
+    memoryConfig,
+    storage,
+    input,
+    workingMemoryJsonSchema
+  )
+
+  const userMessage: AIMessage = {
+    id: randomUUID(),
+    role: 'user',
+    content: input.message,
+    createdAt: new Date(),
+  }
+
+  const allMessages = [...contextMessages, ...messages, userMessage]
+  const trimmedMessages = trimMessages(allMessages)
+
+  const { tools, missingRpcs } = buildToolDefs(
+    singletonServices,
+    params,
+    agentSessionMap,
+    input.resourceId,
+    resolvedName,
+    packageName,
+    streamContext
+  )
+
+  const instructions = buildInstructions(resolvedName, packageName)
+
+  const resolved = resolveModelConfig(resolvedName, agent)
+
+  const runnerParams: AIAgentRunnerParams = {
+    model: resolved.model,
+    temperature: resolved.temperature,
+    instructions,
+    messages: trimmedMessages,
+    tools,
+    maxSteps: resolved.maxSteps ?? 10,
+    toolChoice: agent.toolChoice ?? 'auto',
+    outputSchema,
+  }
+
+  return {
+    agent,
+    packageName,
+    resolvedName,
+    agentRunner,
+    storage,
+    memoryConfig,
+    threadId,
+    userMessage,
+    runnerParams,
+    missingRpcs,
+    workingMemoryJsonSchema,
+    workingMemorySchemaName,
+  }
+}

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

@@ -0,0 +1,37 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { approveAIAgent } from './ai-agent-registry.js'
+
+describe('approveAIAgent', () => {
+  test('rejects approval when run agent does not match expected agent', async () => {
+    const aiRunState = {
+      getRun: async () => ({
+        runId: 'run-1',
+        agentName: 'internal-agent',
+        threadId: 'thread-1',
+        resourceId: 'resource-1',
+        status: 'suspended',
+        pendingApprovals: [],
+        usage: { inputTokens: 0, outputTokens: 0, model: 'test-model' },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }),
+      updateRun: async () => {},
+    } as any
+
+    await assert.rejects(
+      () =>
+        approveAIAgent(
+          aiRunState,
+          'run-1',
+          [{ toolCallId: 'call-1', approved: true }],
+          'public-agent'
+        ),
+      {
+        message:
+          "Run run-1 belongs to agent 'internal-agent', not 'public-agent'",
+      }
+    )
+  })
+})

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

@@ -0,0 +1,82 @@
+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 { PikkuMissingMetaError } from '../../errors/errors.js'
+
+export const addAIAgent = (
+  agentName: string,
+  agent: CoreAIAgent<any, any>,
+  packageName: string | null = null
+) => {
+  const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
+  const agentMeta = agentsMeta[agentName]
+  if (!agentMeta) {
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for AI agent '${agentName}'`
+    )
+  }
+  const agents = pikkuState(packageName, 'agent', 'agents')
+  if (agents.has(agentName)) {
+    throw new Error(`AI agent already exists: ${agentName}`)
+  }
+  agents.set(agentName, agent)
+}
+
+export async function approveAIAgent(
+  aiRunState: AIRunStateService,
+  runId: string,
+  approvals: { toolCallId: string; approved: boolean }[],
+  expectedAgentName?: string
+): Promise<{
+  status: 'resumed' | 'suspended'
+  runId: string
+  approved: string[]
+  rejected: string[]
+  remainingApprovals: number
+}> {
+  if (!aiRunState) throw new Error('AIRunStateService not available')
+
+  const run = await aiRunState.getRun(runId)
+  if (!run) throw new Error('Run not found: ' + runId)
+  if (expectedAgentName && run.agentName !== expectedAgentName) {
+    throw new Error(
+      `Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`
+    )
+  }
+  if (run.status !== 'suspended')
+    throw new Error('Run is not suspended: ' + run.status)
+
+  const approvedIds = new Set(
+    approvals.filter((a) => a.approved).map((a) => a.toolCallId)
+  )
+  const rejectedIds = new Set(
+    approvals.filter((a) => !a.approved).map((a) => a.toolCallId)
+  )
+
+  const remaining = (run.pendingApprovals ?? []).filter(
+    (p: NonNullable<AgentRunState['pendingApprovals']>[number]) =>
+      !approvedIds.has(p.toolCallId) && !rejectedIds.has(p.toolCallId)
+  )
+
+  const hasApproved = approvedIds.size > 0
+  await aiRunState.updateRun(runId, {
+    status: hasApproved ? 'running' : 'suspended',
+    pendingApprovals: remaining.length > 0 ? remaining : undefined,
+  })
+
+  return {
+    status: hasApproved ? 'resumed' : 'suspended',
+    runId,
+    approved: [...approvedIds],
+    rejected: [...rejectedIds],
+    remainingApprovals: remaining.length,
+  }
+}
+
+export const getAIAgents = () => {
+  return pikkuState(null, 'agent', 'agents')
+}
+
+export const getAIAgentsMeta = () => {
+  return pikkuState(null, 'agent', 'agentsMeta')
+}

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

@@ -0,0 +1,75 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import { runAIAgent } from './ai-agent-runner.js'
+import type { CoreAIAgent } from './ai-agent.types.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const addTestAgent = (agentName: string) => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: 'test agent',
+    instructions: 'be helpful',
+    model: 'test-model',
+  }
+
+  pikkuState(null, 'agent', 'agentsMeta')[agentName] = {
+    ...agent,
+    inputSchema: null,
+    outputSchema: null,
+    workingMemorySchema: null,
+  }
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  pikkuState(null, 'models', 'config', {
+    models: { 'test-model': 'test/test-model' },
+  })
+}
+
+describe('runAIAgent', () => {
+  test('marks run as failed when runner throws', async () => {
+    addTestAgent('failing-agent')
+
+    const updates: unknown[] = []
+    const expectedError = new Error('runner failed')
+
+    const singletonServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        run: async () => {
+          throw expectedError
+        },
+      },
+      aiRunState: {
+        createRun: async () => 'run-1',
+        updateRun: async (_runId: string, patch: unknown) => {
+          updates.push(patch)
+        },
+      },
+    } as any
+
+    await assert.rejects(
+      () =>
+        runAIAgent(
+          'failing-agent',
+          {
+            message: 'hello',
+            threadId: 'thread-1',
+            resourceId: 'resource-1',
+          },
+          { singletonServices }
+        ),
+      expectedError
+    )
+
+    assert.deepEqual(updates, [{ status: 'failed' }])
+  })
+})