@pikku/core 0.12.83 → 0.12.86

package/src/wirings/{ai-agent/ai-agent-runner.ts → agent/agent-runner.ts}

@@ -1,19 +1,19 @@
 import type {
-  AIAgentInput,
-  AIAgentOutput,
-  AIAgentStep,
-  AIAgentMemoryConfig,
-  CoreAIAgent,
-  PikkuAIMiddlewareHooks,
+  AgentInput,
+  AgentOutput,
+  AgentStep,
+  AgentMemoryConfig,
+  CoreAgent,
+  PikkuAgentMiddlewareHooks,
   AgentRunState,
-} from './ai-agent.types.js'
+} from './agent.types.js'
 import type {
-  AIAgentStepResult,
-  AIAgentRunnerParams,
-  AIAgentRunnerService,
-} from '../../services/ai-agent-runner-service.js'
-import type { AIStorageService } from '../../services/ai-storage-service.js'
-import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+  AgentStepResult,
+  AgentRunnerParams,
+  AgentRunnerService,
+} from '../../services/agent-runner-service.js'
+import type { AgentStorageService } from '../../services/agent-storage-service.js'
+import type { AgentRunStateService } from '../../services/agent-run-state-service.js'
 
 import {
   saveMessages,
@@ -21,7 +21,7 @@ import {
   loadContextMessages,
   trimMessages,
   getWorkingMemoryMiddleware,
-} from './ai-agent-memory.js'
+} from './agent-memory.js'
 import {
   prepareAgentRun,
   resolveAgent,
@@ -31,9 +31,9 @@ import {
   agentSessionScope,
   assertResourcePrincipalOwner,
   assertAgentAuthorized,
-  type RunAIAgentParams,
-} from './ai-agent-prepare.js'
-import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js'
+  type RunAgentParams,
+} from './agent-prepare.js'
+import { checkForApprovals, appendStepMessages } from './agent-stream.js'
 import {
   AgentInterruptedError,
   isAbortError,
@@ -41,22 +41,22 @@ import {
   registerInterruptibleRun,
   trackInterruptNote,
   trackToolExecution,
-} from './ai-agent-interrupt.js'
+} from './agent-interrupt.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import {
   applyInputMiddleware,
   describeApprovals,
   notifyAfterStep,
   toAccumulatedStep,
-} from './ai-agent-turn.js'
+} from './agent-turn.js'
 import {
   applyOutputMiddleware,
   finalizeAgentRun,
   lastUserMessageText,
-} from './ai-agent-finalize.js'
-import { resolveModelConfig } from './ai-agent-model-config.js'
+} from './agent-finalize.js'
+import { resolveModelConfig } from './agent-model-config.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
-import { randomUUID } from './ai-agent-utils.js'
+import { deniedToolResult, randomUUID } from './agent-utils.js'
 
 function stripNulls(obj: unknown): unknown {
   if (obj === null) return undefined
@@ -86,12 +86,12 @@ function extractStructuredAssistantOutput(object: unknown): {
   }
 }
 
-export async function runAIAgent(
+export async function runAgent(
   agentName: string,
-  input: AIAgentInput,
-  params: RunAIAgentParams,
+  input: AgentInput,
+  params: RunAgentParams,
   agentSessionMap?: Map<string, string>
-): Promise<AIAgentOutput> {
+): Promise<AgentOutput> {
   const sessionMap = agentSessionMap ?? new Map<string, string>()
 
   input = {
@@ -119,13 +119,13 @@ export async function runAIAgent(
   runnerParams.agentId = agentName
 
   const singletonServices = getSingletonServices()
-  const { aiRunState } = singletonServices
-  if (!aiRunState) {
-    throw new Error('AIRunStateService not available in singletonServices')
+  const { agentRunState } = singletonServices
+  if (!agentRunState) {
+    throw new Error('AgentRunStateService not available in singletonServices')
   }
 
   if (missingRpcs.length > 0) {
-    const runId = await aiRunState.createRun({
+    const runId = await agentRunState.createRun({
       agentName,
       threadId,
       resourceId: input.resourceId,
@@ -145,22 +145,22 @@ export async function runAIAgent(
     }
   }
 
-  const aiMiddlewares: PikkuAIMiddlewareHooks[] = [
+  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
     ...getWorkingMemoryMiddleware(memoryConfig, storage, {
       threadId,
       workingMemorySchemaName,
       logger: singletonServices.logger,
       schemaService: singletonServices.schema,
     }),
-    ...(agent.aiMiddleware ?? []),
+    ...(agent.agentMiddleware ?? []),
   ]
 
-  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  // One bag per run, shared by every middleware — see PikkuAgentMiddlewareHooks.
   const sharedNotes: Record<string, unknown> = {}
 
   const { messages: modifiedMessages, instructions: modifiedInstructions } =
     await applyInputMiddleware(
-      aiMiddlewares,
+      agentMiddlewares,
       singletonServices,
       {
         messages: runnerParams.messages,
@@ -176,7 +176,7 @@ export async function runAIAgent(
   const persistedUserMessage =
     lastModified?.id === userMessage.id ? lastModified : userMessage
 
-  const runId = await aiRunState.createRun({
+  const runId = await agentRunState.createRun({
     agentName,
     threadId,
     resourceId: input.resourceId,
@@ -192,9 +192,9 @@ export async function runAIAgent(
   runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
 
   try {
-    const accumulatedSteps: AIAgentStep[] = []
+    const accumulatedSteps: AgentStep[] = []
     const totalUsage = { inputTokens: 0, outputTokens: 0 }
-    let lastStepResult: AIAgentStepResult | null = null
+    let lastStepResult: AgentStepResult | null = null
 
     for (let step = 0; step < maxSteps; step++) {
       if (agent.prepareStep) {
@@ -218,7 +218,12 @@ export async function runAIAgent(
       totalUsage.inputTokens += stepResult.usage.inputTokens
       totalUsage.outputTokens += stepResult.usage.outputTokens
 
-      await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult)
+      await notifyAfterStep(
+        agentMiddlewares,
+        singletonServices,
+        step,
+        stepResult
+      )
 
       accumulatedSteps.push(toAccumulatedStep(stepResult))
 
@@ -271,7 +276,7 @@ export async function runAIAgent(
           ])
         }
 
-        await aiRunState.updateRun(runId, {
+        await agentRunState.updateRun(runId, {
           status: 'suspended',
           suspendReason: 'approval',
           pendingApprovals,
@@ -309,7 +314,7 @@ export async function runAIAgent(
     }
 
     const { text: outputText, steps: outputSteps } =
-      await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+      await applyOutputMiddleware(agentMiddlewares, singletonServices, {
         text: finalText,
         messages: runnerParams.messages,
         steps: result.steps,
@@ -329,7 +334,7 @@ export async function runAIAgent(
       }
     )
 
-    await finalizeAgentRun(aiRunState, {
+    await finalizeAgentRun(agentRunState, {
       runId,
       agentName,
       threadId,
@@ -352,7 +357,7 @@ export async function runAIAgent(
     // knowledge: decisions/internals/an-agent-interrupt-is-not-a-failure.md
     const interruption = interruptHandle.interruption
     if (interruption || isAbortError(error)) {
-      await aiRunState.updateRun(runId, { status: 'interrupted' })
+      await agentRunState.updateRun(runId, { status: 'interrupted' })
       if (storage) {
         trackInterruptNote(
           threadId,
@@ -361,7 +366,7 @@ export async function runAIAgent(
       }
       throw new AgentInterruptedError(runId, interruption ?? { reason: 'user' })
     }
-    for (const mw of aiMiddlewares) {
+    for (const mw of agentMiddlewares) {
       if (mw.onError) {
         try {
           await mw.onError(singletonServices, {
@@ -372,7 +377,7 @@ export async function runAIAgent(
         } catch {}
       }
     }
-    await aiRunState.updateRun(runId, {
+    await agentRunState.updateRun(runId, {
       status: 'failed',
       errorMessage: error instanceof Error ? error.message : String(error),
     })
@@ -382,19 +387,19 @@ export async function runAIAgent(
   }
 }
 
-export async function resumeAIAgentSync(
+export async function resumeAgentSync(
   runId: string,
   approvals: { toolCallId: string; approved: boolean }[],
-  params: RunAIAgentParams,
+  params: RunAgentParams,
   expectedAgentName?: string
-): Promise<AIAgentOutput> {
+): Promise<AgentOutput> {
   const singletonServices = getSingletonServices()
-  const { aiRunState } = singletonServices
-  if (!aiRunState) {
-    throw new Error('AIRunStateService not available in singletonServices')
+  const { agentRunState } = singletonServices
+  if (!agentRunState) {
+    throw new Error('AgentRunStateService not available in singletonServices')
   }
 
-  const run = await aiRunState.getRun(runId)
+  const run = await agentRunState.getRun(runId)
   if (!run) throw new Error(`No run found for runId ${runId}`)
   assertResourcePrincipalOwner(
     params,
@@ -417,7 +422,7 @@ export async function resumeAIAgentSync(
 
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
-  const agentRunner = singletonServices.aiAgentRunner
+  const agentRunner = singletonServices.agentRunner
   if (!agentRunner) {
     throw new AIProviderNotConfiguredError()
   }
@@ -436,7 +441,7 @@ export async function resumeAIAgentSync(
   // for may run the tool.
   const claimedIds = new Set<string>()
   for (const { toolCallId, approved } of approvals) {
-    const claimed = await aiRunState.resolveApproval(
+    const claimed = await agentRunState.resolveApproval(
       toolCallId,
       approved ? 'approved' : 'denied'
     )
@@ -458,7 +463,7 @@ export async function resumeAIAgentSync(
     resolvedName,
     packageName,
     undefined,
-    agent.aiMiddleware ?? []
+    agent.agentMiddleware ?? []
   )
 
   const toolCallMessages: {
@@ -479,8 +484,7 @@ export async function resumeAIAgentSync(
     let toolError: string | undefined
 
     if (rejectedIds.has(toolCallId)) {
-      resultStr =
-        'The user explicitly declined this action. Inform them that it was declined and do not retry.'
+      resultStr = deniedToolResult()
     } else if (approvedIds.has(toolCallId)) {
       const matchingTool = tools.find((t) => t.name === pending.toolName)
       if (!matchingTool) {
@@ -538,7 +542,7 @@ export async function resumeAIAgentSync(
     ])
   }
 
-  await aiRunState.updateRun(runId, { status: 'running' })
+  await agentRunState.updateRun(runId, { status: 'running' })
 
   return continueAfterToolResultSync(
     run,
@@ -549,7 +553,7 @@ export async function resumeAIAgentSync(
     memoryConfig,
     agentRunner,
     params,
-    aiRunState,
+    agentRunState,
     // The approved tools were executed here, before the model was re-entered,
     // so they belong to the run's step record — otherwise a tool that failed
     // after approval leaves no trace on the run at all.
@@ -569,16 +573,16 @@ export async function resumeAIAgentSync(
 
 async function continueAfterToolResultSync(
   run: AgentRunState,
-  agent: CoreAIAgent,
+  agent: CoreAgent,
   packageName: string | null,
   resolvedName: string,
-  storage: AIStorageService | undefined,
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  agentRunner: AIAgentRunnerService,
-  params: RunAIAgentParams,
-  aiRunState: AIRunStateService,
-  resumedToolStep?: AIAgentStep
-): Promise<AIAgentOutput> {
+  storage: AgentStorageService | undefined,
+  memoryConfig: AgentMemoryConfig | undefined,
+  agentRunner: AgentRunnerService,
+  params: RunAgentParams,
+  agentRunState: AgentRunStateService,
+  resumedToolStep?: AgentStep
+): Promise<AgentOutput> {
   const singletonServices = getSingletonServices()
   const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
   const meta = agentsMeta[resolvedName]
@@ -606,21 +610,21 @@ async function continueAfterToolResultSync(
 
   const instructions = await buildInstructions(resolvedName, packageName)
 
-  const aiMiddlewares: PikkuAIMiddlewareHooks[] = [
+  const agentMiddlewares: PikkuAgentMiddlewareHooks[] = [
     ...getWorkingMemoryMiddleware(memoryConfig, storage, {
       threadId: run.threadId,
       workingMemorySchemaName,
       logger: singletonServices.logger,
       schemaService: singletonServices.schema,
     }),
-    ...(agent.aiMiddleware ?? []),
+    ...(agent.agentMiddleware ?? []),
   ]
-  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  // One bag per run, shared by every middleware — see PikkuAgentMiddlewareHooks.
   const sharedNotes: Record<string, unknown> = {}
 
   const { messages: modifiedMessages, instructions: modifiedInstructions } =
     await applyInputMiddleware(
-      aiMiddlewares,
+      agentMiddlewares,
       singletonServices,
       { messages: trimmedMessages, instructions: instructions },
       sharedNotes
@@ -633,13 +637,13 @@ async function continueAfterToolResultSync(
     resolvedName,
     packageName,
     undefined,
-    aiMiddlewares
+    agentMiddlewares
   )
 
   const resolved = resolveModelConfig(resolvedName, agent)
   const maxSteps = resolved.maxSteps ?? 10
 
-  const runnerParams: AIAgentRunnerParams = {
+  const runnerParams: AgentRunnerParams = {
     model: resolved.model,
     temperature: resolved.temperature,
     instructions: modifiedInstructions,
@@ -666,12 +670,12 @@ async function continueAfterToolResultSync(
     // `saveMessages`, and the approved tool's messages were already written to
     // the thread before the model was re-entered. It belongs to the run's step
     // record, not to persistence.
-    const withResumedStep = (steps: AIAgentStep[]): AIAgentStep[] =>
+    const withResumedStep = (steps: AgentStep[]): AgentStep[] =>
       resumedToolStep ? [resumedToolStep, ...steps] : steps
 
-    const accumulatedSteps: AIAgentStep[] = []
+    const accumulatedSteps: AgentStep[] = []
     const totalUsage = { inputTokens: 0, outputTokens: 0 }
-    let lastStepResult: AIAgentStepResult | null = null
+    let lastStepResult: AgentStepResult | null = null
 
     for (let step = 0; step < maxSteps; step++) {
       const stepResult = await agentRunner.run(runnerParams)
@@ -680,7 +684,12 @@ async function continueAfterToolResultSync(
       totalUsage.inputTokens += stepResult.usage.inputTokens
       totalUsage.outputTokens += stepResult.usage.outputTokens
 
-      await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult)
+      await notifyAfterStep(
+        agentMiddlewares,
+        singletonServices,
+        step,
+        stepResult
+      )
 
       accumulatedSteps.push(toAccumulatedStep(stepResult))
 
@@ -735,7 +744,7 @@ async function continueAfterToolResultSync(
           ])
         }
 
-        await aiRunState.updateRun(run.runId, {
+        await agentRunState.updateRun(run.runId, {
           status: 'suspended',
           suspendReason: 'approval',
           pendingApprovals,
@@ -772,7 +781,7 @@ async function continueAfterToolResultSync(
     }
 
     const { text: outputText, steps: outputSteps } =
-      await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+      await applyOutputMiddleware(agentMiddlewares, singletonServices, {
         text: finalText,
         messages: runnerParams.messages,
         steps: withResumedStep(result.steps),
@@ -793,7 +802,7 @@ async function continueAfterToolResultSync(
       }
     )
 
-    await finalizeAgentRun(aiRunState, {
+    await finalizeAgentRun(agentRunState, {
       runId: run.runId,
       agentName: resolvedName,
       threadId: run.threadId,
@@ -815,7 +824,7 @@ async function continueAfterToolResultSync(
   } catch (error) {
     const interruption = interruptHandle.interruption
     if (interruption || isAbortError(error)) {
-      await aiRunState.updateRun(run.runId, { status: 'interrupted' })
+      await agentRunState.updateRun(run.runId, { status: 'interrupted' })
       if (storage) {
         trackInterruptNote(
           run.threadId,
@@ -827,7 +836,7 @@ async function continueAfterToolResultSync(
         interruption ?? { reason: 'user' }
       )
     }
-    for (const mw of aiMiddlewares) {
+    for (const mw of agentMiddlewares) {
       if (mw.onError) {
         try {
           await mw.onError(singletonServices, {
@@ -838,7 +847,7 @@ async function continueAfterToolResultSync(
         } catch {}
       }
     }
-    await aiRunState.updateRun(run.runId, {
+    await agentRunState.updateRun(run.runId, {
       status: 'failed',
       errorMessage: error instanceof Error ? error.message : String(error),
     })

package/src/wirings/{ai-agent/ai-agent-stream-output-hooks.test.ts → agent/agent-stream-output-hooks.test.ts}

@@ -2,16 +2,16 @@ import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { streamAIAgent } from './ai-agent-stream.js'
-import type { CoreAIAgent, PikkuAIMiddlewareHooks } from './ai-agent.types.js'
-import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+import { streamAgent } from './agent-stream.js'
+import type { CoreAgent, PikkuAgentMiddlewareHooks } from './agent.types.js'
+import type { AgentStepResult } from '../../services/agent-runner-service.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
 const addTestAgent = (agentName: string) => {
-  const agent: CoreAIAgent = {
+  const agent: CoreAgent = {
     name: agentName,
     description: 'test agent',
     instructions: 'be helpful',
@@ -28,8 +28,8 @@ const addTestAgent = (agentName: string) => {
 }
 
 const makeStepResult = (
-  overrides?: Partial<AIAgentStepResult>
-): AIAgentStepResult => ({
+  overrides?: Partial<AgentStepResult>
+): AgentStepResult => ({
   text: '',
   toolCalls: [],
   toolResults: [],
@@ -38,7 +38,7 @@ const makeStepResult = (
   ...overrides,
 })
 
-describe('streamAIAgent output hooks', () => {
+describe('streamAgent output hooks', () => {
   test('does not run modifyOutput on a streamed run, and warns the hook it is inert there', async () => {
     addTestAgent('stream-modify-output-agent')
 
@@ -46,7 +46,7 @@ describe('streamAIAgent output hooks', () => {
     const modifyOutputCalls: unknown[] = []
     const sideEffects: string[] = []
 
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       modifyOutput: async (_services, ctx) => {
         modifyOutputCalls.push(ctx)
         sideEffects.push(ctx.text)
@@ -56,7 +56,7 @@ describe('streamAIAgent output hooks', () => {
     const agent = pikkuState(null, 'agent', 'agents').get(
       'stream-modify-output-agent'
     )!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     pikkuState(null, 'agent', 'agents').set('stream-modify-output-agent', agent)
 
     const mockServices = {
@@ -66,13 +66,13 @@ describe('streamAIAgent output hooks', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (_params: any, channel: any) => {
           channel.send({ type: 'text-delta', text: 'Hello' })
           return makeStepResult({ text: 'Hello', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-modify-output',
         updateRun: async () => {},
       },
@@ -80,7 +80,7 @@ describe('streamAIAgent output hooks', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    const result = await streamAIAgent(
+    const result = await streamAgent(
       'stream-modify-output-agent',
       {
         message: 'hello',
@@ -139,7 +139,7 @@ describe('streamAIAgent output hooks', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (_params: any, channel: any) => {
           channel.send({
             type: 'text-delta',
@@ -148,11 +148,11 @@ describe('streamAIAgent output hooks', () => {
           return makeStepResult({ text: 'Noted', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-working-memory',
         updateRun: async () => {},
       },
-      aiStorage: {
+      agentStorage: {
         createThread: async () => {},
         getMessages: async () => [],
         saveMessages: async () => {},
@@ -169,7 +169,7 @@ describe('streamAIAgent output hooks', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'stream-working-memory-agent',
       {
         message: 'remember I live in Berlin',
@@ -210,7 +210,7 @@ describe('streamAIAgent output hooks', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (_params: any, channel: any) => {
           channel.send({
             type: 'tool-call',
@@ -240,11 +240,11 @@ describe('streamAIAgent output hooks', () => {
           return makeStepResult({ text: 'done', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-tool-error',
         updateRun: async () => {},
       },
-      aiStorage: {
+      agentStorage: {
         createThread: async () => {},
         getMessages: async () => [],
         saveMessages: async (_threadId: string, messages: any[]) => {
@@ -255,7 +255,7 @@ describe('streamAIAgent output hooks', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'stream-tool-error-agent',
       {
         message: 'look it up',
@@ -290,7 +290,7 @@ describe('streamAIAgent output hooks', () => {
 
     const warnings: unknown[][] = []
 
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       modifyOutput: async (_services, ctx) => ({
         text: ctx.text,
         messages: ctx.messages,
@@ -300,7 +300,7 @@ describe('streamAIAgent output hooks', () => {
     const agent = pikkuState(null, 'agent', 'agents').get(
       'stream-both-hooks-agent'
     )!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     pikkuState(null, 'agent', 'agents').set('stream-both-hooks-agent', agent)
 
     const mockServices = {
@@ -310,13 +310,13 @@ describe('streamAIAgent output hooks', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (_params: any, channel: any) => {
           channel.send({ type: 'text-delta', text: 'Hi' })
           return makeStepResult({ text: 'Hi', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-both-hooks',
         updateRun: async () => {},
       },
@@ -324,7 +324,7 @@ describe('streamAIAgent output hooks', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'stream-both-hooks-agent',
       {
         message: 'hello',