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

package/config/config.development.js

@@ -17,73 +17,7 @@ module.exports = {
     timeoutMs: 300
   },
   /*
-    AI Client Configuration
-
-    Provider-agnostic configuration for the default AI client used by board-ai
-    and any other module that calls `getDefaultAIClient()`.
-
-    To activate, override this in your application's config (config.development.js
-    or config.production.js) with your provider/key.
-
-    Currently supported providers (registered via @things-factory/ai-client-base):
-      - 'anthropic'  — Anthropic Claude (default model: claude-sonnet-4-6)
-      - 'gemini'     — Google Gemini  (default model: gemini-3-pro)
-      - 'openai'     — OpenAI GPT     (default model: gpt-4o)
-
-    Example for Anthropic Claude:
-
-      aiClient: {
-        provider: 'anthropic',
-        model: 'claude-sonnet-4-6',
-        apiKey: process.env.ANTHROPIC_API_KEY
-      }
-
-    Example for Google Gemini:
-
-      aiClient: {
-        provider: 'gemini',
-        model: 'gemini-3-pro',
-        apiKey: process.env.GOOGLE_API_KEY
-      }
-
-    Example for on-prem / proxy / Bedrock-style endpoint:
-
-      aiClient: {
-        provider: 'anthropic',
-        model: 'claude-sonnet-4-6',
-        apiKey: 'internal-key',
-        baseURL: 'https://internal-llm-gateway.example.com'
-      }
-
-    Fields:
-      - provider : Registered adapter name. Required.
-      - model    : Model ID. Optional; falls back to adapter default.
-      - apiKey   : API key. If omitted, SDK-level environment fallback applies
-                   (Anthropic SDK: ANTHROPIC_API_KEY; Gemini adapter: GOOGLE_API_KEY,
-                   GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY).
-      - baseURL  : Optional. On-prem / proxy / compatible endpoint.
-
-    Example for OpenAI:
-
-      aiClient: {
-        provider: 'openai',
-        model: 'gpt-4o',
-        apiKey: process.env.OPENAI_API_KEY,
-        organization: process.env.OPENAI_ORGANIZATION  // optional
-      }
-
-    Note on the legacy `openai` config key:
-      @things-factory/codelingua uses a separate `openai: { organization, apiKey }` key.
-      The two keys are intentionally independent — codelingua keeps using `openai`,
-      ai-client-base only reads `aiClient`. If you want OpenAI here too, set `aiClient`
-      explicitly with provider:'openai' (the values may duplicate codelingua's,
-      that's fine — they live in different modules).
-
-    If `aiClient` is absent, no default client is created — chat() calls will fail
-    with a clear message. Modules can still be used with an explicitly-passed AIClient
-    via setDefaultAIClient(...).
+    There is no deployment-wide AI client. Each domain sets its AI agents (provider, model, API key) in
+    Settings, and a domain with no agent has no AI - see operato-application design/ai/agent-settings.md.
   */
-  // aiClient: {
-  //   provider: 'anthropic'
-  // }
 }

package/config/config.production.js

@@ -9,25 +9,7 @@ module.exports = {
     timeoutMs: 300
   },
   /*
-    AI Client Configuration — Production
-
-    See config.development.js for the full reference and provider examples.
-
-    Override this in your application's production config with the actual
-    provider and credentials. Never commit real API keys to the source tree.
-
-    Recommended pattern — read from environment in your application config:
-
-      aiClient: {
-        provider: process.env.AI_PROVIDER || 'anthropic',
-        model: process.env.AI_MODEL,
-        apiKey: process.env.AI_API_KEY
-                || process.env.ANTHROPIC_API_KEY
-                || process.env.GOOGLE_API_KEY,
-        baseURL: process.env.AI_BASE_URL
-      }
+    There is no deployment-wide AI client. Each domain sets its AI agents (provider, model, API key) in
+    Settings, and a domain with no agent has no AI - see operato-application design/ai/agent-settings.md.
   */
-  // aiClient: {
-  //   provider: 'anthropic'
-  // }
 }

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

@@ -0,0 +1,71 @@
+import { Domain } from '@things-factory/shell';
+import { type AiAgentSpec, type AiAgentsSetting } 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 declare function readAiAgentDirectory(given: Domain | {
+    id: string;
+}): Promise<AiAgentDirectory>;
+/**
+ * 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 declare function fullDomain(given: Domain | {
+    id: string;
+}): Promise<Domain>;
+/** Every domain below this one, any depth. */
+export declare function readDescendantDomains(domain: Domain): Promise<Domain[]>;
+/**
+ * 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 declare function readAgentUsersBelow(domain: Domain, agentIds: string[]): Promise<Map<string, {
+    id: string;
+    name: string;
+}[]>>;

package/dist-server/service/agent/agent-directory.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAiAgentDirectory = readAiAgentDirectory;
+exports.fullDomain = fullDomain;
+exports.readDescendantDomains = readDescendantDomains;
+exports.readAgentUsersBelow = readAgentUsersBelow;
+const typeorm_1 = require("typeorm");
+const shell_1 = require("@things-factory/shell");
+const setting_base_1 = require("@things-factory/setting-base");
+const agent_spec_js_1 = require("./agent-spec.js");
+async function readAiAgentDirectory(given) {
+    const domain = await fullDomain(given);
+    const chainIds = await (0, shell_1.getDomainIdsWithAncestors)(domain);
+    const [settings, domains] = await Promise.all([
+        (0, shell_1.getRepository)(setting_base_1.Setting).find({ where: { domain: { id: (0, typeorm_1.In)(chainIds) }, name: agent_spec_js_1.AI_AGENTS_SETTING } }),
+        (0, shell_1.getRepository)(shell_1.Domain).find({ where: { id: (0, typeorm_1.In)(chainIds) } })
+    ]);
+    const settingOf = new Map(settings.map(one => [one.domainId, (0, agent_spec_js_1.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 = [];
+    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 => (0, agent_spec_js_1.aiAgentKeyName)(one.spec.id));
+    const keyRows = keyNames.length
+        ? await (0, shell_1.getRepository)(shell_1.EnvVar).find({ where: { domain: { id: (0, typeorm_1.In)(chainIds) }, name: (0, typeorm_1.In)(keyNames), active: true } })
+        : [];
+    const keyOf = new Map((0, shell_1.dedupByClosestDomain)(keyRows, chainIds, row => row.name).map(row => [row.name, row]));
+    const entries = declared.map(({ spec, ownerDomainId }) => {
+        const inherited = ownerDomainId !== domain.id;
+        const key = keyOf.get((0, agent_spec_js_1.aiAgentKeyName)(spec.id));
+        const keyHere = key?.domainId === domain.id;
+        const keyState = !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: (0, shell_1.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.
+ */
+async function fullDomain(given) {
+    if (given.parentId !== undefined)
+        return given;
+    const found = await (0, shell_1.getRepository)(shell_1.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, settingOf, entries) {
+    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. */
+async function readDescendantDomains(domain) {
+    const found = [];
+    const seen = new Set([domain.id]);
+    let frontier = [domain.id];
+    for (let depth = 0; frontier.length && depth < 10; depth++) {
+        const children = await (0, shell_1.getRepository)(shell_1.Domain).find({ where: { parent: { id: (0, typeorm_1.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).
+ */
+async function readAgentUsersBelow(domain, agentIds) {
+    const result = new Map(agentIds.map(id => [id, []]));
+    if (!agentIds.length)
+        return result;
+    const descendants = await readDescendantDomains(domain);
+    if (!descendants.length)
+        return result;
+    const settings = await (0, shell_1.getRepository)(setting_base_1.Setting).find({
+        where: { domain: { id: (0, typeorm_1.In)(descendants.map(one => one.id)) }, name: agent_spec_js_1.AI_AGENTS_SETTING }
+    });
+    const offOf = new Map(settings.map(one => [one.domainId, new Set((0, agent_spec_js_1.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;
+}
+//# sourceMappingURL=agent-directory.js.map

package/dist-server/service/agent/agent-directory.js.map

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

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

@@ -0,0 +1,38 @@
+import { EntityManager } from 'typeorm';
+import { Domain } from '@things-factory/shell';
+/** 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 declare function saveAiAgents(write: AiAgentsWrite, { tx, domain, user }: {
+    tx: EntityManager;
+    domain: Domain;
+    user?: {
+        id: string;
+    };
+}): Promise<void>;

package/dist-server/service/agent/agent-settings-save.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveAiAgents = saveAiAgents;
+const crypto_1 = require("crypto");
+const typeorm_1 = require("typeorm");
+const shell_1 = require("@things-factory/shell");
+const setting_base_1 = require("@things-factory/setting-base");
+const agent_directory_js_1 = require("./agent-directory.js");
+const agent_spec_js_1 = require("./agent-spec.js");
+const provider_models_js_1 = require("./provider-models.js");
+/**
+ * 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).
+ */
+async function saveAiAgents(write, { tx, domain, user }) {
+    const directory = await (0, agent_directory_js_1.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 shell_1.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 (0, provider_models_js_1.listProviderModels)({ provider: agent.provider, apiKey: key, baseURL: agent.baseURL, organization: agent.organization });
+            if (!offered.includes(agent.model)) {
+                throw new shell_1.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 shell_1.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, (0, agent_spec_js_1.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 shell_1.Refusal('ai-agent-not-available', { agentId: one.agentId }, 'That agent is not inherited by this domain.');
+        }
+        if (one.clear) {
+            await tx.getRepository(shell_1.EnvVar).delete({ domain: { id: domain.id }, name: (0, agent_spec_js_1.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 => (0, agent_spec_js_1.aiAgentKeyName)(one.id));
+    if (deleted.length) {
+        const below = await (0, agent_directory_js_1.readDescendantDomains)(domain);
+        await tx.getRepository(shell_1.EnvVar).delete({
+            domain: { id: (0, typeorm_1.In)([domain.id, ...below.map(one => one.id)]) },
+            name: (0, typeorm_1.In)(deleted)
+        });
+    }
+}
+function normalize(write, storedById) {
+    const name = write.name?.trim();
+    if (!name)
+        throw new shell_1.Refusal('ai-agent-name-required', {}, 'Every agent needs a name.');
+    if (!(0, agent_spec_js_1.isAiAgentProvider)(write.provider)) {
+        throw new shell_1.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 shell_1.Refusal('ai-agent-model-required', { agent: name }, `Pick the model of "${name}".`);
+    if (write.id && !storedById.has(write.id)) {
+        throw new shell_1.Refusal('ai-agent-not-in-domain', { agentId: write.id }, 'That agent does not belong to this domain.');
+    }
+    return {
+        id: write.id || (0, crypto_1.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, stored, newKey) {
+    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) {
+    const seen = new Set();
+    for (const agent of agents) {
+        const key = agent.name.toLowerCase();
+        if (seen.has(key))
+            throw new shell_1.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, agents, inherited) {
+    const taken = new Map();
+    for (const spec of inherited)
+        taken.set(spec.name.toLowerCase(), '');
+    const below = await (0, agent_directory_js_1.readDescendantDomains)(domain);
+    if (below.length) {
+        const settings = await (0, shell_1.getRepository)(setting_base_1.Setting).find({
+            where: { domain: { id: (0, typeorm_1.In)(below.map(one => one.id)) }, name: agent_spec_js_1.AI_AGENTS_SETTING }
+        });
+        const nameOf = new Map(below.map(one => [one.id, one.name]));
+        for (const setting of settings) {
+            for (const spec of (0, agent_spec_js_1.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 shell_1.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, domain, user, value) {
+    const repository = tx.getRepository(setting_base_1.Setting);
+    const stored = await repository.findOne({ where: { domain: { id: domain.id }, name: agent_spec_js_1.AI_AGENTS_SETTING } });
+    await repository.save({
+        ...(stored ?? { domain: { id: domain.id }, name: agent_spec_js_1.AI_AGENTS_SETTING, category: agent_spec_js_1.AI_AGENTS_SETTING_CATEGORY, creator: user }),
+        value,
+        updater: user
+    });
+}
+async function upsertKey(tx, domain, agent, apiKey) {
+    const repository = tx.getRepository(shell_1.EnvVar);
+    const name = (0, agent_spec_js_1.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
+    });
+}
+//# sourceMappingURL=agent-settings-save.js.map

package/dist-server/service/agent/agent-settings-save.js.map

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

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

@@ -0,0 +1,43 @@
+/**
+ * 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 declare const AI_AGENT_PROVIDERS: readonly ["openai", "anthropic", "gemini"];
+export type AiAgentProvider = (typeof AI_AGENT_PROVIDERS)[number];
+/** The Setting row that holds a domain's agents. */
+export declare const AI_AGENTS_SETTING = "ai-agents";
+export declare 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 declare function aiAgentKeyName(agentId: string): string;
+export declare const AI_AGENT_KEY_PREFIX = "AiAgent::";
+export declare function isAiAgentProvider(value: unknown): value is AiAgentProvider;
+/**
+ * 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 declare function parseAiAgentsSetting(value: string | null | undefined): AiAgentsSetting;
+export declare function stringifyAiAgentsSetting(setting: AiAgentsSetting): string;