@pikku/core 0.12.82 → 0.12.84

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

@@ -2,12 +2,8 @@ import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import {
-  interruptAIAgent,
-  resumeAIAgent,
-  streamAIAgent,
-} from './ai-agent-stream.js'
-import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js'
+import { interruptAgent, resumeAgent, streamAgent } from './agent-stream.js'
+import { runAgent, resumeAgentSync } from './agent-runner.js'
 import {
   AgentInterruptedError,
   awaitPendingInterruptNote,
@@ -17,25 +13,25 @@ import {
   registerInterruptibleRun,
   signalRunInterrupt,
   trackToolExecution,
-} from './ai-agent-interrupt.js'
+} from './agent-interrupt.js'
 import { AbandonedError, beginChanges } from '../../function/abort-scope.js'
 import type {
   AgentRunState,
-  AIMessage,
-  AIStreamEvent,
-  CoreAIAgent,
-} from './ai-agent.types.js'
+  AgentMessage,
+  AgentStreamEvent,
+  CoreAgent,
+} from './agent.types.js'
 import type {
-  AIAgentRunnerParams,
-  AIAgentStepResult,
-} from '../../services/ai-agent-runner-service.js'
+  AgentRunnerParams,
+  AgentStepResult,
+} from '../../services/agent-runner-service.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
 const addTestAgent = (agentName: string) => {
-  const agent: CoreAIAgent = {
+  const agent: CoreAgent = {
     name: agentName,
     description: 'test agent',
     goal: 'be helpful',
@@ -62,9 +58,9 @@ const abortError = () => {
  */
 const interruptingRunner = (getRunId: () => string | undefined) => ({
   stream: async (
-    params: AIAgentRunnerParams,
-    channel: { send: (event: AIStreamEvent) => void }
-  ): Promise<AIAgentStepResult> => {
+    params: AgentRunnerParams,
+    channel: { send: (event: AgentStreamEvent) => void }
+  ): Promise<AgentStepResult> => {
     channel.send({ type: 'text-delta', text: 'I will delete the staging ' })
     const runId = getRunId()
     assert.ok(runId, 'run should exist before the model call')
@@ -80,7 +76,7 @@ describe('agent interruption', () => {
     addTestAgent('interrupted-agent')
 
     const updates: Array<{ runId: string; patch: unknown }> = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     let runId: string | undefined
 
     pikkuState(null, 'package', 'singletonServices', {
@@ -90,8 +86,8 @@ describe('agent interruption', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: interruptingRunner(() => runId),
-      aiRunState: {
+      agentRunner: interruptingRunner(() => runId),
+      agentRunState: {
         createRun: async () => 'run-interrupted',
         updateRun: async (id: string, patch: unknown) => {
           updates.push({ runId: id, patch })
@@ -99,7 +95,7 @@ describe('agent interruption', () => {
       },
     } as any)
 
-    const text = await streamAIAgent(
+    const text = await streamAgent(
       'interrupted-agent',
       {
         message: 'delete staging',
@@ -110,7 +106,7 @@ describe('agent interruption', () => {
         channelId: 'channel-int',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       } as any,
       {},
@@ -144,7 +140,7 @@ describe('agent interruption', () => {
   test('persists the truncated reply marked as interrupted', async () => {
     addTestAgent('interrupted-persisting-agent')
 
-    const saved: AIMessage[] = []
+    const saved: AgentMessage[] = []
     let runId: string | undefined
 
     pikkuState(null, 'package', 'singletonServices', {
@@ -154,21 +150,21 @@ describe('agent interruption', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: interruptingRunner(() => runId),
-      aiRunState: {
+      agentRunner: interruptingRunner(() => runId),
+      agentRunState: {
         createRun: async () => 'run-persist-int',
         updateRun: async () => {},
       },
-      aiStorage: {
+      agentStorage: {
         createThread: async () => {},
         getMessages: async () => [],
-        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+        saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
           saved.push(...messages)
         },
       },
     } as any)
 
-    await streamAIAgent(
+    await streamAgent(
       'interrupted-persisting-agent',
       {
         message: 'delete staging',
@@ -209,8 +205,8 @@ describe('agent interruption', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
-        stream: async (): Promise<AIAgentStepResult> => ({
+      agentRunner: {
+        stream: async (): Promise<AgentStepResult> => ({
           text: 'done',
           toolCalls: [],
           toolResults: [],
@@ -218,13 +214,13 @@ describe('agent interruption', () => {
           finishReason: 'stop',
         }),
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-released',
         updateRun: async () => {},
       },
     } as any)
 
-    await streamAIAgent(
+    await streamAgent(
       'released-agent',
       { message: 'hi', threadId: 't', resourceId: 'r' },
       {
@@ -279,7 +275,7 @@ describe('tool results that outlive an interrupt', () => {
   test('a tool still running when the user cuts in is kept, not dropped', async () => {
     addTestAgent('tool-interrupt-agent')
 
-    const saved: AIMessage[] = []
+    const saved: AgentMessage[] = []
     let runId: string | undefined
     let releaseTool: (value: string) => void
     const toolFinished = new Promise<string>((resolve) => {
@@ -294,11 +290,11 @@ describe('tool results that outlive an interrupt', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: {
+      agentRunner: {
         stream: async (
-          params: AIAgentRunnerParams,
-          channel: { send: (event: AIStreamEvent) => void }
-        ): Promise<AIAgentStepResult> => {
+          params: AgentRunnerParams,
+          channel: { send: (event: AgentStreamEvent) => void }
+        ): Promise<AgentStepResult> => {
           // The agent kicks off a deploy and starts narrating it; the user talks
           // over the narration while the deploy is still running.
           const tool = params.tools[0]
@@ -311,20 +307,20 @@ describe('tool results that outlive an interrupt', () => {
           throw abortError()
         },
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-tool-int',
         updateRun: async () => {},
       },
-      aiStorage: {
+      agentStorage: {
         createThread: async () => {},
         getMessages: async () => [],
-        saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+        saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
           saved.push(...messages)
         },
       },
     } as any)
 
-    await streamAIAgent(
+    await streamAgent(
       'tool-interrupt-agent',
       { message: 'deploy staging', threadId: 'thread-tool', resourceId: 'r' },
       {
@@ -457,7 +453,7 @@ describe('tool results that outlive an interrupt', () => {
 
 /**
  * The non-streaming path (`rpc.agent.run` / `rpc.agent.approve`) creates runs
- * through the same `aiRunState`, so `interruptAIAgent` resolves and authorizes
+ * through the same `agentRunState`, so `interruptAgent` resolves and authorizes
  * them either way. If it did not also register an abort controller, that call
  * would pass the ownership check, fail to stop anything, and — because the run
  * is still marked `running` — report it as executing on another instance.
@@ -471,7 +467,7 @@ describe('non-streaming agent interruption', () => {
   }
 
   const interruptingSyncRunner = (runId: string) => ({
-    run: async (params: AIAgentRunnerParams): Promise<AIAgentStepResult> => {
+    run: async (params: AgentRunnerParams): Promise<AgentStepResult> => {
       assert.ok(params.abortSignal, 'the runner must receive an abort signal')
       assert.equal(
         isRunInterruptible(runId),
@@ -484,14 +480,14 @@ describe('non-streaming agent interruption', () => {
     },
   })
 
-  test('runAIAgent reports an interrupt as an interrupt, not a failure', async () => {
+  test('runAgent reports an interrupt as an interrupt, not a failure', async () => {
     addTestAgent('sync-agent')
 
     const updates: unknown[] = []
     pikkuState(null, 'package', 'singletonServices', {
       logger,
-      aiAgentRunner: interruptingSyncRunner('run-sync-int'),
-      aiRunState: {
+      agentRunner: interruptingSyncRunner('run-sync-int'),
+      agentRunState: {
         createRun: async () => 'run-sync-int',
         updateRun: async (_runId: string, patch: unknown) => {
           updates.push(patch)
@@ -501,7 +497,7 @@ describe('non-streaming agent interruption', () => {
 
     await assert.rejects(
       () =>
-        runAIAgent(
+        runAgent(
           'sync-agent',
           { message: 'delete staging', threadId: 't', resourceId: 'r' },
           {}
@@ -525,8 +521,8 @@ describe('non-streaming agent interruption', () => {
 
     pikkuState(null, 'package', 'singletonServices', {
       logger,
-      aiAgentRunner: {
-        run: async (): Promise<AIAgentStepResult> => ({
+      agentRunner: {
+        run: async (): Promise<AgentStepResult> => ({
           text: 'done',
           toolCalls: [],
           toolResults: [],
@@ -534,13 +530,13 @@ describe('non-streaming agent interruption', () => {
           finishReason: 'stop',
         }),
       },
-      aiRunState: {
+      agentRunState: {
         createRun: async () => 'run-sync-clean',
         updateRun: async () => {},
       },
     } as any)
 
-    await runAIAgent(
+    await runAgent(
       'sync-clean-agent',
       { message: 'hi', threadId: 't', resourceId: 'r' },
       {}
@@ -567,8 +563,8 @@ describe('non-streaming agent interruption', () => {
     const updates: unknown[] = []
     pikkuState(null, 'package', 'singletonServices', {
       logger,
-      aiAgentRunner: interruptingSyncRunner('run-sync-resume'),
-      aiRunState: {
+      agentRunner: interruptingSyncRunner('run-sync-resume'),
+      agentRunState: {
         getRun: async () => run,
         createRun: async () => 'unused',
         updateRun: async (_runId: string, patch: unknown) => {
@@ -580,7 +576,7 @@ describe('non-streaming agent interruption', () => {
 
     await assert.rejects(
       () =>
-        resumeAIAgentSync('run-sync-resume', [], {
+        resumeAgentSync('run-sync-resume', [], {
           sessionService: { get: () => ({ userId: 'resource-sync-resume' }) },
         } as any),
       (error: unknown) => error instanceof AgentInterruptedError
@@ -628,7 +624,7 @@ describe('streaming resume interruption', () => {
     }
 
     const updates: unknown[] = []
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
 
     pikkuState(null, 'package', 'singletonServices', {
       logger: {
@@ -637,8 +633,8 @@ describe('streaming resume interruption', () => {
         error: () => {},
         debug: () => {},
       },
-      aiAgentRunner: interruptingRunner(() => run.runId),
-      aiRunState: {
+      agentRunner: interruptingRunner(() => run.runId),
+      agentRunState: {
         getRun: async () => run,
         createRun: async () => run.runId,
         updateRun: async (_runId: string, patch: unknown) => {
@@ -653,13 +649,13 @@ describe('streaming resume interruption', () => {
       },
     } as any)
 
-    await resumeAIAgent(
+    await resumeAgent(
       { runId: run.runId, toolCallId: 'call-1', approved: true },
       {
         channelId: 'channel-resume',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => events.push(event),
+        send: (event: AgentStreamEvent) => events.push(event),
         close: () => {},
       } as any,
       {
@@ -685,7 +681,7 @@ describe('streaming resume interruption', () => {
   })
 })
 
-describe('interruptAIAgent authorization', () => {
+describe('interruptAgent authorization', () => {
   const withRun = (run: Record<string, unknown> | null) => {
     pikkuState(null, 'package', 'singletonServices', {
       logger: {
@@ -694,7 +690,7 @@ describe('interruptAIAgent authorization', () => {
         error: () => {},
         debug: () => {},
       },
-      aiRunState: { getRun: async () => run },
+      agentRunState: { getRun: async () => run },
     } as any)
   }
 
@@ -713,7 +709,7 @@ describe('interruptAIAgent authorization', () => {
 
     const handle = registerInterruptibleRun('run-alice')
     await assert.rejects(
-      () => interruptAIAgent({ runId: 'run-alice' }, session('mallory') as any),
+      () => interruptAgent({ runId: 'run-alice' }, session('mallory') as any),
       /Not authorized to access this run/
     )
     // The gate has to hold before the abort, not after it.
@@ -732,7 +728,7 @@ describe('interruptAIAgent authorization', () => {
 
     const handle = registerInterruptibleRun('run-alice-2')
     await assert.rejects(
-      () => interruptAIAgent({ runId: 'run-alice-2' }, session('alice') as any),
+      () => interruptAgent({ runId: 'run-alice-2' }, session('alice') as any),
       /Not authorized to access this run/
     )
     assert.equal(handle.signal.aborted, false)
@@ -749,7 +745,7 @@ describe('interruptAIAgent authorization', () => {
     })
 
     const handle = registerInterruptibleRun('run-mine')
-    const result = await interruptAIAgent(
+    const result = await interruptAgent(
       { runId: 'run-mine', reason: 'speech' },
       session('alice') as any
     )
@@ -769,10 +765,7 @@ describe('interruptAIAgent authorization', () => {
     })
 
     assert.deepEqual(
-      await interruptAIAgent(
-        { runId: 'run-finished' },
-        session('alice') as any
-      ),
+      await interruptAgent({ runId: 'run-finished' }, session('alice') as any),
       { stopped: false, inFlightTools: [] }
     )
   })
@@ -787,7 +780,7 @@ describe('interruptAIAgent authorization', () => {
         error: () => {},
         debug: () => {},
       },
-      aiRunState: {
+      agentRunState: {
         getRun: async () => ({
           runId: 'run-elsewhere',
           agentName: 'remote-agent',
@@ -799,10 +792,7 @@ describe('interruptAIAgent authorization', () => {
     } as any)
 
     assert.deepEqual(
-      await interruptAIAgent(
-        { runId: 'run-elsewhere' },
-        session('alice') as any
-      ),
+      await interruptAgent({ runId: 'run-elsewhere' }, session('alice') as any),
       { stopped: false, inFlightTools: [] }
     )
     assert.equal(warnings.length, 1)
@@ -819,7 +809,7 @@ describe('interruptAIAgent authorization', () => {
         error: () => {},
         debug: () => {},
       },
-      aiRunState: {
+      agentRunState: {
         getRun: async () => ({
           runId: 'run-done',
           agentName: 'done-agent',
@@ -829,14 +819,14 @@ describe('interruptAIAgent authorization', () => {
       },
     } as any)
 
-    await interruptAIAgent({ runId: 'run-done' }, session('alice') as any)
+    await interruptAgent({ runId: 'run-done' }, session('alice') as any)
     assert.deepEqual(warnings, [])
   })
 
   test('rejects an unknown runId', async () => {
     withRun(null)
     await assert.rejects(
-      () => interruptAIAgent({ runId: 'nope' }, session('alice') as any),
+      () => interruptAgent({ runId: 'nope' }, session('alice') as any),
       /No run found for runId nope/
     )
   })

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

@@ -1,10 +1,10 @@
-import { randomUUID } from './ai-agent-utils.js'
+import { randomUUID } from './agent-utils.js'
 import {
   AbandonedError,
   runInAbortScope,
   type AbortScope,
 } from '../../function/abort-scope.js'
-import type { AIStorageService } from '../../services/ai-storage-service.js'
+import type { AgentStorageService } from '../../services/agent-storage-service.js'
 
 /**
  * Why an in-flight agent run was cut short.
@@ -12,7 +12,7 @@ import type { AIStorageService } from '../../services/ai-storage-service.js'
  * Deliberately carries no interjection text. A voice interruption is not a
  * cancel button — it is the user starting to talk — but what they said arrives
  * a second later as an ordinary next turn on the same thread, and that turn
- * already has a working path through `streamAIAgent`. The model then sees its
+ * already has a working path through `streamAgent`. The model then sees its
  * own truncated message (marked `interrupted`) followed by the interjection and
  * decides for itself whether to resume, correct itself or drop the thread.
  * Nothing here classifies the interjection; a second delivery path for the same
@@ -219,7 +219,7 @@ export const registerInterruptibleRun = (
  * Stop a run that is generating right now.
  *
  * Plumbing: this performs NO authorization, so anyone holding a runId can stop
- * it. Reach for {@link interruptAIAgent} instead unless the caller has already
+ * it. Reach for {@link interruptAgent} instead unless the caller has already
  * established that the run belongs to the session — which in practice means
  * only the runner itself and code already inside an authorized run.
  *
@@ -359,7 +359,7 @@ export const awaitPendingInterruptNote = async (
  */
 export const persistOrphanedToolResults = async (
   handle: InterruptibleRunHandle,
-  storage: AIStorageService,
+  storage: AgentStorageService,
   threadId: string
 ): Promise<void> => {
   let orphaned: OrphanedToolResult[]

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

@@ -12,14 +12,14 @@ import {
   saveMessages,
   stripWorkingMemoryTags,
   trimMessages,
-} from './ai-agent-memory.js'
-import type { AIMessage, CoreAIAgent } from './ai-agent.types.js'
+} from './agent-memory.js'
+import type { AgentMessage, CoreAgent } from './agent.types.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
-const makeMessage = (overrides: Partial<AIMessage>): AIMessage => ({
+const makeMessage = (overrides: Partial<AgentMessage>): AgentMessage => ({
   id: 'msg',
   role: 'user',
   content: 'hello',
@@ -27,19 +27,19 @@ const makeMessage = (overrides: Partial<AIMessage>): AIMessage => ({
   ...overrides,
 })
 
-describe('ai-agent-memory', () => {
-  test('resolveMemoryServices prefers named storage and falls back to aiStorage', () => {
+describe('agent-memory', () => {
+  test('resolveMemoryServices prefers named storage and falls back to agentStorage', () => {
     const singletonServices = {
-      aiStorage: { kind: 'default' },
+      agentStorage: { kind: 'default' },
       customStorage: { kind: 'custom' },
     } as any
 
-    const defaultAgent = {} as CoreAIAgent
-    const namedAgent = { memory: { storage: 'customStorage' } } as CoreAIAgent
+    const defaultAgent = {} as CoreAgent
+    const namedAgent = { memory: { storage: 'customStorage' } } as CoreAgent
 
     assert.equal(
       resolveMemoryServices(defaultAgent, singletonServices).storage,
-      singletonServices.aiStorage
+      singletonServices.agentStorage
     )
     assert.equal(
       resolveMemoryServices(namedAgent, singletonServices).storage,
@@ -139,10 +139,10 @@ describe('ai-agent-memory', () => {
   })
 
   test('saveMessages persists tool calls and strips working memory tags from returned text', async () => {
-    const savedMessages: AIMessage[][] = []
+    const savedMessages: AgentMessage[][] = []
 
     const storage = {
-      saveMessages: async (_threadId: string, messages: AIMessage[]) => {
+      saveMessages: async (_threadId: string, messages: AgentMessage[]) => {
         savedMessages.push(messages)
       },
     } as any
@@ -265,7 +265,7 @@ describe('ai-agent-memory', () => {
   })
 
   test('trimMessages sanitizes orphaned tool messages and keeps first user/system boundary', () => {
-    const messages: AIMessage[] = [
+    const messages: AgentMessage[] = [
       makeMessage({
         id: 'assistant-1',
         role: 'assistant',