@pikku/core 0.12.83 → 0.12.86

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

@@ -6,29 +6,29 @@ import {
   appendStepMessages,
   checkForApprovals,
   checkForCredentialRequests,
-  resumeAIAgent,
-  streamAIAgent,
-} from './ai-agent-stream.js'
+  resumeAgent,
+  streamAgent,
+} from './agent-stream.js'
 import {
   ToolApprovalRequired,
   APPROVAL_REQUIRED,
   CREDENTIAL_REQUIRED,
-} from './ai-agent-prepare.js'
+} from './agent-prepare.js'
 import type {
   AgentRunState,
-  CoreAIAgent,
-  AIStreamEvent,
-  AIMessage,
-  PikkuAIMiddlewareHooks,
-} from './ai-agent.types.js'
-import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+  CoreAgent,
+  AgentStreamEvent,
+  AgentMessage,
+  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',
@@ -45,8 +45,8 @@ const addTestAgent = (agentName: string) => {
 }
 
 const makeStepResult = (
-  overrides?: Partial<AIAgentStepResult>
-): AIAgentStepResult => ({
+  overrides?: Partial<AgentStepResult>
+): AgentStepResult => ({
   text: '',
   toolCalls: [],
   toolResults: [],
@@ -55,12 +55,12 @@ const makeStepResult = (
   ...overrides,
 })
 
-describe('streamAIAgent', () => {
+describe('streamAgent', () => {
   test('marks run as failed and emits error/done when stream runner throws', async () => {
     addTestAgent('failing-stream-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -69,12 +69,12 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async () => {
           throw new Error('stream failed')
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-1',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -84,7 +84,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'failing-stream-agent',
       {
         message: 'hello',
@@ -95,7 +95,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-1',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -119,7 +119,7 @@ describe('streamAIAgent', () => {
     addTestAgent('simple-stream-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -128,12 +128,12 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           return makeStepResult({ text: 'Hello world' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-simple',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -143,7 +143,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'simple-stream-agent',
       {
         message: 'hello',
@@ -154,7 +154,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-simple',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -175,10 +175,10 @@ describe('streamAIAgent', () => {
       description: 'test agent',
       instructions: 'be helpful',
       model: 'test/test-model',
-    } as CoreAIAgent)
+    } as CoreAgent)
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -187,11 +187,11 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> =>
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> =>
           makeStepResult({ text: 'Hello world' }),
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-no-meta',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -201,7 +201,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       agentName,
       {
         message: 'hello',
@@ -212,7 +212,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-no-meta',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -234,7 +234,7 @@ describe('streamAIAgent', () => {
     addTestAgent('approval-stream-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -243,8 +243,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           return makeStepResult({
             toolCalls: [
               {
@@ -256,7 +256,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-2',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -281,7 +281,7 @@ describe('streamAIAgent', () => {
       properties: { id: { type: 'number' } },
     })
 
-    await streamAIAgent(
+    await streamAgent(
       agentName,
       {
         message: 'hello',
@@ -292,7 +292,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-2',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -340,7 +340,7 @@ describe('streamAIAgent', () => {
     addTestAgent('multi-approval-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -349,8 +349,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           return makeStepResult({
             toolCalls: [
               {
@@ -372,7 +372,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-multi-approval',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -398,7 +398,7 @@ describe('streamAIAgent', () => {
       properties: { title: { type: 'string' } },
     })
 
-    await streamAIAgent(
+    await streamAgent(
       agentName,
       {
         message: 'create 3 todos',
@@ -409,7 +409,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-multi-approval',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -436,7 +436,7 @@ describe('streamAIAgent', () => {
     addTestAgent('addon-approval-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -445,8 +445,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (params: any): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (params: any): Promise<AgentStepResult> => {
           const addTodoTool = params.tools.find(
             (t: any) => t.name === 'todos__addTodo'
           )
@@ -468,7 +468,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-addon-approval',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -496,7 +496,7 @@ describe('streamAIAgent', () => {
     const agentName = 'addon-approval-agent'
     pikkuState(null, 'agent', 'agentsMeta')[agentName].tools = ['todos:addTodo']
 
-    await streamAIAgent(
+    await streamAgent(
       agentName,
       {
         message: 'add a todo',
@@ -507,7 +507,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-addon-approval',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -536,7 +536,7 @@ describe('streamAIAgent', () => {
     ]
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -545,8 +545,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           return makeStepResult({
             toolCalls: [
               {
@@ -573,7 +573,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-3',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -583,7 +583,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'parent-agent',
       {
         message: 'hello',
@@ -594,7 +594,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-3',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -635,7 +635,7 @@ describe('streamAIAgent', () => {
     addTestAgent('multi-step-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     let callCount = 0
 
     const mockServices = {
@@ -645,8 +645,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           callCount++
           if (callCount === 1) {
             return makeStepResult({
@@ -667,7 +667,7 @@ describe('streamAIAgent', () => {
           return makeStepResult({ text: 'Final answer', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-multi',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -677,7 +677,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'multi-step-agent',
       {
         message: 'hello',
@@ -688,7 +688,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-multi',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         close: () => {},
@@ -707,7 +707,7 @@ describe('streamAIAgent', () => {
     addTestAgent('afterstep-stream-agent')
 
     const afterStepCalls: unknown[] = []
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       afterStep: async (_services, ctx) => {
         afterStepCalls.push(ctx)
       },
@@ -715,11 +715,11 @@ describe('streamAIAgent', () => {
     const agent = pikkuState(null, 'agent', 'agents').get(
       'afterstep-stream-agent'
     )!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     pikkuState(null, 'agent', 'agents').set('afterstep-stream-agent', agent)
 
     let callCount = 0
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -728,8 +728,8 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => {
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => {
           callCount++
           if (callCount === 1) {
             return makeStepResult({
@@ -750,7 +750,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-as',
         updateRun: async () => {},
       },
@@ -758,14 +758,14 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'afterstep-stream-agent',
       { message: 'hi', threadId: 't-as', resourceId: 'r-as' },
       {
         channelId: 'c-as',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       {}
@@ -782,7 +782,7 @@ describe('streamAIAgent', () => {
     addTestAgent('onerror-stream-agent')
 
     const onErrorCalls: unknown[] = []
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       onError: async (_services, ctx) => {
         onErrorCalls.push(ctx)
       },
@@ -790,10 +790,10 @@ describe('streamAIAgent', () => {
     const agent = pikkuState(null, 'agent', 'agents').get(
       'onerror-stream-agent'
     )!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     pikkuState(null, 'agent', 'agents').set('onerror-stream-agent', agent)
 
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     const mockServices = {
       logger: {
         info: () => {},
@@ -801,12 +801,12 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async () => {
           throw new Error('stream boom')
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-oe',
         updateRun: async () => {},
       },
@@ -814,14 +814,14 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'onerror-stream-agent',
       { message: 'hi', threadId: 't-oe', resourceId: 'r-oe' },
       {
         channelId: 'c-oe',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       {}
@@ -837,7 +837,7 @@ describe('streamAIAgent', () => {
     addTestAgent('toolhooks-stream-agent')
 
     const hookCalls: { hook: string; ctx: any }[] = []
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       beforeToolCall: async (_services, ctx) => {
         hookCalls.push({ hook: 'before', ctx })
         return { args: { ...ctx.args, injected: true } }
@@ -849,7 +849,7 @@ describe('streamAIAgent', () => {
     }
     const agentName = 'toolhooks-stream-agent'
     const agent = pikkuState(null, 'agent', 'agents').get(agentName)!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     agent.tools = ['myTool']
     pikkuState(null, 'agent', 'agents').set(agentName, agent)
     pikkuState(null, 'agent', 'agentsMeta')[agentName].tools = ['myTool']
@@ -858,7 +858,7 @@ describe('streamAIAgent', () => {
       description: 'test tool',
     }
 
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     let callCount = 0
 
     const mockServices = {
@@ -868,11 +868,11 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
           params: any,
           _channel: any
-        ): Promise<AIAgentStepResult> => {
+        ): Promise<AgentStepResult> => {
           callCount++
           if (callCount === 1) {
             const tool = params.tools.find((t: any) => t.name === 'myTool')
@@ -889,7 +889,7 @@ describe('streamAIAgent', () => {
           return makeStepResult({ text: 'done', finishReason: 'stop' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-th',
         updateRun: async () => {},
       },
@@ -898,14 +898,14 @@ describe('streamAIAgent', () => {
     pikkuState(null, 'package', 'singletonServices', mockServices)
     pikkuState(null, 'package', 'createWireServices', () => ({}))
 
-    await streamAIAgent(
+    await streamAgent(
       agentName,
       { message: 'hi', threadId: 't-th', resourceId: 'r-th' },
       {
         channelId: 'c-th',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       {}
@@ -925,7 +925,7 @@ describe('streamAIAgent', () => {
     addTestAgent('credential-stream-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     const mockServices = {
       logger: {
@@ -934,11 +934,11 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
           _params: unknown,
-          streamChannel: AIStreamChannel | null
-        ): Promise<AIAgentStepResult> => {
+          streamChannel: AgentStreamChannel | null
+        ): Promise<AgentStepResult> => {
           const credentialResult = {
             [CREDENTIAL_REQUIRED]: true,
             __credentialRequired: true,
@@ -966,7 +966,7 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-cred',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
@@ -976,7 +976,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await streamAIAgent(
+    await streamAgent(
       'credential-stream-agent',
       {
         message: 'connect',
@@ -987,7 +987,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-cred',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       {}
@@ -1038,12 +1038,13 @@ describe('streamAIAgent', () => {
   test('persists streamed events, applies output stream middleware, and updates usage', async () => {
     addTestAgent('persisted-stream-agent')
 
-    const events: AIStreamEvent[] = []
-    const savedMessages: Array<{ threadId: string; messages: AIMessage[] }> = []
+    const events: AgentStreamEvent[] = []
+    const savedMessages: Array<{ threadId: string; messages: AgentMessage[] }> =
+      []
     const updates: Array<{ runId: string; patch: unknown }> = []
     const middlewareStateSnapshots: number[] = []
 
-    const middleware: PikkuAIMiddlewareHooks = {
+    const middleware: PikkuAgentMiddlewareHooks = {
       modifyOutputStream: async (_services, ctx) => {
         const count = Number((ctx.state.count as number | undefined) ?? 0) + 1
         ctx.state.count = count
@@ -1051,7 +1052,10 @@ describe('streamAIAgent', () => {
         if (ctx.event.type === 'text-delta') {
           return [
             ctx.event,
-            { type: 'reasoning-delta', text: `seen:${count}` } as AIStreamEvent,
+            {
+              type: 'reasoning-delta',
+              text: `seen:${count}`,
+            } as AgentStreamEvent,
           ]
         }
         return ctx.event
@@ -1064,7 +1068,7 @@ describe('streamAIAgent', () => {
     const agent = pikkuState(null, 'agent', 'agents').get(
       'persisted-stream-agent'
     )!
-    agent.aiMiddleware = [middleware] as any
+    agent.agentMiddleware = [middleware] as any
     pikkuState(null, 'agent', 'agents').set('persisted-stream-agent', agent)
 
     const mockServices = {
@@ -1074,11 +1078,11 @@ describe('streamAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
           _params: any,
           channel: any
-        ): Promise<AIAgentStepResult> => {
+        ): Promise<AgentStepResult> => {
           channel.send({ type: 'text-delta', text: 'Hello' })
           channel.send({
             type: 'tool-call',
@@ -1096,7 +1100,7 @@ describe('streamAIAgent', () => {
             type: 'usage',
             tokens: { input: 3, output: 4 },
             model: 'test/test-model',
-          } as AIStreamEvent)
+          } as AgentStreamEvent)
           return makeStepResult({
             text: 'Hello',
             usage: { inputTokens: 3, outputTokens: 4 },
@@ -1104,16 +1108,16 @@ describe('streamAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-persisted',
         updateRun: async (runId: string, patch: unknown) => {
           updates.push({ runId, patch })
         },
       },
-      aiStorage: {
+      agentStorage: {
         createThread: async () => {},
         getMessages: async () => [],
-        saveMessages: async (threadId: string, messages: AIMessage[]) => {
+        saveMessages: async (threadId: string, messages: AgentMessage[]) => {
           savedMessages.push({ threadId, messages })
         },
       },
@@ -1121,7 +1125,7 @@ describe('streamAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    const result = await streamAIAgent(
+    const result = await streamAgent(
       'persisted-stream-agent',
       {
         message: 'hello',
@@ -1132,7 +1136,7 @@ describe('streamAIAgent', () => {
         channelId: 'channel-persisted',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       {}
@@ -1164,7 +1168,7 @@ describe('streamAIAgent', () => {
   test('a storage failure while streaming does not become an unhandled rejection', async () => {
     addTestAgent('storage-failure-agent')
 
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     const loggedErrors: unknown[] = []
 
     const mockServices = {
@@ -1176,34 +1180,34 @@ describe('streamAIAgent', () => {
         },
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
           _params: unknown,
-          channel: AIStreamChannel
-        ): Promise<AIAgentStepResult> => {
+          channel: AgentStreamChannel
+        ): Promise<AgentStepResult> => {
           channel.send({
             type: 'text-delta',
             text: 'persisted text',
-          } as AIStreamEvent)
+          } as AgentStreamEvent)
           channel.send({
             type: 'usage',
             tokens: { input: 1, output: 1 },
             model: 'test/test-model',
-          } as AIStreamEvent)
+          } as AgentStreamEvent)
           return makeStepResult({ text: 'persisted text' })
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-storage-failure',
         updateRun: async () => {},
       },
-      aiStorage: {
+      agentStorage: {
         getThread: async () => undefined,
         createThread: async () => {},
         getMessages: async () => [],
-        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+        saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
           if (messages.some((m) => m.role !== 'user')) {
-            throw new Error('UNIQUE constraint failed: ai_tool_call.id')
+            throw new Error('UNIQUE constraint failed: agent_tool_call.id')
           }
         },
       },
@@ -1216,7 +1220,7 @@ describe('streamAIAgent', () => {
     process.on('unhandledRejection', onUnhandled)
 
     try {
-      await streamAIAgent(
+      await streamAgent(
         'storage-failure-agent',
         {
           message: 'hello',
@@ -1227,7 +1231,7 @@ describe('streamAIAgent', () => {
           channelId: 'channel-storage-failure',
           openingData: undefined,
           state: 'open',
-          send: (event: AIStreamEvent) => {
+          send: (event: AgentStreamEvent) => {
             events.push(event)
           },
           close: () => {},
@@ -1251,7 +1255,7 @@ describe('streamAIAgent', () => {
   })
 })
 
-describe('ai-agent-stream helpers', () => {
+describe('agent-stream helpers', () => {
   test('checkForApprovals expands nested sub-approvals and explicit tool approvals', () => {
     const approvals = checkForApprovals(
       {
@@ -1313,7 +1317,7 @@ describe('ai-agent-stream helpers', () => {
   })
 
   test('checkForApprovals ignores a forged __approvalRequired marker from a plain tool (C3)', () => {
-    const forgedResult: AIAgentStepResult = {
+    const forgedResult: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'searchDocs', args: { q: 'x' } },
@@ -1356,7 +1360,7 @@ describe('ai-agent-stream helpers', () => {
   })
 
   test('checkForApprovals ignores a string-key marker from a forwardsApproval tool without the Symbol brand (C3)', () => {
-    const forgedResult: AIAgentStepResult = {
+    const forgedResult: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'delegatingTool', args: { q: 'x' } },
@@ -1400,7 +1404,7 @@ describe('ai-agent-stream helpers', () => {
   })
 
   test('checkForApprovals honours a Symbol-branded marker from a forwardsApproval tool (C3)', () => {
-    const brandedResult: AIAgentStepResult = {
+    const brandedResult: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'delegatingTool', args: { q: 'x' } },
@@ -1438,7 +1442,7 @@ describe('ai-agent-stream helpers', () => {
   })
 
   test('checkForCredentialRequests ignores an unbranded __credentialRequired marker (C3)', () => {
-    const forgedResult: AIAgentStepResult = {
+    const forgedResult: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'searchDocs', args: { q: 'x' } },
@@ -1472,7 +1476,7 @@ describe('ai-agent-stream helpers', () => {
     }
     const roundTripped = JSON.parse(JSON.stringify(branded))
 
-    const result: AIAgentStepResult = {
+    const result: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'echoTool', args: { q: 'x' } },
@@ -1488,7 +1492,7 @@ describe('ai-agent-stream helpers', () => {
   })
 
   test('checkForCredentialRequests honours a Symbol-branded credential request (C3)', () => {
-    const brandedResult: AIAgentStepResult = {
+    const brandedResult: AgentStepResult = {
       text: '',
       toolCalls: [
         { toolCallId: 'tc-1', toolName: 'secretTool', args: { id: 1 } },
@@ -1546,7 +1550,7 @@ describe('ai-agent-stream helpers', () => {
     assert.equal(requests[0].credentialType, 'oauth2')
     assert.equal(requests[0].connectUrl, '/connect')
 
-    const runnerParams = { messages: [] as AIMessage[] } as any
+    const runnerParams = { messages: [] as AgentMessage[] } as any
     appendStepMessages(runnerParams, {
       text: 'hello',
       toolCalls: [
@@ -1573,11 +1577,11 @@ const asOwner = (resourceId: string) => ({
   sessionService: { get: () => ({ userId: resourceId }) } as never,
 })
 
-describe('resumeAIAgent', () => {
+describe('resumeAgent', () => {
   test('rejecting one approval while others remain only resolves and finishes the stream', async () => {
     addTestAgent('resume-stream-agent')
 
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     const updates: any[] = []
     const resolveCalls: any[] = []
     const savedMessages: any[] = []
@@ -1620,12 +1624,12 @@ describe('resumeAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async () => {
           throw new Error('should not continue')
         },
       },
-      aiRunState: {
+      agentRunState: {
         getRun: async () => remainingRun,
         resolveApproval: async (toolCallId: string, status: string) => {
           resolveCalls.push({ toolCallId, status })
@@ -1635,15 +1639,15 @@ describe('resumeAIAgent', () => {
           updates.push(patch)
         },
       },
-      aiStorage: {
-        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+      agentStorage: {
+        saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
           savedMessages.push(messages)
         },
       },
     } as any
 
     let first = true
-    mockServices.aiRunState.getRun = async () => {
+    mockServices.agentRunState.getRun = async () => {
       if (first) {
         first = false
         return initialRun
@@ -1653,13 +1657,13 @@ describe('resumeAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await resumeAIAgent(
+    await resumeAgent(
       { runId: 'run-1', toolCallId: 'tool-1', approved: false },
       {
         channelId: 'resume-channel',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       asOwner('resource-1')
@@ -1693,7 +1697,7 @@ describe('resumeAIAgent', () => {
       func: async (_services: any, input: any) => ({ deployed: input.env }),
     })
 
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     const updates: any[] = []
     const resolveCalls: any[] = []
     const savedMessages: any[] = []
@@ -1726,17 +1730,17 @@ describe('resumeAIAgent', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
           _params: any,
           channel: any
-        ): Promise<AIAgentStepResult> => {
+        ): Promise<AgentStepResult> => {
           channel.send({ type: 'text-delta', text: 'continued' })
           channel.send({
             type: 'usage',
             tokens: { input: 2, output: 3 },
             model: 'test/test-model',
-          } as AIStreamEvent)
+          } as AgentStreamEvent)
           return makeStepResult({
             text: 'continued',
             usage: { inputTokens: 2, outputTokens: 3 },
@@ -1744,7 +1748,7 @@ describe('resumeAIAgent', () => {
           })
         },
       },
-      aiRunState: {
+      agentRunState: {
         getRun: async () => {
           getRunCalls++
           return getRunCalls === 1 ? run : { ...run, pendingApprovals: [] }
@@ -1757,8 +1761,8 @@ describe('resumeAIAgent', () => {
           updates.push(patch)
         },
       },
-      aiStorage: {
-        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+      agentStorage: {
+        saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
           savedMessages.push(messages)
         },
         getMessages: async () => [],
@@ -1767,13 +1771,13 @@ describe('resumeAIAgent', () => {
 
     pikkuState(null, 'package', 'singletonServices', mockServices)
 
-    await resumeAIAgent(
+    await resumeAgent(
       { runId: 'run-approve', toolCallId: 'tool-1', approved: true },
       {
         channelId: 'resume-channel',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       },
       asOwner('resource-approve')