@pikku/core 0.12.20 → 0.12.22

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

@@ -1,14 +1,14 @@
 import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert'
 import { resolveModelConfig } from './ai-agent-model-config.js'
-import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import { resetPikkuState } from '../../pikku-state.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
 describe('resolveModelConfig', () => {
-  test('should return agent model when no config', () => {
+  test('passes through the provider-qualified agent model', () => {
     const result = resolveModelConfig('testAgent', {
       model: 'anthropic/claude-3',
       temperature: 0.7,
@@ -17,99 +17,21 @@ describe('resolveModelConfig', () => {
     assert.strictEqual(result.temperature, 0.7)
   })
 
-  test('should resolve model alias to string', () => {
-    pikkuState(null, 'models', 'config', {
-      models: { fast: 'anthropic/claude-haiku' },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', { model: 'fast' })
-    assert.strictEqual(result.model, 'anthropic/claude-haiku')
-  })
-
-  test('should resolve model alias with temperature and maxSteps', () => {
-    pikkuState(null, 'models', 'config', {
-      models: {
-        smart: {
-          model: 'anthropic/claude-opus',
-          temperature: 0.3,
-          maxSteps: 10,
-        },
-      },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', { model: 'smart' })
-    assert.strictEqual(result.model, 'anthropic/claude-opus')
+  test('passes through temperature and maxSteps from the agent', () => {
+    const result = resolveModelConfig('testAgent', {
+      model: 'openai/gpt-4',
+      temperature: 0.3,
+      maxSteps: 10,
+    })
+    assert.strictEqual(result.model, 'openai/gpt-4')
     assert.strictEqual(result.temperature, 0.3)
     assert.strictEqual(result.maxSteps, 10)
   })
 
-  test('should throw for unknown model alias', () => {
-    pikkuState(null, 'models', 'config', {
-      models: {},
-    } as any)
-
-    assert.throws(() => resolveModelConfig('testAgent', { model: 'unknown' }), {
-      message: "Unknown model alias 'unknown'.",
-    })
-  })
-
-  test('should pass through model with slash (not an alias)', () => {
-    pikkuState(null, 'models', 'config', {
-      models: {},
-    } as any)
-
+  test('leaves temperature and maxSteps undefined when not set', () => {
     const result = resolveModelConfig('testAgent', { model: 'openai/gpt-4' })
     assert.strictEqual(result.model, 'openai/gpt-4')
-  })
-
-  test('should use agent override model', () => {
-    pikkuState(null, 'models', 'config', {
-      models: { fast: 'anthropic/haiku' },
-      agentOverrides: { testAgent: { model: 'fast' } },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', {
-      model: 'anthropic/default',
-    })
-    assert.strictEqual(result.model, 'anthropic/haiku')
-  })
-
-  test('should use agent override temperature over alias', () => {
-    pikkuState(null, 'models', 'config', {
-      models: { smart: { model: 'anthropic/opus', temperature: 0.5 } },
-      agentOverrides: { testAgent: { model: 'smart', temperature: 0.1 } },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', {
-      model: 'anthropic/default',
-    })
-    assert.strictEqual(result.temperature, 0.1)
-  })
-
-  test('should use agentDefaults as fallback', () => {
-    pikkuState(null, 'models', 'config', {
-      models: {},
-      agentDefaults: { temperature: 0.5, maxSteps: 20 },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', {
-      model: 'anthropic/claude-3',
-    })
-    assert.strictEqual(result.temperature, 0.5)
-    assert.strictEqual(result.maxSteps, 20)
-  })
-
-  test('should prioritize: override > alias > defaults > agent', () => {
-    pikkuState(null, 'models', 'config', {
-      models: { fast: { model: 'anthropic/haiku', temperature: 0.3 } },
-      agentDefaults: { temperature: 0.5 },
-      agentOverrides: { testAgent: { temperature: 0.1 } },
-    } as any)
-
-    const result = resolveModelConfig('testAgent', {
-      model: 'fast',
-      temperature: 0.9,
-    })
-    assert.strictEqual(result.temperature, 0.1)
+    assert.strictEqual(result.temperature, undefined)
+    assert.strictEqual(result.maxSteps, undefined)
   })
 })

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

@@ -1,43 +1,19 @@
-import { pikkuState } from '../../pikku-state.js'
-
+/**
+ * Resolves the effective model/temperature/maxSteps for an agent at runtime.
+ *
+ * Models are declared per-agent using the provider-qualified `provider/model`
+ * form (e.g. `openai/gpt-5-mini`); there is no config-level alias map. This
+ * function remains the single merge point for request-time overrides (see
+ * ai-agent-prepare's `input.model`), so callers stay decoupled from how the
+ * effective config is assembled.
+ */
 export function resolveModelConfig(
-  agentName: string,
+  _agentName: string,
   agent: { model: string; temperature?: number; maxSteps?: number }
 ): { model: string; temperature?: number; maxSteps?: number } {
-  let config: any = {}
-  try {
-    config = pikkuState(null, 'models', 'config') ?? {}
-  } catch {}
-  const models = config.models ?? {}
-  const defaults = config.agentDefaults
-  const agentOverride = config.agentOverrides?.[agentName]
-
-  let rawModel = agentOverride?.model ?? agent.model
-
-  let aliasTemperature: number | undefined
-  let aliasMaxSteps: number | undefined
-  if (!rawModel.includes('/')) {
-    const entry = models[rawModel]
-    if (!entry) throw new Error(`Unknown model alias '${rawModel}'.`)
-    if (typeof entry === 'string') {
-      rawModel = entry
-    } else {
-      rawModel = entry.model
-      aliasTemperature = entry.temperature
-      aliasMaxSteps = entry.maxSteps
-    }
+  return {
+    model: agent.model,
+    temperature: agent.temperature,
+    maxSteps: agent.maxSteps,
   }
-
-  const temperature =
-    agentOverride?.temperature ??
-    aliasTemperature ??
-    defaults?.temperature ??
-    agent.temperature
-  const maxSteps =
-    agentOverride?.maxSteps ??
-    aliasMaxSteps ??
-    defaults?.maxSteps ??
-    agent.maxSteps
-
-  return { model: rawModel, temperature, maxSteps }
 }

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

@@ -0,0 +1,292 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import {
+  buildInstructions,
+  buildToolDefs,
+  createScopedChannel,
+  getAddonCredentialRequirements,
+  resolveAgent,
+} from './ai-agent-prepare.js'
+import type {
+  AIStreamChannel,
+  AIStreamEvent,
+  CoreAIAgent,
+  PikkuAIMiddlewareHooks,
+} from './ai-agent.types.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const addAgent = (agentName: string, overrides: Partial<CoreAIAgent> = {}) => {
+  const agent: CoreAIAgent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    instructions: `${agentName} instructions`,
+    model: 'test/test-model',
+    ...overrides,
+  }
+
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  pikkuState(null, 'agent', 'agentsMeta')[agentName] = {
+    ...agent,
+    inputSchema: null,
+    outputSchema: null,
+    workingMemorySchema: null,
+  } as any
+}
+
+describe('ai-agent-prepare', () => {
+  test('getAddonCredentialRequirements returns deduplicated wire oauth credentials', () => {
+    pikkuState(null, 'addons', 'packages').set('github', {
+      package: '@test/github-addon',
+    })
+    pikkuState('@test/github-addon', 'package', 'credentialsMeta', {
+      githubAuth: {
+        type: 'wire',
+        oauth2: true,
+        displayName: 'GitHub OAuth',
+      },
+      apiKey: {
+        type: 'wire',
+        oauth2: false,
+      },
+    })
+
+    const requirements = getAddonCredentialRequirements([
+      'github:getProfile',
+      'github:listRepos',
+      'localTool',
+    ])
+
+    assert.deepEqual(requirements, [
+      {
+        credentialName: 'githubAuth',
+        displayName: 'GitHub OAuth',
+        addonNamespace: 'github',
+        type: 'wire',
+        oauth2: true,
+      },
+    ])
+  })
+
+  test('resolveAgent resolves root and addon agents and rejects missing names', () => {
+    addAgent('root-agent')
+
+    const addonAgent: CoreAIAgent = {
+      name: 'addon-agent',
+      description: 'addon',
+      goal: 'addon goal',
+      instructions: 'addon instructions',
+      model: 'test/test-model',
+    }
+
+    pikkuState(null, 'addons', 'packages').set('support', {
+      package: '@test/support-addon',
+    })
+    pikkuState('@test/support-addon', 'agent', 'agents').set(
+      'helper',
+      addonAgent
+    )
+
+    assert.equal(resolveAgent('root-agent').packageName, null)
+    assert.equal(resolveAgent('root-agent').resolvedName, 'root-agent')
+    assert.equal(
+      resolveAgent('support:helper').packageName,
+      '@test/support-addon'
+    )
+    assert.equal(resolveAgent('support:helper').resolvedName, 'helper')
+    assert.throws(() => resolveAgent(''), {
+      message: 'resolveAgent called with undefined agentName',
+    })
+    assert.throws(() => resolveAgent('missing-agent'), {
+      message: 'AI agent not found: missing-agent',
+    })
+  })
+
+  test('buildInstructions includes tool and sub-agent guidance when configured', async () => {
+    addAgent('planner', {
+      role: 'You are a planner.',
+      personality: 'Be concise.',
+      goal: 'Finish the task.',
+      tools: ['search'],
+      agents: ['coder'],
+    })
+
+    const instructions = await buildInstructions('planner', null)
+    assert.match(instructions, /You are a planner\./)
+    assert.match(instructions, /Be concise\./)
+    assert.match(instructions, /Finish the task\./)
+    assert.match(instructions, /Tool usage rules:/)
+    assert.match(instructions, /When calling a sub-agent/)
+  })
+
+  test('createScopedChannel forwards stream events, captures approvals, and suppresses done', () => {
+    const events: AIStreamEvent[] = []
+    const channel = createScopedChannel(
+      {
+        channelId: 'root',
+        openingData: undefined,
+        state: 'open',
+        send: (event: AIStreamEvent) => {
+          events.push(event)
+        },
+        sendBinary: () => {},
+        close: () => {},
+        setState: () => {},
+        getState: () => 'open',
+        clearState: () => {},
+      } as AIStreamChannel,
+      'sub-agent',
+      'session-1'
+    )
+
+    channel.send({ type: 'text-delta', text: 'hello' } as AIStreamEvent)
+    channel.send({
+      type: 'approval-request',
+      toolCallId: 'tc-1',
+      toolName: 'tool-a',
+      args: { x: 1 },
+      runId: 'run-1',
+    } as AIStreamEvent)
+    channel.send({ type: 'done' } as AIStreamEvent)
+
+    assert.equal(events.length, 1)
+    assert.equal(events[0].type, 'text-delta')
+    assert.deepEqual(channel.approvals, [
+      {
+        toolCallId: 'tc-1',
+        toolName: 'tool-a',
+        args: { x: 1 },
+        runId: 'run-1',
+      },
+    ])
+    assert.equal(channel.channelId, 'root:sub-agent:session-1')
+  })
+
+  test('buildToolDefs reports missing RPCs, builds approval descriptions, and wraps tool hooks', async () => {
+    addAgent('ops-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['ops-agent'] = {
+      ...pikkuState(null, 'agent', 'agentsMeta')['ops-agent'],
+      tools: ['missingTool', 'deploy'],
+    } as any
+    pikkuState(null, 'rpc', 'meta').deploy = 'deploy'
+    pikkuState(null, 'function', 'meta').deploy = {
+      description: 'Deploy the service',
+      approvalRequired: true,
+      inputSchemaName: 'DeployInput',
+    }
+    pikkuState(null, 'misc', 'schemas').set('DeployInput', {
+      type: 'object',
+    })
+    pikkuState(null, 'function', 'functions').set('deploy', {
+      func: async (_services: any, input: any) => `ok:${JSON.stringify(input)}`,
+      approvalDescription: async (_services: any, input: any) =>
+        `Deploy ${input.env}`,
+    })
+
+    const beforeCalls: unknown[] = []
+    const afterCalls: unknown[] = []
+    const middlewares: PikkuAIMiddlewareHooks[] = [
+      {
+        beforeToolCall: async (_services, ctx) => {
+          beforeCalls.push(ctx)
+          return { args: { ...(ctx.args as any), extra: true } }
+        },
+        afterToolCall: async (_services, ctx) => {
+          afterCalls.push(ctx)
+          return { result: `wrapped:${String(ctx.result)}` }
+        },
+      },
+    ]
+
+    const singletonServices = {
+      logger: {
+        warn: () => {},
+      },
+    } as any
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
+
+    const { tools, missingRpcs } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'ops-agent',
+      null,
+      undefined,
+      middlewares
+    )
+
+    assert.deepEqual(missingRpcs, ['missingTool'])
+    assert.equal(tools.length, 1)
+    assert.equal(tools[0].name, 'deploy')
+    assert.equal(tools[0].needsApproval, true)
+    assert.deepEqual(tools[0].inputSchema, { type: 'object', properties: {} })
+    assert.equal(
+      await tools[0].approvalDescriptionFn?.({ env: 'prod' }),
+      'Deploy prod'
+    )
+
+    const result = await tools[0].execute({ env: 'prod' })
+    assert.equal(result, 'wrapped:ok:{"env":"prod","extra":true}')
+    assert.equal(beforeCalls.length, 1)
+    assert.equal(afterCalls.length, 1)
+  })
+
+  test('buildToolDefs skips permissioned tools without a session and adds sub-agent tools', async () => {
+    addAgent('manager', {
+      agents: ['assistant'],
+    })
+    addAgent('assistant', {
+      description: 'Assistant agent',
+    })
+
+    pikkuState(null, 'agent', 'agentsMeta').manager = {
+      ...pikkuState(null, 'agent', 'agentsMeta').manager,
+      tools: ['secret-tool'],
+      agents: ['assistant'],
+    } as any
+    pikkuState(null, 'rpc', 'meta')['secret-tool'] = 'secret-tool'
+    pikkuState(null, 'function', 'meta')['secret-tool'] = {
+      description: 'Secret tool',
+      permissions: ['admin'],
+      inputSchemaName: 'SecretInput',
+    }
+    pikkuState(null, 'misc', 'schemas').set('SecretInput', {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+    })
+
+    const singletonServices = {
+      logger: {
+        warn: () => {},
+      },
+    } as any
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
+
+    const { tools } = await buildToolDefs(
+      {},
+      new Map<string, string>(),
+      'resource-1',
+      'manager',
+      null
+    )
+
+    assert.equal(tools.length, 1)
+    assert.equal(tools[0].name, 'assistant')
+    assert.deepEqual(tools[0].inputSchema, {
+      type: 'object',
+      properties: {
+        message: { type: 'string' },
+        session: {
+          type: 'string',
+          description: 'Short session label for thread continuity',
+        },
+      },
+      required: ['message', 'session'],
+    })
+  })
+})

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

@@ -265,6 +265,9 @@ export function createScopedChannel(
         parent.send(event)
       }
     },
+    setState: (s) => parent.setState(s),
+    getState: () => parent.getState(),
+    clearState: () => parent.clearState(),
   }
 }
 
@@ -386,7 +389,7 @@ export async function buildToolDefs(
       }
 
       tools.push({
-        name: toolName.replaceAll(':', '__'),
+        name: toolName.replaceAll('@', '_').replaceAll(':', '__'),
         description: fnMeta?.description || fnMeta?.title || toolName,
         inputSchema,
         needsApproval: needsApproval || undefined,