@pikku/core 0.12.83 → 0.12.84

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

@@ -1,40 +1,37 @@
 import type {
-  AIStreamChannel,
-  AIStreamEvent,
-  AIAgentStep,
-  AIMessage,
-  AIToolCall,
-  AIToolResult,
-  PikkuAIMiddlewareHooks,
+  AgentStreamChannel,
+  AgentStreamEvent,
+  AgentStep,
+  AgentMessage,
+  AgentToolCall,
+  AgentToolResult,
+  PikkuAgentMiddlewareHooks,
   AgentRunState,
-  CoreAIAgent,
-  AIAgentMemoryConfig,
-} from './ai-agent.types.js'
-import {
-  finalizeAgentRun,
-  lastUserMessageText,
-} from './ai-agent-finalize.js'
+  CoreAgent,
+  AgentMemoryConfig,
+} from './agent.types.js'
+import { finalizeAgentRun, lastUserMessageText } from './agent-finalize.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
-import { applyInputMiddleware } from './ai-agent-turn.js'
+import { applyInputMiddleware } from './agent-turn.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
-import { randomUUID } from './ai-agent-utils.js'
+import { randomUUID } from './agent-utils.js'
 import { SPOKEN_TRANSCRIPT } from './voice-input.js'
 import {
   combineChannelMiddleware,
   wrapChannelWithMiddleware,
 } from '../channel/channel-middleware-runner.js'
-import type { AIStorageService } from '../../services/ai-storage-service.js'
+import type { AgentStorageService } from '../../services/agent-storage-service.js'
 import type {
-  AIAgentRunnerParams,
-  AIAgentStepResult,
-} from '../../services/ai-agent-runner-service.js'
+  AgentRunnerParams,
+  AgentStepResult,
+} from '../../services/agent-runner-service.js'
 
 import {
   resolveMemoryServices,
   loadContextMessages,
   trimMessages,
   getWorkingMemoryMiddleware,
-} from './ai-agent-memory.js'
+} from './agent-memory.js'
 import {
   prepareAgentRun,
   resolveAgent,
@@ -50,13 +47,13 @@ import {
   ToolCredentialRequired,
   APPROVAL_REQUIRED,
   CREDENTIAL_REQUIRED,
-  type RunAIAgentParams,
-  type StreamAIAgentOptions,
+  type RunAgentParams,
+  type StreamAgentOptions,
   type StreamContext,
-} from './ai-agent-prepare.js'
-import { resolveModelConfig } from './ai-agent-model-config.js'
-import type { AIRunStateService } from '../../services/ai-run-state-service.js'
-import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
+} from './agent-prepare.js'
+import { resolveModelConfig } from './agent-model-config.js'
+import type { AgentRunStateService } from '../../services/agent-run-state-service.js'
+import type { AgentRunnerService } from '../../services/agent-runner-service.js'
 import {
   getInFlightTools,
   isAbortError,
@@ -67,27 +64,27 @@ import {
   trackToolExecution,
   type AgentInterruption,
   type AgentInterruptResult,
-} from './ai-agent-interrupt.js'
+} from './agent-interrupt.js'
 
-type PersistingChannel = AIStreamChannel & {
+type PersistingChannel = AgentStreamChannel & {
   fullText: string
   flush: (opts?: { interrupted?: boolean }) => Promise<void>
   totalUsage: { inputTokens: number; outputTokens: number; model?: string }
   /** Every tool the run called, kept for the whole run rather than per step. */
-  runToolCalls: NonNullable<AIAgentStep['toolCalls']>
+  runToolCalls: NonNullable<AgentStep['toolCalls']>
 }
 
 function createPersistingChannel(
-  parent: AIStreamChannel,
-  storage: AIStorageService | undefined,
+  parent: AgentStreamChannel,
+  storage: AgentStorageService | undefined,
   threadId: string,
   logger?: { error: (...args: any[]) => void }
 ): PersistingChannel {
   let fullText = ''
   let stepText = ''
   let stepGenerativeUI: unknown | null = null
-  let stepToolCalls: AIToolCall[] = []
-  let stepToolResults: AIToolResult[] = []
+  let stepToolCalls: AgentToolCall[] = []
+  let stepToolResults: AgentToolResult[] = []
   const totalUsage: {
     inputTokens: number
     outputTokens: number
@@ -98,7 +95,7 @@ function createPersistingChannel(
   }
   // Survives the per-step flush below, which clears its own buffers: the run
   // record needs every call the run made, not just the last step's.
-  const runToolCalls: NonNullable<AIAgentStep['toolCalls']> = []
+  const runToolCalls: NonNullable<AgentStep['toolCalls']> = []
 
   const flushStep = async (opts?: { interrupted?: boolean }) => {
     if (!storage) return
@@ -111,7 +108,7 @@ function createPersistingChannel(
     stepToolCalls = []
     stepToolResults = []
     if (text || generativeUI != null || calls.length > 0) {
-      const assistantMsg: AIMessage = {
+      const assistantMsg: AgentMessage = {
         id: randomUUID(),
         role: 'assistant',
         content:
@@ -125,7 +122,7 @@ function createPersistingChannel(
         ...(opts?.interrupted ? { interrupted: true } : {}),
         createdAt: new Date(),
       }
-      const messages: AIMessage[] = [assistantMsg]
+      const messages: AgentMessage[] = [assistantMsg]
       if (results.length > 0) {
         messages.push({
           id: randomUUID(),
@@ -167,7 +164,7 @@ function createPersistingChannel(
     flush: flushStep,
     close: () => parent.close(),
     sendBinary: (data) => parent.sendBinary(data),
-    send: (event: AIStreamEvent) => {
+    send: (event: AgentStreamEvent) => {
       // Accumulated whether or not storage is configured: `fullText` is what
       // the client was streamed, and an interrupted run has to be able to
       // report the fragment it got through even with persistence turned off.
@@ -259,11 +256,11 @@ const warnedUnstreamedOutputHooks = new Set<string>()
  */
 const warnUnstreamedOutputHooks = (
   agentName: string,
-  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  agentMiddlewares: PikkuAgentMiddlewareHooks[],
   logger?: { warn: (...args: any[]) => void }
 ) => {
   if (warnedUnstreamedOutputHooks.has(agentName)) return
-  const unstreamed = aiMiddlewares.some(
+  const unstreamed = agentMiddlewares.some(
     (mw) => mw.modifyOutput && !mw.modifyOutputStream
   )
   if (!unstreamed) return
@@ -275,7 +272,7 @@ const warnUnstreamedOutputHooks = (
 
 async function postStreamCleanup(
   persistingChannel: PersistingChannel,
-  aiRunState: AIRunStateService,
+  agentRunState: AgentRunStateService,
   runId: string,
   run: {
     agentName: string
@@ -284,7 +281,7 @@ async function postStreamCleanup(
     input: string
   }
 ): Promise<void> {
-  await finalizeAgentRun(aiRunState, {
+  await finalizeAgentRun(agentRunState, {
     runId,
     agentName: run.agentName,
     threadId: run.threadId,
@@ -304,14 +301,14 @@ async function postStreamCleanup(
 }
 
 type StepLoopParams = {
-  agent: CoreAIAgent
-  runnerParams: AIAgentRunnerParams
+  agent: CoreAgent
+  runnerParams: AgentRunnerParams
   maxSteps: number
-  agentRunner: AIAgentRunnerService
-  streamChannel: AIStreamChannel
+  agentRunner: AgentRunnerService
+  streamChannel: AgentStreamChannel
   persistingChannel: PersistingChannel
-  channel: AIStreamChannel
-  aiMiddlewares: PikkuAIMiddlewareHooks[]
+  channel: AgentStreamChannel
+  agentMiddlewares: PikkuAgentMiddlewareHooks[]
 }
 
 type StepLoopResult =
@@ -329,7 +326,7 @@ async function runStreamStepLoop(
     agentRunner,
     streamChannel,
     channel,
-    aiMiddlewares,
+    agentMiddlewares,
   } = params
 
   const singletonServices = getSingletonServices()
@@ -354,7 +351,7 @@ async function runStreamStepLoop(
 
     const stepResult = await agentRunner.stream(runnerParams, streamChannel)
 
-    for (const mw of aiMiddlewares) {
+    for (const mw of agentMiddlewares) {
       if (mw.afterStep) {
         await mw.afterStep(singletonServices, {
           stepNumber: step,
@@ -397,8 +394,8 @@ async function runStreamStepLoop(
 }
 
 export function checkForApprovals(
-  stepResult: AIAgentStepResult,
-  tools: AIAgentRunnerParams['tools']
+  stepResult: AgentStepResult,
+  tools: AgentRunnerParams['tools']
 ): ToolApprovalRequired[] {
   const approvals: ToolApprovalRequired[] = []
   for (const tc of stepResult.toolCalls) {
@@ -471,11 +468,11 @@ export function checkForApprovals(
 }
 
 export function checkForCredentialRequests(
-  stepResult: AIAgentStepResult
+  stepResult: AgentStepResult
 ): ToolCredentialRequired[] {
   const requests: ToolCredentialRequired[] = []
   for (const tr of stepResult.toolResults) {
-    // knowledge: decisions/security/ai-agent-credential-requests-are-symbol-branded.md
+    // knowledge: decisions/security/agent-credential-requests-are-symbol-branded.md
     if (
       tr.result &&
       typeof tr.result === 'object' &&
@@ -505,8 +502,8 @@ export function checkForCredentialRequests(
 }
 
 export function appendStepMessages(
-  runnerParams: AIAgentRunnerParams,
-  stepResult: AIAgentStepResult
+  runnerParams: AgentRunnerParams,
+  stepResult: AgentStepResult
 ): void {
   const structuredOutput =
     stepResult.object && typeof stepResult.object === 'object'
@@ -522,7 +519,7 @@ export function appendStepMessages(
         ]
       : stepResult.text || undefined
 
-  const assistantMsg: AIMessage = {
+  const assistantMsg: AgentMessage = {
     id: randomUUID(),
     role: 'assistant',
     content: assistantContent,
@@ -542,7 +539,7 @@ export function appendStepMessages(
   runnerParams.messages.push(assistantMsg)
 
   if (stepResult.toolResults.length > 0) {
-    const toolMsg: AIMessage = {
+    const toolMsg: AgentMessage = {
       id: randomUUID(),
       role: 'tool',
       toolResults: stepResult.toolResults.map((tr) => ({
@@ -560,8 +557,8 @@ export function appendStepMessages(
 function handleApprovals(
   approvals: ToolApprovalRequired[],
   runId: string,
-  channel: AIStreamChannel,
-  aiRunState: AIRunStateService,
+  channel: AgentStreamChannel,
+  agentRunState: AgentRunStateService,
   persistingChannel: PersistingChannel
 ): Promise<void> {
   return (async () => {
@@ -585,7 +582,7 @@ function handleApprovals(
           }
     )
 
-    await aiRunState.updateRun(runId, {
+    await agentRunState.updateRun(runId, {
       status: 'suspended',
       suspendReason: 'approval',
       pendingApprovals,
@@ -610,8 +607,8 @@ function handleApprovals(
 function handleCredentialRequests(
   requests: ToolCredentialRequired[],
   runId: string,
-  channel: AIStreamChannel,
-  aiRunState: AIRunStateService,
+  channel: AgentStreamChannel,
+  agentRunState: AgentRunStateService,
   persistingChannel: PersistingChannel
 ): Promise<void> {
   return (async () => {
@@ -627,7 +624,7 @@ function handleCredentialRequests(
       connectUrl: req.connectUrl,
     }))
 
-    await aiRunState.updateRun(runId, {
+    await agentRunState.updateRun(runId, {
       status: 'suspended',
       suspendReason: 'credential',
       pendingApprovals,
@@ -650,7 +647,7 @@ function handleCredentialRequests(
   })()
 }
 
-export async function streamAIAgent(
+export async function streamAgent(
   agentName: string,
   input: {
     message: string
@@ -659,10 +656,10 @@ export async function streamAIAgent(
     model?: string
     temperature?: number
   },
-  channel: AIStreamChannel,
-  params: RunAIAgentParams,
+  channel: AgentStreamChannel,
+  params: RunAgentParams,
   agentSessionMap?: Map<string, string>,
-  options?: StreamAIAgentOptions
+  options?: StreamAgentOptions
 ): Promise<string> {
   const sessionMap = agentSessionMap ?? new Map<string, string>()
 
@@ -701,13 +698,13 @@ export async function streamAIAgent(
   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) {
-    await aiRunState.createRun({
+    await agentRunState.createRun({
       agentName,
       threadId,
       resourceId: normalizedInput.resourceId,
@@ -723,22 +720,22 @@ export async function streamAIAgent(
     return ''
   }
 
-  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,
@@ -760,7 +757,7 @@ export async function streamAIAgent(
   const persistedUserMessage =
     lastModified?.id === userMessage.id ? lastModified : userMessage
 
-  const runId = await aiRunState.createRun({
+  const runId = await agentRunState.createRun({
     agentName,
     threadId,
     resourceId: normalizedInput.resourceId,
@@ -782,13 +779,17 @@ export async function streamAIAgent(
     await storage.saveMessages(threadId, [persistedUserMessage])
   }
 
-  warnUnstreamedOutputHooks(agentName, aiMiddlewares, singletonServices.logger)
+  warnUnstreamedOutputHooks(
+    agentName,
+    agentMiddlewares,
+    singletonServices.logger
+  )
 
-  const streamMiddleware = aiMiddlewares
+  const streamMiddleware = agentMiddlewares
     .filter((mw) => mw.modifyOutputStream)
     .map((mw) => {
       const state: Record<string, unknown> = {}
-      const allEvents: AIStreamEvent[] = []
+      const allEvents: AgentStreamEvent[] = []
       return async (services: any, event: any, next: any) => {
         allEvents.push(event)
         const result = await mw.modifyOutputStream!(services, {
@@ -837,13 +838,13 @@ export async function streamAIAgent(
           { channel: persistingChannel },
           singletonServices,
           allChannelMiddleware
-        ).channel as AIStreamChannel)
+        ).channel as AgentStreamChannel)
       : persistingChannel
 
-  const credentialFilteredChannel: AIStreamChannel = {
+  const credentialFilteredChannel: AgentStreamChannel = {
     ...wrappedChannel,
     // knowledge: decisions/internals/an-agent-stream-send-must-return-the-inner-sends-promise.md
-    send: (event: AIStreamEvent) => {
+    send: (event: AgentStreamEvent) => {
       if (
         event.type === 'tool-result' &&
         event.result !== null &&
@@ -864,7 +865,7 @@ export async function streamAIAgent(
   const outputChannel = isDelegateMode
     ? {
         ...credentialFilteredChannel,
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           if (
             delegateState.delegated &&
             (event.type === 'text-delta' || event.type === 'reasoning-delta')
@@ -885,7 +886,7 @@ export async function streamAIAgent(
       streamChannel: outputChannel,
       persistingChannel,
       channel,
-      aiMiddlewares,
+      agentMiddlewares,
     })
 
     if (loopResult.outcome === 'approval') {
@@ -893,7 +894,7 @@ export async function streamAIAgent(
         loopResult.approvals,
         runId,
         channel,
-        aiRunState,
+        agentRunState,
         persistingChannel
       )
       return persistingChannel.fullText
@@ -904,13 +905,13 @@ export async function streamAIAgent(
         loopResult.credentialRequests,
         runId,
         channel,
-        aiRunState,
+        agentRunState,
         persistingChannel
       )
       return persistingChannel.fullText
     }
 
-    await postStreamCleanup(persistingChannel, aiRunState, runId, {
+    await postStreamCleanup(persistingChannel, agentRunState, runId, {
       agentName,
       threadId,
       resourceId: input.resourceId,
@@ -927,7 +928,7 @@ export async function streamAIAgent(
     const interruption = interruptHandle.interruption
     if (interruption || isAbortError(err)) {
       await persistingChannel.flush({ interrupted: true })
-      await aiRunState.updateRun(runId, { status: 'interrupted' })
+      await agentRunState.updateRun(runId, { status: 'interrupted' })
       // Deliberately not awaited. A tool still running must not hold the stream
       // open — the whole point of barge-in is that the agent stops now — so the
       // note lands later and the next run on this thread waits for it instead.
@@ -948,7 +949,7 @@ export async function streamAIAgent(
       return persistingChannel.fullText
     }
 
-    for (const mw of aiMiddlewares) {
+    for (const mw of agentMiddlewares) {
       if (mw.onError) {
         try {
           await mw.onError(singletonServices, {
@@ -959,7 +960,7 @@ export async function streamAIAgent(
         } catch {}
       }
     }
-    await aiRunState.updateRun(runId, {
+    await agentRunState.updateRun(runId, {
       status: 'failed',
       errorMessage: err instanceof Error ? err.message : String(err),
     })
@@ -978,9 +979,9 @@ export async function streamAIAgent(
 /**
  * Stop an in-flight run on behalf of a caller, after checking the run is theirs.
  *
- * Unlike {@link resumeAIAgent} this needs no channel: it does not continue the
+ * Unlike {@link resumeAgent} this needs no channel: it does not continue the
  * stream, it ends one. The `interrupted` event and the truncated message are
- * emitted by the original {@link streamAIAgent} call on its own channel, so this
+ * emitted by the original {@link streamAgent} call on its own channel, so this
  * can be reached over a plain RPC while the stream is held open elsewhere —
  * which is exactly the shape a voice barge-in needs.
  *
@@ -993,16 +994,16 @@ export async function streamAIAgent(
  * Returns `false` when there was nothing to stop. Racing a run that finishes on
  * its own is the normal case in voice, so it is not an error.
  */
-export async function interruptAIAgent(
+export async function interruptAgent(
   input: { runId: string; reason?: AgentInterruption['reason'] },
-  params: RunAIAgentParams
+  params: RunAgentParams
 ): Promise<AgentInterruptResult> {
-  const { aiRunState, logger } = getSingletonServices()
-  if (!aiRunState) {
-    throw new Error('AIRunStateService not available in singletonServices')
+  const { agentRunState, logger } = getSingletonServices()
+  if (!agentRunState) {
+    throw new Error('AgentRunStateService not available in singletonServices')
   }
 
-  const run = await aiRunState.getRun(input.runId)
+  const run = await agentRunState.getRun(input.runId)
   if (!run) {
     throw new Error(`No run found for runId ${input.runId}`)
   }
@@ -1033,23 +1034,23 @@ export async function interruptAIAgent(
   return { stopped, inFlightTools: getInFlightTools(input.runId) }
 }
 
-export async function resumeAIAgent(
+export async function resumeAgent(
   input: {
     runId: string
     toolCallId: string
     approved: boolean
   },
-  channel: AIStreamChannel,
-  params: RunAIAgentParams,
-  options?: StreamAIAgentOptions
+  channel: AgentStreamChannel,
+  params: RunAgentParams,
+  options?: StreamAgentOptions
 ): Promise<void> {
   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(input.runId)
+  const run = await agentRunState.getRun(input.runId)
   if (!run) {
     throw new Error(`No run found for runId ${input.runId}`)
   }
@@ -1076,7 +1077,7 @@ export async function resumeAIAgent(
   // The read above is not a claim — concurrent resumes all see the same pending
   // approval. `resolveApproval` is the claim, and the loser must not go on to
   // run the tool a second time.
-  const claimed = await aiRunState.resolveApproval(
+  const claimed = await agentRunState.resolveApproval(
     input.toolCallId,
     input.approved ? 'approved' : 'denied'
   )
@@ -1088,14 +1089,14 @@ export async function resumeAIAgent(
 
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
-  const agentRunner = singletonServices.aiAgentRunner
+  const agentRunner = singletonServices.agentRunner
   if (!agentRunner) {
     throw new AIProviderNotConfiguredError()
   }
 
   if (!input.approved) {
     if (pending.type === 'agent-call') {
-      await aiRunState.updateRun(pending.agentRunId, { status: 'failed' })
+      await agentRunState.updateRun(pending.agentRunId, { status: 'failed' })
     }
 
     const denialResult =
@@ -1132,7 +1133,7 @@ export async function resumeAIAgent(
       result: denialResult,
     })
 
-    const updatedRun = await aiRunState.getRun(run.runId)
+    const updatedRun = await agentRunState.getRun(run.runId)
     const remaining = updatedRun?.pendingApprovals ?? []
 
     if (remaining.length > 0) {
@@ -1141,7 +1142,7 @@ export async function resumeAIAgent(
       return
     }
 
-    await aiRunState.updateRun(run.runId, { status: 'running' })
+    await agentRunState.updateRun(run.runId, { status: 'running' })
 
     await continueAfterToolResult(
       run,
@@ -1153,14 +1154,14 @@ export async function resumeAIAgent(
       agentRunner,
       channel,
       params,
-      aiRunState,
+      agentRunState,
       options
     )
     return
   }
 
   if (pending.type === 'agent-call') {
-    const subRun = await aiRunState.getRun(pending.agentRunId)
+    const subRun = await agentRunState.getRun(pending.agentRunId)
     if (!subRun) {
       throw new Error(`Sub-agent run not found: ${pending.agentRunId}`)
     }
@@ -1181,7 +1182,7 @@ export async function resumeAIAgent(
       input: null,
     })
 
-    await resumeAIAgent(
+    await resumeAgent(
       {
         runId: pending.agentRunId,
         toolCallId: subPending.toolCallId,
@@ -1220,8 +1221,8 @@ export async function resumeAIAgent(
       channel,
       options: { ...options, requiresToolApproval: false },
     }
-    const aiMiddlewaresForResume: PikkuAIMiddlewareHooks[] =
-      agent.aiMiddleware ?? []
+    const agentMiddlewaresForResume: PikkuAgentMiddlewareHooks[] =
+      agent.agentMiddleware ?? []
     const { tools } = await buildToolDefs(
       params,
       new Map<string, string>(),
@@ -1229,7 +1230,7 @@ export async function resumeAIAgent(
       resolvedName,
       packageName,
       streamContext,
-      aiMiddlewaresForResume
+      agentMiddlewaresForResume
     )
 
     const matchingTool = tools.find((t) => t.name === pending.toolName)
@@ -1284,7 +1285,7 @@ export async function resumeAIAgent(
     })
   }
 
-  const updatedRun = await aiRunState.getRun(run.runId)
+  const updatedRun = await agentRunState.getRun(run.runId)
   const remaining = updatedRun?.pendingApprovals ?? []
 
   if (remaining.length > 0) {
@@ -1293,7 +1294,7 @@ export async function resumeAIAgent(
     return
   }
 
-  await aiRunState.updateRun(run.runId, { status: 'running' })
+  await agentRunState.updateRun(run.runId, { status: 'running' })
 
   await continueAfterToolResult(
     run,
@@ -1305,23 +1306,23 @@ export async function resumeAIAgent(
     agentRunner,
     channel,
     params,
-    aiRunState,
+    agentRunState,
     options
   )
 }
 
 async function continueAfterToolResult(
   run: AgentRunState,
-  agent: CoreAIAgent,
+  agent: CoreAgent,
   packageName: string | null,
   resolvedName: string,
-  storage: AIStorageService | undefined,
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  agentRunner: AIAgentRunnerService,
-  channel: AIStreamChannel,
-  params: RunAIAgentParams,
-  aiRunState: AIRunStateService,
-  options?: StreamAIAgentOptions
+  storage: AgentStorageService | undefined,
+  memoryConfig: AgentMemoryConfig | undefined,
+  agentRunner: AgentRunnerService,
+  channel: AgentStreamChannel,
+  params: RunAgentParams,
+  agentRunState: AgentRunStateService,
+  options?: StreamAgentOptions
 ): Promise<void> {
   const singletonServices = getSingletonServices()
   const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
@@ -1350,21 +1351,21 @@ async function continueAfterToolResult(
 
   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
@@ -1375,15 +1376,15 @@ async function continueAfterToolResult(
 
   warnUnstreamedOutputHooks(
     run.agentName,
-    aiMiddlewares,
+    agentMiddlewares,
     singletonServices.logger
   )
 
-  const streamMiddleware = aiMiddlewares
+  const streamMiddleware = agentMiddlewares
     .filter((mw) => mw.modifyOutputStream)
     .map((mw) => {
       const state: Record<string, unknown> = {}
-      const allEvents: AIStreamEvent[] = []
+      const allEvents: AgentStreamEvent[] = []
       return async (services: any, event: any, next: any) => {
         allEvents.push(event)
         const result = await mw.modifyOutputStream!(services, {
@@ -1430,7 +1431,7 @@ async function continueAfterToolResult(
           { channel: persistingChannel },
           singletonServices,
           allChannelMiddleware
-        ).channel as AIStreamChannel)
+        ).channel as AgentStreamChannel)
       : persistingChannel
 
   const streamContext: StreamContext = { channel, options }
@@ -1442,14 +1443,14 @@ async function continueAfterToolResult(
       resolvedName,
       packageName,
       streamContext,
-      aiMiddlewares
+      agentMiddlewares
     )
   ).tools
 
   const resolved = resolveModelConfig(resolvedName, agent)
   const maxSteps = resolved.maxSteps ?? 10
 
-  const runnerParams: AIAgentRunnerParams = {
+  const runnerParams: AgentRunnerParams = {
     model: resolved.model,
     temperature: resolved.temperature,
     instructions: modifiedInstructions,
@@ -1475,7 +1476,7 @@ async function continueAfterToolResult(
       streamChannel: wrappedChannel,
       persistingChannel,
       channel,
-      aiMiddlewares,
+      agentMiddlewares,
     })
 
     if (loopResult.outcome === 'approval') {
@@ -1483,7 +1484,7 @@ async function continueAfterToolResult(
         loopResult.approvals,
         run.runId,
         channel,
-        aiRunState,
+        agentRunState,
         persistingChannel
       )
       return
@@ -1494,13 +1495,13 @@ async function continueAfterToolResult(
         loopResult.credentialRequests,
         run.runId,
         channel,
-        aiRunState,
+        agentRunState,
         persistingChannel
       )
       return
     }
 
-    await postStreamCleanup(persistingChannel, aiRunState, run.runId, {
+    await postStreamCleanup(persistingChannel, agentRunState, run.runId, {
       ...run,
       input: lastUserMessageText(runnerParams.messages),
     })
@@ -1514,7 +1515,7 @@ async function continueAfterToolResult(
     const interruption = interruptHandle.interruption
     if (interruption || isAbortError(err)) {
       await persistingChannel.flush({ interrupted: true })
-      await aiRunState.updateRun(run.runId, { status: 'interrupted' })
+      await agentRunState.updateRun(run.runId, { status: 'interrupted' })
       if (storage) {
         trackInterruptNote(
           run.threadId,
@@ -1532,7 +1533,7 @@ async function continueAfterToolResult(
       return
     }
 
-    for (const mw of aiMiddlewares) {
+    for (const mw of agentMiddlewares) {
       if (mw.onError) {
         try {
           await mw.onError(singletonServices, {
@@ -1543,7 +1544,7 @@ async function continueAfterToolResult(
         } catch {}
       }
     }
-    await aiRunState.updateRun(run.runId, {
+    await agentRunState.updateRun(run.runId, {
       status: 'failed',
       errorMessage: err instanceof Error ? err.message : String(err),
     })