@pikku/core 0.12.83 → 0.12.86

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

@@ -8,7 +8,7 @@ import {
   SPOKEN_TURN,
   SPOKEN_TRANSCRIPT,
 } from './voice-input.js'
-import type { AIContentPart, AIMessage } from './ai-agent.types.js'
+import type { AgentContentPart, AgentMessage } from './agent.types.js'
 
 class ThisDependentRunner {
   private readonly transcript = 'the transcribed spoken words'
@@ -24,19 +24,19 @@ class ThisDependentRunner {
   }
 }
 
-const audioMessage = (): AIMessage => ({
+const audioMessage = (): AgentMessage => ({
   id: 'm1',
   role: 'user',
   content: [
     { type: 'file', mediaType: 'audio/wav', data: 'AAAA' },
-  ] as AIContentPart[],
+  ] as AgentContentPart[],
   createdAt: new Date(0),
 })
 
 describe('voiceInput', () => {
   test('transcribes an audio part by calling the runner with its receiver intact', async () => {
     const mw = voiceInput({ model: 'mock/whisper' })
-    const services = { aiAgentRunner: new ThisDependentRunner() }
+    const services = { agentRunner: new ThisDependentRunner() }
 
     const result = await mw.modifyInput!(services as any, {
       messages: [audioMessage()],
@@ -45,7 +45,7 @@ describe('voiceInput', () => {
     })
 
     const last = result.messages[result.messages.length - 1]!
-    const parts = last.content as AIContentPart[]
+    const parts = last.content as AgentContentPart[]
     assert.equal(parts.length, 1)
     assert.equal(parts[0]!.type, 'text')
     assert.equal(
@@ -57,8 +57,8 @@ describe('voiceInput', () => {
 
   test('leaves the message untouched when there is no audio part', async () => {
     const mw = voiceInput({ model: 'mock/whisper' })
-    const services = { aiAgentRunner: new ThisDependentRunner() }
-    const messages: AIMessage[] = [
+    const services = { agentRunner: new ThisDependentRunner() }
+    const messages: AgentMessage[] = [
       {
         id: 'm1',
         role: 'user',
@@ -78,7 +78,7 @@ describe('voiceInput', () => {
 
   test('throws when an audio part is present but no model is configured', async () => {
     const mw = voiceInput({})
-    const services = { aiAgentRunner: new ThisDependentRunner() }
+    const services = { agentRunner: new ThisDependentRunner() }
 
     await assert.rejects(
       () =>
@@ -107,7 +107,7 @@ describe('voiceInput', () => {
 
     await assert.rejects(
       () =>
-        mw.modifyInput!({ aiAgentRunner: silent } as any, {
+        mw.modifyInput!({ agentRunner: silent } as any, {
           messages: [audioMessage()],
           instructions: 'sys',
           shared: {},
@@ -130,13 +130,13 @@ describe('voiceInput', () => {
     }
     const mw = voiceInput({ model: 'mock/asr' })
 
-    const result = await mw.modifyInput!({ aiAgentRunner: spaced } as any, {
+    const result = await mw.modifyInput!({ agentRunner: spaced } as any, {
       messages: [audioMessage()],
       instructions: 'sys',
       shared: {},
     })
 
-    const parts = result.messages.at(-1)!.content as AIContentPart[]
+    const parts = result.messages.at(-1)!.content as AgentContentPart[]
     assert.equal(
       (parts[0] as { text: string }).text,
       '  spacing   the provider chose  '
@@ -166,7 +166,7 @@ describe('readsAsNonSpeech', () => {
     const mw = voiceInput({ model: 'mock/whisper' })
     const shared: Record<string, unknown> = {}
 
-    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+    await mw.modifyInput!({ agentRunner: new ThisDependentRunner() } as any, {
       messages: [audioMessage()],
       instructions: 'sys',
       shared,
@@ -179,7 +179,7 @@ describe('readsAsNonSpeech', () => {
     const mw = voiceInput({ model: 'mock/whisper' })
     const shared: Record<string, unknown> = {}
 
-    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+    await mw.modifyInput!({ agentRunner: new ThisDependentRunner() } as any, {
       messages: [{ role: 'user', content: 'typed' } as any],
       instructions: 'sys',
       shared,
@@ -194,7 +194,7 @@ describe('readsAsNonSpeech', () => {
     const mw = voiceInput({ model: 'mock/whisper' })
     const shared: Record<string, unknown> = {}
 
-    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+    await mw.modifyInput!({ agentRunner: new ThisDependentRunner() } as any, {
       messages: [audioMessage()],
       instructions: 'sys',
       shared,
@@ -209,7 +209,7 @@ describe('readsAsNonSpeech', () => {
     const mw = voiceInput({ model: 'mock/whisper' })
     const shared: Record<string, unknown> = {}
 
-    await mw.modifyInput!({ aiAgentRunner: new ThisDependentRunner() } as any, {
+    await mw.modifyInput!({ agentRunner: new ThisDependentRunner() } as any, {
       messages: [{ role: 'user', content: 'typed' } as any],
       instructions: 'sys',
       shared,

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

@@ -1,7 +1,7 @@
-import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
-import { pikkuAIMiddleware } from '../../types/core.types.js'
+import type { AgentRunnerService } from '../../services/agent-runner-service.js'
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
 import { safeFetch } from '../../utils/safe-fetch.js'
-import type { AIContentPart } from './ai-agent.types.js'
+import type { AgentContentPart } from './agent.types.js'
 
 function base64ToUint8Array(base64: string): Uint8Array {
   const binary = atob(base64)
@@ -97,19 +97,19 @@ export const voiceInput = (config?: {
   model?: string
   allowedAudioHosts?: string[]
 }) =>
-  pikkuAIMiddleware({
+  pikkuAgentMiddleware({
     modifyInput: async (services, { messages, instructions, shared }) => {
-      const aiAgentRunner = (
+      const agentRunner = (
         services as {
-          aiAgentRunner?: AIAgentRunnerService
+          agentRunner?: AgentRunnerService
         }
-      ).aiAgentRunner
-      if (!aiAgentRunner?.transcribe) return { messages, instructions }
+      ).agentRunner
+      if (!agentRunner?.transcribe) return { messages, instructions }
 
       const last = messages[messages.length - 1]
       const parts =
         last?.role === 'user' && typeof last.content !== 'string'
-          ? (last.content as AIContentPart[] | undefined)
+          ? (last.content as AgentContentPart[] | undefined)
           : undefined
 
       const hasAudio = !!parts?.some(
@@ -121,7 +121,7 @@ export const voiceInput = (config?: {
       shared[SPOKEN_TURN] = hasAudio
       if (!hasAudio || !parts) return { messages, instructions }
 
-      const updatedContent: AIContentPart[] = []
+      const updatedContent: AgentContentPart[] = []
       const heard: string[] = []
       for (const p of parts) {
         if (!(p.type === 'file' && p.mediaType?.startsWith('audio/'))) {
@@ -139,7 +139,7 @@ export const voiceInput = (config?: {
         if (audioData.byteLength > MAX_AUDIO_SIZE) {
           throw new Error('Audio file exceeds maximum size')
         }
-        const result = await aiAgentRunner.transcribe({
+        const result = await agentRunner.transcribe({
           model: config.model,
           audio: audioData,
           ...(config.language

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

@@ -6,7 +6,7 @@ import {
   unspeakableScripts,
   voiceForText,
 } from './voice-output.js'
-import type { AIStreamEvent } from './ai-agent.types.js'
+import type { AgentStreamEvent } from './agent.types.js'
 import { SPOKEN_TURN } from './voice-input.js'
 
 const KOKORO_SCRIPTS = ['latin', 'devanagari', 'han', 'kana']
@@ -28,7 +28,7 @@ const deferred = () => {
 }
 
 /**
- * Drives the hook exactly as `ai-agent-stream` does, so `out` is the order the
+ * Drives the hook exactly as `agent-stream` does, so `out` is the order the
  * client actually sees — returned events and `emit`ed ones interleaved on the
  * one channel.
  */
@@ -38,9 +38,9 @@ const createStream = (
   shared: Record<string, unknown> = {}
 ) => {
   const state: Record<string, unknown> = {}
-  const allEvents: AIStreamEvent[] = []
-  const out: AIStreamEvent[] = []
-  const next = async (event: AIStreamEvent) => {
+  const allEvents: AgentStreamEvent[] = []
+  const out: AgentStreamEvent[] = []
+  const next = async (event: AgentStreamEvent) => {
     out.push(event)
   }
   return {
@@ -50,7 +50,7 @@ const createStream = (
       out
         .filter((event) => event.type === 'audio-delta')
         .map((event) => atob((event as { data: string }).data)),
-    send: async (event: AIStreamEvent) => {
+    send: async (event: AgentStreamEvent) => {
       allEvents.push(event)
       const result = await mw.modifyOutputStream!(services as any, {
         event,
@@ -81,7 +81,7 @@ describe('voiceOutput', () => {
     // provider takes.
     const gate = deferred()
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           await gate.promise
           return speechFor(text)
@@ -99,7 +99,7 @@ describe('voiceOutput', () => {
   test('speaks sentences in order even when the later one is ready first', async () => {
     const slow = deferred()
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           // A short sentence after a long one routinely finishes first.
           if (text.includes('first')) await slow.promise
@@ -120,7 +120,7 @@ describe('voiceOutput', () => {
   test('holds done until everything queued has been spoken', async () => {
     const gate = deferred()
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           await gate.promise
           return speechFor(text)
@@ -148,7 +148,7 @@ describe('voiceOutput', () => {
 
   test('speaks a trailing fragment the model never punctuated', async () => {
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => speechFor(text),
       },
     }
@@ -162,7 +162,7 @@ describe('voiceOutput', () => {
 
   test('says nothing extra when the reply ended on a boundary', async () => {
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => speechFor(text),
       },
     }
@@ -178,7 +178,7 @@ describe('voiceOutput', () => {
     const errors: string[] = []
     const services = {
       logger: { error: (message: string) => errors.push(message) },
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           if (text.includes('boom')) throw new Error('provider exploded')
           return speechFor(text)
@@ -200,7 +200,7 @@ describe('voiceOutput', () => {
 
   test('stays out of the way when the runner cannot speak at all', async () => {
     const stream = createStream(voiceOutput({ model: 'mock/tts' }), {
-      aiAgentRunner: {},
+      agentRunner: {},
     })
     await stream.send({ type: 'text-delta', text: 'Hello.' } as any)
     await stream.send({ type: 'done' } as any)
@@ -216,7 +216,7 @@ describe('voiceOutput', () => {
     // is the only honest option.
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -233,15 +233,14 @@ describe('voiceOutput', () => {
 
     assert.deepEqual(asked, [], 'nothing should have been sent for synthesis')
     const notice = stream.out.find((event) => event.type === 'data') as
-      | { name: string; data: { scripts: string[] } }
-      | undefined
+      { name: string; data: { scripts: string[] } } | undefined
     assert.equal(notice?.name, 'voice-unsupported')
     assert.deepEqual(notice?.data.scripts, ['arabic'])
   })
 
   test('a reply says it once, however many sentences it is', async () => {
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => speechFor(text),
       },
     }
@@ -264,7 +263,7 @@ describe('voiceOutput', () => {
   test('a bilingual reply still speaks the half it can', async () => {
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text.trim())
           return speechFor(text)
@@ -289,7 +288,7 @@ describe('voiceOutput', () => {
     // characters out for three times the duration.
     const asked: Array<{ text: string; voice?: string }> = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({
           text,
           voice,
@@ -323,7 +322,7 @@ describe('voiceOutput', () => {
     // — it is billed per sentence, on every turn.
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -344,7 +343,7 @@ describe('voiceOutput', () => {
   test('a spoken turn is answered aloud', async () => {
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -365,7 +364,7 @@ describe('voiceOutput', () => {
     // Read-aloud modes exist, and for them speech is not a reply to speech.
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -389,7 +388,7 @@ describe('voiceOutput', () => {
     // evidence the turn was typed and the pre-existing behaviour stands.
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -407,7 +406,7 @@ describe('voiceOutput', () => {
   test('a script with no voice mapped is still refused, not mis-voiced', async () => {
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text)
           return speechFor(text)
@@ -424,15 +423,14 @@ describe('voiceOutput', () => {
 
     assert.deepEqual(asked, [])
     const notice = stream.out.find((event) => event.type === 'data') as
-      | { name: string; data: { scripts: string[] } }
-      | undefined
+      { name: string; data: { scripts: string[] } } | undefined
     assert.deepEqual(notice?.data.scripts, ['arabic'])
   })
 
   test('no declared scripts means every model is trusted with everything', async () => {
     const asked: string[] = []
     const services = {
-      aiAgentRunner: {
+      agentRunner: {
         generateSpeech: async ({ text }: { text: string }) => {
           asked.push(text.trim())
           return speechFor(text)

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

@@ -1,8 +1,8 @@
-import type { AIAgentRunnerService } from '../../services/ai-agent-runner-service.js'
-import { pikkuAIMiddleware } from '../../types/core.types.js'
+import type { AgentRunnerService } from '../../services/agent-runner-service.js'
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
 import { SPOKEN_TURN } from './voice-input.js'
 
-type VoiceOutputState = {
+export type VoiceOutputState = {
   textBuffer?: string
   /**
    * The audio emitted so far, as a chain.
@@ -129,7 +129,7 @@ export const voiceForText = (
 }
 
 async function synthesizeAudio(
-  aiAgentRunner: AIAgentRunnerService,
+  agentRunner: AgentRunnerService,
   input: {
     model: string
     text: string
@@ -141,7 +141,7 @@ async function synthesizeAudio(
     abortSignal?: AbortSignal
   }
 ): Promise<{ bytes: Uint8Array; format: string }> {
-  const result = await aiAgentRunner.generateSpeech?.({
+  const result = await agentRunner.generateSpeech?.({
     model: input.model,
     text: input.text,
     voice: input.voice,
@@ -153,7 +153,7 @@ async function synthesizeAudio(
   })
   if (!result) {
     throw new Error(
-      'voiceOutput requires an aiAgentRunner with generateSpeech support'
+      'voiceOutput requires an agentRunner with generateSpeech support'
     )
   }
   return {
@@ -195,16 +195,16 @@ export const voiceOutput = (config?: {
    */
   always?: boolean
 }) =>
-  pikkuAIMiddleware<VoiceOutputState>({
+  pikkuAgentMiddleware<VoiceOutputState>({
     modifyOutputStream: async (
       services,
       { event, state, shared, emit, signal }
     ) => {
-      const { aiAgentRunner, logger } = services as {
-        aiAgentRunner?: AIAgentRunnerService
+      const { agentRunner, logger } = services as {
+        agentRunner?: AgentRunnerService
         logger?: { error: (message: string) => void }
       }
-      if (!aiAgentRunner?.generateSpeech) return event
+      if (!agentRunner?.generateSpeech) return event
 
       // knowledge: decisions/internals/voice-output-speaks-unless-voice-input-explicitly-says-otherwise.md
       if (!config?.always && shared[SPOKEN_TURN] === false) return event
@@ -246,7 +246,7 @@ export const voiceOutput = (config?: {
         // Settled into a value rather than left as a rejectable promise: it
         // sits unobserved until the chain reaches it, and an unhandled
         // rejection in that window would take the process down.
-        const synthesis = synthesizeAudio(aiAgentRunner, {
+        const synthesis = synthesizeAudio(agentRunner, {
           model: config.model,
           text,
           voice,

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

@@ -1,9 +1,9 @@
 import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import { gradeRun } from './ai-scorer-grade.js'
-import { pikkuAIJudge, pikkuAIScorer } from './ai-scorer.js'
-import type { ScoreJob } from './ai-scorer.types.js'
+import { gradeRun } from './agent-scorer-grade.js'
+import { pikkuAgentJudge, pikkuAgentScorer } from './agent-scorer.js'
+import type { ScoreJob } from './agent-scorer.types.js'
 
 const job = (overrides: Partial<ScoreJob> = {}): ScoreJob => ({
   scorerName: 'correctness',
@@ -22,7 +22,7 @@ describe('gradeRun', () => {
   test('a scenario grade is returned and not written to the live record', async () => {
     pikkuState(null, 'agent', 'scorers').set(
       'correctness',
-      pikkuAIScorer({
+      pikkuAgentScorer({
         name: 'correctness',
         description: 'Matches the answer key',
         requiresReference: true,
@@ -36,7 +36,7 @@ describe('gradeRun', () => {
     const result = await gradeRun(
       job({ reference: 'Paris' }),
       {
-        aiRunState: {
+        agentRunState: {
           saveScore: async () => {
             saves++
           },
@@ -52,7 +52,7 @@ describe('gradeRun', () => {
   test('a reference-based scorer sees the answer key it was given', async () => {
     pikkuState(null, 'agent', 'scorers').set(
       'correctness',
-      pikkuAIScorer({
+      pikkuAgentScorer({
         name: 'correctness',
         description: 'Matches the answer key',
         requiresReference: true,
@@ -76,7 +76,7 @@ describe('gradeRun', () => {
   test('a judge grades without a score function, and reports the model it used', async () => {
     pikkuState(null, 'agent', 'scorers').set(
       'helpfulness',
-      pikkuAIJudge({
+      pikkuAgentJudge({
         name: 'helpfulness',
         description: 'Is the answer useful',
         model: 'claude-opus-5',
@@ -87,7 +87,7 @@ describe('gradeRun', () => {
     const result = await gradeRun(
       job({ scorerName: 'helpfulness' }),
       {
-        aiAgentRunner: {
+        agentRunner: {
           run: async () => ({
             object: { score: 0.75, reason: 'Correct but terse.' },
             usage: { inputTokens: 80, outputTokens: 20 },

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

@@ -1,6 +1,6 @@
-import { runJudge } from './ai-scorer-judge.js'
-import { resolveAIScorer } from './ai-scorer-registry.js'
-import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js'
+import { runJudge } from './agent-scorer-judge.js'
+import { resolveAgentScorer } from './agent-scorer-registry.js'
+import type { ScoreJob, ScorerOutput } from './agent-scorer.types.js'
 
 /**
  * Grade one run with one scorer.
@@ -16,8 +16,8 @@ import type { ScoreJob, ScorerOutput } from './ai-scorer.types.js'
 export const gradeRun = async (
   job: ScoreJob,
   services: {
-    aiAgentRunner?: unknown
-    aiRunState?: {
+    agentRunner?: unknown
+    agentRunState?: {
       saveScore: (score: {
         runId: string
         scorerName: string
@@ -30,19 +30,19 @@ export const gradeRun = async (
   options: { persist: boolean }
 ): Promise<ScorerOutput> => {
   const { scorerName, ...input } = job
-  const scorer = resolveAIScorer(scorerName)
+  const scorer = resolveAgentScorer(scorerName)
 
   const result = scorer.score
     ? await scorer.score(input, services)
-    : await runJudge(scorer, input, services.aiAgentRunner as never)
+    : await runJudge(scorer, input, services.agentRunner as never)
 
   if (options.persist) {
-    if (!services.aiRunState) {
+    if (!services.agentRunState) {
       throw new Error(
         `AI run state service not initialized: cannot record the '${scorerName}' grade of run ${job.runId}`
       )
     }
-    await services.aiRunState.saveScore({
+    await services.agentRunState.saveScore({
       runId: job.runId,
       scorerName,
       score: result.score,