@things-factory/ai-client-base 10.1.129 → 10.1.155

package/server/service/agent/agent-settings-save.ts

@@ -0,0 +1,205 @@
+import { randomUUID } from 'crypto'
+import { EntityManager, In } from 'typeorm'
+
+import { Domain, EnvVar, getRepository, Refusal } from '@things-factory/shell'
+import { Setting } from '@things-factory/setting-base'
+
+import { readAiAgentDirectory, readDescendantDomains } from './agent-directory.js'
+import {
+  AI_AGENTS_SETTING,
+  AI_AGENTS_SETTING_CATEGORY,
+  aiAgentKeyName,
+  type AiAgentSpec,
+  isAiAgentProvider,
+  parseAiAgentsSetting,
+  stringifyAiAgentsSetting
+} from './agent-spec.js'
+import { listProviderModels } from './provider-models.js'
+
+/** One of this domain's own agents as the settings card sends it. No id means a new agent. */
+export interface AiAgentWrite {
+  id?: string
+  name: string
+  provider: string
+  model: string
+  baseURL?: string
+  organization?: string
+  active: boolean
+  /** A new key. Left out, the stored key stays (ADR-0112 decision 3). */
+  apiKey?: string
+}
+
+/** This domain's key for an agent it inherits - set one, or clear it to go back to the key above. */
+export interface InheritedKeyWrite {
+  agentId: string
+  apiKey?: string
+  clear?: boolean
+}
+
+export interface AiAgentsWrite {
+  /** The whole list of this domain's own agents. One that is left out is deleted. */
+  agents: AiAgentWrite[]
+  defaultAgentId?: string
+  turnedOff?: string[]
+  inheritedKeys?: InheritedKeyWrite[]
+}
+
+/**
+ * Saves a domain's agents and their keys in one transaction, touching only the request domain's rows - except that
+ * deleting an agent also removes the keys domains below had set for it (design/ai/agent-settings.md §3-2, §3-3).
+ */
+export async function saveAiAgents(
+  write: AiAgentsWrite,
+  { tx, domain, user }: { tx: EntityManager; domain: Domain; user?: { id: string } }
+): Promise<void> {
+  const directory = await readAiAgentDirectory(domain)
+  const storedById = new Map(directory.own.agents.map(one => [one.id, one]))
+  const inheritedIds = new Set(directory.entries.filter(one => one.inherited).map(one => one.spec.id))
+
+  const agents = write.agents.map(one => normalize(one, storedById))
+  refuseDuplicateNames(agents)
+  await refuseNamesTakenAround(domain, agents, directory.entries.filter(one => one.inherited).map(one => one.spec))
+
+  const storedKeyOf = new Map(
+    directory.entries.filter(one => !one.inherited && one.keyState === 'own').map(one => [one.spec.id, one.apiKey!])
+  )
+  for (const [index, agent] of agents.entries()) {
+    const newKey = write.agents[index].apiKey?.trim()
+    const key = newKey || storedKeyOf.get(agent.id)
+    if (!key) throw new Refusal('ai-agent-key-required', { agent: agent.name }, `Enter the API key of "${agent.name}".`)
+    if (needsModelCheck(agent, storedById.get(agent.id), !!newKey)) {
+      const offered = await listProviderModels({ provider: agent.provider, apiKey: key, baseURL: agent.baseURL, organization: agent.organization })
+      if (!offered.includes(agent.model)) {
+        throw new Refusal(
+          'ai-agent-model-not-offered',
+          { agent: agent.name, model: agent.model },
+          `The provider does not offer "${agent.model}" to this key.`
+        )
+      }
+    }
+  }
+
+  const ownIds = new Set(agents.map(one => one.id))
+  const defaultAgentId = write.defaultAgentId && (ownIds.has(write.defaultAgentId) || inheritedIds.has(write.defaultAgentId))
+    ? write.defaultAgentId
+    : undefined
+  if (write.defaultAgentId && !defaultAgentId) {
+    throw new Refusal('ai-agent-not-available', { agentId: write.defaultAgentId }, 'The default agent is not one this domain can use.')
+  }
+  const turnedOff = (write.turnedOff ?? []).filter(id => inheritedIds.has(id))
+
+  await upsertSetting(tx, domain, user, stringifyAiAgentsSetting({ agents, defaultAgentId, turnedOff }))
+
+  for (const [index, agent] of agents.entries()) {
+    const newKey = write.agents[index].apiKey?.trim()
+    if (newKey) await upsertKey(tx, domain, agent, newKey)
+  }
+
+  for (const one of write.inheritedKeys ?? []) {
+    if (!inheritedIds.has(one.agentId)) {
+      throw new Refusal('ai-agent-not-available', { agentId: one.agentId }, 'That agent is not inherited by this domain.')
+    }
+    if (one.clear) {
+      await tx.getRepository(EnvVar).delete({ domain: { id: domain.id }, name: aiAgentKeyName(one.agentId) })
+    } else if (one.apiKey?.trim()) {
+      const spec = directory.entries.find(entry => entry.spec.id === one.agentId)!.spec
+      await upsertKey(tx, domain, spec, one.apiKey.trim())
+    }
+  }
+
+  const deleted = directory.own.agents.filter(one => !ownIds.has(one.id)).map(one => aiAgentKeyName(one.id))
+  if (deleted.length) {
+    const below = await readDescendantDomains(domain)
+    await tx.getRepository(EnvVar).delete({
+      domain: { id: In([domain.id, ...below.map(one => one.id)]) },
+      name: In(deleted)
+    })
+  }
+}
+
+function normalize(write: AiAgentWrite, storedById: Map<string, AiAgentSpec>): AiAgentSpec {
+  const name = write.name?.trim()
+  if (!name) throw new Refusal('ai-agent-name-required', {}, 'Every agent needs a name.')
+  if (!isAiAgentProvider(write.provider)) {
+    throw new Refusal('ai-agent-provider-unknown', { provider: String(write.provider) }, `"${write.provider}" is not a provider an agent can use.`)
+  }
+  const model = write.model?.trim()
+  if (!model) throw new Refusal('ai-agent-model-required', { agent: name }, `Pick the model of "${name}".`)
+  if (write.id && !storedById.has(write.id)) {
+    throw new Refusal('ai-agent-not-in-domain', { agentId: write.id }, 'That agent does not belong to this domain.')
+  }
+  return {
+    id: write.id || randomUUID(),
+    name,
+    provider: write.provider,
+    model,
+    ...(write.baseURL?.trim() && { baseURL: write.baseURL.trim() }),
+    ...(write.provider === 'openai' && write.organization?.trim() && { organization: write.organization.trim() }),
+    active: write.active !== false
+  }
+}
+
+/** The model is checked against the provider's list when anything that decides the list, or the model, changed. */
+function needsModelCheck(agent: AiAgentSpec, stored: AiAgentSpec | undefined, newKey: boolean): boolean {
+  if (!stored || newKey) return true
+  return stored.provider !== agent.provider || stored.model !== agent.model || stored.baseURL !== agent.baseURL || stored.organization !== agent.organization
+}
+
+function refuseDuplicateNames(agents: AiAgentSpec[]) {
+  const seen = new Set<string>()
+  for (const agent of agents) {
+    const key = agent.name.toLowerCase()
+    if (seen.has(key)) throw new Refusal('ai-agent-name-taken', { name: agent.name, domain: '' }, `There is already an agent named "${agent.name}".`)
+    seen.add(key)
+  }
+}
+
+/**
+ * A name is one across the chain, so a picker never shows two agents of the same name: not the name of an agent
+ * inherited from above, nor of an agent a domain below declared.
+ */
+async function refuseNamesTakenAround(domain: Domain, agents: AiAgentSpec[], inherited: AiAgentSpec[]) {
+  const taken = new Map<string, string>()
+  for (const spec of inherited) taken.set(spec.name.toLowerCase(), '')
+  const below = await readDescendantDomains(domain)
+  if (below.length) {
+    const settings = await getRepository(Setting).find({
+      where: { domain: { id: In(below.map(one => one.id)) }, name: AI_AGENTS_SETTING }
+    })
+    const nameOf = new Map(below.map(one => [one.id, one.name]))
+    for (const setting of settings) {
+      for (const spec of parseAiAgentsSetting(setting.value).agents) taken.set(spec.name.toLowerCase(), nameOf.get(setting.domainId) ?? '')
+    }
+  }
+  for (const agent of agents) {
+    if (taken.has(agent.name.toLowerCase())) {
+      throw new Refusal(
+        'ai-agent-name-taken',
+        { name: agent.name, domain: taken.get(agent.name.toLowerCase()) ?? '' },
+        `There is already an agent named "${agent.name}".`
+      )
+    }
+  }
+}
+
+async function upsertSetting(tx: EntityManager, domain: Domain, user: { id: string } | undefined, value: string) {
+  const repository = tx.getRepository(Setting)
+  const stored = await repository.findOne({ where: { domain: { id: domain.id }, name: AI_AGENTS_SETTING } })
+  await repository.save({
+    ...(stored ?? { domain: { id: domain.id }, name: AI_AGENTS_SETTING, category: AI_AGENTS_SETTING_CATEGORY, creator: user }),
+    value,
+    updater: user
+  } as any)
+}
+
+async function upsertKey(tx: EntityManager, domain: Domain, agent: AiAgentSpec, apiKey: string) {
+  const repository = tx.getRepository(EnvVar)
+  const name = aiAgentKeyName(agent.id)
+  const stored = await repository.findOne({ where: { domain: { id: domain.id }, name } })
+  await repository.save({
+    ...(stored ?? { domain: { id: domain.id }, name }),
+    value: apiKey,
+    description: `API key of the AI agent "${agent.name}"`,
+    active: true
+  } as any)
+}

package/server/service/agent/agent-spec.ts

@@ -0,0 +1,103 @@
+/**
+ * An AI agent - a provider, a model and a key that together can answer (design/ai/agent-settings.md §3).
+ *
+ * A domain keeps its agents in one Setting row (`ai-agents`) and each key in an EnvVar of its own, so the
+ * definition and the secret live where the framework already keeps domain settings and secrets (ADR-0112).
+ * This file is the shape and its parsing - no database.
+ */
+
+/** The providers an agent may name. Three, by decision (2026-10-12). */
+export const AI_AGENT_PROVIDERS = ['openai', 'anthropic', 'gemini'] as const
+export type AiAgentProvider = (typeof AI_AGENT_PROVIDERS)[number]
+
+/** The Setting row that holds a domain's agents. */
+export const AI_AGENTS_SETTING = 'ai-agents'
+export const AI_AGENTS_SETTING_CATEGORY = 'ai'
+
+export interface AiAgentSpec {
+  id: string
+  name: string
+  provider: AiAgentProvider
+  model: string
+  baseURL?: string
+  /** OpenAI only. */
+  organization?: string
+  /** Off takes the agent out of this domain and every domain below it. */
+  active: boolean
+}
+
+/** What the `ai-agents` Setting row holds for one domain. */
+export interface AiAgentsSetting {
+  agents: AiAgentSpec[]
+  /** This domain's default - one of its own agents or an inherited one. */
+  defaultAgentId?: string
+  /** Inherited agents this domain does not use. */
+  turnedOff?: string[]
+}
+
+/** The EnvVar that holds an agent's key. Named by the agent id, so renaming an agent keeps its key. */
+export function aiAgentKeyName(agentId: string): string {
+  return `AiAgent::${agentId}::apiKey`
+}
+
+export const AI_AGENT_KEY_PREFIX = 'AiAgent::'
+
+export function isAiAgentProvider(value: unknown): value is AiAgentProvider {
+  return typeof value === 'string' && (AI_AGENT_PROVIDERS as readonly string[]).includes(value)
+}
+
+const EMPTY: AiAgentsSetting = { agents: [] }
+
+/**
+ * Reads a stored `ai-agents` value. The row can also be written through the generic setting doors, so a value that
+ * does not parse reads as no agents, and an entry without an id, a name, a known provider or a model is left out -
+ * a broken row never becomes an agent that fails at the provider.
+ */
+export function parseAiAgentsSetting(value: string | null | undefined): AiAgentsSetting {
+  if (!value) return EMPTY
+  let raw: any
+  try {
+    raw = JSON.parse(value)
+  } catch {
+    return EMPTY
+  }
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.agents)) return EMPTY
+
+  const agents: AiAgentSpec[] = raw.agents.flatMap((one: any) => {
+    if (!one || typeof one !== 'object') return []
+    const id = text(one.id)
+    const name = text(one.name)
+    const model = text(one.model)
+    if (!id || !name || !model || !isAiAgentProvider(one.provider)) return []
+    return [
+      {
+        id,
+        name,
+        provider: one.provider,
+        model,
+        ...(text(one.baseURL) && { baseURL: text(one.baseURL) }),
+        ...(one.provider === 'openai' && text(one.organization) && { organization: text(one.organization) }),
+        active: one.active !== false
+      }
+    ]
+  })
+
+  const turnedOff = Array.isArray(raw.turnedOff) ? raw.turnedOff.filter((id: unknown) => typeof id === 'string') : []
+  return {
+    agents,
+    ...(text(raw.defaultAgentId) && { defaultAgentId: text(raw.defaultAgentId) }),
+    ...(turnedOff.length && { turnedOff })
+  }
+}
+
+export function stringifyAiAgentsSetting(setting: AiAgentsSetting): string {
+  return JSON.stringify({
+    agents: setting.agents,
+    ...(setting.defaultAgentId && { defaultAgentId: setting.defaultAgentId }),
+    ...(setting.turnedOff?.length && { turnedOff: setting.turnedOff })
+  })
+}
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}

package/server/service/agent/ai-client-for.test.ts

@@ -0,0 +1,141 @@
+/*
+ * What this guards: **the one door to a model picks the agent the person asked for or the domain's default, refuses
+ * anything else, and writes a usage row for every provider request** (ADR-0061 decision 6,
+ * design/ai/agent-settings.md §4).
+ */
+const saved: any[] = []
+
+jest.mock('@things-factory/shell', () => ({
+  ...jest.requireActual('@things-factory/shell'),
+  getRepository: jest.fn(() => ({ save: async (rows: any[]) => saved.push(...rows) }))
+}))
+jest.mock('./agent-directory', () => ({ readAiAgentDirectory: jest.fn() }))
+
+import { readAiAgentDirectory } from './agent-directory'
+import { aiClientFor, hourOf, outcomeOf, pickAgent } from './ai-client-for'
+import { registerAIProvider } from '../factory'
+
+const entry = (id: string, extra: any = {}) => ({
+  spec: { id, name: id.toUpperCase(), provider: 'fake', model: 'fake-1', active: true },
+  ownerDomainId: 'hq',
+  inherited: true,
+  turnedOff: false,
+  keyState: 'inherited',
+  keyDomainId: 'hq',
+  apiKey: 'k',
+  keyVersion: 'hq:0',
+  usable: true,
+  ...extra
+})
+
+let replies: Array<(options: any) => any> = []
+registerAIProvider('fake', config => ({
+  id: `fake:${config.model}`,
+  chat: async (_messages, options: any) => {
+    const reply = replies.shift()!
+    return reply(options)
+  },
+  generateJSON: async () => ({}),
+  chatWithTools: async (_messages, _tools, options: any) => {
+    options.onUsage?.({ model: 'fake-1-0607', inputTokens: 100, outputTokens: 20 })
+    options.onUsage?.({ model: 'fake-1-0607', inputTokens: 300, outputTokens: 5 })
+    return { toolCalls: [], stopReason: 'end_turn' }
+  },
+  listModels: async () => ['fake-1']
+}))
+
+const flush = () => new Promise(resolve => setImmediate(resolve))
+
+beforeEach(() => {
+  saved.length = 0
+  replies = []
+})
+
+describe('which agent answers', () => {
+  it('★ the agent the person picked, when this domain can use it', () => {
+    expect(pickAgent([entry('a'), entry('b')] as any, 'b', 'a').spec.id).toBe('b')
+  })
+
+  it('★ the domain default when nobody picked', () => {
+    expect(pickAgent([entry('a'), entry('b')] as any, undefined, 'a').spec.id).toBe('a')
+  })
+
+  it('★ a picked agent this domain cannot use is refused - never swapped for another', () => {
+    const entries = [entry('a'), entry('b', { usable: false })] as any
+    expect(() => pickAgent(entries, 'b', 'a')).toThrow(expect.objectContaining({ code: 'ai-agent-not-available' }))
+    expect(() => pickAgent(entries, 'nonesuch', 'a')).toThrow(expect.objectContaining({ code: 'ai-agent-not-available' }))
+  })
+
+  it('★ no usable agent is "not configured"', () => {
+    expect(() => pickAgent([entry('a', { usable: false })] as any, undefined, 'a')).toThrow(
+      expect.objectContaining({ code: 'ai-not-configured' })
+    )
+  })
+})
+
+describe('usage', () => {
+  beforeEach(() => {
+    ;(readAiAgentDirectory as jest.Mock).mockResolvedValue({ entries: [entry('a')], defaultAgentId: 'a' })
+  })
+
+  it('★ every provider request of a call is one row, with the domain, the person, the agent and who paid', async () => {
+    const client = await aiClientFor({ domain: { id: 'plant' } as any, user: { id: 'u1' }, modeKind: 'twin.space', sessionId: 's1' })
+    await client.chatWithTools!([], [], {})
+    await flush()
+
+    expect(saved).toHaveLength(2)
+    expect(saved[0]).toMatchObject({
+      domain: { id: 'plant' },
+      creator: { id: 'u1' },
+      agentId: 'a',
+      agentDomainId: 'hq',
+      keyDomainId: 'hq',
+      provider: 'fake',
+      model: 'fake-1-0607',
+      modeKind: 'twin.space',
+      operation: 'chatWithTools',
+      sessionId: 's1',
+      inputTokens: 100,
+      outputTokens: 20,
+      outcome: 'ok'
+    })
+    expect(saved[1]).toMatchObject({ inputTokens: 300, outputTokens: 5 })
+  })
+
+  it('★ a failed request is still a row, with why it failed', async () => {
+    replies.push(() => {
+      throw Object.assign(new Error('nope'), { status: 429 })
+    })
+    const client = await aiClientFor({ domain: { id: 'plant' } as any })
+
+    await expect(client.chat([])).rejects.toThrow('nope')
+    await flush()
+
+    expect(saved).toEqual([expect.objectContaining({ operation: 'chat', outcome: 'rate-limited', model: 'fake-1' })])
+    expect(saved[0].creator).toBeUndefined()
+  })
+
+  it('the caller\'s own usage listener still hears every request', async () => {
+    const heard: any[] = []
+    const client = await aiClientFor({ domain: { id: 'plant' } as any })
+    await client.chatWithTools!([], [], { onUsage: usage => heard.push(usage) })
+    expect(heard).toHaveLength(2)
+  })
+
+  it('the client names the agent that answered', async () => {
+    const client = await aiClientFor({ domain: { id: 'plant' } as any })
+    expect(client.agent).toEqual({ id: 'a', name: 'A', provider: 'fake', model: 'fake-1' })
+    expect(client.id).toBe('fake:fake-1')
+  })
+})
+
+it('a failure is named by what the provider said', () => {
+  expect(outcomeOf({ status: 401 })).toBe('key-rejected')
+  expect(outcomeOf({ status: 403 })).toBe('key-rejected')
+  expect(outcomeOf({ status: 429 })).toBe('rate-limited')
+  expect(outcomeOf(new Error('socket hang up'))).toBe('provider-error')
+})
+
+it('a call is grouped by the UTC hour it started in', () => {
+  expect(hourOf(new Date('2026-10-12T05:47:13.120Z')).toISOString()).toBe('2026-10-12T05:00:00.000Z')
+})

package/server/service/agent/ai-client-for.ts

@@ -0,0 +1,201 @@
+import { Domain, getRepository, Refusal } from '@things-factory/shell'
+
+import { createAIClient } from '../factory.js'
+import type { AIChatOptions, AIClient, AIProviderUsage } from '../types.js'
+import { type AiAgentEntry, readAiAgentDirectory } from './agent-directory.js'
+import type { AiUsage } from './ai-usage.js'
+
+/**
+ * **The one door to a model** (design/ai/agent-settings.md §4).
+ *
+ * Every call that reaches a provider gets its client here, for a domain: the agent is the one asked for, or the
+ * domain's default, and its key is the closest one on the domain chain. There is no deployment-wide client - a domain
+ * with no usable agent has no AI (user decision 2026-10-12).
+ *
+ * The client handed back is metered: each provider request writes one AiUsage row with the domain, the person, the
+ * agent and what was used (ADR-0061 decision 6).
+ */
+export interface AiClientRequest {
+  domain: Domain
+  /** The person calling. Empty for a call with no person, such as a webhook. */
+  user?: { id: string } | null
+  /** The agent the person picked. Empty takes the domain's default. */
+  agentId?: string | null
+  /** The conversation mode, when the call is part of a conversation. */
+  modeKind?: string | null
+  /** The conversation, by id. */
+  sessionId?: string | null
+}
+
+/** The client of one agent, as a call got it. */
+export interface AgentClient extends AIClient {
+  readonly agent: { id: string; name: string; provider: string; model: string }
+}
+
+export async function aiClientFor(request: AiClientRequest): Promise<AgentClient> {
+  if (_testing) return _testing(request)
+  if (!request.domain) throw new Error('aiClientFor needs the domain the call is made in')
+
+  const directory = await readAiAgentDirectory(request.domain)
+  const entry = pickAgent(directory.entries, request.agentId, directory.defaultAgentId)
+  return meter(providerClientOf(entry), entry, request)
+}
+
+/**
+ * The agent a request is answered by. A named agent that this domain cannot use is refused, never swapped for
+ * another; no agent at all is "not configured".
+ */
+export function pickAgent(entries: AiAgentEntry[], agentId: string | null | undefined, defaultAgentId?: string): AiAgentEntry {
+  if (agentId) {
+    const named = entries.find(one => one.spec.id === agentId)
+    if (!named?.usable) {
+      throw new Refusal('ai-agent-not-available', { agentId }, 'The AI agent you picked is not available here.')
+    }
+    return named
+  }
+  const fallback = entries.find(one => one.spec.id === defaultAgentId && one.usable)
+  if (!fallback) {
+    throw new Refusal('ai-not-configured', {}, 'AI is not set up for this domain.')
+  }
+  return fallback
+}
+
+/* Provider clients are kept per agent and rebuilt when its definition or its key changes. */
+const _clients = new Map<string, { version: string; client: AIClient }>()
+
+function providerClientOf(entry: AiAgentEntry): AIClient {
+  const { spec } = entry
+  const version = JSON.stringify([spec.provider, spec.model, spec.baseURL, spec.organization, entry.keyVersion])
+  const cached = _clients.get(spec.id)
+  if (cached?.version === version) return cached.client
+
+  const client = createAIClient({
+    provider: spec.provider,
+    model: spec.model,
+    apiKey: entry.apiKey!,
+    ...(spec.baseURL && { baseURL: spec.baseURL }),
+    ...(spec.organization && { organization: spec.organization })
+  })
+  _clients.set(spec.id, { version, client })
+  return client
+}
+
+function meter(client: AIClient, entry: AiAgentEntry, request: AiClientRequest): AgentClient {
+  const { spec } = entry
+
+  async function measured<T>(operation: string, options: AIChatOptions | undefined, call: (options: AIChatOptions) => Promise<T>): Promise<T> {
+    const started = new Date()
+    const reported: AIProviderUsage[] = []
+    const withUsage: AIChatOptions = {
+      ...options,
+      onUsage: usage => {
+        reported.push(usage)
+        options?.onUsage?.(usage)
+      }
+    }
+    try {
+      const result = await call(withUsage)
+      record(operation, started, reported, 'ok')
+      return result
+    } catch (error: any) {
+      record(operation, started, reported, outcomeOf(error))
+      /* A failure must say why somewhere: the loop above turns it into a sentence for the person, and the usage row
+         keeps only its code. The provider's own message names no key. */
+      console.error(
+        `[ai-client-base] ${spec.provider}:${spec.model} (${spec.name}) ${operation} failed:`,
+        error?.status ?? '',
+        error?.message ?? error
+      )
+      throw error
+    }
+  }
+
+  function record(operation: string, started: Date, reported: AIProviderUsage[], outcome: string) {
+    const durationMs = Date.now() - started.valueOf()
+    /* A failed request reports nothing, and is still one row - a failure costs time and often money. */
+    const rows = (reported.length ? reported : [{ model: spec.model } as AIProviderUsage]).map((usage, index, all) => ({
+      domain: { id: request.domain.id },
+      ...(request.user?.id && { creator: { id: request.user.id } }),
+      agentId: spec.id,
+      agentDomainId: entry.ownerDomainId,
+      keyDomainId: entry.keyDomainId,
+      provider: spec.provider,
+      model: usage.model || spec.model,
+      modeKind: request.modeKind ?? undefined,
+      operation,
+      sessionId: request.sessionId ?? undefined,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      /* The whole call's time goes on its last request; the rows of one call still add up to it. */
+      durationMs: index === all.length - 1 ? durationMs : 0,
+      outcome: index === all.length - 1 ? outcome : 'ok',
+      hourStart: hourOf(started)
+    }))
+    /* Outside the caller's transaction: a rolled-back write still spent the tokens. By name, so the decorated entity
+       stays out of this module's imports. */
+    getRepository<AiUsage>('AiUsage')
+      .save(rows as any)
+      .catch(error => console.error('[ai-client-base] could not record AI usage:', error?.message ?? error))
+  }
+
+  const metered: AgentClient = {
+    id: `${spec.provider}:${spec.model}`,
+    agent: { id: spec.id, name: spec.name, provider: spec.provider, model: spec.model },
+    chat: (messages, options) => measured('chat', options, o => client.chat(messages, o)),
+    generateJSON: (prompt, options) => measured('generateJSON', options, o => client.generateJSON(prompt, o)),
+    ...(client.vision && {
+      vision: (image, prompt, options) => measured('vision', options, o => client.vision!(image, prompt, o))
+    }),
+    ...(client.chatWithTools && {
+      chatWithTools: (messages, tools, options) =>
+        measured('chatWithTools', options, o => client.chatWithTools!(messages, tools, o))
+    }),
+    listModels: () => client.listModels()
+  }
+  return metered
+}
+
+/** The UTC hour a moment falls in. */
+export function hourOf(moment: Date): Date {
+  const hour = new Date(moment)
+  hour.setUTCMinutes(0, 0, 0)
+  return hour
+}
+
+/** Why a provider request failed, as the usage row keeps it. */
+export function outcomeOf(error: any): string {
+  const status = Number(error?.status ?? error?.statusCode ?? error?.response?.status)
+  if (status === 401 || status === 403) return 'key-rejected'
+  if (status === 429) return 'rate-limited'
+  return 'provider-error'
+}
+
+type TestClientResolver = (request: AiClientRequest) => AgentClient
+
+let _testing: TestClientResolver | undefined
+
+export function isAIClientForTesting(): boolean {
+  return !!_testing
+}
+
+/**
+ * Tests answer aiClientFor with a client of their own - no database, no provider, no usage rows. A client is wrapped
+ * as an agent named after it; a function decides per request. `undefined` puts the real door back.
+ */
+export function setAIClientForTesting(client: AIClient | TestClientResolver | undefined): void {
+  if (!client) {
+    _testing = undefined
+  } else if (typeof client === 'function') {
+    _testing = client
+  } else {
+    /* The test's own object answers - its counters and `this` stay its own; it only gains the agent it is named as. */
+    if (!(client as AgentClient).agent) {
+      const [provider, model] = String(client.id ?? 'test:test').split(':')
+      Object.defineProperty(client, 'agent', {
+        value: { id: 'test-agent', name: client.id ?? 'test', provider, model },
+        configurable: true
+      })
+    }
+    _testing = () => client as AgentClient
+  }
+}