@pikku/core 0.12.80 → 0.12.82

package/src/wirings/ai-agent/ai-agent-memory.ts

@@ -4,6 +4,7 @@ import type {
   CoreAIAgent,
   AIAgentMemoryConfig,
   AIAgentInput,
+  AIAgentStep,
   AIMessage,
 } from './ai-agent.types.js'
 import type { AIStorageService } from '../../services/ai-storage-service.js'
@@ -143,13 +144,7 @@ export async function saveMessages(
   result: {
     text: string
     uiSpec?: unknown
-    steps: {
-      toolCalls?: {
-        name: string
-        args: Record<string, unknown>
-        result: string
-      }[]
-    }[]
+    steps: Pick<AIAgentStep, 'toolCalls'>[]
   }
 ): Promise<string> {
   const responseText = memoryConfig?.workingMemory
@@ -179,6 +174,7 @@ export async function saveMessages(
             id: toolCallIds[i],
             name: tc.name,
             result: tc.result,
+            ...(tc.error ? { error: tc.error } : {}),
           })),
           createdAt: new Date(),
         })
@@ -370,6 +366,39 @@ export function stripWorkingMemoryForStreaming(text: string): string {
   return output
 }
 
+async function persistWorkingMemory(
+  options: {
+    storage?: AIStorageService
+    threadId: string
+    workingMemorySchemaName?: string | null
+    logger?: Logger
+    schemaService?: SchemaService
+  },
+  workingMemory: Record<string, unknown>
+): Promise<void> {
+  if (!options.storage) return
+
+  const existing =
+    (await options.storage.getWorkingMemory(options.threadId, 'thread')) ?? {}
+  const merged = deepMergeWorkingMemory(existing, workingMemory)
+
+  if (options.schemaService && options.workingMemorySchemaName) {
+    try {
+      await options.schemaService.validateSchema(
+        options.workingMemorySchemaName,
+        merged
+      )
+    } catch (err) {
+      options.logger?.warn(
+        `Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`
+      )
+      return
+    }
+  }
+
+  await options.storage.saveWorkingMemory(options.threadId, 'thread', merged)
+}
+
 export function createWorkingMemoryMiddleware(options: {
   storage?: AIStorageService
   threadId: string
@@ -382,6 +411,21 @@ export function createWorkingMemoryMiddleware(options: {
 }> {
   return {
     modifyOutputStream: async (_services, { event, state }) => {
+      // A streamed step ends at its `usage` event, or at `done` for a model
+      // that reports no usage. That is the last moment the unstripped text is
+      // still reachable: it lives only in `state.rawText`, because the strip
+      // below runs before anything downstream — including the channel that
+      // accumulates what `modifyOutput` would later be handed.
+      if (event.type === 'usage' || event.type === 'done') {
+        const { workingMemory } = extractWorkingMemory(state.rawText ?? '')
+        state.rawText = ''
+        state.emittedVisibleText = ''
+        if (workingMemory) {
+          await persistWorkingMemory(options, workingMemory)
+        }
+        return event
+      }
+
       if (event.type !== 'text-delta') return event
 
       const rawText = `${state.rawText ?? ''}${event.text}`
@@ -400,38 +444,10 @@ export function createWorkingMemoryMiddleware(options: {
       if (!delta) return null
       return { ...event, text: delta }
     },
-    modifyOutput: async (_services, { text, messages, usage }) => {
+    modifyOutput: async (_services, { text, messages }) => {
       const { workingMemory, cleanedText } = extractWorkingMemory(text)
-      if (workingMemory && options.storage) {
-        const existing =
-          (await options.storage.getWorkingMemory(
-            options.threadId,
-            'thread'
-          )) ?? {}
-        const merged = deepMergeWorkingMemory(existing, workingMemory)
-
-        let valid = true
-        if (options.schemaService && options.workingMemorySchemaName) {
-          try {
-            await options.schemaService.validateSchema(
-              options.workingMemorySchemaName,
-              merged
-            )
-          } catch (err) {
-            valid = false
-            options.logger?.warn(
-              `Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`
-            )
-          }
-        }
-
-        if (valid) {
-          await options.storage.saveWorkingMemory(
-            options.threadId,
-            'thread',
-            merged
-          )
-        }
+      if (workingMemory) {
+        await persistWorkingMemory(options, workingMemory)
       }
 
       return {

package/src/wirings/ai-agent/ai-agent-model-config.test.ts

@@ -1,10 +1,21 @@
-import { describe, test, beforeEach } from 'node:test'
+import { describe, test, beforeEach, afterEach } from 'node:test'
 import assert from 'node:assert'
-import { resolveModelConfig } from './ai-agent-model-config.js'
-import { resetPikkuState } from '../../pikku-state.js'
+import {
+  resolveModelAlias,
+  resolveModelConfig,
+} from './ai-agent-model-config.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+
+const setAliases = (aliases: Record<string, string>) =>
+  pikkuState(null, 'agent', 'modelAliases', aliases)
 
 beforeEach(() => {
   resetPikkuState()
+  delete process.env.PIKKU_MODEL_ALIASES
+})
+
+afterEach(() => {
+  delete process.env.PIKKU_MODEL_ALIASES
 })
 
 describe('resolveModelConfig', () => {
@@ -34,4 +45,62 @@ describe('resolveModelConfig', () => {
     assert.strictEqual(result.temperature, undefined)
     assert.strictEqual(result.maxSteps, undefined)
   })
+
+  test('resolves an aliased agent model through the table', () => {
+    setAliases({ cheap: 'openai/gpt-5-mini' })
+    const result = resolveModelConfig('testAgent', {
+      model: 'cheap',
+      temperature: 0.2,
+    })
+    assert.strictEqual(result.model, 'openai/gpt-5-mini')
+    assert.strictEqual(result.temperature, 0.2)
+  })
+})
+
+describe('resolveModelAlias', () => {
+  test('a provider-qualified model is never treated as an alias', () => {
+    setAliases({ 'openai/gpt-4': 'anthropic/claude-3' })
+    assert.strictEqual(resolveModelAlias('openai/gpt-4'), 'openai/gpt-4')
+  })
+
+  test('an alias resolves to its provider-qualified model', () => {
+    setAliases({
+      cheap: 'openai/gpt-5-mini',
+      tool: 'anthropic/claude-sonnet-5',
+    })
+    assert.strictEqual(resolveModelAlias('cheap'), 'openai/gpt-5-mini')
+    assert.strictEqual(resolveModelAlias('tool'), 'anthropic/claude-sonnet-5')
+  })
+
+  test('PIKKU_MODEL_ALIASES beats the generated table', () => {
+    setAliases({ cheap: 'openai/gpt-5-mini' })
+    process.env.PIKKU_MODEL_ALIASES = 'cheap:anthropic/claude-haiku-4-5'
+    assert.strictEqual(resolveModelAlias('cheap'), 'anthropic/claude-haiku-4-5')
+  })
+
+  test('an env override splits on the first colon only', () => {
+    // A model id may itself contain a colon — `ollama/qwen2.5:7b` is the shape
+    // the runner's own error message cites. It stays provider-qualified so the
+    // resolved value is one `VercelAIAgentRunner.parseModel` would accept; a
+    // bare `bedrock:nova-lite:1` would pass here and fail the moment anything
+    // tried to use it.
+    process.env.PIKKU_MODEL_ALIASES = 'cheap:ollama/qwen2.5:7b'
+    assert.strictEqual(resolveModelAlias('cheap'), 'ollama/qwen2.5:7b')
+  })
+
+  test('an env override leaves aliases it does not name alone', () => {
+    setAliases({ cheap: 'openai/gpt-5-mini', tool: 'openai/gpt-5' })
+    process.env.PIKKU_MODEL_ALIASES = 'cheap:openai/gpt-5-nano'
+    assert.strictEqual(resolveModelAlias('tool'), 'openai/gpt-5')
+  })
+
+  test('an unknown alias throws rather than reaching a provider', () => {
+    setAliases({ cheap: 'openai/gpt-5-mini' })
+    assert.throws(() => resolveModelAlias('expensive'), /expensive/)
+  })
+
+  test('the error names the aliases that do exist', () => {
+    setAliases({ cheap: 'openai/gpt-5-mini', tool: 'openai/gpt-5' })
+    assert.throws(() => resolveModelAlias('exspensive'), /cheap, tool/)
+  })
 })

package/src/wirings/ai-agent/ai-agent-model-config.ts

@@ -1,10 +1,58 @@
 // knowledge: decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md
+import { pikkuState } from '../../pikku-state.js'
+
+const isProviderQualified = (model: string) => model.includes('/')
+
+/** `PIKKU_MODEL_ALIASES=cheap:openai/gpt-5-mini,tool:anthropic/claude-sonnet-5` */
+const envAliases = (): Record<string, string> => {
+  const raw = process.env.PIKKU_MODEL_ALIASES
+  if (!raw) return {}
+  const aliases: Record<string, string> = {}
+  for (const entry of raw.split(',')) {
+    // First colon only — a model id may contain its own.
+    const separator = entry.indexOf(':')
+    if (separator === -1) continue
+    const alias = entry.slice(0, separator).trim()
+    const model = entry.slice(separator + 1).trim()
+    if (alias && model) aliases[alias] = model
+  }
+  return aliases
+}
+
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export const resolveModelAlias = (model: string): string => {
+  if (isProviderQualified(model)) return model
+
+  const generated = pikkuState(null, 'agent', 'modelAliases')
+  const override = envAliases()[model]
+  const resolved = override ?? generated[model]
+
+  if (!resolved) {
+    const known = Object.keys({ ...generated, ...envAliases() }).sort()
+    throw new Error(
+      `Unknown model alias '${model}'. ` +
+        (known.length
+          ? `Known aliases: ${known.join(', ')}. `
+          : `No aliases are configured. `) +
+        `Add it to the "models" table in pikku.config.json, or name a ` +
+        `provider-qualified model such as 'openai/gpt-5-mini'.`
+    )
+  }
+
+  return resolved
+}
+
 export function resolveModelConfig(
   _agentName: string,
   agent: { model: string; temperature?: number; maxSteps?: number }
 ): { model: string; temperature?: number; maxSteps?: number } {
   return {
-    model: agent.model,
+    model: resolveModelAlias(agent.model),
     temperature: agent.temperature,
     maxSteps: agent.maxSteps,
   }

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -565,6 +565,8 @@ export async function buildToolDefs(
                     variableOverrides: capturedAddonConfig?.variableOverrides,
                     credentialOverrides:
                       capturedAddonConfig?.credentialOverrides,
+                    globalSecrets: capturedAddonConfig?.globalSecrets,
+                    globalCredentials: capturedAddonConfig?.globalCredentials,
                   }
                 : undefined
               services = await getOrCreatePackageSingletonServices(

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -49,6 +49,11 @@ import {
   notifyAfterStep,
   toAccumulatedStep,
 } from './ai-agent-turn.js'
+import {
+  applyOutputMiddleware,
+  finalizeAgentRun,
+  lastUserMessageText,
+} from './ai-agent-finalize.js'
 import { resolveModelConfig } from './ai-agent-model-config.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { randomUUID } from './ai-agent-utils.js'
@@ -303,20 +308,13 @@ export async function runAIAgent(
       steps: accumulatedSteps,
     }
 
-    let outputText = finalText
-    let outputMessages = runnerParams.messages
-    for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-      const mw = aiMiddlewares[i]
-      if (mw.modifyOutput) {
-        const modResult = await mw.modifyOutput(singletonServices, {
-          text: outputText,
-          messages: outputMessages,
-          usage: totalUsage,
-        })
-        outputText = modResult.text
-        outputMessages = modResult.messages
-      }
-    }
+    const { text: outputText, steps: outputSteps } =
+      await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+        text: finalText,
+        messages: runnerParams.messages,
+        steps: result.steps,
+        usage: totalUsage,
+      })
 
     await saveMessages(
       storage,
@@ -325,14 +323,20 @@ export async function runAIAgent(
       memoryConfig,
       persistedUserMessage,
       {
-        ...result,
         text: outputText,
+        steps: outputSteps,
         uiSpec: structuredOutput.uiSpec,
       }
     )
 
-    await aiRunState.updateRun(runId, {
-      status: 'completed',
+    await finalizeAgentRun(aiRunState, {
+      runId,
+      agentName,
+      threadId,
+      resourceId: input.resourceId,
+      input: lastUserMessageText(runnerParams.messages),
+      text: outputText,
+      steps: outputSteps,
       usage: { ...totalUsage, model: agent.model },
     })
 
@@ -341,7 +345,7 @@ export async function runAIAgent(
       text: outputText,
       object: finalObject,
       threadId,
-      steps: accumulatedSteps,
+      steps: outputSteps,
       usage: totalUsage,
     }
   } catch (error) {
@@ -462,6 +466,7 @@ export async function resumeAIAgentSync(
     toolName: string
     args: any
     result: string
+    error?: string
   }[] = []
 
   for (const pending of savedPendingApprovals) {
@@ -471,6 +476,7 @@ export async function resumeAIAgentSync(
     if (!claimedIds.has(toolCallId)) continue
 
     let resultStr: string
+    let toolError: string | undefined
 
     if (rejectedIds.has(toolCallId)) {
       resultStr =
@@ -497,7 +503,8 @@ export async function resumeAIAgentSync(
         if (err?.payload?.error === 'missing_credential') {
           resultStr = JSON.stringify(err.payload)
         } else {
-          resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`
+          toolError = err instanceof Error ? err.message : String(err)
+          resultStr = `Error: ${toolError}`
         }
       }
     } else {
@@ -512,6 +519,7 @@ export async function resumeAIAgentSync(
           ? JSON.parse(pending.args)
           : pending.args,
       result: resultStr,
+      ...(toolError ? { error: toolError } : {}),
     })
   }
 
@@ -541,7 +549,21 @@ export async function resumeAIAgentSync(
     memoryConfig,
     agentRunner,
     params,
-    aiRunState
+    aiRunState,
+    // The approved tools were executed here, before the model was re-entered,
+    // so they belong to the run's step record — otherwise a tool that failed
+    // after approval leaves no trace on the run at all.
+    toolCallMessages.length > 0
+      ? {
+          usage: { inputTokens: 0, outputTokens: 0 },
+          toolCalls: toolCallMessages.map((tc) => ({
+            name: tc.toolName,
+            args: (tc.args ?? {}) as Record<string, unknown>,
+            result: tc.result,
+            ...(tc.error ? { error: tc.error } : {}),
+          })),
+        }
+      : undefined
   )
 }
 
@@ -554,7 +576,8 @@ async function continueAfterToolResultSync(
   memoryConfig: AIAgentMemoryConfig | undefined,
   agentRunner: AIAgentRunnerService,
   params: RunAIAgentParams,
-  aiRunState: AIRunStateService
+  aiRunState: AIRunStateService,
+  resumedToolStep?: AIAgentStep
 ): Promise<AIAgentOutput> {
   const singletonServices = getSingletonServices()
   const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
@@ -639,6 +662,13 @@ async function continueAfterToolResultSync(
   runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
 
   try {
+    // Kept out of `accumulatedSteps` deliberately: that array drives
+    // `saveMessages`, and the approved tool's messages were already written to
+    // the thread before the model was re-entered. It belongs to the run's step
+    // record, not to persistence.
+    const withResumedStep = (steps: AIAgentStep[]): AIAgentStep[] =>
+      resumedToolStep ? [resumedToolStep, ...steps] : steps
+
     const accumulatedSteps: AIAgentStep[] = []
     const totalUsage = { inputTokens: 0, outputTokens: 0 }
     let lastStepResult: AIAgentStepResult | null = null
@@ -717,7 +747,7 @@ async function continueAfterToolResultSync(
           runId: run.runId,
           text: suspendedText,
           threadId: run.threadId,
-          steps: accumulatedSteps,
+          steps: withResumedStep(accumulatedSteps),
           usage: totalUsage,
           status: 'suspended',
           pendingApprovals: approvalsNeeded.map((a) => ({
@@ -741,20 +771,13 @@ async function continueAfterToolResultSync(
       steps: accumulatedSteps,
     }
 
-    let outputText = finalText
-    let outputMessages = runnerParams.messages
-    for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
-      const mw = aiMiddlewares[i]
-      if (mw.modifyOutput) {
-        const modResult = await mw.modifyOutput(singletonServices, {
-          text: outputText,
-          messages: outputMessages,
-          usage: totalUsage,
-        })
-        outputText = modResult.text
-        outputMessages = modResult.messages
-      }
-    }
+    const { text: outputText, steps: outputSteps } =
+      await applyOutputMiddleware(aiMiddlewares, singletonServices, {
+        text: finalText,
+        messages: runnerParams.messages,
+        steps: withResumedStep(result.steps),
+        usage: totalUsage,
+      })
 
     await saveMessages(
       storage,
@@ -763,13 +786,21 @@ async function continueAfterToolResultSync(
       memoryConfig,
       null,
       {
-        ...result,
         text: outputText,
+        // The approved tool's messages were written before the model was
+        // re-entered, so only the steps this leg generated are persisted here.
+        steps: accumulatedSteps,
       }
     )
 
-    await aiRunState.updateRun(run.runId, {
-      status: 'completed',
+    await finalizeAgentRun(aiRunState, {
+      runId: run.runId,
+      agentName: resolvedName,
+      threadId: run.threadId,
+      resourceId: run.resourceId,
+      input: lastUserMessageText(runnerParams.messages),
+      text: outputText,
+      steps: outputSteps,
       usage: { ...totalUsage, model: agent.model },
     })
 
@@ -778,7 +809,7 @@ async function continueAfterToolResultSync(
       text: outputText,
       object: finalObject,
       threadId: run.threadId,
-      steps: accumulatedSteps,
+      steps: outputSteps,
       usage: totalUsage,
     }
   } catch (error) {