@pikku/core 0.12.106 → 0.12.111

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

@@ -1,496 +0,0 @@
-import { randomUUID } from 'crypto'
-import type { CoreSingletonServices } from '../../types/core.types.js'
-import type {
-  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 { PikkuAgentMiddlewareHooks } from './agent.types.js'
-
-export function resolveMemoryServices(
-  agent: CoreAgent,
-  singletonServices: CoreSingletonServices
-): {
-  storage: AgentStorageService | undefined
-} {
-  const memoryConfig = agent.memory
-  const storage = 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,
-          AgentStorageService | undefined
-        >
-      )[memoryConfig.storage]
-    : singletonServices.agentStorage
-  return { storage }
-}
-
-export function isWorkingMemoryEnabled(
-  memoryConfig: AgentMemoryConfig | undefined,
-  storage: AgentStorageService | undefined
-): boolean {
-  return !!memoryConfig?.workingMemory && !!storage
-}
-
-/**
- * Merges a model-emitted working memory update into the stored state.
- *
- * Objects merge key by key, and `null` deletes a key. Arrays are replaced
- * wholesale — deliberately, not as a side effect of the object guard below.
- * The full state is echoed back to the model every turn by
- * {@link buildWorkingMemoryPrompt}, so it can always re-emit an array in full,
- * and appending instead would duplicate every item each time it did.
- * `buildWorkingMemoryPrompt` states this contract to the model; the two must
- * stay in agreement.
- */
-export function deepMergeWorkingMemory(
-  existing: Record<string, unknown>,
-  updates: Record<string, unknown>
-): Record<string, unknown> {
-  const result = { ...existing }
-  for (const key of Object.keys(updates)) {
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-      continue
-    }
-    const value = updates[key]
-    if (value === null) {
-      delete result[key]
-    } else if (Array.isArray(value)) {
-      result[key] = value
-    } else if (
-      typeof value === 'object' &&
-      typeof result[key] === 'object' &&
-      result[key] !== null &&
-      !Array.isArray(result[key])
-    ) {
-      result[key] = deepMergeWorkingMemory(
-        result[key] as Record<string, unknown>,
-        value as Record<string, unknown>
-      )
-    } else {
-      result[key] = value
-    }
-  }
-  return result
-}
-
-export function buildWorkingMemoryPrompt(
-  currentState: Record<string, unknown> | null,
-  jsonSchema?: Record<string, unknown>
-): string {
-  const parts: string[] = []
-
-  if (jsonSchema?.properties) {
-    const props = jsonSchema.properties as Record<
-      string,
-      { type?: string; description?: string }
-    >
-    const fieldLines = Object.entries(props).map(([name, def]) => {
-      const type = def.type ?? 'unknown'
-      const desc = def.description ? ` - ${def.description}` : ''
-      return `  - ${name} (${type})${desc}`
-    })
-    if (fieldLines.length > 0) {
-      parts.push(`Working memory fields:\n${fieldLines.join('\n')}`)
-    }
-  }
-
-  if (currentState && Object.keys(currentState).length > 0) {
-    parts.push(`Current working memory:\n${JSON.stringify(currentState)}`)
-  } else {
-    parts.push('Current working memory: (empty)')
-  }
-
-  parts.push(
-    'When you learn new information, output a partial JSON update in <working_memory> tags. ' +
-      'Only include durable facts you have actually derived or the user has confirmed. ' +
-      'Do not output templates, placeholders, or narration. ' +
-      'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it. ' +
-      'Arrays are replaced, not merged: to change one, repeat every item you want to keep alongside the new ones, ' +
-      'because any item you leave out is deleted.'
-  )
-
-  return parts.join('\n\n')
-}
-
-export async function loadContextMessages(
-  memoryConfig: AgentMemoryConfig | undefined,
-  storage: AgentStorageService | undefined,
-  input: AgentInput,
-  workingMemoryJsonSchema?: Record<string, unknown>
-): Promise<AgentMessage[]> {
-  const contextMessages: AgentMessage[] = []
-
-  const workingMemoryStorage = isWorkingMemoryEnabled(memoryConfig, storage)
-    ? storage
-    : undefined
-
-  if (workingMemoryStorage) {
-    const workingMem = await workingMemoryStorage.getWorkingMemory(
-      input.threadId,
-      'thread'
-    )
-    const prompt = buildWorkingMemoryPrompt(workingMem, workingMemoryJsonSchema)
-    contextMessages.push({
-      id: `wm-${randomUUID()}`,
-      role: 'system',
-      content: prompt,
-      createdAt: new Date(),
-    })
-  }
-
-  return contextMessages
-}
-
-export async function saveMessages(
-  storage: AgentStorageService | undefined,
-  threadId: string,
-  resourceId: string,
-  memoryConfig: AgentMemoryConfig | undefined,
-  userMessage: AgentMessage | null | undefined,
-  result: {
-    text: string
-    uiSpec?: unknown
-    steps: Pick<AgentStep, 'toolCalls'>[]
-  }
-): Promise<string> {
-  const responseText = memoryConfig?.workingMemory
-    ? extractWorkingMemory(result.text).cleanedText
-    : result.text
-
-  if (storage) {
-    const newMessages: AgentMessage[] = userMessage ? [userMessage] : []
-
-    for (const step of result.steps) {
-      if (step.toolCalls?.length) {
-        const toolCallIds = step.toolCalls.map(() => randomUUID())
-        newMessages.push({
-          id: randomUUID(),
-          role: 'assistant',
-          toolCalls: step.toolCalls.map((tc, i) => ({
-            id: toolCallIds[i],
-            name: tc.name,
-            args: tc.args,
-          })),
-          createdAt: new Date(),
-        })
-        newMessages.push({
-          id: randomUUID(),
-          role: 'tool',
-          toolResults: step.toolCalls.map((tc, i) => ({
-            id: toolCallIds[i],
-            name: tc.name,
-            result: tc.result,
-            ...(tc.error ? { error: tc.error } : {}),
-          })),
-          createdAt: new Date(),
-        })
-      }
-    }
-
-    const assistantContent =
-      result.uiSpec != null
-        ? [
-            ...(responseText
-              ? [{ type: 'text' as const, text: responseText }]
-              : []),
-            { type: 'generative-ui' as const, spec: result.uiSpec },
-          ]
-        : responseText
-
-    newMessages.push({
-      id: randomUUID(),
-      role: 'assistant',
-      content: assistantContent || undefined,
-      createdAt: new Date(),
-    })
-
-    await storage.saveMessages(threadId, newMessages)
-  }
-
-  return responseText
-}
-
-export function trimMessages(
-  messages: AgentMessage[],
-  maxTokenBudget: number = 100000
-): AgentMessage[] {
-  const sanitized = sanitizeToolMessages(messages)
-
-  let estimatedTokens = 0
-  const result: AgentMessage[] = []
-
-  for (let i = sanitized.length - 1; i >= 0; i--) {
-    const msg = sanitized[i]
-    const msgTokens = estimateTokens(msg)
-    if (estimatedTokens + msgTokens > maxTokenBudget && result.length > 0) {
-      break
-    }
-    estimatedTokens += msgTokens
-    result.unshift(msg)
-  }
-
-  if (
-    result.length > 0 &&
-    result[0].role !== 'user' &&
-    result[0].role !== 'system'
-  ) {
-    const firstUserIdx = result.findIndex(
-      (m) => m.role === 'user' || m.role === 'system'
-    )
-    if (firstUserIdx > 0) {
-      return result.slice(firstUserIdx)
-    }
-  }
-
-  return result
-}
-
-function sanitizeToolMessages(messages: AgentMessage[]): AgentMessage[] {
-  const result: AgentMessage[] = []
-
-  for (let i = 0; i < messages.length; i++) {
-    const msg = messages[i]
-
-    if (msg.role === 'assistant' && msg.toolCalls?.length) {
-      const next = messages[i + 1]
-      if (!next || next.role !== 'tool' || !next.toolResults?.length) {
-        if (msg.content) {
-          result.push({ ...msg, toolCalls: undefined })
-        }
-        continue
-      }
-
-      const toolCallIds = new Set(msg.toolCalls.map((tc) => tc.id))
-      const resultIds = new Set(next.toolResults.map((tr) => tr.id))
-      const allMatched = [...toolCallIds].every((id) => resultIds.has(id))
-
-      if (!allMatched) {
-        if (msg.content) {
-          result.push({ ...msg, toolCalls: undefined })
-        }
-        result.push({
-          ...next,
-          toolResults:
-            next.toolResults.filter((tr) => !toolCallIds.has(tr.id)) ||
-            undefined,
-        })
-        i++
-        continue
-      }
-    }
-
-    result.push(msg)
-  }
-
-  return result.filter(
-    (m) => m.role !== 'tool' || (m.toolResults && m.toolResults.length > 0)
-  )
-}
-
-function estimateTokens(msg: AgentMessage): number {
-  let chars = 0
-  if (msg.content) {
-    if (typeof msg.content === 'string') {
-      chars += msg.content.length
-    } else {
-      for (const part of msg.content) {
-        if (part.type === 'text') chars += part.text.length
-        else chars += 1000
-      }
-    }
-  }
-  if (msg.toolCalls) chars += JSON.stringify(msg.toolCalls).length
-  if (msg.toolResults) chars += JSON.stringify(msg.toolResults).length
-  return Math.ceil(chars / 4)
-}
-
-export function parseWorkingMemory(
-  text: string
-): Record<string, unknown> | null {
-  const match = text.match(/<working_memory>([\s\S]*?)<\/working_memory>/)
-  if (!match) return null
-  try {
-    return JSON.parse(match[1].trim())
-  } catch {
-    return null
-  }
-}
-
-export function stripWorkingMemoryTags(text: string): string {
-  return text.replace(/<working_memory>[\s\S]*?<\/working_memory>/g, '').trim()
-}
-
-export function extractWorkingMemory(text: string): {
-  workingMemory: Record<string, unknown> | null
-  cleanedText: string
-} {
-  const workingMemory = parseWorkingMemory(text)
-  return {
-    workingMemory,
-    cleanedText: workingMemory ? stripWorkingMemoryTags(text) : text,
-  }
-}
-
-function getPendingWorkingMemoryPrefixLength(text: string): number {
-  const prefixes = ['<working_memory>', '</working_memory>']
-  const lastLt = text.lastIndexOf('<')
-  if (lastLt === -1) return 0
-
-  const suffix = text.slice(lastLt)
-  for (const prefix of prefixes) {
-    if (prefix.startsWith(suffix)) {
-      return suffix.length
-    }
-  }
-
-  return 0
-}
-
-export function stripWorkingMemoryForStreaming(text: string): string {
-  let output = ''
-  let cursor = 0
-
-  while (cursor < text.length) {
-    const openIndex = text.indexOf('<working_memory>', cursor)
-    if (openIndex === -1) {
-      const tail = text.slice(cursor)
-      const pendingPrefixLength = getPendingWorkingMemoryPrefixLength(tail)
-      output +=
-        pendingPrefixLength > 0 ? tail.slice(0, -pendingPrefixLength) : tail
-      return output
-    }
-
-    output += text.slice(cursor, openIndex)
-    const closeIndex = text.indexOf('</working_memory>', openIndex)
-    if (closeIndex === -1) {
-      return output
-    }
-
-    cursor = closeIndex + '</working_memory>'.length
-  }
-
-  return output
-}
-
-async function persistWorkingMemory(
-  options: {
-    storage?: AgentStorageService
-    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?: AgentStorageService
-  threadId: string
-  workingMemorySchemaName?: string | null
-  logger?: Logger
-  schemaService?: SchemaService
-}): PikkuAgentMiddlewareHooks<{
-  rawText?: string
-  emittedVisibleText?: string
-}> {
-  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}`
-      state.rawText = rawText
-
-      const visibleText = stripWorkingMemoryForStreaming(rawText)
-      const emittedVisibleText = state.emittedVisibleText ?? ''
-
-      if (!visibleText.startsWith(emittedVisibleText)) {
-        state.emittedVisibleText = visibleText
-        return { ...event, text: visibleText }
-      }
-
-      const delta = visibleText.slice(emittedVisibleText.length)
-      state.emittedVisibleText = visibleText
-      if (!delta) return null
-      return { ...event, text: delta }
-    },
-    modifyOutput: async (_services, { text, messages }) => {
-      const { workingMemory, cleanedText } = extractWorkingMemory(text)
-      if (workingMemory) {
-        await persistWorkingMemory(options, workingMemory)
-      }
-
-      return {
-        text: cleanedText,
-        messages,
-      }
-    },
-  }
-}
-
-export function getWorkingMemoryMiddleware(
-  memoryConfig: AgentMemoryConfig | undefined,
-  storage: AgentStorageService | undefined,
-  options: {
-    threadId: string
-    workingMemorySchemaName?: string | null
-    logger?: Logger
-    schemaService?: SchemaService
-  }
-): PikkuAgentMiddlewareHooks[] {
-  if (!isWorkingMemoryEnabled(memoryConfig, storage)) return []
-
-  return [
-    createWorkingMemoryMiddleware({
-      storage,
-      threadId: options.threadId,
-      workingMemorySchemaName: options.workingMemorySchemaName,
-      logger: options.logger,
-      schemaService: options.schemaService,
-    }),
-  ]
-}

package/src/wirings/agent/agent-middleware.types.test.ts

@@ -1,41 +0,0 @@
-// Type-checked via tsconfig.type-tests.json; no runtime assertions.
-
-import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
-import type { PikkuAgentMiddlewareHooks } from './agent.types.js'
-
-const _singletonServicesCompile = pikkuAgentMiddleware<{ count: number }>({
-  modifyInput: async ({ logger }, { messages, instructions }) => {
-    logger.info(`agent input: ${messages.length} messages`)
-    return { messages, instructions }
-  },
-  modifyOutputStream: async ({ logger }, { event, state }) => {
-    state.count = (state.count ?? 0) + 1
-    logger.info(`event: ${event.type}`)
-    return event
-  },
-  afterStep: async ({ variables }, { stepNumber }) => {
-    variables.get(`STEP_${stepNumber}`)
-  },
-  onError: async ({ logger }, { error }) => {
-    logger.error(error.message)
-  },
-})
-void _singletonServicesCompile
-
-const _wireServiceIsNotAvailable: PikkuAgentMiddlewareHooks = {
-  // @ts-expect-error — `http` is a wire service, and an agent run has no wire
-  modifyInput: async ({ http }, { messages, instructions }) => {
-    void http
-    return { messages, instructions }
-  },
-}
-void _wireServiceIsNotAvailable
-
-const _wireServiceIsNotAvailableToTheFactory = pikkuAgentMiddleware({
-  // @ts-expect-error — `channel` is a wire service, and an agent run has no wire
-  afterToolCall: async ({ channel }, { result }) => {
-    void channel
-    return { result }
-  },
-})
-void _wireServiceIsNotAvailableToTheFactory

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

@@ -1,103 +0,0 @@
-import { describe, test, beforeEach, afterEach } from 'node:test'
-import assert from 'node:assert'
-import { resolveModelAlias, resolveModelConfig } from './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', () => {
-  test('passes through the provider-qualified agent model', () => {
-    const result = resolveModelConfig('testAgent', {
-      model: 'anthropic/claude-3',
-      temperature: 0.7,
-    })
-    assert.strictEqual(result.model, 'anthropic/claude-3')
-    assert.strictEqual(result.temperature, 0.7)
-  })
-
-  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('leaves temperature and maxSteps undefined when not set', () => {
-    const result = resolveModelConfig('testAgent', { model: 'openai/gpt-4' })
-    assert.strictEqual(result.model, 'openai/gpt-4')
-    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 `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'
-    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/agent/agent-model-config.ts

@@ -1,59 +0,0 @@
-// knowledge: decisions/internals/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: resolveModelAlias(agent.model),
-    temperature: agent.temperature,
-    maxSteps: agent.maxSteps,
-  }
-}