@pikku/core 0.12.80 → 0.12.83

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

@@ -0,0 +1,197 @@
+import type {
+  AIAgentStep,
+  AIMessage,
+  PikkuAIMiddlewareHooks,
+} from './ai-agent.types.js'
+import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { scoreFinishedRun } from '../ai-scorer/ai-scorer-live.js'
+import { recordScoreSnapshot } from '../ai-scorer/ai-scorer-snapshots.js'
+
+export type RunUsage = {
+  inputTokens: number
+  outputTokens: number
+  model?: string
+}
+
+/**
+ * Everything a finished run produced, after all middleware has had its say.
+ *
+ * One snapshot feeds persistence and anything that grades the run, so that what
+ * a scorer is shown is exactly what was stored — including the redactions.
+ */
+export type FinalizedRun = {
+  runId: string
+  agentName: string
+  threadId: string
+  resourceId?: string
+  /** The prompt the run answered — what a scorer grades the answer against. */
+  input: string
+  text: string
+  steps: AIAgentStep[]
+  usage: RunUsage
+}
+
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export const lastUserMessageText = (messages: AIMessage[]): string => {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]
+    if (message?.role !== 'user') continue
+    if (typeof message.content === 'string') return message.content
+    if (Array.isArray(message.content)) {
+      return message.content
+        .filter((part) => part.type === 'text')
+        .map((part) => (part as { text: string }).text)
+        .join('\n')
+    }
+  }
+  return ''
+}
+
+const flattenToolCalls = (
+  steps: AIAgentStep[]
+): NonNullable<AIAgentStep['toolCalls']> =>
+  steps.flatMap((step) => step.toolCalls ?? [])
+
+/**
+ * Push a rewritten flat tool-call list back onto the steps it came from,
+ * preserving the step boundaries. A hook that adds or drops calls would make
+ * the boundaries meaningless, so a length change collapses them into the last
+ * step rather than silently mis-attributing calls to the wrong step.
+ */
+const distributeToolCalls = (
+  steps: AIAgentStep[],
+  toolCalls: NonNullable<AIAgentStep['toolCalls']>
+): AIAgentStep[] => {
+  if (toolCalls.length !== flattenToolCalls(steps).length) {
+    return steps.map((step, index) => ({
+      ...step,
+      toolCalls: index === steps.length - 1 ? toolCalls : [],
+    }))
+  }
+
+  let cursor = 0
+  return steps.map((step) => {
+    if (!step.toolCalls) return step
+    const next = toolCalls.slice(cursor, cursor + step.toolCalls.length)
+    cursor += step.toolCalls.length
+    return { ...step, toolCalls: next }
+  })
+}
+
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export const applyOutputMiddleware = async (
+  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  singletonServices: any,
+  input: {
+    text: string
+    messages: AIMessage[]
+    steps: AIAgentStep[]
+    usage: { inputTokens: number; outputTokens: number }
+  }
+): Promise<{ text: string; messages: AIMessage[]; steps: AIAgentStep[] }> => {
+  let text = input.text
+  let messages = input.messages
+  let steps = input.steps
+  let toolCalls = flattenToolCalls(steps)
+
+  for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
+    const mw = aiMiddlewares[i]
+    if (!mw.modifyOutput) continue
+    const result = await mw.modifyOutput(singletonServices, {
+      text,
+      messages,
+      usage: {
+        inputTokens: input.usage.inputTokens,
+        outputTokens: input.usage.outputTokens,
+      },
+      toolCalls,
+    })
+    text = result.text
+    messages = result.messages
+    if (result.toolCalls) {
+      toolCalls = result.toolCalls
+      steps = distributeToolCalls(steps, toolCalls)
+    }
+  }
+
+  return { text, messages, steps }
+}
+
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export const finalizeAgentRun = async (
+  aiRunState: AIRunStateService,
+  run: FinalizedRun
+): Promise<void> => {
+  await aiRunState.updateRun(run.runId, {
+    status: 'completed',
+    ...(run.usage.model
+      ? {
+          usage: {
+            inputTokens: run.usage.inputTokens,
+            outputTokens: run.usage.outputTokens,
+            model: run.usage.model,
+          },
+        }
+      : {}),
+  })
+
+  // Read rather than `getSingletonServices()`: a process that never registered
+  // them grades nothing, which is not an error at the point a run has already
+  // succeeded.
+  const services = pikkuState(null, 'package', 'singletonServices')
+  if (!services) return
+
+  const snapshot = {
+    runId: run.runId,
+    agentName: run.agentName,
+    threadId: run.threadId,
+    ...(run.resourceId !== undefined ? { resourceId: run.resourceId } : {}),
+    input: run.input,
+    output: run.text,
+    toolCalls: run.steps.flatMap((step) =>
+      (step.toolCalls ?? []).map((call) => ({
+        name: call.name,
+        args: call.args,
+        result: call.result,
+        ...(call.error !== undefined ? { error: call.error } : {}),
+      }))
+    ),
+    usage: {
+      inputTokens: run.usage.inputTokens,
+      outputTokens: run.usage.outputTokens,
+      ...(run.usage.model !== undefined ? { model: run.usage.model } : {}),
+    },
+  }
+
+  // The same object a scenario grades, so an asserted score and a sampled one
+  // are the same measurement. A no-op unless a dev server turned retention on.
+  recordScoreSnapshot(snapshot)
+
+  // Best-effort and last: the client already has its answer, so a grading
+  // failure must not surface as a failed run.
+  try {
+    await scoreFinishedRun(snapshot, services)
+  } catch (error) {
+    services.logger?.error(
+      `[pikku] Live scoring failed for run ${run.runId}`,
+      error
+    )
+  }
+}

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

@@ -381,6 +381,7 @@ export const persistOrphanedToolResults = async (
           : typeof entry.result === 'string'
             ? entry.result
             : JSON.stringify(entry.result),
+        ...(entry.error ? { error: entry.error } : {}),
       })),
       undelivered: true,
       createdAt: new Date(),

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,10 @@ export async function buildToolDefs(
                     variableOverrides: capturedAddonConfig?.variableOverrides,
                     credentialOverrides:
                       capturedAddonConfig?.credentialOverrides,
+                    secretGrants: capturedAddonConfig?.secretGrants,
+                    credentialGrants: capturedAddonConfig?.credentialGrants,
+                    globalSecrets: capturedAddonConfig?.globalSecrets,
+                    globalCredentials: capturedAddonConfig?.globalCredentials,
                   }
                 : undefined
               services = await getOrCreatePackageSingletonServices(