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

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

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_AGENT_KEY_PREFIX = exports.AI_AGENTS_SETTING_CATEGORY = exports.AI_AGENTS_SETTING = exports.AI_AGENT_PROVIDERS = void 0;
+exports.aiAgentKeyName = aiAgentKeyName;
+exports.isAiAgentProvider = isAiAgentProvider;
+exports.parseAiAgentsSetting = parseAiAgentsSetting;
+exports.stringifyAiAgentsSetting = stringifyAiAgentsSetting;
+/** The providers an agent may name. Three, by decision (2026-10-12). */
+exports.AI_AGENT_PROVIDERS = ['openai', 'anthropic', 'gemini'];
+/** The Setting row that holds a domain's agents. */
+exports.AI_AGENTS_SETTING = 'ai-agents';
+exports.AI_AGENTS_SETTING_CATEGORY = 'ai';
+/** The EnvVar that holds an agent's key. Named by the agent id, so renaming an agent keeps its key. */
+function aiAgentKeyName(agentId) {
+    return `AiAgent::${agentId}::apiKey`;
+}
+exports.AI_AGENT_KEY_PREFIX = 'AiAgent::';
+function isAiAgentProvider(value) {
+    return typeof value === 'string' && exports.AI_AGENT_PROVIDERS.includes(value);
+}
+const EMPTY = { agents: [] };
+/**
+ * Reads a stored `ai-agents` value. The row can also be written through the generic setting doors, so a value that
+ * does not parse reads as no agents, and an entry without an id, a name, a known provider or a model is left out -
+ * a broken row never becomes an agent that fails at the provider.
+ */
+function parseAiAgentsSetting(value) {
+    if (!value)
+        return EMPTY;
+    let raw;
+    try {
+        raw = JSON.parse(value);
+    }
+    catch {
+        return EMPTY;
+    }
+    if (!raw || typeof raw !== 'object' || !Array.isArray(raw.agents))
+        return EMPTY;
+    const agents = raw.agents.flatMap((one) => {
+        if (!one || typeof one !== 'object')
+            return [];
+        const id = text(one.id);
+        const name = text(one.name);
+        const model = text(one.model);
+        if (!id || !name || !model || !isAiAgentProvider(one.provider))
+            return [];
+        return [
+            {
+                id,
+                name,
+                provider: one.provider,
+                model,
+                ...(text(one.baseURL) && { baseURL: text(one.baseURL) }),
+                ...(one.provider === 'openai' && text(one.organization) && { organization: text(one.organization) }),
+                active: one.active !== false
+            }
+        ];
+    });
+    const turnedOff = Array.isArray(raw.turnedOff) ? raw.turnedOff.filter((id) => typeof id === 'string') : [];
+    return {
+        agents,
+        ...(text(raw.defaultAgentId) && { defaultAgentId: text(raw.defaultAgentId) }),
+        ...(turnedOff.length && { turnedOff })
+    };
+}
+function stringifyAiAgentsSetting(setting) {
+    return JSON.stringify({
+        agents: setting.agents,
+        ...(setting.defaultAgentId && { defaultAgentId: setting.defaultAgentId }),
+        ...(setting.turnedOff?.length && { turnedOff: setting.turnedOff })
+    });
+}
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+//# sourceMappingURL=agent-spec.js.map

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

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

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

@@ -0,0 +1,53 @@
+import { Domain } from '@things-factory/shell';
+import type { AIClient } from '../types.js';
+import { type AiAgentEntry } from './agent-directory.js';
+/**
+ * **The one door to a model** (design/ai/agent-settings.md §4).
+ *
+ * Every call that reaches a provider gets its client here, for a domain: the agent is the one asked for, or the
+ * domain's default, and its key is the closest one on the domain chain. There is no deployment-wide client - a domain
+ * with no usable agent has no AI (user decision 2026-10-12).
+ *
+ * The client handed back is metered: each provider request writes one AiUsage row with the domain, the person, the
+ * agent and what was used (ADR-0061 decision 6).
+ */
+export interface AiClientRequest {
+    domain: Domain;
+    /** The person calling. Empty for a call with no person, such as a webhook. */
+    user?: {
+        id: string;
+    } | null;
+    /** The agent the person picked. Empty takes the domain's default. */
+    agentId?: string | null;
+    /** The conversation mode, when the call is part of a conversation. */
+    modeKind?: string | null;
+    /** The conversation, by id. */
+    sessionId?: string | null;
+}
+/** The client of one agent, as a call got it. */
+export interface AgentClient extends AIClient {
+    readonly agent: {
+        id: string;
+        name: string;
+        provider: string;
+        model: string;
+    };
+}
+export declare function aiClientFor(request: AiClientRequest): Promise<AgentClient>;
+/**
+ * The agent a request is answered by. A named agent that this domain cannot use is refused, never swapped for
+ * another; no agent at all is "not configured".
+ */
+export declare function pickAgent(entries: AiAgentEntry[], agentId: string | null | undefined, defaultAgentId?: string): AiAgentEntry;
+/** The UTC hour a moment falls in. */
+export declare function hourOf(moment: Date): Date;
+/** Why a provider request failed, as the usage row keeps it. */
+export declare function outcomeOf(error: any): string;
+type TestClientResolver = (request: AiClientRequest) => AgentClient;
+export declare function isAIClientForTesting(): boolean;
+/**
+ * Tests answer aiClientFor with a client of their own - no database, no provider, no usage rows. A client is wrapped
+ * as an agent named after it; a function decides per request. `undefined` puts the real door back.
+ */
+export declare function setAIClientForTesting(client: AIClient | TestClientResolver | undefined): void;
+export {};

package/dist-server/service/agent/ai-client-for.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiClientFor = aiClientFor;
+exports.pickAgent = pickAgent;
+exports.hourOf = hourOf;
+exports.outcomeOf = outcomeOf;
+exports.isAIClientForTesting = isAIClientForTesting;
+exports.setAIClientForTesting = setAIClientForTesting;
+const shell_1 = require("@things-factory/shell");
+const factory_js_1 = require("../factory.js");
+const agent_directory_js_1 = require("./agent-directory.js");
+async function aiClientFor(request) {
+    if (_testing)
+        return _testing(request);
+    if (!request.domain)
+        throw new Error('aiClientFor needs the domain the call is made in');
+    const directory = await (0, agent_directory_js_1.readAiAgentDirectory)(request.domain);
+    const entry = pickAgent(directory.entries, request.agentId, directory.defaultAgentId);
+    return meter(providerClientOf(entry), entry, request);
+}
+/**
+ * The agent a request is answered by. A named agent that this domain cannot use is refused, never swapped for
+ * another; no agent at all is "not configured".
+ */
+function pickAgent(entries, agentId, defaultAgentId) {
+    if (agentId) {
+        const named = entries.find(one => one.spec.id === agentId);
+        if (!named?.usable) {
+            throw new shell_1.Refusal('ai-agent-not-available', { agentId }, 'The AI agent you picked is not available here.');
+        }
+        return named;
+    }
+    const fallback = entries.find(one => one.spec.id === defaultAgentId && one.usable);
+    if (!fallback) {
+        throw new shell_1.Refusal('ai-not-configured', {}, 'AI is not set up for this domain.');
+    }
+    return fallback;
+}
+/* Provider clients are kept per agent and rebuilt when its definition or its key changes. */
+const _clients = new Map();
+function providerClientOf(entry) {
+    const { spec } = entry;
+    const version = JSON.stringify([spec.provider, spec.model, spec.baseURL, spec.organization, entry.keyVersion]);
+    const cached = _clients.get(spec.id);
+    if (cached?.version === version)
+        return cached.client;
+    const client = (0, factory_js_1.createAIClient)({
+        provider: spec.provider,
+        model: spec.model,
+        apiKey: entry.apiKey,
+        ...(spec.baseURL && { baseURL: spec.baseURL }),
+        ...(spec.organization && { organization: spec.organization })
+    });
+    _clients.set(spec.id, { version, client });
+    return client;
+}
+function meter(client, entry, request) {
+    const { spec } = entry;
+    async function measured(operation, options, call) {
+        const started = new Date();
+        const reported = [];
+        const withUsage = {
+            ...options,
+            onUsage: usage => {
+                reported.push(usage);
+                options?.onUsage?.(usage);
+            }
+        };
+        try {
+            const result = await call(withUsage);
+            record(operation, started, reported, 'ok');
+            return result;
+        }
+        catch (error) {
+            record(operation, started, reported, outcomeOf(error));
+            /* A failure must say why somewhere: the loop above turns it into a sentence for the person, and the usage row
+               keeps only its code. The provider's own message names no key. */
+            console.error(`[ai-client-base] ${spec.provider}:${spec.model} (${spec.name}) ${operation} failed:`, error?.status ?? '', error?.message ?? error);
+            throw error;
+        }
+    }
+    function record(operation, started, reported, outcome) {
+        const durationMs = Date.now() - started.valueOf();
+        /* A failed request reports nothing, and is still one row - a failure costs time and often money. */
+        const rows = (reported.length ? reported : [{ model: spec.model }]).map((usage, index, all) => ({
+            domain: { id: request.domain.id },
+            ...(request.user?.id && { creator: { id: request.user.id } }),
+            agentId: spec.id,
+            agentDomainId: entry.ownerDomainId,
+            keyDomainId: entry.keyDomainId,
+            provider: spec.provider,
+            model: usage.model || spec.model,
+            modeKind: request.modeKind ?? undefined,
+            operation,
+            sessionId: request.sessionId ?? undefined,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            /* The whole call's time goes on its last request; the rows of one call still add up to it. */
+            durationMs: index === all.length - 1 ? durationMs : 0,
+            outcome: index === all.length - 1 ? outcome : 'ok',
+            hourStart: hourOf(started)
+        }));
+        /* Outside the caller's transaction: a rolled-back write still spent the tokens. By name, so the decorated entity
+           stays out of this module's imports. */
+        (0, shell_1.getRepository)('AiUsage')
+            .save(rows)
+            .catch(error => console.error('[ai-client-base] could not record AI usage:', error?.message ?? error));
+    }
+    const metered = {
+        id: `${spec.provider}:${spec.model}`,
+        agent: { id: spec.id, name: spec.name, provider: spec.provider, model: spec.model },
+        chat: (messages, options) => measured('chat', options, o => client.chat(messages, o)),
+        generateJSON: (prompt, options) => measured('generateJSON', options, o => client.generateJSON(prompt, o)),
+        ...(client.vision && {
+            vision: (image, prompt, options) => measured('vision', options, o => client.vision(image, prompt, o))
+        }),
+        ...(client.chatWithTools && {
+            chatWithTools: (messages, tools, options) => measured('chatWithTools', options, o => client.chatWithTools(messages, tools, o))
+        }),
+        listModels: () => client.listModels()
+    };
+    return metered;
+}
+/** The UTC hour a moment falls in. */
+function hourOf(moment) {
+    const hour = new Date(moment);
+    hour.setUTCMinutes(0, 0, 0);
+    return hour;
+}
+/** Why a provider request failed, as the usage row keeps it. */
+function outcomeOf(error) {
+    const status = Number(error?.status ?? error?.statusCode ?? error?.response?.status);
+    if (status === 401 || status === 403)
+        return 'key-rejected';
+    if (status === 429)
+        return 'rate-limited';
+    return 'provider-error';
+}
+let _testing;
+function isAIClientForTesting() {
+    return !!_testing;
+}
+/**
+ * Tests answer aiClientFor with a client of their own - no database, no provider, no usage rows. A client is wrapped
+ * as an agent named after it; a function decides per request. `undefined` puts the real door back.
+ */
+function setAIClientForTesting(client) {
+    if (!client) {
+        _testing = undefined;
+    }
+    else if (typeof client === 'function') {
+        _testing = client;
+    }
+    else {
+        /* The test's own object answers - its counters and `this` stay its own; it only gains the agent it is named as. */
+        if (!client.agent) {
+            const [provider, model] = String(client.id ?? 'test:test').split(':');
+            Object.defineProperty(client, 'agent', {
+                value: { id: 'test-agent', name: client.id ?? 'test', provider, model },
+                configurable: true
+            });
+        }
+        _testing = () => client;
+    }
+}
+//# sourceMappingURL=ai-client-for.js.map

package/dist-server/service/agent/ai-client-for.js.map

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

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

@@ -0,0 +1,37 @@
+import { Domain } from '@things-factory/shell';
+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 declare function summarizeAiUsage(given: Domain, filter: AiUsageFilter): Promise<AiUsageBucketRow[]>;
+export declare function rollUp(hours: any[], bucket: AiUsageBucketSize, timezone: string | undefined, hereId: string, agentNameOf: Map<string, string>): AiUsageBucketRow[];

package/dist-server/service/agent/ai-usage-summary.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeAiUsage = summarizeAiUsage;
+exports.rollUp = rollUp;
+const shell_1 = require("@things-factory/shell");
+const agent_directory_js_1 = require("./agent-directory.js");
+/**
+ * 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.
+ */
+async function summarizeAiUsage(given, filter) {
+    /* The time zone and the chain are the domain row's. */
+    const domain = await (0, agent_directory_js_1.fullDomain)(given);
+    const below = filter.includeDescendants ? await (0, agent_directory_js_1.readDescendantDomains)(domain) : [];
+    const query = (0, shell_1.getRepository)('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(), (0, agent_directory_js_1.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);
+}
+function rollUp(hours, bucket, timezone, hereId, agentNameOf) {
+    const label = bucketLabeller(bucket, timezone);
+    const rows = new Map();
+    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, timezone) {
+    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`;
+    };
+}
+//# sourceMappingURL=ai-usage-summary.js.map

package/dist-server/service/agent/ai-usage-summary.js.map

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

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

@@ -0,0 +1,35 @@
+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.
+ */
+export declare class AiUsage {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    agentId?: string;
+    agentDomainId?: string;
+    keyDomainId?: string;
+    provider: string;
+    model: string;
+    modeKind?: string;
+    operation: string;
+    sessionId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    durationMs: number;
+    /** `ok`, or why it failed: key-rejected · rate-limited · 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.
+     */
+    hourStart: Date;
+    creator?: User;
+    creatorId?: string;
+    createdAt: Date;
+}