@pikku/core 0.12.79 → 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'
@@ -19,7 +20,14 @@ export function resolveMemoryServices(
 } {
   const memoryConfig = agent.memory
   const storage = memoryConfig?.storage
-    ? (singletonServices as any)[memoryConfig.storage]
+    ? // The service is named by string in agent config, so the lookup cannot be
+      // checked — only the shape it is required to have.
+      (
+        singletonServices as unknown as Record<
+          string,
+          AIStorageService | undefined
+        >
+      )[memoryConfig.storage]
     : singletonServices.aiStorage
   return { storage }
 }
@@ -136,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
@@ -172,6 +174,7 @@ export async function saveMessages(
             id: toolCallIds[i],
             name: tc.name,
             result: tc.result,
+            ...(tc.error ? { error: tc.error } : {}),
           })),
           createdAt: new Date(),
         })
@@ -363,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
@@ -375,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}`
@@ -393,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

@@ -12,7 +12,11 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import { checkAuthPermissions, runPermissions } from '../../permissions.js'
+import {
+  checkAuthPermissions,
+  runPermissions,
+  type PermissionWire,
+} from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { ForbiddenError } from '../../errors/errors.js'
 import { verifyScopes } from '../../scopes.js'
@@ -319,8 +323,8 @@ export async function assertAgentAuthorized(
 
   await runPermissions({
     funcPermissions: agent.permissions,
-    services: singletonServices as any,
-    wire: wire as any,
+    services: singletonServices,
+    wire: wire as PermissionWire,
     data: {},
     packageName,
     label: 'agent',
@@ -395,7 +399,7 @@ export function createScopedChannel(
           toolName: event.toolName,
           args: event.args,
           ...(event.reason !== undefined ? { reason: event.reason } : {}),
-          runId: (event as any).runId,
+          runId: event.runId,
         })
         return
       }
@@ -561,6 +565,8 @@ export async function buildToolDefs(
                     variableOverrides: capturedAddonConfig?.variableOverrides,
                     credentialOverrides:
                       capturedAddonConfig?.credentialOverrides,
+                    globalSecrets: capturedAddonConfig?.globalSecrets,
+                    globalCredentials: capturedAddonConfig?.globalCredentials,
                   }
                 : undefined
               services = await getOrCreatePackageSingletonServices(
@@ -940,10 +946,7 @@ export async function prepareAgentRun(
 
   let messages: AIMessage[] = []
   if (storage) {
-    // A tool whose run was interrupted may still be writing its result to this
-    // thread. In voice the next turn lands within a second or two, so without
-    // this the model would load context that is missing the very thing it is
-    // about to be asked about.
+    // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
     await awaitPendingInterruptNote(threadId)
     messages = await storage.getMessages(threadId, {
       lastN: memoryConfig?.lastMessages ?? 20,
@@ -959,10 +962,7 @@ export async function prepareAgentRun(
 
   const userContent: AIMessage['content'] = input.attachments?.length
     ? [
-        // Omitted when there is nothing to say. An attachment on its own is a
-        // real turn — a spoken one carries audio and no text at all — and an
-        // empty text part alongside it is a part providers are entitled to
-        // reject, for a caller who never wrote one.
+        // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
         ...(input.message
           ? [{ type: 'text' as const, text: input.message }]
           : []),

package/src/wirings/ai-agent/ai-agent-resume-authorization.test.ts

@@ -43,6 +43,7 @@ const setup = (agentName: string, resourceId = 'u1') => {
       getRun: async () => suspendedRun(agentName, resourceId),
       resolveApproval: async (toolCallId: string) => {
         resolved.push(toolCallId)
+        return true
       },
     },
   } as any)

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

@@ -707,7 +707,7 @@ describe('resumeAIAgentSync', () => {
           createdAt: new Date(),
           updatedAt: new Date(),
         }),
-        resolveApproval: async () => {},
+        resolveApproval: async () => true,
         updateRun: async () => {},
       },
     } as any)
@@ -784,6 +784,7 @@ describe('resumeAIAgentSync', () => {
         },
         resolveApproval: async (toolCallId: string, status: string) => {
           resolveCalls.push({ toolCallId, status })
+          return true
         },
       },
       aiStorage: {
@@ -816,6 +817,84 @@ describe('resumeAIAgentSync', () => {
     ])
   })
 
+  test('an approver that loses the claim never runs the tool', async () => {
+    addTestAgent('claim-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['claim-agent'].tools = ['refund']
+    pikkuState(null, 'rpc', 'meta').refund = 'refund'
+    pikkuState(null, 'function', 'meta').refund = {
+      description: 'Refund',
+      sessionless: true,
+    }
+
+    let executions = 0
+    pikkuState(null, 'function', 'functions').set('refund', {
+      func: async () => {
+        executions++
+        return { refunded: true }
+      },
+    })
+
+    const run: AgentRunState = {
+      runId: 'run-claim',
+      agentName: 'claim-agent',
+      threadId: 'thread-claim',
+      resourceId: 'resource-claim',
+      status: 'suspended',
+      suspendReason: 'approval',
+      pendingApprovals: [
+        {
+          type: 'tool-call',
+          toolCallId: 'tc-claim',
+          toolName: 'refund',
+          args: {},
+        },
+      ],
+      usage: { inputTokens: 0, outputTokens: 0, model: 'test/test-model' },
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+
+    // Every concurrent approver reads the same `suspended` run with the same
+    // pending list; the store hands the claim to exactly one of them.
+    let claimsLeft = 1
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        run: async (): Promise<AIAgentStepResult> =>
+          makeStepResult({
+            text: 'Refunded',
+            usage: { inputTokens: 1, outputTokens: 1 },
+          }),
+      },
+      aiRunState: {
+        getRun: async () => run,
+        createRun: async () => 'unused',
+        updateRun: async () => {},
+        resolveApproval: async () => claimsLeft-- > 0,
+      },
+      aiStorage: {
+        saveMessages: async () => {},
+        getMessages: async () => [],
+      },
+    } as any)
+
+    const approvals = [{ toolCallId: 'tc-claim', approved: true }]
+    await resumeAIAgentSync('run-claim', approvals, asOwner('resource-claim'))
+    assert.equal(executions, 1, 'the winner ran the tool once')
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync('run-claim', approvals, asOwner('resource-claim')),
+      /already resolved by another caller/
+    )
+    assert.equal(executions, 1, 'the loser did not run it a second time')
+  })
+
   test('records denied approvals and rejects agent mismatches', async () => {
     addTestAgent('resume-agent')
 
@@ -861,6 +940,7 @@ describe('resumeAIAgentSync', () => {
         updateRun: async () => {},
         resolveApproval: async (toolCallId: string, status: string) => {
           resolveCalls.push({ toolCallId, status })
+          return true
         },
       },
       aiStorage: {
@@ -959,7 +1039,7 @@ describe('resumeAIAgentSync', () => {
       },
       aiRunState: {
         getRun: async () => run,
-        resolveApproval: async () => {},
+        resolveApproval: async () => true,
         updateRun: async () => {},
       },
       aiStorage: {