@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-tokens.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AiUsage } from '../providers/contract';
+/**
+ * TOKENS AS THE ROLLUPS KEEP THEM (AGL-2937): the pure half.
+ *
+ * A provider reports four counts per request, and each is priced at its own
+ * rate: prompt tokens sent uncached, prompt tokens read from the prompt
+ * cache, prompt tokens written to it, and tokens generated. The org month
+ * (per kind), the person's month and the job step keep the same four, so a
+ * figure read off one means what it means on the others, and the cache hit
+ * rate is the same division everywhere it is shown.
+ *
+ * Stored shapes:
+ *
+ *   orgs/{orgId}/assistUsage/{YYYY-MM}
+ *     kinds: { [kind]: { requests, estCostUsd, providerCostUsd,
+ *                        tokens: { input, cached, cacheWrite, output } } }
+ *   orgs/{orgId}/aiUsageByUser/{uid}/months/{YYYY-MM}
+ *     tokens: { input, cached, cacheWrite, output }
+ *
+ * The month document's own top-level `inputTokens`, `outputTokens`,
+ * `cacheReadTokens` and `cacheWriteTokens` stay its totals; `kinds` splits
+ * them by what the request was for.
+ */
+/** The month document's per-kind map. */
+export declare const AI_USAGE_MONTH_KINDS_FIELD = "kinds";
+/** The token map, on a person's month and on each kind of the org's. */
+export declare const AI_USAGE_TOKENS_FIELD = "tokens";
+export interface AiTokenTotals {
+    /** Prompt tokens sent uncached, at the model's input rate. */
+    input: number;
+    /** Prompt tokens read from the prompt cache, at its read rate. */
+    cached: number;
+    /** Prompt tokens written to the prompt cache, at its write rate. */
+    cacheWrite: number;
+    /** Tokens the model generated, thinking included. */
+    output: number;
+}
+export declare function emptyAiTokenTotals(): AiTokenTotals;
+/** A request's usage, in the rollups' names. */
+export declare function aiTokenTotalsFrom(usage: AiUsage): AiTokenTotals;
+export declare function addAiTokenTotals(a: AiTokenTotals, b: AiTokenTotals): AiTokenTotals;
+/** A stored token map read back, every absent or malformed count as zero. */
+export declare function readAiTokenTotals(raw: unknown): AiTokenTotals;
+/**
+ * The share of prompt tokens served from the cache: reads over everything the
+ * prompt was billed as — sent, read and written.
+ *
+ * Writes sit in the denominator on purpose. A prefix that expires and is
+ * rewritten every other request is the expensive failure, since a write costs
+ * more than a fresh input token; a rate over reads and fresh input alone
+ * reads that month as healthy. `null` when there are no prompt tokens at all,
+ * which is nothing to divide rather than a 0% hit rate.
+ */
+export declare function aiCacheHitRate(tokens: Pick<AiTokenTotals, 'input' | 'cached' | 'cacheWrite'>): number | null;
+/** One kind of request in an org's month. */
+export interface AiKindMonth {
+    /** An `AiUsageKind`: `assist`, a besigner mode, or a job kind. */
+    kind: string;
+    /** Metered model requests; a docs answer or a cache hit is not one. */
+    requests: number;
+    /** What the kind DREW, at billed rates — the credits behind it. */
+    estCostUsd: number;
+    /**
+     * What the kind COST US (AGL-3015). Equal to `estCostUsd` on a kind served
+     * only by models billed at their provider's list, and below it wherever a
+     * marked-up model served. A month written before the split answers the
+     * billed figure here, which over-reads our bill rather than under-reads it.
+     */
+    providerCostUsd: number;
+    tokens: AiTokenTotals;
+}
+/**
+ * The month document's `kinds` map as rows, dearest first.
+ *
+ * Ordered on what each kind DREW, not on what it cost us: the reader asking
+ * "which kind is expensive" is asking about the meter every other figure on
+ * the card is denominated in, and the two orders differ only where a kind's
+ * model mix differs from its neighbour's.
+ */
+export declare function readAiKindMonths(raw: unknown): AiKindMonth[];

package/src/lib/model/ai-tokens.js

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { assistProviderCostUsd, ASSIST_PROVIDER_COST_FIELD } from "@aglyn/aglyn/app-utils/assist-credits";
+/**
+ * TOKENS AS THE ROLLUPS KEEP THEM (AGL-2937): the pure half.
+ *
+ * A provider reports four counts per request, and each is priced at its own
+ * rate: prompt tokens sent uncached, prompt tokens read from the prompt
+ * cache, prompt tokens written to it, and tokens generated. The org month
+ * (per kind), the person's month and the job step keep the same four, so a
+ * figure read off one means what it means on the others, and the cache hit
+ * rate is the same division everywhere it is shown.
+ *
+ * Stored shapes:
+ *
+ *   orgs/{orgId}/assistUsage/{YYYY-MM}
+ *     kinds: { [kind]: { requests, estCostUsd, providerCostUsd,
+ *                        tokens: { input, cached, cacheWrite, output } } }
+ *   orgs/{orgId}/aiUsageByUser/{uid}/months/{YYYY-MM}
+ *     tokens: { input, cached, cacheWrite, output }
+ *
+ * The month document's own top-level `inputTokens`, `outputTokens`,
+ * `cacheReadTokens` and `cacheWriteTokens` stay its totals; `kinds` splits
+ * them by what the request was for.
+ */ /** The month document's per-kind map. */ export const AI_USAGE_MONTH_KINDS_FIELD = 'kinds';
+/** The token map, on a person's month and on each kind of the org's. */ export const AI_USAGE_TOKENS_FIELD = 'tokens';
+const count = (value)=>{
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+};
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+export function emptyAiTokenTotals() {
+    return {
+        input: 0,
+        cached: 0,
+        cacheWrite: 0,
+        output: 0
+    };
+}
+/** A request's usage, in the rollups' names. */ export function aiTokenTotalsFrom(usage) {
+    return {
+        input: count(usage.inputTokens),
+        cached: count(usage.cacheReadTokens),
+        cacheWrite: count(usage.cacheWriteTokens),
+        output: count(usage.outputTokens)
+    };
+}
+export function addAiTokenTotals(a, b) {
+    return {
+        input: a.input + b.input,
+        cached: a.cached + b.cached,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+        output: a.output + b.output
+    };
+}
+/** A stored token map read back, every absent or malformed count as zero. */ export function readAiTokenTotals(raw) {
+    const record = isRecord(raw) ? raw : {};
+    return {
+        input: count(record['input']),
+        cached: count(record['cached']),
+        cacheWrite: count(record['cacheWrite']),
+        output: count(record['output'])
+    };
+}
+/**
+ * The share of prompt tokens served from the cache: reads over everything the
+ * prompt was billed as — sent, read and written.
+ *
+ * Writes sit in the denominator on purpose. A prefix that expires and is
+ * rewritten every other request is the expensive failure, since a write costs
+ * more than a fresh input token; a rate over reads and fresh input alone
+ * reads that month as healthy. `null` when there are no prompt tokens at all,
+ * which is nothing to divide rather than a 0% hit rate.
+ */ export function aiCacheHitRate(tokens) {
+    const prompt = tokens.input + tokens.cached + tokens.cacheWrite;
+    return prompt > 0 ? tokens.cached / prompt : null;
+}
+/**
+ * The month document's `kinds` map as rows, dearest first.
+ *
+ * Ordered on what each kind DREW, not on what it cost us: the reader asking
+ * "which kind is expensive" is asking about the meter every other figure on
+ * the card is denominated in, and the two orders differ only where a kind's
+ * model mix differs from its neighbour's.
+ */ export function readAiKindMonths(raw) {
+    if (!isRecord(raw)) return [];
+    const rows = [];
+    for (const [kind, value] of Object.entries(raw)){
+        var _value_estCostUsd;
+        if (!isRecord(value)) continue;
+        const cost = Number((_value_estCostUsd = value['estCostUsd']) != null ? _value_estCostUsd : 0);
+        const billed = Number.isFinite(cost) && cost > 0 ? cost : 0;
+        rows.push({
+            kind,
+            requests: count(value['requests']),
+            estCostUsd: billed,
+            providerCostUsd: assistProviderCostUsd(billed, value[ASSIST_PROVIDER_COST_FIELD]),
+            tokens: readAiTokenTotals(value[AI_USAGE_TOKENS_FIELD])
+        });
+    }
+    return rows.sort((a, b)=>b.estCostUsd - a.estCostUsd || b.requests - a.requests || a.kind.localeCompare(b.kind));
+}
+
+//# sourceMappingURL=ai-tokens.js.map

package/src/lib/model/ai-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-tokens.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  assistProviderCostUsd,\n  ASSIST_PROVIDER_COST_FIELD,\n} from '@aglyn/aglyn/app-utils/assist-credits'\nimport type { AiUsage } from '../providers/contract'\n\n/**\n * TOKENS AS THE ROLLUPS KEEP THEM (AGL-2937): the pure half.\n *\n * A provider reports four counts per request, and each is priced at its own\n * rate: prompt tokens sent uncached, prompt tokens read from the prompt\n * cache, prompt tokens written to it, and tokens generated. The org month\n * (per kind), the person's month and the job step keep the same four, so a\n * figure read off one means what it means on the others, and the cache hit\n * rate is the same division everywhere it is shown.\n *\n * Stored shapes:\n *\n *   orgs/{orgId}/assistUsage/{YYYY-MM}\n *     kinds: { [kind]: { requests, estCostUsd, providerCostUsd,\n *                        tokens: { input, cached, cacheWrite, output } } }\n *   orgs/{orgId}/aiUsageByUser/{uid}/months/{YYYY-MM}\n *     tokens: { input, cached, cacheWrite, output }\n *\n * The month document's own top-level `inputTokens`, `outputTokens`,\n * `cacheReadTokens` and `cacheWriteTokens` stay its totals; `kinds` splits\n * them by what the request was for.\n */\n\n/** The month document's per-kind map. */\nexport const AI_USAGE_MONTH_KINDS_FIELD = 'kinds'\n\n/** The token map, on a person's month and on each kind of the org's. */\nexport const AI_USAGE_TOKENS_FIELD = 'tokens'\n\nexport interface AiTokenTotals {\n  /** Prompt tokens sent uncached, at the model's input rate. */\n  input: number\n  /** Prompt tokens read from the prompt cache, at its read rate. */\n  cached: number\n  /** Prompt tokens written to the prompt cache, at its write rate. */\n  cacheWrite: number\n  /** Tokens the model generated, thinking included. */\n  output: number\n}\n\nconst count = (value: unknown): number => {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\nexport function emptyAiTokenTotals(): AiTokenTotals {\n  return { input: 0, cached: 0, cacheWrite: 0, output: 0 }\n}\n\n/** A request's usage, in the rollups' names. */\nexport function aiTokenTotalsFrom(usage: AiUsage): AiTokenTotals {\n  return {\n    input: count(usage.inputTokens),\n    cached: count(usage.cacheReadTokens),\n    cacheWrite: count(usage.cacheWriteTokens),\n    output: count(usage.outputTokens),\n  }\n}\n\nexport function addAiTokenTotals(a: AiTokenTotals, b: AiTokenTotals): AiTokenTotals {\n  return {\n    input: a.input + b.input,\n    cached: a.cached + b.cached,\n    cacheWrite: a.cacheWrite + b.cacheWrite,\n    output: a.output + b.output,\n  }\n}\n\n/** A stored token map read back, every absent or malformed count as zero. */\nexport function readAiTokenTotals(raw: unknown): AiTokenTotals {\n  const record = isRecord(raw) ? raw : {}\n  return {\n    input: count(record['input']),\n    cached: count(record['cached']),\n    cacheWrite: count(record['cacheWrite']),\n    output: count(record['output']),\n  }\n}\n\n/**\n * The share of prompt tokens served from the cache: reads over everything the\n * prompt was billed as — sent, read and written.\n *\n * Writes sit in the denominator on purpose. A prefix that expires and is\n * rewritten every other request is the expensive failure, since a write costs\n * more than a fresh input token; a rate over reads and fresh input alone\n * reads that month as healthy. `null` when there are no prompt tokens at all,\n * which is nothing to divide rather than a 0% hit rate.\n */\nexport function aiCacheHitRate(\n  tokens: Pick<AiTokenTotals, 'input' | 'cached' | 'cacheWrite'>,\n): number | null {\n  const prompt = tokens.input + tokens.cached + tokens.cacheWrite\n  return prompt > 0 ? tokens.cached / prompt : null\n}\n\n/** One kind of request in an org's month. */\nexport interface AiKindMonth {\n  /** An `AiUsageKind`: `assist`, a besigner mode, or a job kind. */\n  kind: string\n  /** Metered model requests; a docs answer or a cache hit is not one. */\n  requests: number\n  /** What the kind DREW, at billed rates — the credits behind it. */\n  estCostUsd: number\n  /**\n   * What the kind COST US (AGL-3015). Equal to `estCostUsd` on a kind served\n   * only by models billed at their provider's list, and below it wherever a\n   * marked-up model served. A month written before the split answers the\n   * billed figure here, which over-reads our bill rather than under-reads it.\n   */\n  providerCostUsd: number\n  tokens: AiTokenTotals\n}\n\n/**\n * The month document's `kinds` map as rows, dearest first.\n *\n * Ordered on what each kind DREW, not on what it cost us: the reader asking\n * \"which kind is expensive\" is asking about the meter every other figure on\n * the card is denominated in, and the two orders differ only where a kind's\n * model mix differs from its neighbour's.\n */\nexport function readAiKindMonths(raw: unknown): AiKindMonth[] {\n  if (!isRecord(raw)) return []\n  const rows: AiKindMonth[] = []\n  for (const [kind, value] of Object.entries(raw)) {\n    if (!isRecord(value)) continue\n    const cost = Number(value['estCostUsd'] ?? 0)\n    const billed = Number.isFinite(cost) && cost > 0 ? cost : 0\n    rows.push({\n      kind,\n      requests: count(value['requests']),\n      estCostUsd: billed,\n      providerCostUsd: assistProviderCostUsd(\n        billed,\n        value[ASSIST_PROVIDER_COST_FIELD],\n      ),\n      tokens: readAiTokenTotals(value[AI_USAGE_TOKENS_FIELD]),\n    })\n  }\n  return rows.sort(\n    (a, b) => b.estCostUsd - a.estCostUsd || b.requests - a.requests || a.kind.localeCompare(b.kind),\n  )\n}\n"],"names":["assistProviderCostUsd","ASSIST_PROVIDER_COST_FIELD","AI_USAGE_MONTH_KINDS_FIELD","AI_USAGE_TOKENS_FIELD","count","value","parsed","Number","isFinite","Math","floor","isRecord","Array","isArray","emptyAiTokenTotals","input","cached","cacheWrite","output","aiTokenTotalsFrom","usage","inputTokens","cacheReadTokens","cacheWriteTokens","outputTokens","addAiTokenTotals","a","b","readAiTokenTotals","raw","record","aiCacheHitRate","tokens","prompt","readAiKindMonths","rows","kind","Object","entries","cost","billed","push","requests","estCostUsd","providerCostUsd","sort","localeCompare"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,qBAAqB,EACrBC,0BAA0B,QACrB,wCAAuC;AAG9C;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,uCAAuC,GACvC,OAAO,MAAMC,6BAA6B,QAAO;AAEjD,sEAAsE,GACtE,OAAO,MAAMC,wBAAwB,SAAQ;AAa7C,MAAMC,QAAQ,CAACC;IACb,MAAMC,SAASC,OAAOF,gBAAAA,QAAS;IAC/B,OAAOE,OAAOC,QAAQ,CAACF,WAAWA,SAAS,IAAIG,KAAKC,KAAK,CAACJ,UAAU;AACtE;AAEA,MAAMK,WAAW,CAACN,QAChB,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACO,MAAMC,OAAO,CAACR;AAEhE,OAAO,SAASS;IACd,OAAO;QAAEC,OAAO;QAAGC,QAAQ;QAAGC,YAAY;QAAGC,QAAQ;IAAE;AACzD;AAEA,8CAA8C,GAC9C,OAAO,SAASC,kBAAkBC,KAAc;IAC9C,OAAO;QACLL,OAAOX,MAAMgB,MAAMC,WAAW;QAC9BL,QAAQZ,MAAMgB,MAAME,eAAe;QACnCL,YAAYb,MAAMgB,MAAMG,gBAAgB;QACxCL,QAAQd,MAAMgB,MAAMI,YAAY;IAClC;AACF;AAEA,OAAO,SAASC,iBAAiBC,CAAgB,EAAEC,CAAgB;IACjE,OAAO;QACLZ,OAAOW,EAAEX,KAAK,GAAGY,EAAEZ,KAAK;QACxBC,QAAQU,EAAEV,MAAM,GAAGW,EAAEX,MAAM;QAC3BC,YAAYS,EAAET,UAAU,GAAGU,EAAEV,UAAU;QACvCC,QAAQQ,EAAER,MAAM,GAAGS,EAAET,MAAM;IAC7B;AACF;AAEA,2EAA2E,GAC3E,OAAO,SAASU,kBAAkBC,GAAY;IAC5C,MAAMC,SAASnB,SAASkB,OAAOA,MAAM,CAAC;IACtC,OAAO;QACLd,OAAOX,MAAM0B,MAAM,CAAC,QAAQ;QAC5Bd,QAAQZ,MAAM0B,MAAM,CAAC,SAAS;QAC9Bb,YAAYb,MAAM0B,MAAM,CAAC,aAAa;QACtCZ,QAAQd,MAAM0B,MAAM,CAAC,SAAS;IAChC;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASC,eACdC,MAA8D;IAE9D,MAAMC,SAASD,OAAOjB,KAAK,GAAGiB,OAAOhB,MAAM,GAAGgB,OAAOf,UAAU;IAC/D,OAAOgB,SAAS,IAAID,OAAOhB,MAAM,GAAGiB,SAAS;AAC/C;AAoBA;;;;;;;CAOC,GACD,OAAO,SAASC,iBAAiBL,GAAY;IAC3C,IAAI,CAAClB,SAASkB,MAAM,OAAO,EAAE;IAC7B,MAAMM,OAAsB,EAAE;IAC9B,KAAK,MAAM,CAACC,MAAM/B,MAAM,IAAIgC,OAAOC,OAAO,CAACT,KAAM;YAE3BxB;QADpB,IAAI,CAACM,SAASN,QAAQ;QACtB,MAAMkC,OAAOhC,QAAOF,oBAAAA,KAAK,CAAC,aAAa,YAAnBA,oBAAuB;QAC3C,MAAMmC,SAASjC,OAAOC,QAAQ,CAAC+B,SAASA,OAAO,IAAIA,OAAO;QAC1DJ,KAAKM,IAAI,CAAC;YACRL;YACAM,UAAUtC,MAAMC,KAAK,CAAC,WAAW;YACjCsC,YAAYH;YACZI,iBAAiB5C,sBACfwC,QACAnC,KAAK,CAACJ,2BAA2B;YAEnC+B,QAAQJ,kBAAkBvB,KAAK,CAACF,sBAAsB;QACxD;IACF;IACA,OAAOgC,KAAKU,IAAI,CACd,CAACnB,GAAGC,IAAMA,EAAEgB,UAAU,GAAGjB,EAAEiB,UAAU,IAAIhB,EAAEe,QAAQ,GAAGhB,EAAEgB,QAAQ,IAAIhB,EAAEU,IAAI,CAACU,aAAa,CAACnB,EAAES,IAAI;AAEnG"}

package/src/lib/model/ai-usage-by-user.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AiJobKind } from './ai-jobs.types';
+/**
+ * PER-USER AI USAGE (AGL-2928): the pure half.
+ *
+ * The org rollup at `assistUsage/{month}` says what a workspace spent on AI
+ * and nothing about who spent it. This module is the shape and the arithmetic
+ * of the second rollup — one document per person per month, under the org,
+ * keyed by uid — so an agency or a multi-brand workspace can see which of its
+ * people, on which site, is generating what. No prose, no PII beyond the uid
+ * the document is keyed by.
+ *
+ * The write lives in the plugin's `usage/ai-usage-by-user.ts`, inside the
+ * same batch as the org rollup. Everything here is dependency-free so the
+ * plugin's tables and the doors that serve them read one definition of a
+ * share, a month key and a retention window.
+ */
+/** `orgs/{orgId}/{this}/{uid}/{months}/{YYYY-MM}` — the subcollection names. */
+export declare const AI_USAGE_BY_USER_COLLECTION = "aiUsageByUser";
+export declare const AI_USAGE_BY_USER_MONTHS_COLLECTION = "months";
+/**
+ * How many months a person's usage is kept, counted from the month it
+ * describes. Thirteen: a full year of month-over-month comparison for a
+ * workspace admin, plus the month in progress. A TTL policy on the month
+ * document's `expiresAt` enforces it — see `aiUsageByUserExpiry`.
+ */
+export declare const AI_USAGE_BY_USER_RETENTION_MONTHS = 13;
+/**
+ * What an AI request was FOR, as the per-user rollup buckets it.
+ *
+ * `assist` is a console chat turn; `element`, `blog` and `section` are the
+ * besigner's three assist modes; the rest are generation job kinds, named
+ * exactly as the job document names them so a reader can join the two.
+ */
+export type AiUsageKind = 'assist' | 'element' | 'blog' | 'section' | AiJobKind;
+/** One person's month, zero-filled — the shape every reader hands on. */
+export interface AiUsageByUserMonth {
+    uid: string;
+    month: string;
+    /** Credits drawn, each request rounded up as the meter rounds. */
+    credits: number;
+    /**
+     * The measured provider spend behind `credits`. Server-side only: no
+     * customer surface renders it, and `aiUsageShare` is how it becomes a
+     * figure a customer may see.
+     */
+    estCostUsd: number;
+    requests: number;
+    refusals: number;
+    /** Credits by `AiUsageKind`. */
+    byKind: Record<string, number>;
+    /** Credits by host id, for requests that named a site. */
+    byHost: Record<string, number>;
+}
+/** Whether `value` is a `YYYY-MM` month key. */
+export declare function isAiUsageMonthKey(value: unknown): value is string;
+/**
+ * The month keys a reader may ask for, newest first: the month in progress
+ * and the twelve before it — the retention window, so a picker built from
+ * this list never names a month the TTL has reaped.
+ */
+export declare function aiUsageMonthKeys(now?: Date, count?: number): string[];
+/** Whether `month` is inside the window `aiUsageMonthKeys` describes. */
+export declare function aiUsageMonthWithinRetention(month: string, now?: Date): boolean;
+/**
+ * When a month document expires: the first instant of the month that is
+ * `AI_USAGE_BY_USER_RETENTION_MONTHS` after the one it describes has closed.
+ *
+ * A `Date`, not a number: the TTL policy keys on a Firestore Timestamp and
+ * silently governs nothing when the field is a number. Deterministic per
+ * month, so every increment into the document re-stamps the same value and
+ * the policy never moves under a month that is still being written.
+ */
+export declare function aiUsageByUserExpiry(month: string): Date;
+/**
+ * The kind an assist request was, read off the route it arrived on — for the
+ * meters that carry a route and no kind of their own. The three besigner
+ * modes name themselves in the path; everything else is a chat turn.
+ */
+export declare function aiUsageKindFromRoute(route: string | null | undefined): AiUsageKind;
+/**
+ * One person's share of the workspace's spend for the month, in `[0, 1]`.
+ *
+ * Measured on the dollar figures, never on credits: the org meter rounds the
+ * month's spend up ONCE, while a person's credits round each request up, so
+ * a roster's credits can sum to a little more than the pool they drew from.
+ * The ratio of measured spends has no such drift. Clamped, because a month
+ * document written a moment after the org rollup is still a fraction, not a
+ * percentage over one hundred — and rounded to a basis point, which is finer
+ * than any surface renders and coarser than floating-point noise.
+ */
+export declare function aiUsageShare(userEstCostUsd: number, orgEstCostUsd: number): number;
+/**
+ * A month document as a complete record. Absent and malformed fields read as
+ * zero; a `credits` the writer never set is derived from the spend, so a
+ * document written before the field existed still ranks.
+ */
+export declare function aiUsageByUserMonthFrom(raw: Record<string, unknown> | null | undefined, uid: string, month: string): AiUsageByUserMonth;
+/** The kinds a person drew the most credits on, dearest first. */
+export declare function topAiUsageKinds(byKind: Record<string, number>, limit?: number): Array<{
+    kind: string;
+    credits: number;
+}>;
+/** Two month documents for one person, summed — the roster column's figure. */
+export declare function sumAiUsageCredits(months: readonly AiUsageByUserMonth[]): number;

package/src/lib/model/ai-usage-by-user.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { assistCreditsFromUsd } from "@aglyn/aglyn/app-utils/assist-credits";
+/**
+ * PER-USER AI USAGE (AGL-2928): the pure half.
+ *
+ * The org rollup at `assistUsage/{month}` says what a workspace spent on AI
+ * and nothing about who spent it. This module is the shape and the arithmetic
+ * of the second rollup — one document per person per month, under the org,
+ * keyed by uid — so an agency or a multi-brand workspace can see which of its
+ * people, on which site, is generating what. No prose, no PII beyond the uid
+ * the document is keyed by.
+ *
+ * The write lives in the plugin's `usage/ai-usage-by-user.ts`, inside the
+ * same batch as the org rollup. Everything here is dependency-free so the
+ * plugin's tables and the doors that serve them read one definition of a
+ * share, a month key and a retention window.
+ */ /** `orgs/{orgId}/{this}/{uid}/{months}/{YYYY-MM}` — the subcollection names. */ export const AI_USAGE_BY_USER_COLLECTION = 'aiUsageByUser';
+export const AI_USAGE_BY_USER_MONTHS_COLLECTION = 'months';
+/**
+ * How many months a person's usage is kept, counted from the month it
+ * describes. Thirteen: a full year of month-over-month comparison for a
+ * workspace admin, plus the month in progress. A TTL policy on the month
+ * document's `expiresAt` enforces it — see `aiUsageByUserExpiry`.
+ */ export const AI_USAGE_BY_USER_RETENTION_MONTHS = 13;
+const MONTH_KEY = /^\d{4}-(0[1-9]|1[0-2])$/;
+/** Whether `value` is a `YYYY-MM` month key. */ export function isAiUsageMonthKey(value) {
+    return typeof value === 'string' && MONTH_KEY.test(value);
+}
+/**
+ * The month keys a reader may ask for, newest first: the month in progress
+ * and the twelve before it — the retention window, so a picker built from
+ * this list never names a month the TTL has reaped.
+ */ export function aiUsageMonthKeys(now = new Date(), count = AI_USAGE_BY_USER_RETENTION_MONTHS) {
+    const keys = [];
+    for(let back = 0; back < count; back += 1){
+        keys.push(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - back, 1)).toISOString().slice(0, 7));
+    }
+    return keys;
+}
+/** Whether `month` is inside the window `aiUsageMonthKeys` describes. */ export function aiUsageMonthWithinRetention(month, now = new Date()) {
+    return isAiUsageMonthKey(month) && aiUsageMonthKeys(now).includes(month);
+}
+/**
+ * When a month document expires: the first instant of the month that is
+ * `AI_USAGE_BY_USER_RETENTION_MONTHS` after the one it describes has closed.
+ *
+ * A `Date`, not a number: the TTL policy keys on a Firestore Timestamp and
+ * silently governs nothing when the field is a number. Deterministic per
+ * month, so every increment into the document re-stamps the same value and
+ * the policy never moves under a month that is still being written.
+ */ export function aiUsageByUserExpiry(month) {
+    if (!isAiUsageMonthKey(month)) {
+        throw new Error(`not a month key: ${month}`);
+    }
+    const [year, monthOfYear] = month.split('-').map(Number);
+    return new Date(Date.UTC(year, monthOfYear + AI_USAGE_BY_USER_RETENTION_MONTHS, 1));
+}
+/**
+ * The kind an assist request was, read off the route it arrived on — for the
+ * meters that carry a route and no kind of their own. The three besigner
+ * modes name themselves in the path; everything else is a chat turn.
+ */ export function aiUsageKindFromRoute(route) {
+    var _String_split_filter_pop;
+    const tail = (_String_split_filter_pop = String(route != null ? route : '').split('/').filter(Boolean).pop()) != null ? _String_split_filter_pop : '';
+    if (tail === 'element' || tail === 'blog' || tail === 'section') return tail;
+    return 'assist';
+}
+/**
+ * One person's share of the workspace's spend for the month, in `[0, 1]`.
+ *
+ * Measured on the dollar figures, never on credits: the org meter rounds the
+ * month's spend up ONCE, while a person's credits round each request up, so
+ * a roster's credits can sum to a little more than the pool they drew from.
+ * The ratio of measured spends has no such drift. Clamped, because a month
+ * document written a moment after the org rollup is still a fraction, not a
+ * percentage over one hundred — and rounded to a basis point, which is finer
+ * than any surface renders and coarser than floating-point noise.
+ */ export function aiUsageShare(userEstCostUsd, orgEstCostUsd) {
+    const user = Number(userEstCostUsd);
+    const org = Number(orgEstCostUsd);
+    if (!Number.isFinite(user) || user <= 0) return 0;
+    if (!Number.isFinite(org) || org <= 0) return 0;
+    return Math.min(1, Math.round(user / org * 10000) / 10000);
+}
+const finite = (value)=>{
+    const parsed = Number(value != null ? value : 0);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+const creditMap = (raw)=>{
+    const out = {};
+    for (const [key, value] of Object.entries(raw != null ? raw : {})){
+        const credits = Math.floor(finite(value));
+        if (credits > 0) out[key] = credits;
+    }
+    return out;
+};
+/**
+ * A month document as a complete record. Absent and malformed fields read as
+ * zero; a `credits` the writer never set is derived from the spend, so a
+ * document written before the field existed still ranks.
+ */ export function aiUsageByUserMonthFrom(raw, uid, month) {
+    const estCostUsd = finite(raw == null ? void 0 : raw['estCostUsd']);
+    const stored = Math.floor(finite(raw == null ? void 0 : raw['credits']));
+    return {
+        uid,
+        month,
+        credits: stored > 0 ? stored : assistCreditsFromUsd(estCostUsd),
+        estCostUsd,
+        requests: Math.floor(finite(raw == null ? void 0 : raw['requests'])),
+        refusals: Math.floor(finite(raw == null ? void 0 : raw['refusals'])),
+        byKind: creditMap(raw == null ? void 0 : raw['byKind']),
+        byHost: creditMap(raw == null ? void 0 : raw['byHost'])
+    };
+}
+/** The kinds a person drew the most credits on, dearest first. */ export function topAiUsageKinds(byKind, limit = 3) {
+    return Object.entries(byKind).map(([kind, credits])=>({
+            kind,
+            credits
+        })).sort((a, b)=>b.credits - a.credits || a.kind.localeCompare(b.kind)).slice(0, limit);
+}
+/** Two month documents for one person, summed — the roster column's figure. */ export function sumAiUsageCredits(months) {
+    return months.reduce((sum, entry)=>sum + entry.credits, 0);
+}
+
+//# sourceMappingURL=ai-usage-by-user.js.map

package/src/lib/model/ai-usage-by-user.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-usage-by-user.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AiJobKind } from './ai-jobs.types'\nimport { assistCreditsFromUsd } from '@aglyn/aglyn/app-utils/assist-credits'\n\n/**\n * PER-USER AI USAGE (AGL-2928): the pure half.\n *\n * The org rollup at `assistUsage/{month}` says what a workspace spent on AI\n * and nothing about who spent it. This module is the shape and the arithmetic\n * of the second rollup — one document per person per month, under the org,\n * keyed by uid — so an agency or a multi-brand workspace can see which of its\n * people, on which site, is generating what. No prose, no PII beyond the uid\n * the document is keyed by.\n *\n * The write lives in the plugin's `usage/ai-usage-by-user.ts`, inside the\n * same batch as the org rollup. Everything here is dependency-free so the\n * plugin's tables and the doors that serve them read one definition of a\n * share, a month key and a retention window.\n */\n\n/** `orgs/{orgId}/{this}/{uid}/{months}/{YYYY-MM}` — the subcollection names. */\nexport const AI_USAGE_BY_USER_COLLECTION = 'aiUsageByUser'\nexport const AI_USAGE_BY_USER_MONTHS_COLLECTION = 'months'\n\n/**\n * How many months a person's usage is kept, counted from the month it\n * describes. Thirteen: a full year of month-over-month comparison for a\n * workspace admin, plus the month in progress. A TTL policy on the month\n * document's `expiresAt` enforces it — see `aiUsageByUserExpiry`.\n */\nexport const AI_USAGE_BY_USER_RETENTION_MONTHS = 13\n\n/**\n * What an AI request was FOR, as the per-user rollup buckets it.\n *\n * `assist` is a console chat turn; `element`, `blog` and `section` are the\n * besigner's three assist modes; the rest are generation job kinds, named\n * exactly as the job document names them so a reader can join the two.\n */\nexport type AiUsageKind = 'assist' | 'element' | 'blog' | 'section' | AiJobKind\n\n/** One person's month, zero-filled — the shape every reader hands on. */\nexport interface AiUsageByUserMonth {\n  uid: string\n  month: string\n  /** Credits drawn, each request rounded up as the meter rounds. */\n  credits: number\n  /**\n   * The measured provider spend behind `credits`. Server-side only: no\n   * customer surface renders it, and `aiUsageShare` is how it becomes a\n   * figure a customer may see.\n   */\n  estCostUsd: number\n  requests: number\n  refusals: number\n  /** Credits by `AiUsageKind`. */\n  byKind: Record<string, number>\n  /** Credits by host id, for requests that named a site. */\n  byHost: Record<string, number>\n}\n\nconst MONTH_KEY = /^\\d{4}-(0[1-9]|1[0-2])$/\n\n/** Whether `value` is a `YYYY-MM` month key. */\nexport function isAiUsageMonthKey(value: unknown): value is string {\n  return typeof value === 'string' && MONTH_KEY.test(value)\n}\n\n/**\n * The month keys a reader may ask for, newest first: the month in progress\n * and the twelve before it — the retention window, so a picker built from\n * this list never names a month the TTL has reaped.\n */\nexport function aiUsageMonthKeys(\n  now: Date = new Date(),\n  count: number = AI_USAGE_BY_USER_RETENTION_MONTHS,\n): string[] {\n  const keys: string[] = []\n  for (let back = 0; back < count; back += 1) {\n    keys.push(\n      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - back, 1))\n        .toISOString()\n        .slice(0, 7),\n    )\n  }\n  return keys\n}\n\n/** Whether `month` is inside the window `aiUsageMonthKeys` describes. */\nexport function aiUsageMonthWithinRetention(\n  month: string,\n  now: Date = new Date(),\n): boolean {\n  return isAiUsageMonthKey(month) && aiUsageMonthKeys(now).includes(month)\n}\n\n/**\n * When a month document expires: the first instant of the month that is\n * `AI_USAGE_BY_USER_RETENTION_MONTHS` after the one it describes has closed.\n *\n * A `Date`, not a number: the TTL policy keys on a Firestore Timestamp and\n * silently governs nothing when the field is a number. Deterministic per\n * month, so every increment into the document re-stamps the same value and\n * the policy never moves under a month that is still being written.\n */\nexport function aiUsageByUserExpiry(month: string): Date {\n  if (!isAiUsageMonthKey(month)) {\n    throw new Error(`not a month key: ${month}`)\n  }\n  const [year, monthOfYear] = month.split('-').map(Number)\n  return new Date(\n    Date.UTC(year, monthOfYear + AI_USAGE_BY_USER_RETENTION_MONTHS, 1),\n  )\n}\n\n/**\n * The kind an assist request was, read off the route it arrived on — for the\n * meters that carry a route and no kind of their own. The three besigner\n * modes name themselves in the path; everything else is a chat turn.\n */\nexport function aiUsageKindFromRoute(route: string | null | undefined): AiUsageKind {\n  const tail = String(route ?? '').split('/').filter(Boolean).pop() ?? ''\n  if (tail === 'element' || tail === 'blog' || tail === 'section') return tail\n  return 'assist'\n}\n\n/**\n * One person's share of the workspace's spend for the month, in `[0, 1]`.\n *\n * Measured on the dollar figures, never on credits: the org meter rounds the\n * month's spend up ONCE, while a person's credits round each request up, so\n * a roster's credits can sum to a little more than the pool they drew from.\n * The ratio of measured spends has no such drift. Clamped, because a month\n * document written a moment after the org rollup is still a fraction, not a\n * percentage over one hundred — and rounded to a basis point, which is finer\n * than any surface renders and coarser than floating-point noise.\n */\nexport function aiUsageShare(\n  userEstCostUsd: number,\n  orgEstCostUsd: number,\n): number {\n  const user = Number(userEstCostUsd)\n  const org = Number(orgEstCostUsd)\n  if (!Number.isFinite(user) || user <= 0) return 0\n  if (!Number.isFinite(org) || org <= 0) return 0\n  return Math.min(1, Math.round((user / org) * 10_000) / 10_000)\n}\n\nconst finite = (value: unknown): number => {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\nconst creditMap = (raw: unknown): Record<string, number> => {\n  const out: Record<string, number> = {}\n  for (const [key, value] of Object.entries(\n    (raw ?? {}) as Record<string, unknown>,\n  )) {\n    const credits = Math.floor(finite(value))\n    if (credits > 0) out[key] = credits\n  }\n  return out\n}\n\n/**\n * A month document as a complete record. Absent and malformed fields read as\n * zero; a `credits` the writer never set is derived from the spend, so a\n * document written before the field existed still ranks.\n */\nexport function aiUsageByUserMonthFrom(\n  raw: Record<string, unknown> | null | undefined,\n  uid: string,\n  month: string,\n): AiUsageByUserMonth {\n  const estCostUsd = finite(raw?.['estCostUsd'])\n  const stored = Math.floor(finite(raw?.['credits']))\n  return {\n    uid,\n    month,\n    credits: stored > 0 ? stored : assistCreditsFromUsd(estCostUsd),\n    estCostUsd,\n    requests: Math.floor(finite(raw?.['requests'])),\n    refusals: Math.floor(finite(raw?.['refusals'])),\n    byKind: creditMap(raw?.['byKind']),\n    byHost: creditMap(raw?.['byHost']),\n  }\n}\n\n/** The kinds a person drew the most credits on, dearest first. */\nexport function topAiUsageKinds(\n  byKind: Record<string, number>,\n  limit = 3,\n): Array<{ kind: string; credits: number }> {\n  return Object.entries(byKind)\n    .map(([kind, credits]) => ({ kind, credits }))\n    .sort((a, b) => b.credits - a.credits || a.kind.localeCompare(b.kind))\n    .slice(0, limit)\n}\n\n/** Two month documents for one person, summed — the roster column's figure. */\nexport function sumAiUsageCredits(months: readonly AiUsageByUserMonth[]): number {\n  return months.reduce((sum, entry) => sum + entry.credits, 0)\n}\n"],"names":["assistCreditsFromUsd","AI_USAGE_BY_USER_COLLECTION","AI_USAGE_BY_USER_MONTHS_COLLECTION","AI_USAGE_BY_USER_RETENTION_MONTHS","MONTH_KEY","isAiUsageMonthKey","value","test","aiUsageMonthKeys","now","Date","count","keys","back","push","UTC","getUTCFullYear","getUTCMonth","toISOString","slice","aiUsageMonthWithinRetention","month","includes","aiUsageByUserExpiry","Error","year","monthOfYear","split","map","Number","aiUsageKindFromRoute","route","String","tail","filter","Boolean","pop","aiUsageShare","userEstCostUsd","orgEstCostUsd","user","org","isFinite","Math","min","round","finite","parsed","creditMap","raw","out","key","Object","entries","credits","floor","aiUsageByUserMonthFrom","uid","estCostUsd","stored","requests","refusals","byKind","byHost","topAiUsageKinds","limit","kind","sort","a","b","localeCompare","sumAiUsageCredits","months","reduce","sum","entry"],"mappings":"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"}

package/src/lib/model/ai-workflow-job.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type HostEventType } from '@aglyn/aglyn/app-utils/workflows';
+import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
+/**
+ * A `workflow` job (AGL-2919): an automation drafted from a description, or an
+ * existing automation explained — what it does, or why one of its runs failed.
+ *
+ * One kind, three modes, because the three share everything a job carries:
+ * the site, the gates, the meter and the automation vocabulary. `inputs.mode`
+ * picks the mode, and a job created without one drafts.
+ *
+ *  - `draft` writes a new automation to the site's Actions through the
+ *    workflows plugin's draft writer, OFF, built only from the triggers and
+ *    steps below that this workspace can run. What the description names that
+ *    the site does not have is left as a placeholder, never guessed.
+ *  - `explain` reads a saved automation — an action or a workflow — and
+ *    answers in plain words what it does.
+ *  - `diagnose` reads a saved automation and one of its FAILED runs, as the
+ *    run history recorded it, and answers why it failed and what to change.
+ *
+ * Nothing in any mode switches an automation on, runs one, or changes one.
+ */
+export declare const AI_WORKFLOW_JOB_MODES: readonly ["draft", "explain", "diagnose"];
+export type AiWorkflowJobMode = (typeof AI_WORKFLOW_JOB_MODES)[number];
+/** What an explained automation is: an action, or a workflow of function calls. */
+export declare const AI_WORKFLOW_TARGET_TYPES: readonly ["action", "workflow"];
+export type AiWorkflowTargetType = (typeof AI_WORKFLOW_TARGET_TYPES)[number];
+export type AiWorkflowJobInputs = {
+    mode: 'draft';
+} | {
+    mode: 'explain';
+    targetType: AiWorkflowTargetType;
+    targetId: string;
+} | {
+    mode: 'diagnose';
+    targetType: AiWorkflowTargetType;
+    targetId: string;
+    runId: string;
+};
+/** A job's inputs read into its mode, or the sentence that says what is wrong with them. */
+export declare function parseAiWorkflowJobInputs(inputs: Readonly<Record<string, unknown>> | null | undefined): AiWorkflowJobInputs | string;
+/** A part of the platform some triggers and steps need beyond the actions builder itself. */
+export type AiAutomationNeed = 'crm' | 'webhooks' | 'bookings';
+export type AiAutomationCapabilities = Readonly<Record<AiAutomationNeed, boolean>>;
+/** Each need as a sentence names it. */
+export declare const AI_AUTOMATION_NEED_LABELS: Readonly<Record<AiAutomationNeed, string>>;
+/**
+ * What this workspace can run, from the entitlements the executor itself
+ * reads before it runs a step: `crm` for the CRM steps, `webhooks` for a
+ * webhook post, and `bookings` for the booking trigger's door.
+ */
+export declare function aiAutomationCapabilities(org: Partial<AglynOrgBilling> | Readonly<Record<string, unknown>> | null | undefined): AiAutomationCapabilities;
+/**
+ * The triggers a drafted automation may start on: every host event, which is
+ * every event a server door emits. The on-page events (a click, a scroll) are
+ * left out: they watch one element of one page, which a description cannot
+ * name, and they belong to the page's own interactions.
+ */
+export declare const AI_AUTOMATION_TRIGGERS: readonly HostEventType[];
+/** The triggers only a door of a part of the platform emits. */
+export declare const AI_AUTOMATION_TRIGGER_NEEDS: Readonly<Partial<Record<HostEventType, AiAutomationNeed>>>;
+/**
+ * The steps a drafted automation may take: the server steps and the flow
+ * steps, which act on the person an event names. The on-page steps — show an
+ * element, open a menu, run a script — are left out for the reason the
+ * on-page triggers are: they need a selector on a page a description cannot
+ * name.
+ */
+export declare const AI_AUTOMATION_STEP_TYPES: readonly ["sendEmail", "notifyAdmins", "enrollList", "assignCampaign", "runWorkflow", "datasetAppend", "updateDataset", "webhookPost", "siteAlert", "wait", "waitForEvent", "exitFlow", "setContactStage", "addContactTag", "assignContactOwner", "createCrmTask", "logCrmActivity"];
+export type AiAutomationStepType = (typeof AI_AUTOMATION_STEP_TYPES)[number];
+/** The steps the executor refuses without a part of the platform. */
+export declare const AI_AUTOMATION_STEP_NEEDS: Readonly<Partial<Record<AiAutomationStepType, AiAutomationNeed>>>;
+/** The trigger's name as the Actions editor labels it. */
+export declare function aiAutomationTriggerLabel(event: string): string;
+/**
+ * Why a description was answered with no automation. Each is a fixed reason
+ * with a fixed sentence, so what a person reads is never the model's own
+ * account of itself.
+ */
+export declare const AI_AUTOMATION_UNSUPPORTED: readonly ["not-an-automation", "no-trigger", "no-step", "needs-crm", "needs-webhooks", "needs-bookings"];
+export type AiAutomationUnsupported = (typeof AI_AUTOMATION_UNSUPPORTED)[number];
+/** The need an unsupported reason names, for the reasons that name one. */
+export declare const AI_AUTOMATION_UNSUPPORTED_NEED: Readonly<Partial<Record<AiAutomationUnsupported, AiAutomationNeed>>>;
+export declare const AI_AUTOMATION_UNSUPPORTED_COPY: Readonly<Record<AiAutomationUnsupported, string>>;
+/** The id the workflows plugin is registered under. */
+export declare const AI_WORKFLOWS_PLUGIN_ID = "workflows";
+/** The resource the workflows plugin writes a drafted automation under. */
+export declare const AI_AUTOMATION_RESOURCE = "automation";
+export declare const AI_WORKFLOW_NO_SITE_COPY = "This automation job names a site this workspace does not have.";
+export declare const AI_WORKFLOW_UNAVAILABLE_COPY = "Automations are not available on this site.";
+export declare const AI_WORKFLOW_GONE_COPY = "That automation no longer exists.";
+export declare const AI_WORKFLOW_RUN_GONE_COPY = "That run is no longer in the automation\u2019s history.";
+export declare const AI_WORKFLOW_RUN_NOT_FAILED_COPY = "That run did not fail, so there is nothing to explain.";
+export declare const AI_WORKFLOW_NO_DRAFT_COPY = "The AI could not draft an automation from this description. Try describing what happens, and what should happen then.";
+export declare const AI_WORKFLOW_NO_EXPLANATION_COPY = "The AI could not explain this automation. Try again.";
+export declare const AI_WORKFLOW_SAVE_FAILURE_COPY = "The automation was drafted but could not be saved. Try the job again.";