@pikku/core 0.12.82 → 0.12.84

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

@@ -1,22 +1,22 @@
 import { randomUUID } from 'crypto'
 import type { CoreSingletonServices } from '../../types/core.types.js'
 import type {
-  CoreAIAgent,
-  AIAgentMemoryConfig,
-  AIAgentInput,
-  AIAgentStep,
-  AIMessage,
-} from './ai-agent.types.js'
-import type { AIStorageService } from '../../services/ai-storage-service.js'
+  CoreAgent,
+  AgentMemoryConfig,
+  AgentInput,
+  AgentStep,
+  AgentMessage,
+} from './agent.types.js'
+import type { AgentStorageService } from '../../services/agent-storage-service.js'
 import type { Logger } from '../../services/logger.js'
 import type { SchemaService } from '../../services/schema-service.js'
-import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js'
+import type { PikkuAgentMiddlewareHooks } from './agent.types.js'
 
 export function resolveMemoryServices(
-  agent: CoreAIAgent,
+  agent: CoreAgent,
   singletonServices: CoreSingletonServices
 ): {
-  storage: AIStorageService | undefined
+  storage: AgentStorageService | undefined
 } {
   const memoryConfig = agent.memory
   const storage = memoryConfig?.storage
@@ -25,16 +25,16 @@ export function resolveMemoryServices(
       (
         singletonServices as unknown as Record<
           string,
-          AIStorageService | undefined
+          AgentStorageService | undefined
         >
       )[memoryConfig.storage]
-    : singletonServices.aiStorage
+    : singletonServices.agentStorage
   return { storage }
 }
 
 export function isWorkingMemoryEnabled(
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  storage: AIStorageService | undefined
+  memoryConfig: AgentMemoryConfig | undefined,
+  storage: AgentStorageService | undefined
 ): boolean {
   return !!memoryConfig?.workingMemory && !!storage
 }
@@ -107,12 +107,12 @@ export function buildWorkingMemoryPrompt(
 }
 
 export async function loadContextMessages(
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  storage: AIStorageService | undefined,
-  input: AIAgentInput,
+  memoryConfig: AgentMemoryConfig | undefined,
+  storage: AgentStorageService | undefined,
+  input: AgentInput,
   workingMemoryJsonSchema?: Record<string, unknown>
-): Promise<AIMessage[]> {
-  const contextMessages: AIMessage[] = []
+): Promise<AgentMessage[]> {
+  const contextMessages: AgentMessage[] = []
 
   const workingMemoryStorage = isWorkingMemoryEnabled(memoryConfig, storage)
     ? storage
@@ -136,15 +136,15 @@ export async function loadContextMessages(
 }
 
 export async function saveMessages(
-  storage: AIStorageService | undefined,
+  storage: AgentStorageService | undefined,
   threadId: string,
   resourceId: string,
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  userMessage: AIMessage | null | undefined,
+  memoryConfig: AgentMemoryConfig | undefined,
+  userMessage: AgentMessage | null | undefined,
   result: {
     text: string
     uiSpec?: unknown
-    steps: Pick<AIAgentStep, 'toolCalls'>[]
+    steps: Pick<AgentStep, 'toolCalls'>[]
   }
 ): Promise<string> {
   const responseText = memoryConfig?.workingMemory
@@ -152,7 +152,7 @@ export async function saveMessages(
     : result.text
 
   if (storage) {
-    const newMessages: AIMessage[] = userMessage ? [userMessage] : []
+    const newMessages: AgentMessage[] = userMessage ? [userMessage] : []
 
     for (const step of result.steps) {
       if (step.toolCalls?.length) {
@@ -205,13 +205,13 @@ export async function saveMessages(
 }
 
 export function trimMessages(
-  messages: AIMessage[],
+  messages: AgentMessage[],
   maxTokenBudget: number = 100000
-): AIMessage[] {
+): AgentMessage[] {
   const sanitized = sanitizeToolMessages(messages)
 
   let estimatedTokens = 0
-  const result: AIMessage[] = []
+  const result: AgentMessage[] = []
 
   for (let i = sanitized.length - 1; i >= 0; i--) {
     const msg = sanitized[i]
@@ -239,8 +239,8 @@ export function trimMessages(
   return result
 }
 
-function sanitizeToolMessages(messages: AIMessage[]): AIMessage[] {
-  const result: AIMessage[] = []
+function sanitizeToolMessages(messages: AgentMessage[]): AgentMessage[] {
+  const result: AgentMessage[] = []
 
   for (let i = 0; i < messages.length; i++) {
     const msg = messages[i]
@@ -281,7 +281,7 @@ function sanitizeToolMessages(messages: AIMessage[]): AIMessage[] {
   )
 }
 
-function estimateTokens(msg: AIMessage): number {
+function estimateTokens(msg: AgentMessage): number {
   let chars = 0
   if (msg.content) {
     if (typeof msg.content === 'string') {
@@ -368,7 +368,7 @@ export function stripWorkingMemoryForStreaming(text: string): string {
 
 async function persistWorkingMemory(
   options: {
-    storage?: AIStorageService
+    storage?: AgentStorageService
     threadId: string
     workingMemorySchemaName?: string | null
     logger?: Logger
@@ -400,12 +400,12 @@ async function persistWorkingMemory(
 }
 
 export function createWorkingMemoryMiddleware(options: {
-  storage?: AIStorageService
+  storage?: AgentStorageService
   threadId: string
   workingMemorySchemaName?: string | null
   logger?: Logger
   schemaService?: SchemaService
-}): PikkuAIMiddlewareHooks<{
+}): PikkuAgentMiddlewareHooks<{
   rawText?: string
   emittedVisibleText?: string
 }> {
@@ -459,15 +459,15 @@ export function createWorkingMemoryMiddleware(options: {
 }
 
 export function getWorkingMemoryMiddleware(
-  memoryConfig: AIAgentMemoryConfig | undefined,
-  storage: AIStorageService | undefined,
+  memoryConfig: AgentMemoryConfig | undefined,
+  storage: AgentStorageService | undefined,
   options: {
     threadId: string
     workingMemorySchemaName?: string | null
     logger?: Logger
     schemaService?: SchemaService
   }
-): PikkuAIMiddlewareHooks[] {
+): PikkuAgentMiddlewareHooks[] {
   if (!isWorkingMemoryEnabled(memoryConfig, storage)) return []
 
   return [

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

@@ -1,9 +1,6 @@
 import { describe, test, beforeEach, afterEach } from 'node:test'
 import assert from 'node:assert'
-import {
-  resolveModelAlias,
-  resolveModelConfig,
-} from './ai-agent-model-config.js'
+import { resolveModelAlias, resolveModelConfig } from './agent-model-config.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 
 const setAliases = (aliases: Record<string, string>) =>
@@ -81,7 +78,7 @@ describe('resolveModelAlias', () => {
   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
+    // resolved value is one `VercelAgentRunner.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'

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

@@ -1,4 +1,4 @@
-// knowledge: decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md
+// knowledge: decisions/internals/agent-model-config-stays-a-single-resolution-seam.md
 import { pikkuState } from '../../pikku-state.js'
 
 const isProviderQualified = (model: string) => model.includes('/')

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

@@ -18,22 +18,22 @@ import {
   resolveOwnerResourceId,
   sessionPrincipals,
   threadOwnerConstraint,
-} from './ai-agent-prepare.js'
+} from './agent-prepare.js'
 import { ForbiddenError, MissingCredentialError } from '../../errors/errors.js'
 import { pikkuAuth } from '../../function/functions.types.js'
 import type {
-  AIStreamChannel,
-  AIStreamEvent,
-  CoreAIAgent,
-  PikkuAIMiddlewareHooks,
-} from './ai-agent.types.js'
+  AgentStreamChannel,
+  AgentStreamEvent,
+  CoreAgent,
+  PikkuAgentMiddlewareHooks,
+} from './agent.types.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
-const addAgent = (agentName: string, overrides: Partial<CoreAIAgent> = {}) => {
-  const agent: CoreAIAgent = {
+const addAgent = (agentName: string, overrides: Partial<CoreAgent> = {}) => {
+  const agent: CoreAgent = {
     name: agentName,
     description: `${agentName} description`,
     goal: `${agentName} goal`,
@@ -51,7 +51,7 @@ const addAgent = (agentName: string, overrides: Partial<CoreAIAgent> = {}) => {
   } as any
 }
 
-describe('ai-agent-prepare', () => {
+describe('agent-prepare', () => {
   test('getAddonCredentialRequirements returns deduplicated wire oauth credentials', () => {
     pikkuState(null, 'addons', 'packages').set('github', {
       package: '@test/github-addon',
@@ -88,7 +88,7 @@ describe('ai-agent-prepare', () => {
   test('resolveAgent resolves root and addon agents and rejects missing names', () => {
     addAgent('root-agent')
 
-    const addonAgent: CoreAIAgent = {
+    const addonAgent: CoreAgent = {
       name: 'addon-agent',
       description: 'addon',
       goal: 'addon goal',
@@ -164,13 +164,13 @@ describe('ai-agent-prepare', () => {
   })
 
   test('createScopedChannel forwards stream events, captures approvals, and suppresses done', () => {
-    const events: AIStreamEvent[] = []
+    const events: AgentStreamEvent[] = []
     const channel = createScopedChannel(
       {
         channelId: 'root',
         openingData: undefined,
         state: 'open',
-        send: (event: AIStreamEvent) => {
+        send: (event: AgentStreamEvent) => {
           events.push(event)
         },
         sendBinary: () => {},
@@ -178,12 +178,12 @@ describe('ai-agent-prepare', () => {
         setState: () => {},
         getState: () => 'open',
         clearState: () => {},
-      } as AIStreamChannel,
+      } as AgentStreamChannel,
       'sub-agent',
       'session-1'
     )
 
-    channel.send({ type: 'text-delta', text: 'hello' } as AIStreamEvent)
+    channel.send({ type: 'text-delta', text: 'hello' } as AgentStreamEvent)
     channel.send({
       type: 'approval-request',
       toolCallId: 'tc-1',
@@ -191,8 +191,8 @@ describe('ai-agent-prepare', () => {
       args: { x: 1 },
       reason: 'Delete todo "x"',
       runId: 'run-1',
-    } as AIStreamEvent)
-    channel.send({ type: 'done' } as AIStreamEvent)
+    } as AgentStreamEvent)
+    channel.send({ type: 'done' } as AgentStreamEvent)
 
     assert.equal(events.length, 1)
     assert.equal(events[0].type, 'text-delta')
@@ -232,7 +232,7 @@ describe('ai-agent-prepare', () => {
 
     const beforeCalls: unknown[] = []
     const afterCalls: unknown[] = []
-    const middlewares: PikkuAIMiddlewareHooks[] = [
+    const middlewares: PikkuAgentMiddlewareHooks[] = [
       {
         beforeToolCall: async (_services, ctx) => {
           beforeCalls.push(ctx)
@@ -333,7 +333,7 @@ describe('ai-agent-prepare', () => {
     )
   })
 
-  test('buildToolDefs logs a tool execute() failure even without aiMiddleware hooks, then rethrows', async () => {
+  test('buildToolDefs logs a tool execute() failure even without agentMiddleware hooks, then rethrows', async () => {
     addAgent('ops-agent')
     pikkuState(null, 'agent', 'agentsMeta')['ops-agent'] = {
       ...pikkuState(null, 'agent', 'agentsMeta')['ops-agent'],

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

@@ -1,16 +1,16 @@
 import type { PikkuRawWire, CoreUserSession } from '../../types/core.types.js'
 import type {
-  CoreAIAgent,
-  AIAgentInput,
-  AIAgentToolDef,
-  AIContentPart,
-  AIMessage,
-  AIStreamChannel,
-  AIStreamEvent,
-  PikkuAIMiddlewareHooks,
+  CoreAgent,
+  AgentInput,
+  AgentToolDef,
+  AgentContentPart,
+  AgentMessage,
+  AgentStreamChannel,
+  AgentStreamEvent,
+  PikkuAgentMiddlewareHooks,
   SessionScope,
-} from './ai-agent.types.js'
-import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
+} from './agent.types.js'
+import type { AgentRunnerParams } from '../../services/agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
 import {
   checkAuthPermissions,
@@ -23,10 +23,10 @@ import { verifyScopes } from '../../scopes.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
-import { randomUUID } from './ai-agent-utils.js'
-import { awaitPendingInterruptNote } from './ai-agent-interrupt.js'
-import { streamAIAgent } from './ai-agent-stream.js'
-import { runAIAgent } from './ai-agent-runner.js'
+import { randomUUID } from './agent-utils.js'
+import { awaitPendingInterruptNote } from './agent-interrupt.js'
+import { streamAgent } from './agent-stream.js'
+import { runAgent } from './agent-runner.js'
 import {
   resolveNamespace,
   ContextAwareRPCService,
@@ -36,10 +36,10 @@ import {
   resolveMemoryServices,
   loadContextMessages,
   trimMessages,
-} from './ai-agent-memory.js'
-import { resolveModelConfig } from './ai-agent-model-config.js'
+} from './agent-memory.js'
+import { resolveModelConfig } from './agent-model-config.js'
 
-export type RunAIAgentParams = {
+export type RunAgentParams = {
   sessionService?: SessionService<CoreUserSession>
   /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
   getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>
@@ -48,7 +48,7 @@ export type RunAIAgentParams = {
 }
 
 export function resolveSessionPrincipal(
-  params: RunAIAgentParams,
+  params: RunAgentParams,
   sessionScope: SessionScope | undefined
 ): string | undefined {
   const session = params.sessionService?.get()
@@ -64,7 +64,7 @@ export function resolveSessionPrincipal(
 }
 
 export function resolveOwnerResourceId(
-  params: RunAIAgentParams,
+  params: RunAgentParams,
   sessionScope: SessionScope | undefined,
   requestedResourceId: string
 ): string {
@@ -85,7 +85,7 @@ export function resolveOwnerResourceId(
 }
 
 export function assertResourcePrincipalOwner(
-  params: RunAIAgentParams,
+  params: RunAgentParams,
   sessionScope: SessionScope | undefined,
   storedResourceId: string,
   kind: 'thread' | 'run'
@@ -145,7 +145,7 @@ export function canAccessThread(
   )
 }
 
-export type StreamAIAgentOptions = {
+export type StreamAgentOptions = {
   requiresToolApproval?: 'all' | 'explicit' | false
   onRunCreated?: (runId: string) => void
 }
@@ -258,14 +258,14 @@ export function getAddonCredentialRequirements(
 }
 
 export type StreamContext = {
-  channel: AIStreamChannel
-  options?: StreamAIAgentOptions
+  channel: AgentStreamChannel
+  options?: StreamAgentOptions
   delegateState?: { delegated: boolean }
 }
 
 export const resolveAgent = (
   agentName: string
-): { agent: CoreAIAgent; packageName: string | null; resolvedName: string } => {
+): { agent: CoreAgent; packageName: string | null; resolvedName: string } => {
   if (!agentName) {
     console.error(
       '[resolveAgent] agentName is undefined/null! Stack:',
@@ -302,8 +302,8 @@ export const resolveAgent = (
 }
 
 export async function assertAgentAuthorized(
-  agent: CoreAIAgent,
-  params: RunAIAgentParams,
+  agent: CoreAgent,
+  params: RunAgentParams,
   packageName: string | null
 ): Promise<void> {
   const session = params.sessionService
@@ -363,7 +363,7 @@ export async function buildInstructions(
   return instructions
 }
 
-export type ScopedChannel = AIStreamChannel & {
+export type ScopedChannel = AgentStreamChannel & {
   approvals: Array<{
     toolCallId: string
     toolName: string
@@ -374,7 +374,7 @@ export type ScopedChannel = AIStreamChannel & {
 }
 
 export function createScopedChannel(
-  parent: AIStreamChannel,
+  parent: AgentStreamChannel,
   agentName: string,
   session: string
 ): ScopedChannel {
@@ -391,7 +391,7 @@ export function createScopedChannel(
     },
     close: () => {},
     sendBinary: (data) => parent.sendBinary(data),
-    send: (event: AIStreamEvent) => {
+    send: (event: AgentStreamEvent) => {
       if (event.type === 'done') return
       if (event.type === 'approval-request') {
         capturedApprovals.push({
@@ -412,7 +412,7 @@ export function createScopedChannel(
         event.type === 'usage' ||
         event.type === 'error'
       ) {
-        parent.send({ ...event, agent: agentName, session } as AIStreamEvent)
+        parent.send({ ...event, agent: agentName, session } as AgentStreamEvent)
       } else {
         parent.send(event)
       }
@@ -434,18 +434,18 @@ export function buildSubAgentRunInput(
 }
 
 export async function buildToolDefs(
-  params: RunAIAgentParams,
+  params: RunAgentParams,
   agentSessionMap: Map<string, string>,
   resourceId: string,
   agentName: string,
   packageName: string | null,
   streamContext?: StreamContext,
-  aiMiddlewares?: PikkuAIMiddlewareHooks[],
+  agentMiddlewares?: PikkuAgentMiddlewareHooks[],
   agentMode?: 'delegate' | 'supervise',
   parentContext?: string
-): Promise<{ tools: AIAgentToolDef[]; missingRpcs: string[] }> {
+): Promise<{ tools: AgentToolDef[]; missingRpcs: string[] }> {
   const singletonServices = getSingletonServices()
-  const tools: AIAgentToolDef[] = []
+  const tools: AgentToolDef[] = []
   const missingRpcs: string[] = []
   const approvalPolicy =
     streamContext?.options?.requiresToolApproval ?? 'explicit'
@@ -565,6 +565,8 @@ export async function buildToolDefs(
                     variableOverrides: capturedAddonConfig?.variableOverrides,
                     credentialOverrides:
                       capturedAddonConfig?.credentialOverrides,
+                    secretGrants: capturedAddonConfig?.secretGrants,
+                    credentialGrants: capturedAddonConfig?.credentialGrants,
                     globalSecrets: capturedAddonConfig?.globalSecrets,
                     globalCredentials: capturedAddonConfig?.globalCredentials,
                   }
@@ -676,7 +678,7 @@ export async function buildToolDefs(
               ? subChannel
               : {
                   ...subChannel,
-                  send: (event: AIStreamEvent) => {
+                  send: (event: AgentStreamEvent) => {
                     if (
                       event.type === 'text-delta' ||
                       event.type === 'reasoning-delta'
@@ -685,7 +687,7 @@ export async function buildToolDefs(
                     subChannel.send(event)
                   },
                 }
-            const resultText = await streamAIAgent(
+            const resultText = await streamAgent(
               subAgentName,
               buildSubAgentRunInput(
                 message,
@@ -717,7 +719,7 @@ export async function buildToolDefs(
             return resultText
           }
 
-          const result = await runAIAgent(
+          const result = await runAgent(
             subAgentName,
             buildSubAgentRunInput(message, threadId, resourceId, parentContext),
             params,
@@ -828,7 +830,7 @@ export async function buildToolDefs(
     }
   }
 
-  const hasToolHooks = aiMiddlewares?.some(
+  const hasToolHooks = agentMiddlewares?.some(
     (mw) => mw.beforeToolCall || mw.afterToolCall
   )
   if (hasToolHooks) {
@@ -838,7 +840,7 @@ export async function buildToolDefs(
         const toolCallId = randomUUID()
         let args = (toolInput ?? {}) as Record<string, unknown>
 
-        for (const mw of aiMiddlewares!) {
+        for (const mw of agentMiddlewares!) {
           if (mw.beforeToolCall) {
             const beforeResult = await mw.beforeToolCall(singletonServices, {
               toolName: tool.name,
@@ -863,8 +865,8 @@ export async function buildToolDefs(
         }
         const durationMs = Date.now() - startTime
 
-        for (let i = aiMiddlewares!.length - 1; i >= 0; i--) {
-          const mw = aiMiddlewares![i]
+        for (let i = agentMiddlewares!.length - 1; i >= 0; i--) {
+          const mw = agentMiddlewares![i]
           if (mw.afterToolCall) {
             const afterResult = await mw.afterToolCall(singletonServices, {
               toolName: tool.name,
@@ -890,8 +892,8 @@ export async function buildToolDefs(
 
 export async function prepareAgentRun(
   agentName: string,
-  input: AIAgentInput,
-  params: RunAIAgentParams,
+  input: AgentInput,
+  params: RunAgentParams,
   agentSessionMap: Map<string, string>,
   streamContext?: StreamContext
 ) {
@@ -900,7 +902,7 @@ export async function prepareAgentRun(
 
   await assertAgentAuthorized(agent, params, packageName)
 
-  let agentRunner = singletonServices.aiAgentRunner
+  let agentRunner = singletonServices.agentRunner
   if (!agentRunner) {
     throw new AIProviderNotConfiguredError()
   }
@@ -944,7 +946,7 @@ export async function prepareAgentRun(
     }
   }
 
-  let messages: AIMessage[] = []
+  let messages: AgentMessage[] = []
   if (storage) {
     // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
     await awaitPendingInterruptNote(threadId)
@@ -960,7 +962,7 @@ export async function prepareAgentRun(
     workingMemoryJsonSchema
   )
 
-  const userContent: AIMessage['content'] = input.attachments?.length
+  const userContent: AgentMessage['content'] = input.attachments?.length
     ? [
         // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
         ...(input.message
@@ -974,12 +976,12 @@ export async function prepareAgentRun(
               url: a.url,
               mediaType: a.mediaType,
               ...(a.filename ? { filename: a.filename } : {}),
-            }) as AIContentPart
+            }) as AgentContentPart
         ),
       ]
     : input.message
 
-  const userMessage: AIMessage = {
+  const userMessage: AgentMessage = {
     id: randomUUID(),
     role: 'user',
     content: userContent,
@@ -989,7 +991,8 @@ export async function prepareAgentRun(
   const allMessages = [...contextMessages, ...messages, userMessage]
   const trimmedMessages = trimMessages(allMessages)
 
-  const aiMiddlewares: PikkuAIMiddlewareHooks[] = agent.aiMiddleware ?? []
+  const agentMiddlewares: PikkuAgentMiddlewareHooks[] =
+    agent.agentMiddleware ?? []
 
   const { tools, missingRpcs } = await buildToolDefs(
     params,
@@ -998,7 +1001,7 @@ export async function prepareAgentRun(
     resolvedName,
     packageName,
     streamContext,
-    aiMiddlewares,
+    agentMiddlewares,
     agent.agentMode,
     input.context
   )
@@ -1022,7 +1025,7 @@ export async function prepareAgentRun(
 
   const maxSteps = resolved.maxSteps ?? 10
 
-  const runnerParams: AIAgentRunnerParams = {
+  const runnerParams: AgentRunnerParams = {
     model: resolved.model,
     temperature: resolved.temperature,
     instructions,