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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.149",
+  "version": "10.1.157",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -24,8 +24,11 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.40.0",
     "@google/generative-ai": "^0.24.0",
+    "@things-factory/auth-base": "^10.1.157",
     "@things-factory/env": "^10.1.149",
+    "@things-factory/setting-base": "^10.1.157",
+    "@things-factory/shell": "^10.1.157",
     "openai": "^4.0.0"
   },
-  "gitHead": "816f88a9fa6110935a3f71740458db8f7469d2e3"
+  "gitHead": "bde810f804966549a7041457ad7ede40fcb78488"
 }

package/server/service/agent/agent-directory.test.ts

@@ -0,0 +1,206 @@
+/*
+ * What this guards: **a domain sees its own agents and the agents of every domain above it, and the key that answers
+ * is the closest one** (design/ai/agent-settings.md §3-3).
+ *
+ * The screen and the door both read this one directory, so what the settings card shows as "usable" is exactly what a
+ * conversation can be answered by.
+ */
+jest.mock('@things-factory/shell', () => ({
+  ...jest.requireActual('@things-factory/shell'),
+  getRepository: jest.fn(),
+  getDomainIdsWithAncestors: jest.fn()
+}))
+
+import { getDomainIdsWithAncestors, getRepository } from '@things-factory/shell'
+
+import { readAgentUsersBelow, readAiAgentDirectory } from './agent-directory'
+import { aiAgentKeyName } from './agent-spec'
+
+type Row = Record<string, any>
+
+const world = {
+  domains: [] as Row[],
+  settings: [] as Row[],
+  envVars: [] as Row[]
+}
+
+/* Answers the three finds the directory makes, by what they ask for. */
+function idsOf(where: any): string[] | undefined {
+  const value = where?.domain?.id ?? where?.id ?? where?.parent?.id
+  return value?._value ?? (value === undefined ? undefined : [value])
+}
+
+;(getRepository as jest.Mock).mockImplementation((target: any) => ({
+  findOne: async ({ where }: any) => world.domains.find(one => one.id === where.id) ?? null,
+  find: async ({ where }: any) => {
+    const name = target?.name
+    if (name === 'Domain') {
+      if (where.parent) return world.domains.filter(one => idsOf(where)!.includes(one.parentId))
+      return world.domains.filter(one => idsOf(where)!.includes(one.id))
+    }
+    if (name === 'Setting') return world.settings.filter(one => idsOf(where)!.includes(one.domainId) && one.name === where.name)
+    if (name === 'EnvVar') {
+      const names = where.name?._value ?? [where.name]
+      return world.envVars.filter(one => idsOf(where)!.includes(one.domainId) && names.includes(one.name) && one.active !== false)
+    }
+    return []
+  }
+}))
+;(getDomainIdsWithAncestors as jest.Mock).mockImplementation(async (domain: Row) => {
+  const ids = [domain.id]
+  let parentId = domain.parentId
+  while (parentId) {
+    ids.push(parentId)
+    parentId = world.domains.find(one => one.id === parentId)?.parentId
+  }
+  return ids
+})
+
+const group = { id: 'group', name: '그룹', parentId: null }
+const hq = { id: 'hq', name: '본사', parentId: 'group' }
+const plant = { id: 'plant', name: '서울공장', parentId: 'hq' }
+
+function agent(id: string, name: string, extra: Row = {}) {
+  return { id, name, provider: 'openai', model: 'gpt-4o', active: true, ...extra }
+}
+
+function agentsOf(domainId: string, value: Row) {
+  world.settings.push({ domainId, name: 'ai-agents', value: JSON.stringify(value) })
+}
+
+function keyOf(domainId: string, agentId: string, value = 'sk-0123456789abcdefWXYZ') {
+  world.envVars.push({ domainId, name: aiAgentKeyName(agentId), value, active: true, updatedAt: new Date(0) })
+}
+
+beforeEach(() => {
+  world.domains = [group, hq, plant]
+  world.settings = []
+  world.envVars = []
+})
+
+it('★ a domain sees its own agents first, then each ancestor\'s, closest first', async () => {
+  agentsOf('group', { agents: [agent('g1', 'Group GPT')] })
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT')] })
+  agentsOf('plant', { agents: [agent('p1', 'Plant GPT')] })
+
+  const directory = await readAiAgentDirectory(plant as any)
+
+  expect(directory.entries.map(one => [one.spec.id, one.ownerDomainId, one.inherited])).toEqual([
+    ['p1', 'plant', false],
+    ['h1', 'hq', true],
+    ['g1', 'group', true]
+  ])
+  expect(directory.chain).toEqual([
+    { id: 'plant', name: '서울공장' },
+    { id: 'hq', name: '본사' },
+    { id: 'group', name: '그룹' }
+  ])
+})
+
+it('★ a caller holding only the domain id still gets the whole chain - the row is read for its parent', async () => {
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT')] })
+  keyOf('hq', 'h1')
+
+  const directory = await readAiAgentDirectory({ id: 'plant' })
+  expect(directory.entries.map(one => [one.spec.id, one.usable])).toEqual([['h1', true]])
+})
+
+it('★ the key states: own, inherited, overridden and missing', async () => {
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT'), agent('h2', 'HQ Claude', { provider: 'anthropic', model: 'claude-x' })] })
+  agentsOf('plant', { agents: [agent('p1', 'Plant GPT'), agent('p2', 'Plant Gemini', { provider: 'gemini', model: 'g' })] })
+  keyOf('plant', 'p1')
+  keyOf('hq', 'h1')
+  keyOf('hq', 'h2')
+  keyOf('plant', 'h2', 'sk-plant-own-key-for-h2-0000')
+
+  const entries = (await readAiAgentDirectory(plant as any)).entries
+  const state = Object.fromEntries(entries.map(one => [one.spec.id, [one.keyState, one.keyDomainId, one.keyHint, one.usable]]))
+
+  expect(state).toEqual({
+    p1: ['own', 'plant', '••••WXYZ', true],
+    p2: ['missing', undefined, undefined, false],
+    h1: ['inherited', 'hq', undefined, true],
+    h2: ['overridden', 'plant', '••••0000', true]
+  })
+})
+
+it('★ a key from a domain above is never hinted below, and never leaves the entry\'s server-only field', async () => {
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT')] })
+  keyOf('hq', 'h1')
+
+  const [entry] = (await readAiAgentDirectory(plant as any)).entries
+
+  expect(entry.keyHint).toBeUndefined()
+  expect(entry.apiKey).toBe('sk-0123456789abcdefWXYZ')
+})
+
+it('★ an owner that turns its agent off takes it out of every domain below; its own list still shows it', async () => {
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT', { active: false })] })
+  keyOf('hq', 'h1')
+
+  expect((await readAiAgentDirectory(plant as any)).entries).toEqual([])
+  const own = (await readAiAgentDirectory(hq as any)).entries
+  expect(own.map(one => [one.spec.id, one.usable])).toEqual([['h1', false]])
+})
+
+it('★ a domain may turn an inherited agent off for itself only', async () => {
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT')] })
+  agentsOf('plant', { agents: [], turnedOff: ['h1'] })
+  keyOf('hq', 'h1')
+
+  const [below] = (await readAiAgentDirectory(plant as any)).entries
+  expect([below.turnedOff, below.usable]).toEqual([true, false])
+  const [atOwner] = (await readAiAgentDirectory(hq as any)).entries
+  expect([atOwner.turnedOff, atOwner.usable]).toEqual([false, true])
+})
+
+describe('the default agent', () => {
+  beforeEach(() => {
+    agentsOf('hq', { agents: [agent('h1', 'Beta'), agent('h2', 'Alpha')], defaultAgentId: 'h1' })
+    keyOf('hq', 'h1')
+    keyOf('hq', 'h2')
+  })
+
+  it('★ is this domain\'s own choice when it made one', async () => {
+    agentsOf('plant', { agents: [], defaultAgentId: 'h2' })
+    expect(await defaultOf(plant)).toEqual(['h2', 'own'])
+  })
+
+  it('★ is the closest ancestor\'s choice otherwise', async () => {
+    expect(await defaultOf(plant)).toEqual(['h1', 'inherited'])
+  })
+
+  it('★ skips a choice this domain cannot use, and then takes the first usable agent by name - never the order of declaration', async () => {
+    agentsOf('plant', { agents: [], turnedOff: ['h1'] })
+    expect(await defaultOf(plant)).toEqual(['h2', 'first'])
+  })
+
+  it('is none when nothing is usable', async () => {
+    world.envVars = []
+    expect(await defaultOf(plant)).toEqual([undefined, 'none'])
+  })
+
+  async function defaultOf(domain: Row) {
+    const directory = await readAiAgentDirectory(domain as any)
+    return [directory.defaultAgentId, directory.defaultFrom]
+  }
+})
+
+it('★ a stored value that does not parse reads as no agents - a broken row never becomes an agent', async () => {
+  world.settings.push({ domainId: 'plant', name: 'ai-agents', value: '{not json' })
+  agentsOf('hq', { agents: [{ id: 'h1', name: 'No provider', model: 'x' }, agent('h2', 'Good')] })
+
+  const directory = await readAiAgentDirectory(plant as any)
+  expect(directory.entries.map(one => one.spec.id)).toEqual(['h2'])
+})
+
+it('★ the owner sees which domains below use each agent - all of them, except one that turned it off', async () => {
+  const other = { id: 'busan', name: '부산공장', parentId: 'hq' }
+  const line = { id: 'line', name: '1라인', parentId: 'plant' }
+  world.domains.push(other, line)
+  agentsOf('hq', { agents: [agent('h1', 'HQ GPT')] })
+  agentsOf('busan', { agents: [], turnedOff: ['h1'] })
+
+  const users = await readAgentUsersBelow(hq as any, ['h1'])
+  expect(users.get('h1')!.map(one => one.name).sort()).toEqual(['1라인', '서울공장'])
+})

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

@@ -0,0 +1,198 @@
+import { In } from 'typeorm'
+
+import {
+  dedupByClosestDomain,
+  Domain,
+  EnvVar,
+  getDomainIdsWithAncestors,
+  getRepository,
+  secretHint
+} from '@things-factory/shell'
+import { Setting } from '@things-factory/setting-base'
+
+import {
+  AI_AGENTS_SETTING,
+  aiAgentKeyName,
+  type AiAgentSpec,
+  type AiAgentsSetting,
+  parseAiAgentsSetting
+} from './agent-spec.js'
+
+/**
+ * Which agents a domain can use, read up its chain of domains (design/ai/agent-settings.md §3-3).
+ *
+ * A domain sees its own agents and every agent of the domains above it. The definition belongs to the domain that
+ * declared it; the key is the closest `AiAgent::<id>::apiKey` EnvVar, so a domain below can answer an inherited agent
+ * with a key of its own.
+ */
+
+/**
+ * Where the key an agent answers with comes from, seen from the domain asking:
+ *   own         - this domain's key for its own agent
+ *   inherited   - a domain above holds the key
+ *   overridden  - an inherited agent answered with this domain's key
+ *   missing     - no key anywhere on the chain; the agent cannot answer
+ */
+export type AiAgentKeyState = 'own' | 'inherited' | 'overridden' | 'missing'
+
+export interface AiAgentEntry {
+  spec: AiAgentSpec
+  /** The domain that declared the agent. */
+  ownerDomainId: string
+  inherited: boolean
+  /** An inherited agent this domain turned off for itself. */
+  turnedOff: boolean
+  keyState: AiAgentKeyState
+  /** The domain whose key answers. */
+  keyDomainId?: string
+  /** Shown only for a key of this domain (ADR-0112 decision 5). A key from above is never hinted below. */
+  keyHint?: string
+  /** Active, not turned off here, and has a key. */
+  usable: boolean
+  /** Server-only - never put on a GraphQL type. */
+  apiKey?: string
+  /** For a client cache: changes whenever the key does. */
+  keyVersion?: string
+}
+
+export interface AiAgentDirectory {
+  domainId: string
+  /** The domain and its ancestors, closest first, with names for the screen. */
+  chain: { id: string; name: string }[]
+  /** This domain's own agents first, then each ancestor's, closest first. */
+  entries: AiAgentEntry[]
+  /** This domain's stored setting, as parsed. */
+  own: AiAgentsSetting
+  /** The agent a request without a choice gets, and how it was decided. */
+  defaultAgentId?: string
+  defaultFrom: 'own' | 'inherited' | 'first' | 'none'
+}
+
+export async function readAiAgentDirectory(given: Domain | { id: string }): Promise<AiAgentDirectory> {
+  const domain = await fullDomain(given)
+  const chainIds = await getDomainIdsWithAncestors(domain)
+  const [settings, domains] = await Promise.all([
+    getRepository(Setting).find({ where: { domain: { id: In(chainIds) }, name: AI_AGENTS_SETTING } }),
+    getRepository(Domain).find({ where: { id: In(chainIds) } })
+  ])
+
+  const settingOf = new Map(settings.map(one => [one.domainId, parseAiAgentsSetting(one.value)]))
+  const own = settingOf.get(domain.id) ?? { agents: [] }
+  const turnedOff = new Set(own.turnedOff ?? [])
+
+  /* The domain's own agents whatever their state; an inherited one only while its owner keeps it on. */
+  const declared: { spec: AiAgentSpec; ownerDomainId: string }[] = []
+  for (const domainId of chainIds) {
+    const setting = settingOf.get(domainId)
+    if (!setting) continue
+    for (const spec of setting.agents) {
+      if (domainId !== domain.id && !spec.active) continue
+      declared.push({ spec, ownerDomainId: domainId })
+    }
+  }
+
+  const keyNames = declared.map(one => aiAgentKeyName(one.spec.id))
+  const keyRows = keyNames.length
+    ? await getRepository(EnvVar).find({ where: { domain: { id: In(chainIds) }, name: In(keyNames), active: true } })
+    : []
+  const keyOf = new Map(dedupByClosestDomain(keyRows, chainIds, row => row.name).map(row => [row.name, row]))
+
+  const entries = declared.map(({ spec, ownerDomainId }): AiAgentEntry => {
+    const inherited = ownerDomainId !== domain.id
+    const key = keyOf.get(aiAgentKeyName(spec.id))
+    const keyHere = key?.domainId === domain.id
+    const keyState: AiAgentKeyState = !key?.value ? 'missing' : !keyHere ? 'inherited' : inherited ? 'overridden' : 'own'
+    const off = inherited && turnedOff.has(spec.id)
+    return {
+      spec,
+      ownerDomainId,
+      inherited,
+      turnedOff: off,
+      keyState,
+      ...(key?.value && { keyDomainId: key.domainId, apiKey: key.value, keyVersion: `${key.domainId}:${key.updatedAt?.valueOf() ?? ''}` }),
+      ...(keyHere && key?.value && { keyHint: secretHint(key.value) }),
+      usable: spec.active && !off && keyState !== 'missing'
+    }
+  })
+
+  const nameOf = new Map(domains.map(one => [one.id, one.name]))
+  const { defaultAgentId, defaultFrom } = pickDefault(chainIds, settingOf, entries)
+
+  return {
+    domainId: domain.id,
+    chain: chainIds.map(id => ({ id, name: nameOf.get(id) ?? id })),
+    entries,
+    own,
+    ...(defaultAgentId && { defaultAgentId }),
+    defaultFrom
+  }
+}
+
+/**
+ * A caller that holds only the domain's id (a background job, a webhook) still gets the domain's whole chain: the walk
+ * needs `parentId`, which an id alone does not carry.
+ */
+export async function fullDomain(given: Domain | { id: string }): Promise<Domain> {
+  if ((given as Domain).parentId !== undefined) return given as Domain
+  const found = await getRepository(Domain).findOne({ where: { id: given.id } })
+  if (!found) throw new Error(`no domain ${given.id}`)
+  return found
+}
+
+/**
+ * This domain's own choice, else the closest ancestor's choice that is usable here, else the first usable agent by
+ * name. Registration order never decides it.
+ */
+function pickDefault(
+  chainIds: string[],
+  settingOf: Map<string, AiAgentsSetting>,
+  entries: AiAgentEntry[]
+): { defaultAgentId?: string; defaultFrom: AiAgentDirectory['defaultFrom'] } {
+  const usable = new Map(entries.filter(one => one.usable).map(one => [one.spec.id, one]))
+  for (const [index, domainId] of chainIds.entries()) {
+    const chosen = settingOf.get(domainId)?.defaultAgentId
+    if (chosen && usable.has(chosen)) return { defaultAgentId: chosen, defaultFrom: index === 0 ? 'own' : 'inherited' }
+  }
+  const [first] = [...usable.values()].sort((a, b) => a.spec.name.localeCompare(b.spec.name))
+  return first ? { defaultAgentId: first.spec.id, defaultFrom: 'first' } : { defaultFrom: 'none' }
+}
+
+/** Every domain below this one, any depth. */
+export async function readDescendantDomains(domain: Domain): Promise<Domain[]> {
+  const found: Domain[] = []
+  const seen = new Set<string>([domain.id])
+  let frontier = [domain.id]
+  for (let depth = 0; frontier.length && depth < 10; depth++) {
+    const children = await getRepository(Domain).find({ where: { parent: { id: In(frontier) } } })
+    const fresh = children.filter(one => !seen.has(one.id))
+    fresh.forEach(one => seen.add(one.id))
+    found.push(...fresh)
+    frontier = fresh.map(one => one.id)
+  }
+  return found
+}
+
+/**
+ * For each of this domain's agents, the domains below that use it - every descendant that has not turned it off.
+ * The owner sees these before deleting, turning off or rekeying an agent (§3-3 point 8).
+ */
+export async function readAgentUsersBelow(
+  domain: Domain,
+  agentIds: string[]
+): Promise<Map<string, { id: string; name: string }[]>> {
+  const result = new Map(agentIds.map(id => [id, [] as { id: string; name: string }[]]))
+  if (!agentIds.length) return result
+  const descendants = await readDescendantDomains(domain)
+  if (!descendants.length) return result
+
+  const settings = await getRepository(Setting).find({
+    where: { domain: { id: In(descendants.map(one => one.id)) }, name: AI_AGENTS_SETTING }
+  })
+  const offOf = new Map(settings.map(one => [one.domainId, new Set(parseAiAgentsSetting(one.value).turnedOff ?? [])]))
+  for (const below of descendants) {
+    for (const agentId of agentIds) {
+      if (!offOf.get(below.id)?.has(agentId)) result.get(agentId)!.push({ id: below.id, name: below.name })
+    }
+  }
+  return result
+}

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

@@ -0,0 +1,151 @@
+/*
+ * What this guards: **saving a domain's agents writes the definition and the keys together, keeps a key that was not
+ * sent, and refuses what would make a picker lie** (design/ai/agent-settings.md §3-2, §3-3, ADR-0112 decision 3).
+ */
+jest.mock('@things-factory/shell', () => ({
+  ...jest.requireActual('@things-factory/shell'),
+  getRepository: jest.fn(() => ({ find: async () => mockBelowSettings }))
+}))
+jest.mock('./agent-directory', () => ({
+  readAiAgentDirectory: jest.fn(),
+  readDescendantDomains: jest.fn(async () => mockBelow)
+}))
+jest.mock('./provider-models', () => ({ listProviderModels: jest.fn(async () => ['gpt-4o', 'gpt-4o-mini']) }))
+
+import { readAiAgentDirectory } from './agent-directory'
+import { saveAiAgents } from './agent-settings-save'
+import { aiAgentKeyName } from './agent-spec'
+import { listProviderModels } from './provider-models'
+
+let mockBelow: any[] = []
+let mockBelowSettings: any[] = []
+
+const stored = { id: 'a1', name: 'GPT', provider: 'openai', model: 'gpt-4o', active: true }
+
+function directory(extra: any = {}) {
+  return {
+    own: { agents: [stored] },
+    entries: [
+      { spec: stored, inherited: false, keyState: 'own', apiKey: 'sk-stored', usable: true },
+      { spec: { id: 'h1', name: 'HQ Claude', provider: 'anthropic', model: 'c', active: true }, inherited: true, keyState: 'inherited', usable: true }
+    ],
+    ...extra
+  }
+}
+
+/* A transaction that records what was written. */
+function fakeTx() {
+  const writes: any[] = []
+  const repository = (target: any) => ({
+    findOne: async () => undefined,
+    save: async (row: any) => writes.push({ entity: target.name, op: 'save', row }),
+    delete: async (where: any) => writes.push({ entity: target.name, op: 'delete', where })
+  })
+  return { writes, tx: { getRepository: repository } as any }
+}
+
+const context = (tx: any) => ({ tx, domain: { id: 'plant' } as any, user: { id: 'u1' } })
+
+beforeEach(() => {
+  mockBelow = []
+  mockBelowSettings = []
+  ;(readAiAgentDirectory as jest.Mock).mockResolvedValue(directory())
+  ;(listProviderModels as jest.Mock).mockClear()
+})
+
+it('★ the definition goes to the ai-agents setting, and a new key to its own EnvVar - in the same transaction', async () => {
+  const { writes, tx } = fakeTx()
+  await saveAiAgents({ agents: [{ ...stored, apiKey: 'sk-new-key' }] }, context(tx))
+
+  const setting = writes.find(one => one.entity === 'Setting')
+  expect(JSON.parse(setting.row.value).agents).toEqual([stored])
+  expect(writes).toContainEqual(
+    expect.objectContaining({ entity: 'EnvVar', op: 'save', row: expect.objectContaining({ name: aiAgentKeyName('a1'), value: 'sk-new-key', domain: { id: 'plant' } }) })
+  )
+})
+
+it('★ a key left out keeps the stored one, and an unchanged agent does not ask the provider again', async () => {
+  const { writes, tx } = fakeTx()
+  await saveAiAgents({ agents: [{ ...stored, name: 'GPT renamed' }] }, context(tx))
+
+  expect(writes.filter(one => one.entity === 'EnvVar')).toEqual([])
+  expect(listProviderModels).not.toHaveBeenCalled()
+})
+
+it('★ a new agent without a key is refused', async () => {
+  const { tx } = fakeTx()
+  await expect(
+    saveAiAgents({ agents: [stored, { name: 'New', provider: 'gemini', model: 'g', active: true }] }, context(tx))
+  ).rejects.toMatchObject({ code: 'ai-agent-key-required' })
+})
+
+it('★ a model the provider does not offer to that key is refused', async () => {
+  const { tx } = fakeTx()
+  await expect(saveAiAgents({ agents: [{ ...stored, model: 'gpt-made-up' }] }, context(tx))).rejects.toMatchObject({
+    code: 'ai-agent-model-not-offered',
+    params: { agent: 'GPT', model: 'gpt-made-up' }
+  })
+})
+
+it('★ a name already inherited from above is refused', async () => {
+  const { tx } = fakeTx()
+  await expect(saveAiAgents({ agents: [{ ...stored, name: 'hq claude' }] }, context(tx))).rejects.toMatchObject({
+    code: 'ai-agent-name-taken'
+  })
+})
+
+it('★ a name a domain below already uses is refused, naming that domain', async () => {
+  mockBelow = [{ id: 'line', name: '1라인' }]
+  mockBelowSettings = [{ domainId: 'line', name: 'ai-agents', value: JSON.stringify({ agents: [{ ...stored, id: 'l1', name: 'Line GPT' }] }) }]
+  const { tx } = fakeTx()
+  await expect(saveAiAgents({ agents: [{ ...stored, name: 'Line GPT' }] }, context(tx))).rejects.toMatchObject({
+    code: 'ai-agent-name-taken',
+    params: { name: 'Line GPT', domain: '1라인' }
+  })
+})
+
+it('★ an id that is not this domain\'s own agent is refused - an inherited agent is not edited from below', async () => {
+  const { tx } = fakeTx()
+  await expect(
+    saveAiAgents({ agents: [stored, { id: 'h1', name: 'Hijack', provider: 'anthropic', model: 'c', active: true }] }, context(tx))
+  ).rejects.toMatchObject({ code: 'ai-agent-not-in-domain' })
+})
+
+it('★ deleting an agent removes its key here and the keys domains below set for it', async () => {
+  mockBelow = [{ id: 'line', name: '1라인' }]
+  const { writes, tx } = fakeTx()
+  await saveAiAgents({ agents: [] }, context(tx))
+
+  const removal = writes.find(one => one.entity === 'EnvVar' && one.op === 'delete')
+  expect(removal.where.name._value).toEqual([aiAgentKeyName('a1')])
+  expect(removal.where.domain.id._value).toEqual(['plant', 'line'])
+})
+
+it('★ an inherited agent can be answered with this domain\'s key, and given back to the key above', async () => {
+  const set = fakeTx()
+  await saveAiAgents({ agents: [stored], inheritedKeys: [{ agentId: 'h1', apiKey: 'sk-plant-for-h1' }] }, context(set.tx))
+  expect(set.writes).toContainEqual(
+    expect.objectContaining({ entity: 'EnvVar', op: 'save', row: expect.objectContaining({ name: aiAgentKeyName('h1'), value: 'sk-plant-for-h1' }) })
+  )
+
+  const clear = fakeTx()
+  await saveAiAgents({ agents: [stored], inheritedKeys: [{ agentId: 'h1', clear: true }] }, context(clear.tx))
+  expect(clear.writes).toContainEqual({ entity: 'EnvVar', op: 'delete', where: { domain: { id: 'plant' }, name: aiAgentKeyName('h1') } })
+})
+
+it('★ only inherited agents can be turned off here, and the default must be one this domain can use', async () => {
+  const { writes, tx } = fakeTx()
+  await saveAiAgents({ agents: [stored], turnedOff: ['h1', 'a1', 'nonesuch'], defaultAgentId: 'h1' }, context(tx))
+  const value = JSON.parse(writes.find(one => one.entity === 'Setting').row.value)
+  expect(value).toMatchObject({ turnedOff: ['h1'], defaultAgentId: 'h1' })
+
+  await expect(saveAiAgents({ agents: [stored], defaultAgentId: 'nonesuch' }, context(fakeTx().tx))).rejects.toMatchObject({
+    code: 'ai-agent-not-available'
+  })
+})
+
+it('only three providers', async () => {
+  await expect(
+    saveAiAgents({ agents: [{ ...stored, provider: 'mistral' }] }, context(fakeTx().tx))
+  ).rejects.toMatchObject({ code: 'ai-agent-provider-unknown' })
+})