@things-factory/ai-client-base 10.1.149 → 10.1.157

package/server/service/agent/ai-usage-summary.test.ts

@@ -0,0 +1,65 @@
+/*
+ * What this guards: **usage is counted per bucket × agent × person in the domain's own time zone, and a domain above
+ * never sees the people of a domain below** (design/ai/agent-settings.md §6-2).
+ */
+import { rollUp } from './ai-usage-summary'
+
+const hour = (iso: string, extra: any = {}) => ({
+  hourStart: iso,
+  agentId: 'a1',
+  provider: 'openai',
+  model: 'gpt-4o',
+  domainId: 'hq',
+  domainName: '본사',
+  userId: 'u1',
+  userName: '김철수',
+  calls: '2',
+  inputTokens: '100',
+  outputTokens: '10',
+  failures: '0',
+  ...extra
+})
+
+const names = new Map([['a1', 'GPT-4o']])
+
+it('★ hours roll up into the domain\'s days - 15:00Z on the 11th is the 12th in Seoul', () => {
+  const rows = rollUp(
+    [hour('2026-10-11T14:00:00.000Z'), hour('2026-10-11T15:00:00.000Z'), hour('2026-10-12T03:00:00.000Z', { failures: '1' })],
+    'day',
+    'Asia/Seoul',
+    'hq',
+    names
+  )
+  expect(rows.map(one => [one.bucket, one.calls, one.inputTokens, one.failures])).toEqual([
+    ['2026-10-12', 4, 200, 1],
+    ['2026-10-11', 2, 100, 0]
+  ])
+  expect(rows[0]).toMatchObject({ agentName: 'GPT-4o', userName: '김철수', domainName: '본사' })
+})
+
+it('hour and month buckets are named in the domain\'s time zone too', () => {
+  expect(rollUp([hour('2026-10-31T15:00:00.000Z')], 'hour', 'Asia/Seoul', 'hq', names)[0].bucket).toBe('2026-11-01 00:00')
+  expect(rollUp([hour('2026-10-31T15:00:00.000Z')], 'month', 'Asia/Seoul', 'hq', names)[0].bucket).toBe('2026-11')
+})
+
+it('★ a domain below is one line per domain - its people are not named above', () => {
+  const rows = rollUp(
+    [
+      hour('2026-10-12T01:00:00.000Z', { domainId: 'plant', domainName: '서울공장', userId: 'p1', userName: '이영희' }),
+      hour('2026-10-12T02:00:00.000Z', { domainId: 'plant', domainName: '서울공장', userId: 'p2', userName: '박민수' })
+    ],
+    'day',
+    'Asia/Seoul',
+    'hq',
+    names
+  )
+  expect(rows).toEqual([expect.objectContaining({ domainName: '서울공장', calls: 4 })])
+  expect(rows[0].userId).toBeUndefined()
+  expect(rows[0].userName).toBeUndefined()
+})
+
+it('a deleted agent keeps its usage, without a name', () => {
+  const [row] = rollUp([hour('2026-10-12T01:00:00.000Z', { agentId: 'gone' })], 'day', 'Asia/Seoul', 'hq', names)
+  expect(row).toMatchObject({ agentId: 'gone', calls: 2 })
+  expect(row.agentName).toBeUndefined()
+})

package/server/service/agent/ai-usage-summary.ts

@@ -0,0 +1,146 @@
+import { Domain, getRepository } from '@things-factory/shell'
+
+import { fullDomain, readAiAgentDirectory, readDescendantDomains } from './agent-directory.js'
+import type { AiUsage } from './ai-usage.js'
+
+export type AiUsageBucketSize = 'hour' | 'day' | 'month'
+
+export interface AiUsageFilter {
+  from: Date
+  to: Date
+  bucket: AiUsageBucketSize
+  agentIds?: string[]
+  userIds?: string[]
+  /** Also count what domains below did with this domain's agents - per domain, without their people. */
+  includeDescendants?: boolean
+}
+
+export interface AiUsageBucketRow {
+  /** The bucket in the domain's time zone: `2026-10-12 14:00`, `2026-10-12` or `2026-10`. */
+  bucket: string
+  agentId?: string
+  agentName?: string
+  provider: string
+  model: string
+  /** The domain the calls were made in. */
+  domainId: string
+  domainName: string
+  /** Empty on a row of a domain below, and for calls with no person. */
+  userId?: string
+  userName?: string
+  calls: number
+  inputTokens: number
+  outputTokens: number
+  failures: number
+}
+
+/**
+ * Usage per bucket × agent × person (design/ai/agent-settings.md §6-2).
+ *
+ * The database groups by the stored UTC hour, which every database can do; the hours are then rolled up into the
+ * domain's days or months here. People of a domain below are never named to the domain above.
+ */
+export async function summarizeAiUsage(given: Domain, filter: AiUsageFilter): Promise<AiUsageBucketRow[]> {
+  /* The time zone and the chain are the domain row's. */
+  const domain = await fullDomain(given)
+  const below = filter.includeDescendants ? await readDescendantDomains(domain) : []
+
+  const query = getRepository<AiUsage>('AiUsage')
+    .createQueryBuilder('usage')
+    .leftJoin('usage.domain', 'domain')
+    .leftJoin('usage.creator', 'creator')
+    .select('usage.hourStart', 'hourStart')
+    .addSelect('usage.agentId', 'agentId')
+    .addSelect('usage.provider', 'provider')
+    .addSelect('usage.model', 'model')
+    .addSelect('domain.id', 'domainId')
+    .addSelect('domain.name', 'domainName')
+    .addSelect('creator.id', 'userId')
+    .addSelect('creator.name', 'userName')
+    .addSelect('COUNT(*)', 'calls')
+    .addSelect('SUM(COALESCE(usage.inputTokens, 0))', 'inputTokens')
+    .addSelect('SUM(COALESCE(usage.outputTokens, 0))', 'outputTokens')
+    .addSelect(`SUM(CASE WHEN usage.outcome = 'ok' THEN 0 ELSE 1 END)`, 'failures')
+    .where('usage.hourStart >= :from AND usage.hourStart < :to', { from: filter.from, to: filter.to })
+    .groupBy('usage.hourStart')
+    .addGroupBy('usage.agentId')
+    .addGroupBy('usage.provider')
+    .addGroupBy('usage.model')
+    .addGroupBy('domain.id')
+    .addGroupBy('domain.name')
+    .addGroupBy('creator.id')
+    .addGroupBy('creator.name')
+
+  if (below.length) {
+    query.andWhere('(domain.id = :here OR (domain.id IN (:...below) AND usage.agentDomainId = :here))', {
+      here: domain.id,
+      below: below.map(one => one.id)
+    })
+  } else {
+    query.andWhere('domain.id = :here', { here: domain.id })
+  }
+  if (filter.agentIds?.length) query.andWhere('usage.agentId IN (:...agentIds)', { agentIds: filter.agentIds })
+  if (filter.userIds?.length) query.andWhere('creator.id IN (:...userIds)', { userIds: filter.userIds })
+
+  const [hours, directory] = await Promise.all([query.getRawMany(), readAiAgentDirectory(domain)])
+  const agentNameOf = new Map(directory.entries.map(one => [one.spec.id, one.spec.name]))
+  return rollUp(hours, filter.bucket, domain.timezone, domain.id, agentNameOf)
+}
+
+export function rollUp(
+  hours: any[],
+  bucket: AiUsageBucketSize,
+  timezone: string | undefined,
+  hereId: string,
+  agentNameOf: Map<string, string>
+): AiUsageBucketRow[] {
+  const label = bucketLabeller(bucket, timezone)
+  const rows = new Map<string, AiUsageBucketRow>()
+
+  for (const hour of hours) {
+    const below = hour.domainId !== hereId
+    const userId = below ? undefined : hour.userId ?? undefined
+    const key = [label(new Date(hour.hourStart)), hour.agentId, hour.provider, hour.model, hour.domainId, userId].join('\u0000')
+    const row =
+      rows.get(key) ??
+      rows
+        .set(key, {
+          bucket: label(new Date(hour.hourStart)),
+          ...(hour.agentId && { agentId: hour.agentId, agentName: agentNameOf.get(hour.agentId) }),
+          provider: hour.provider,
+          model: hour.model,
+          domainId: hour.domainId,
+          domainName: hour.domainName,
+          ...(userId && { userId, userName: hour.userName }),
+          calls: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          failures: 0
+        })
+        .get(key)!
+    row.calls += Number(hour.calls) || 0
+    row.inputTokens += Number(hour.inputTokens) || 0
+    row.outputTokens += Number(hour.outputTokens) || 0
+    row.failures += Number(hour.failures) || 0
+  }
+
+  return [...rows.values()].sort((a, b) => b.bucket.localeCompare(a.bucket) || b.calls - a.calls)
+}
+
+/** Names the bucket a UTC moment falls in, in the domain's time zone (the server's when the domain has none). */
+function bucketLabeller(bucket: AiUsageBucketSize, timezone?: string): (moment: Date) => string {
+  const format = new Intl.DateTimeFormat('en-CA', {
+    timeZone: timezone || undefined,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    hourCycle: 'h23'
+  })
+  return moment => {
+    const part = Object.fromEntries(format.formatToParts(moment).map(one => [one.type, one.value]))
+    if (bucket === 'month') return `${part.year}-${part.month}`
+    if (bucket === 'day') return `${part.year}-${part.month}-${part.day}`
+    return `${part.year}-${part.month}-${part.day} ${part.hour}:00`
+  }
+}

package/server/service/agent/ai-usage.ts

@@ -0,0 +1,97 @@
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
+import { Field, ID, Int, ObjectType } from 'type-graphql'
+
+import { User } from '@things-factory/auth-base'
+import { Domain } from '@things-factory/shell'
+
+/**
+ * One provider request - the metering boundary writes a row each time a model is called (ADR-0061 decision 6,
+ * design/ai/agent-settings.md §6).
+ *
+ * A turn that loops through tools makes several rows. The row is joined to a conversation by id only and is never
+ * copied onto a message. It is written once and never changed, so it has no updater.
+ */
+@Entity()
+@Index('ix_ai_usage_0', (usage: AiUsage) => [usage.domain, usage.hourStart])
+@Index('ix_ai_usage_1', (usage: AiUsage) => [usage.agentDomainId, usage.hourStart])
+@ObjectType({ description: 'One request an AI agent sent to its provider, with what it used.' })
+export class AiUsage {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Row id.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'The domain the call was made in.' })
+  domain?: Domain
+
+  @RelationId((usage: AiUsage) => usage.domain)
+  domainId?: string
+
+  @Column({ nullable: true })
+  @Field(type => String, { nullable: true, description: 'The agent that answered.' })
+  agentId?: string
+
+  @Column({ nullable: true })
+  @Field(type => String, { nullable: true, description: 'The domain that declared the agent - a domain above when the agent was inherited.' })
+  agentDomainId?: string
+
+  @Column({ nullable: true })
+  @Field(type => String, { nullable: true, description: 'The domain whose API key answered - whose cost the call is.' })
+  keyDomainId?: string
+
+  @Column()
+  @Field(type => String, { description: 'openai, anthropic or gemini.' })
+  provider: string
+
+  @Column()
+  @Field(type => String, { description: 'The model the provider reported answering.' })
+  model: string
+
+  @Column({ nullable: true })
+  @Field(type => String, { nullable: true, description: 'The conversation mode kind, when the call was part of a conversation.' })
+  modeKind?: string
+
+  @Column()
+  @Field(type => String, { description: 'chat, chatWithTools, generateJSON or vision.' })
+  operation: string
+
+  @Column({ nullable: true })
+  @Field(type => String, { nullable: true, description: 'The conversation the call belongs to, by id only.' })
+  sessionId?: string
+
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Input tokens the provider reported.' })
+  inputTokens?: number
+
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Output tokens the provider reported.' })
+  outputTokens?: number
+
+  @Column({ type: 'int' })
+  @Field(type => Int, { description: 'How long the request took, in milliseconds.' })
+  durationMs: number
+
+  /** `ok`, or why it failed: key-rejected · rate-limited · provider-error. */
+  @Column()
+  @Field(type => String, { description: 'ok, or why the request failed: key-rejected, rate-limited or provider-error.' })
+  outcome: string
+
+  /**
+   * The UTC hour the call started in. Usage is grouped by this column, which every database can do; days and months
+   * are rolled up from it in the domain's time zone.
+   */
+  @Column()
+  @Field(type => Date, { description: 'The UTC hour the call started in.' })
+  hourStart: Date
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'The person who made the call. Empty for a call with no person, such as a webhook.' })
+  creator?: User
+
+  @RelationId((usage: AiUsage) => usage.creator)
+  creatorId?: string
+
+  @CreateDateColumn()
+  @Field(type => Date, { description: 'When the call was made.' })
+  createdAt: Date
+}

package/server/service/agent/index.ts

@@ -0,0 +1,7 @@
+export * from './agent-spec.js'
+export * from './agent-directory.js'
+export * from './ai-client-for.js'
+export * from './provider-models.js'
+export * from './agent-settings-save.js'
+export * from './ai-usage-summary.js'
+export { AiUsage } from './ai-usage.js'

package/server/service/agent/one-door.test.ts

@@ -0,0 +1,57 @@
+/*
+ * What this guards: **every call that reaches a model goes through aiClientFor** - the door that picks the domain's
+ * agent and writes the usage row (ADR-0061 decision 6, design/ai/agent-settings.md §4).
+ *
+ * A module that imports a provider SDK, or builds a client of its own, reaches a provider with no domain, no agent and
+ * no usage row - and with a key from somewhere other than the domain's settings. So this counts, across the
+ * framework's sources, what does either: only this package's adapters and its own door may.
+ */
+import { readdirSync, readFileSync, statSync } from 'fs'
+import path from 'path'
+
+const PACKAGES = path.resolve(__dirname, '../../../..')
+const HOME = path.join(PACKAGES, 'ai-client-base')
+
+function sources(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry.startsWith('dist') || entry.startsWith('.')) continue
+    const full = path.join(dir, entry)
+    if (statSync(full).isDirectory()) sources(full, out)
+    else if (/\.ts$/.test(entry) && !/\.(test|spec)\.ts$/.test(entry) && !entry.endsWith('.d.ts')) out.push(full)
+  }
+  return out
+}
+
+const files = readdirSync(PACKAGES)
+  .flatMap(name => ['server', 'client'].map(part => path.join(PACKAGES, name, part)))
+  .filter(dir => {
+    try {
+      return statSync(dir).isDirectory()
+    } catch {
+      return false
+    }
+  })
+  .flatMap(dir => sources(dir))
+
+const SDK = /from ['"](openai|@anthropic-ai\/sdk|@google\/generative-ai)['"]|require\(['"](openai|@anthropic-ai\/sdk|@google\/generative-ai)['"]\)/
+const OWN_CLIENT = /\bcreateAIClient\s*\(/
+
+it('reads the framework\'s sources', () => {
+  expect(files.length).toBeGreaterThan(1000)
+})
+
+it('★ only ai-client-base\'s adapters import a provider SDK', () => {
+  const outside = files.filter(file => SDK.test(readFileSync(file, 'utf8')) && !file.startsWith(path.join(HOME, 'server/service/providers')))
+  expect(outside.map(file => path.relative(PACKAGES, file))).toEqual([])
+})
+
+it('★ no module builds a provider client of its own - it asks aiClientFor for the domain\'s agent', () => {
+  const outside = files.filter(file => OWN_CLIENT.test(readFileSync(file, 'utf8')) && !file.startsWith(HOME))
+  expect(outside.map(file => path.relative(PACKAGES, file))).toEqual([])
+})
+
+it('★ nothing reads a deployment-wide AI configuration any more', () => {
+  const global = /config\.get\(\s*['"](aiClient|openai)['"]|getDefaultAIClient|setDefaultAIClient/
+  const readers = files.filter(file => global.test(readFileSync(file, 'utf8')))
+  expect(readers.map(file => path.relative(PACKAGES, file))).toEqual([])
+})

package/server/service/agent/provider-models.ts

@@ -0,0 +1,43 @@
+import { Refusal } from '@things-factory/shell'
+
+import { createAIClient } from '../factory.js'
+import { type AiAgentProvider, isAiAgentProvider } from './agent-spec.js'
+import { outcomeOf } from './ai-client-for.js'
+
+export interface ProviderModelsRequest {
+  provider: string
+  apiKey: string
+  baseURL?: string
+  organization?: string
+}
+
+/**
+ * The conversation models a key may call, read from the provider (design/ai/agent-settings.md §3-4). A model is only
+ * ever picked from this list. Reading it also proves the key: a refused key and an unreachable provider come back as
+ * reasons, never as an empty list.
+ */
+export async function listProviderModels(request: ProviderModelsRequest): Promise<string[]> {
+  if (!isAiAgentProvider(request.provider)) {
+    throw new Refusal('ai-agent-provider-unknown', { provider: request.provider }, `"${request.provider}" is not a provider an agent can use.`)
+  }
+  if (!request.apiKey?.trim()) {
+    throw new Refusal('ai-agent-key-required', {}, 'Enter the API key first.')
+  }
+
+  const client = createAIClient({
+    provider: request.provider as AiAgentProvider,
+    apiKey: request.apiKey.trim(),
+    ...(request.baseURL && { baseURL: request.baseURL }),
+    ...(request.organization && { organization: request.organization })
+  })
+
+  try {
+    return await client.listModels()
+  } catch (error) {
+    /* Gemini answers a wrong key with 400 ("API key not valid"); a list request has no other input to be wrong. */
+    if (outcomeOf(error) === 'key-rejected' || Number((error as any)?.status) === 400) {
+      throw new Refusal('ai-provider-key-rejected', { provider: request.provider }, 'The provider did not accept this API key.')
+    }
+    throw new Refusal('ai-provider-unreachable', { provider: request.provider }, 'The provider could not be reached.')
+  }
+}

package/server/service/capability.test.ts

@@ -1,69 +1,40 @@
 /*
- * What this guards: a screen can ask whether this deployment has an AI, instead of finding out by
- * pressing a button that fails.
+ * What this guards: a screen can ask whether this domain has an AI, instead of finding out by pressing a button that
+ * fails.
  *
- * The defect this replaces: twin decided the same question from whether a mutation had thrown once.
- * The mutation stopped being called, the flag stayed true, and deployments with no provider showed
- * the button anyway (standard A7-a).
+ * The defect this replaces: twin decided the same question from whether a mutation had thrown once. The mutation
+ * stopped being called, the flag stayed true, and deployments with no provider showed the button anyway (standard A7-a).
+ * Agents are set per domain now, so the answer is read from the domain's agents.
  */
-const mockConfigGet = jest.fn()
-jest.mock('@things-factory/env', () => ({ config: { get: (...args: any[]) => mockConfigGet(...args) } }))
+import { capabilityOf } from './capability'
 
-import { aiCapability } from './capability'
-import { registerAIProvider, setDefaultAIClient } from './factory'
-
-beforeEach(() => {
-  mockConfigGet.mockReset()
-  setDefaultAIClient(undefined as any)
-})
-
-it('★ a configured deployment says so, and names what answers', () => {
-  mockConfigGet.mockReturnValue(null)
-  setDefaultAIClient({ id: 'anthropic:claude-sonnet-5' } as any)
-
-  expect(aiCapability()).toEqual({ state: 'configured', provider: 'anthropic', model: 'claude-sonnet-5' })
+const entry = (id: string, extra: any = {}) => ({
+  spec: { id, name: id, provider: 'anthropic', model: 'claude-sonnet-5', active: true },
+  turnedOff: false,
+  usable: true,
+  ...extra
 })
 
-it('★ no configuration at all is "not configured", with the reason — never silence', () => {
-  mockConfigGet.mockReturnValue(null)
-
-  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-config' })
-})
-
-it('a configuration naming a provider nobody registered says which one', () => {
-  mockConfigGet.mockReturnValue({ provider: 'nonesuch', model: 'x' })
-
-  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'nonesuch', reason: 'unknown-provider' })
+it('★ a domain with a usable default says so, and names what answers', () => {
+  expect(capabilityOf({ entries: [entry('a')] as any, defaultAgentId: 'a' })).toEqual({
+    state: 'configured',
+    provider: 'anthropic',
+    model: 'claude-sonnet-5'
+  })
 })
 
-it('a configuration with no provider field is its own reason', () => {
-  mockConfigGet.mockReturnValue({ model: 'x' })
-
-  expect(aiCapability()).toEqual({ state: 'not-configured', reason: 'no-provider' })
+it('★ no agent at all is "not configured", with the reason - never silence', () => {
+  expect(capabilityOf({ entries: [] })).toEqual({ state: 'not-configured', reason: 'no-agent' })
 })
 
-it('★ a provider whose adapter throws is not configured — it does not throw at the caller', () => {
-  registerAIProvider('explodes', () => {
-    throw new Error('no api key')
+it('★ agents with no key are their own reason - every request would fail at the provider', () => {
+  expect(capabilityOf({ entries: [entry('a', { usable: false, keyState: 'missing' })] as any })).toEqual({
+    state: 'not-configured',
+    reason: 'no-agent-key'
   })
-  mockConfigGet.mockReturnValue({ provider: 'explodes', model: 'x' })
-
-  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'explodes', model: 'x', reason: 'no-adapter' })
-})
-
-it('★ a key slot with nothing in it is not configured - every request would fail at the provider', () => {
-  mockConfigGet.mockReturnValue({ provider: 'gemini', model: 'gemini-3.5-flash', apiKey: undefined })
-  setDefaultAIClient({ id: 'gemini:gemini-3.5-flash' } as any)
-
-  expect(aiCapability()).toEqual({ state: 'not-configured', provider: 'gemini', model: 'gemini-3.5-flash', reason: 'no-api-key' })
 })
 
-it('a configuration with a key, or one that names no key slot at all, stays configured', () => {
-  setDefaultAIClient({ id: 'gemini:gemini-3.5-flash' } as any)
-
-  mockConfigGet.mockReturnValue({ provider: 'gemini', model: 'gemini-3.5-flash', apiKey: 'k' })
-  expect(aiCapability().state).toBe('configured')
-
-  mockConfigGet.mockReturnValue({ provider: 'local', model: 'm' })
-  expect(aiCapability().state).toBe('configured')
+it('agents that are all off are their own reason', () => {
+  const entries = [entry('a', { usable: false, spec: { id: 'a', active: false } }), entry('b', { usable: false, turnedOff: true })]
+  expect(capabilityOf({ entries: entries as any })).toEqual({ state: 'not-configured', reason: 'no-usable-agent' })
 })

package/server/service/capability.ts

@@ -1,5 +1,5 @@
 /**
- * Is there an AI on this deployment, and what is missing — asked before anything is tried.
+ * Is there an AI for this domain, and what is missing — asked before anything is tried.
  *
  * The twin had a button that asked the assistant, and whether to show it was decided by whether a
  * now-dead mutation had failed once. When the dock moved to the neutral door nothing called that
@@ -7,60 +7,43 @@
  * with no provider at all and failed when pressed (standard A7-a).
  *
  * A capability is read, not discovered by failing (ADR-0042 decision ②). It lives here because the
- * provider configuration does, and the answer has three states — the third is the one a screen
- * must not fold away: **not asked yet** is not "configured".
+ * agents do, and the answer has three states — the third is the one a screen must not fold away:
+ * **not asked yet** is not "configured". Since agents are set per domain (design/ai/agent-settings.md),
+ * so is the answer.
  */
-import { config as envConfig } from '@things-factory/env'
+import type { Domain } from '@things-factory/shell'
 
-import { getDefaultAIClient, listRegisteredProviders } from './factory.js'
+import { type AiAgentDirectory, readAiAgentDirectory } from './agent/agent-directory.js'
+import { isAIClientForTesting } from './agent/ai-client-for.js'
 
 export type AiCapabilityState = 'configured' | 'not-configured'
 
 export interface AiCapability {
   state: AiCapabilityState
-  /** Which provider answers, when one does — for the person reading a boot log, not for a screen. */
+  /** The provider of the agent a request without a choice gets. */
   provider?: string
-  /** The default model this deployment would use. */
+  /** That agent's model. */
   model?: string
-  /** Why it is not configured, as a code: no-config · no-provider · unknown-provider · no-adapter · no-api-key. */
+  /** Why it is not configured, as a code: no-agent · no-agent-key · no-usable-agent. */
   reason?: string
 }
 
-/**
- * What this server can do, as of now.
- *
- * Creating the client is what proves a provider adapter is loaded and the configuration parses, so
- * this asks for it. It never throws: a deployment with no AI is a normal deployment.
- */
-export function aiCapability(): AiCapability {
-  const cfg = envConfig.get('aiClient', null) as { provider?: string; model?: string; apiKey?: unknown } | null
-  const client = safeDefaultClient()
-  if (client) {
-    const [provider, model] = String(client.id ?? '').split(':')
-    /*
-      A configuration that has a key slot and nothing in it - `apiKey: process.env.X` with X unset - still builds a
-      client, and every request then fails at the provider. The dock offered a chat that could only answer "something
-      went wrong" (operato-figure with no .env, 2026-09-25). No key is not configured.
-    */
-    if (cfg && 'apiKey' in cfg && !String(cfg.apiKey ?? '').trim()) {
-      return { state: 'not-configured', provider: provider || cfg.provider, model: model || cfg.model, reason: 'no-api-key' }
-    }
-    return { state: 'configured', provider: provider || undefined, model: model || undefined }
-  }
-
-  if (!cfg) return { state: 'not-configured', reason: 'no-config' }
-  if (!cfg.provider) return { state: 'not-configured', reason: 'no-provider' }
-  if (!listRegisteredProviders().includes(cfg.provider)) {
-    return { state: 'not-configured', provider: cfg.provider, reason: 'unknown-provider' }
+/** What this domain can do, as of now. It never throws: a domain with no AI is a normal domain. */
+export async function aiCapability(domain: Domain): Promise<AiCapability> {
+  if (isAIClientForTesting()) return { state: 'configured' }
+  try {
+    return capabilityOf(await readAiAgentDirectory(domain))
+  } catch (error) {
+    console.error('[ai-client-base] could not read the AI agents of a domain:', (error as Error)?.message)
+    return { state: 'not-configured', reason: 'no-agent' }
   }
-  return { state: 'not-configured', provider: cfg.provider, model: cfg.model, reason: 'no-adapter' }
 }
 
-function safeDefaultClient() {
-  try {
-    return getDefaultAIClient()
-  } catch {
-    /* A broken configuration is "not configured", and it is the reason below that says which. */
-    return undefined
-  }
+export function capabilityOf(directory: Pick<AiAgentDirectory, 'entries' | 'defaultAgentId'>): AiCapability {
+  const chosen = directory.entries.find(one => one.spec.id === directory.defaultAgentId && one.usable)
+  if (chosen) return { state: 'configured', provider: chosen.spec.provider, model: chosen.spec.model }
+
+  const live = directory.entries.filter(one => one.spec.active && !one.turnedOff)
+  if (!live.length) return { state: 'not-configured', reason: directory.entries.length ? 'no-usable-agent' : 'no-agent' }
+  return { state: 'not-configured', reason: 'no-agent-key' }
 }