@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,269 @@
+/**
+ * @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 { ASSIST_HARD_CAP_CONTROL_LOCATION } from "@aglyn/aglyn/app-utils/assist-credits";
+import { ORG_PERMISSIONS } from "@aglyn/aglyn/app-utils/org-permissions";
+/**
+ * AI ALLOTMENTS (AGL-2942): the pure half.
+ *
+ * The workspace's AI pool is one band. An allotment is a manager's decision
+ * about how much of that band one SUBJECT may draw in a calendar month (UTC),
+ * so one client site, one contractor or one teammate cannot spend what the
+ * others were counting on:
+ *
+ *   orgs/{orgId}/aiAllotments/{subject}
+ *     { subject, scope, uid, hostId, credits, mode, models, setBy,
+ *       updatedAt, alerted }
+ *
+ * where `subject` is one of
+ *
+ *   member:{uid}           a team member, across every site
+ *   collab:{hostId}:{uid}  a site collaborator, on that site
+ *   host:{hostId}          a whole site, across everyone who works on it
+ *   org                    the org-wide model restriction (no credits)
+ *
+ * ## An allotment never grants
+ *
+ * The org band stays the outer wall: the reservation decides the workspace's
+ * own ceilings first and consults an allotment only once they admitted the
+ * request. So an allotment larger than the band is not an error and not a
+ * grant — it is a line the workspace reaches after the band.
+ *
+ * ## Hard and soft
+ *
+ * A HARD allotment refuses the request that finds the subject at or past it.
+ * A SOFT one admits it and tells the subject and the workspace's billing
+ * contacts at 80% and again at 100%. Both are measured against what the
+ * subject already drew this month, before the request — the same shape the
+ * band is measured in, so a request that starts under the line may finish
+ * past it, and the next one is the one refused.
+ *
+ * Everything here is dependency-light so the gate, the routes and the console
+ * cards read one definition of a subject, a standing and a refusal sentence.
+ */ /** `orgs/{orgId}/{this}/{subject}`. */ export const AI_ALLOTMENTS_COLLECTION = 'aiAllotments';
+/** The subject id of the org-wide model restriction. */ export const AI_ALLOTMENT_ORG_SUBJECT = 'org';
+/** The share of an allotment at which the strip warns and a soft one alerts. */ export const AI_ALLOTMENT_WARN_SHARE = 0.8;
+/**
+ * The largest monthly allotment a write may carry. A bound on a typing
+ * mistake, not a product limit: a billion credits is a million dollars of
+ * provider spend, far past any band the platform sells.
+ */ export const AI_ALLOTMENT_MAX_CREDITS = 1000000000;
+/** The most catalog ids one allowlist may name. */ export const AI_ALLOTMENT_MAX_MODELS = 20;
+const ID_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+/** The document id for a subject. Throws on a segment that is not an id. */ export function aiAllotmentSubjectId(input) {
+    const segment = (value)=>{
+        if (!ID_SEGMENT.test(value)) throw new Error(`not an id segment: ${value}`);
+        return value;
+    };
+    switch(input.scope){
+        case 'member':
+            return `member:${segment(input.uid)}`;
+        case 'collab':
+            return `collab:${segment(input.hostId)}:${segment(input.uid)}`;
+        case 'host':
+            return `host:${segment(input.hostId)}`;
+        default:
+            return AI_ALLOTMENT_ORG_SUBJECT;
+    }
+}
+/** A subject id read back, or `null` for anything that is not one. */ export function parseAiAllotmentSubject(value) {
+    if (typeof value !== 'string') return null;
+    if (value === AI_ALLOTMENT_ORG_SUBJECT) {
+        return {
+            id: value,
+            scope: 'org',
+            uid: null,
+            hostId: null
+        };
+    }
+    const parts = value.split(':');
+    if (parts.some((part)=>!ID_SEGMENT.test(part))) return null;
+    if (parts.length === 2 && parts[0] === 'member') {
+        return {
+            id: value,
+            scope: 'member',
+            uid: parts[1],
+            hostId: null
+        };
+    }
+    if (parts.length === 2 && parts[0] === 'host') {
+        return {
+            id: value,
+            scope: 'host',
+            uid: null,
+            hostId: parts[1]
+        };
+    }
+    if (parts.length === 3 && parts[0] === 'collab') {
+        return {
+            id: value,
+            scope: 'collab',
+            uid: parts[2],
+            hostId: parts[1]
+        };
+    }
+    return null;
+}
+/** A finite positive whole number of credits, else `null`. */ export function aiAllotmentCredits(value) {
+    const parsed = typeof value === 'number' ? value : Number.NaN;
+    if (!Number.isFinite(parsed) || parsed <= 0) return null;
+    return Math.min(AI_ALLOTMENT_MAX_CREDITS, Math.floor(parsed));
+}
+/** An allowlist read back: unique strings, bounded; empty reads as none. */ export function aiAllotmentModels(value) {
+    if (!Array.isArray(value)) return null;
+    const models = [
+        ...new Set(value.filter((entry)=>typeof entry === 'string').map((entry)=>entry.trim()).filter(Boolean))
+    ].slice(0, AI_ALLOTMENT_MAX_MODELS);
+    return models.length ? models : null;
+}
+/**
+ * A stored allotment as a complete record, or `null` when the id is not a
+ * subject. The scope, uid and site are read off the ID, never off the
+ * fields: the id is what the gate addresses, so it is the only claim about
+ * who the document is for that can be trusted.
+ *
+ * `mode` defaults to `hard`: a document whose mode was lost is a cap, which
+ * is the reading that cannot spend more than a manager set.
+ */ export function aiAllotmentFrom(raw, id) {
+    const subject = parseAiAllotmentSubject(id);
+    if (!subject || !raw) return null;
+    const alertedRaw = raw['alerted'];
+    const threshold = Number(alertedRaw == null ? void 0 : alertedRaw.threshold);
+    return {
+        subject: subject.id,
+        scope: subject.scope,
+        uid: subject.uid,
+        hostId: subject.hostId,
+        credits: subject.scope === 'org' ? null : aiAllotmentCredits(raw['credits']),
+        mode: raw['mode'] === 'soft' ? 'soft' : 'hard',
+        models: aiAllotmentModels(raw['models']),
+        setBy: typeof raw['setBy'] === 'string' ? raw['setBy'] : null,
+        alerted: typeof (alertedRaw == null ? void 0 : alertedRaw.month) === 'string' && (threshold === 80 || threshold === 100) ? {
+            month: alertedRaw.month,
+            threshold
+        } : null
+    };
+}
+/** `reached` at or past the allotment, `warn` from 80% of it. */ export function aiAllotmentState(used, credits) {
+    if (!(credits > 0)) return 'ok';
+    if (used >= credits) return 'reached';
+    if (used >= credits * AI_ALLOTMENT_WARN_SHARE) return 'warn';
+    return 'ok';
+}
+/** The threshold a standing sits at, for the alert pipeline. */ export function aiAllotmentThreshold(used, credits) {
+    const state = aiAllotmentState(used, credits);
+    return state === 'reached' ? 100 : state === 'warn' ? 80 : null;
+}
+/**
+ * Whether a standing admits a request.
+ *
+ * A soft allotment always does. A hard one admits while the subject is under
+ * it — and, for a caller that knows what the request will cost before it
+ * starts (a job's estimate), while the estimate still fits: a 100-credit job
+ * at 0 of 100 is admitted, one at 1 of 100 is not.
+ */ export function aiAllotmentAdmits(standing, estimateCredits = 0) {
+    if (standing.mode === 'soft') return true;
+    const estimate = Number.isFinite(estimateCredits) && estimateCredits > 0 ? estimateCredits : 0;
+    return estimate > 0 ? standing.used + estimate <= standing.credits : standing.used < standing.credits;
+}
+/**
+ * Which subject a refusal names when more than one allotment is spent: the
+ * narrowest first — the person on this site, then the person, then the site.
+ */ const SCOPE_ORDER = [
+    'collab',
+    'member',
+    'host'
+];
+const scopeRank = (scope)=>SCOPE_ORDER.indexOf(scope);
+/** The verdict over every allotment that applies to one request. */ export function aiAllotmentVerdict(standings, estimateCredits = 0) {
+    var _ordered_find;
+    const ordered = [
+        ...standings
+    ].sort((a, b)=>scopeRank(a.scope) - scopeRank(b.scope));
+    const refusal = (_ordered_find = ordered.find((standing)=>!aiAllotmentAdmits(standing, estimateCredits))) != null ? _ordered_find : null;
+    let binding = null;
+    for (const standing of ordered){
+        if (!binding || standing.credits - standing.used < binding.credits - binding.used) {
+            binding = standing;
+        }
+    }
+    const alerts = ordered.flatMap((standing)=>{
+        if (standing.mode !== 'soft') return [];
+        const threshold = aiAllotmentThreshold(standing.used, standing.credits);
+        return threshold ? [
+            {
+                standing,
+                threshold
+            }
+        ] : [];
+    });
+    return {
+        refusal,
+        binding,
+        alerts
+    };
+}
+/**
+ * The allowlists that apply to a request, intersected — `null` when none of
+ * the allotments names one. An empty result is a real answer: two lists that
+ * share no model leave nothing to pick, and the model choice falls back to
+ * the routing table rather than turning AI off for a mistake in a list.
+ */ export function aiAllotmentModelsAllowed(allotments) {
+    const lists = allotments.map((allotment)=>allotment == null ? void 0 : allotment.models).filter((models)=>Array.isArray(models) && models.length > 0);
+    if (!lists.length) return null;
+    return lists.reduce((kept, list)=>kept.filter((id)=>list.includes(id)));
+}
+/** The catalog label for `billing.manage`, the word a sentence names it by. */ export function billingManageLabel() {
+    var _ref;
+    var _ORG_PERMISSIONS_find;
+    return (_ref = (_ORG_PERMISSIONS_find = ORG_PERMISSIONS.find((definition)=>definition.key === 'billing.manage')) == null ? void 0 : _ORG_PERMISSIONS_find.label) != null ? _ref : 'Manage billing';
+}
+/**
+ * The sentence a refused request is told, naming who can raise the
+ * allotment and where. No figures: the strip beside it carries those, and a
+ * refusal that quoted a count would be stale the moment someone raised it.
+ */ export function aiAllotmentRefusalText(scope) {
+    const managers = `an organization admin with the "${billingManageLabel()}" permission`;
+    switch(scope){
+        case 'collab':
+            return 'You have used your AI allotment on this site for this month. ' + `The site's admin, or ${managers}, can raise it on the site's Users card.`;
+        case 'host':
+            return 'This site has used its AI allotment for this month. ' + `Ask ${managers} to raise it under ${ASSIST_HARD_CAP_CONTROL_LOCATION}.`;
+        default:
+            return 'You have used your AI allotment for this month. ' + `Ask ${managers} to raise it under ${ASSIST_HARD_CAP_CONTROL_LOCATION}.`;
+    }
+}
+/**
+ * The words a soft allotment's alert carries, for BOTH channels — the
+ * console notification and the email — so the two cannot say different
+ * things about one crossing. `name` is the member's name or the site's.
+ */ export function aiAllotmentAlertCopy(input) {
+    const who = input.scope === 'host' ? `The ${input.name} site` : input.name;
+    const whose = input.scope === 'host' ? 'its' : 'their';
+    const where = input.scope === 'collab' ? ' on its site' : '';
+    const figures = `${input.used.toLocaleString('en-US')} of ` + `${input.credits.toLocaleString('en-US')} credits used this month.`;
+    if (input.threshold >= 100) {
+        return {
+            title: `${who} has used ${whose} whole AI allotment${where}`,
+            body: `${figures} The allotment is soft, so requests keep working and ` + 'draw on the workspace’s pool. Raise it or make it hard under ' + `${ASSIST_HARD_CAP_CONTROL_LOCATION}.`
+        };
+    }
+    return {
+        title: `${who} is past ${Math.round(AI_ALLOTMENT_WARN_SHARE * 100)}% of ${whose} AI allotment${where}`,
+        body: `${figures} The allotment is soft, so nothing stops at the line.`
+    };
+}
+
+//# sourceMappingURL=ai-allotments.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-allotments.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  ASSIST_HARD_CAP_CONTROL_LOCATION,\n  type AssistRefusedBy,\n} from '@aglyn/aglyn/app-utils/assist-credits'\nimport { ORG_PERMISSIONS } from '@aglyn/aglyn/app-utils/org-permissions'\n\n/**\n * AI ALLOTMENTS (AGL-2942): the pure half.\n *\n * The workspace's AI pool is one band. An allotment is a manager's decision\n * about how much of that band one SUBJECT may draw in a calendar month (UTC),\n * so one client site, one contractor or one teammate cannot spend what the\n * others were counting on:\n *\n *   orgs/{orgId}/aiAllotments/{subject}\n *     { subject, scope, uid, hostId, credits, mode, models, setBy,\n *       updatedAt, alerted }\n *\n * where `subject` is one of\n *\n *   member:{uid}           a team member, across every site\n *   collab:{hostId}:{uid}  a site collaborator, on that site\n *   host:{hostId}          a whole site, across everyone who works on it\n *   org                    the org-wide model restriction (no credits)\n *\n * ## An allotment never grants\n *\n * The org band stays the outer wall: the reservation decides the workspace's\n * own ceilings first and consults an allotment only once they admitted the\n * request. So an allotment larger than the band is not an error and not a\n * grant — it is a line the workspace reaches after the band.\n *\n * ## Hard and soft\n *\n * A HARD allotment refuses the request that finds the subject at or past it.\n * A SOFT one admits it and tells the subject and the workspace's billing\n * contacts at 80% and again at 100%. Both are measured against what the\n * subject already drew this month, before the request — the same shape the\n * band is measured in, so a request that starts under the line may finish\n * past it, and the next one is the one refused.\n *\n * Everything here is dependency-light so the gate, the routes and the console\n * cards read one definition of a subject, a standing and a refusal sentence.\n */\n\n/** `orgs/{orgId}/{this}/{subject}`. */\nexport const AI_ALLOTMENTS_COLLECTION = 'aiAllotments'\n\n/** The subject id of the org-wide model restriction. */\nexport const AI_ALLOTMENT_ORG_SUBJECT = 'org'\n\nexport type AiAllotmentMode = 'hard' | 'soft'\n\nexport type AiAllotmentScope = 'member' | 'collab' | 'host' | 'org'\n\n/** The scopes an allotment of CREDITS can have; `org` carries models only. */\nexport type AiCreditAllotmentScope = Exclude<AiAllotmentScope, 'org'>\n\n/**\n * Why a reservation refused: the meter's own ceilings, and an allotment.\n *\n * Widened here rather than in core's `AssistRefusedBy`, because an allotment\n * is the plugin's rung: core names the ceilings core's billing sells.\n */\nexport type AiRefusedBy = AssistRefusedBy | 'allotment'\n\n/** The two thresholds a soft allotment announces. */\nexport type AiAllotmentThreshold = 80 | 100\n\n/** The share of an allotment at which the strip warns and a soft one alerts. */\nexport const AI_ALLOTMENT_WARN_SHARE = 0.8\n\n/**\n * The largest monthly allotment a write may carry. A bound on a typing\n * mistake, not a product limit: a billion credits is a million dollars of\n * provider spend, far past any band the platform sells.\n */\nexport const AI_ALLOTMENT_MAX_CREDITS = 1_000_000_000\n\n/** The most catalog ids one allowlist may name. */\nexport const AI_ALLOTMENT_MAX_MODELS = 20\n\nconst ID_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/\n\nexport interface AiAllotmentSubject {\n  id: string\n  scope: AiAllotmentScope\n  uid: string | null\n  hostId: string | null\n}\n\nexport type AiAllotmentSubjectInput =\n  | { scope: 'member'; uid: string }\n  | { scope: 'collab'; hostId: string; uid: string }\n  | { scope: 'host'; hostId: string }\n  | { scope: 'org' }\n\n/** The document id for a subject. Throws on a segment that is not an id. */\nexport function aiAllotmentSubjectId(input: AiAllotmentSubjectInput): string {\n  const segment = (value: string): string => {\n    if (!ID_SEGMENT.test(value)) throw new Error(`not an id segment: ${value}`)\n    return value\n  }\n  switch (input.scope) {\n    case 'member':\n      return `member:${segment(input.uid)}`\n    case 'collab':\n      return `collab:${segment(input.hostId)}:${segment(input.uid)}`\n    case 'host':\n      return `host:${segment(input.hostId)}`\n    default:\n      return AI_ALLOTMENT_ORG_SUBJECT\n  }\n}\n\n/** A subject id read back, or `null` for anything that is not one. */\nexport function parseAiAllotmentSubject(value: unknown): AiAllotmentSubject | null {\n  if (typeof value !== 'string') return null\n  if (value === AI_ALLOTMENT_ORG_SUBJECT) {\n    return { id: value, scope: 'org', uid: null, hostId: null }\n  }\n  const parts = value.split(':')\n  if (parts.some((part) => !ID_SEGMENT.test(part))) return null\n  if (parts.length === 2 && parts[0] === 'member') {\n    return { id: value, scope: 'member', uid: parts[1], hostId: null }\n  }\n  if (parts.length === 2 && parts[0] === 'host') {\n    return { id: value, scope: 'host', uid: null, hostId: parts[1] }\n  }\n  if (parts.length === 3 && parts[0] === 'collab') {\n    return { id: value, scope: 'collab', uid: parts[2], hostId: parts[1] }\n  }\n  return null\n}\n\n/** One allotment as every reader hands it on. */\nexport interface AiAllotment {\n  subject: string\n  scope: AiAllotmentScope\n  uid: string | null\n  hostId: string | null\n  /**\n   * Credits a month, or `null` for an allotment that bounds models alone —\n   * and always `null` on the org-wide restriction.\n   */\n  credits: number | null\n  mode: AiAllotmentMode\n  /** Catalog ids the subject may run on, or `null` for no restriction. */\n  models: string[] | null\n  setBy: string | null\n  /** The last threshold announced, and the month it was announced in. */\n  alerted: { month: string; threshold: AiAllotmentThreshold } | null\n}\n\n/** A finite positive whole number of credits, else `null`. */\nexport function aiAllotmentCredits(value: unknown): number | null {\n  const parsed = typeof value === 'number' ? value : Number.NaN\n  if (!Number.isFinite(parsed) || parsed <= 0) return null\n  return Math.min(AI_ALLOTMENT_MAX_CREDITS, Math.floor(parsed))\n}\n\n/** An allowlist read back: unique strings, bounded; empty reads as none. */\nexport function aiAllotmentModels(value: unknown): string[] | null {\n  if (!Array.isArray(value)) return null\n  const models = [\n    ...new Set(\n      value\n        .filter((entry): entry is string => typeof entry === 'string')\n        .map((entry) => entry.trim())\n        .filter(Boolean),\n    ),\n  ].slice(0, AI_ALLOTMENT_MAX_MODELS)\n  return models.length ? models : null\n}\n\n/**\n * A stored allotment as a complete record, or `null` when the id is not a\n * subject. The scope, uid and site are read off the ID, never off the\n * fields: the id is what the gate addresses, so it is the only claim about\n * who the document is for that can be trusted.\n *\n * `mode` defaults to `hard`: a document whose mode was lost is a cap, which\n * is the reading that cannot spend more than a manager set.\n */\nexport function aiAllotmentFrom(\n  raw: Record<string, unknown> | null | undefined,\n  id: string,\n): AiAllotment | null {\n  const subject = parseAiAllotmentSubject(id)\n  if (!subject || !raw) return null\n  const alertedRaw = raw['alerted'] as { month?: unknown; threshold?: unknown } | null\n  const threshold = Number(alertedRaw?.threshold)\n  return {\n    subject: subject.id,\n    scope: subject.scope,\n    uid: subject.uid,\n    hostId: subject.hostId,\n    credits: subject.scope === 'org' ? null : aiAllotmentCredits(raw['credits']),\n    mode: raw['mode'] === 'soft' ? 'soft' : 'hard',\n    models: aiAllotmentModels(raw['models']),\n    setBy: typeof raw['setBy'] === 'string' ? (raw['setBy'] as string) : null,\n    alerted:\n      typeof alertedRaw?.month === 'string' && (threshold === 80 || threshold === 100)\n        ? { month: alertedRaw.month, threshold }\n        : null,\n  }\n}\n\n/** One allotment of credits measured against what its subject drew. */\nexport interface AiAllotmentStanding {\n  subject: string\n  scope: AiCreditAllotmentScope\n  uid: string | null\n  hostId: string | null\n  credits: number\n  /** Credits drawn this month before the request being decided. */\n  used: number\n  mode: AiAllotmentMode\n}\n\nexport type AiAllotmentState = 'ok' | 'warn' | 'reached'\n\n/** `reached` at or past the allotment, `warn` from 80% of it. */\nexport function aiAllotmentState(used: number, credits: number): AiAllotmentState {\n  if (!(credits > 0)) return 'ok'\n  if (used >= credits) return 'reached'\n  if (used >= credits * AI_ALLOTMENT_WARN_SHARE) return 'warn'\n  return 'ok'\n}\n\n/** The threshold a standing sits at, for the alert pipeline. */\nexport function aiAllotmentThreshold(\n  used: number,\n  credits: number,\n): AiAllotmentThreshold | null {\n  const state = aiAllotmentState(used, credits)\n  return state === 'reached' ? 100 : state === 'warn' ? 80 : null\n}\n\n/**\n * Whether a standing admits a request.\n *\n * A soft allotment always does. A hard one admits while the subject is under\n * it — and, for a caller that knows what the request will cost before it\n * starts (a job's estimate), while the estimate still fits: a 100-credit job\n * at 0 of 100 is admitted, one at 1 of 100 is not.\n */\nexport function aiAllotmentAdmits(\n  standing: Pick<AiAllotmentStanding, 'credits' | 'used' | 'mode'>,\n  estimateCredits = 0,\n): boolean {\n  if (standing.mode === 'soft') return true\n  const estimate = Number.isFinite(estimateCredits) && estimateCredits > 0 ? estimateCredits : 0\n  return estimate > 0\n    ? standing.used + estimate <= standing.credits\n    : standing.used < standing.credits\n}\n\n/**\n * Which subject a refusal names when more than one allotment is spent: the\n * narrowest first — the person on this site, then the person, then the site.\n */\nconst SCOPE_ORDER: readonly AiCreditAllotmentScope[] = ['collab', 'member', 'host']\n\nconst scopeRank = (scope: AiCreditAllotmentScope): number => SCOPE_ORDER.indexOf(scope)\n\nexport interface AiAllotmentVerdict {\n  /** The hard allotment that refuses the request, or `null`. */\n  refusal: AiAllotmentStanding | null\n  /** The allotment with the least left, for the usage strip; `null` for none. */\n  binding: AiAllotmentStanding | null\n  /** Soft allotments at a threshold, for the alert pipeline. */\n  alerts: Array<{ standing: AiAllotmentStanding; threshold: AiAllotmentThreshold }>\n}\n\n/** The verdict over every allotment that applies to one request. */\nexport function aiAllotmentVerdict(\n  standings: readonly AiAllotmentStanding[],\n  estimateCredits = 0,\n): AiAllotmentVerdict {\n  const ordered = [...standings].sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope))\n  const refusal =\n    ordered.find((standing) => !aiAllotmentAdmits(standing, estimateCredits)) ?? null\n  let binding: AiAllotmentStanding | null = null\n  for (const standing of ordered) {\n    if (!binding || standing.credits - standing.used < binding.credits - binding.used) {\n      binding = standing\n    }\n  }\n  const alerts = ordered.flatMap((standing) => {\n    if (standing.mode !== 'soft') return []\n    const threshold = aiAllotmentThreshold(standing.used, standing.credits)\n    return threshold ? [{ standing, threshold }] : []\n  })\n  return { refusal, binding, alerts }\n}\n\n/**\n * The allowlists that apply to a request, intersected — `null` when none of\n * the allotments names one. An empty result is a real answer: two lists that\n * share no model leave nothing to pick, and the model choice falls back to\n * the routing table rather than turning AI off for a mistake in a list.\n */\nexport function aiAllotmentModelsAllowed(\n  allotments: ReadonlyArray<Pick<AiAllotment, 'models'> | null | undefined>,\n): string[] | null {\n  const lists = allotments\n    .map((allotment) => allotment?.models)\n    .filter((models): models is string[] => Array.isArray(models) && models.length > 0)\n  if (!lists.length) return null\n  return lists.reduce((kept, list) => kept.filter((id) => list.includes(id)))\n}\n\n/** The catalog label for `billing.manage`, the word a sentence names it by. */\nexport function billingManageLabel(): string {\n  return (\n    ORG_PERMISSIONS.find((definition) => definition.key === 'billing.manage')?.label ??\n    'Manage billing'\n  )\n}\n\n/**\n * The sentence a refused request is told, naming who can raise the\n * allotment and where. No figures: the strip beside it carries those, and a\n * refusal that quoted a count would be stale the moment someone raised it.\n */\nexport function aiAllotmentRefusalText(\n  scope: AiCreditAllotmentScope | null | undefined,\n): string {\n  const managers = `an organization admin with the \"${billingManageLabel()}\" permission`\n  switch (scope) {\n    case 'collab':\n      return (\n        'You have used your AI allotment on this site for this month. ' +\n        `The site's admin, or ${managers}, can raise it on the site's Users card.`\n      )\n    case 'host':\n      return (\n        'This site has used its AI allotment for this month. ' +\n        `Ask ${managers} to raise it under ${ASSIST_HARD_CAP_CONTROL_LOCATION}.`\n      )\n    default:\n      return (\n        'You have used your AI allotment for this month. ' +\n        `Ask ${managers} to raise it under ${ASSIST_HARD_CAP_CONTROL_LOCATION}.`\n      )\n  }\n}\n\n/**\n * The words a soft allotment's alert carries, for BOTH channels — the\n * console notification and the email — so the two cannot say different\n * things about one crossing. `name` is the member's name or the site's.\n */\nexport function aiAllotmentAlertCopy(input: {\n  scope: AiCreditAllotmentScope\n  threshold: AiAllotmentThreshold\n  used: number\n  credits: number\n  name: string\n}): { title: string; body: string } {\n  const who =\n    input.scope === 'host' ? `The ${input.name} site` : input.name\n  const whose = input.scope === 'host' ? 'its' : 'their'\n  const where = input.scope === 'collab' ? ' on its site' : ''\n  const figures =\n    `${input.used.toLocaleString('en-US')} of ` +\n    `${input.credits.toLocaleString('en-US')} credits used this month.`\n  if (input.threshold >= 100) {\n    return {\n      title: `${who} has used ${whose} whole AI allotment${where}`,\n      body:\n        `${figures} The allotment is soft, so requests keep working and ` +\n        'draw on the workspace’s pool. Raise it or make it hard under ' +\n        `${ASSIST_HARD_CAP_CONTROL_LOCATION}.`,\n    }\n  }\n  return {\n    title: `${who} is past ${Math.round(AI_ALLOTMENT_WARN_SHARE * 100)}% of ${whose} AI allotment${where}`,\n    body: `${figures} The allotment is soft, so nothing stops at the line.`,\n  }\n}\n"],"names":["ASSIST_HARD_CAP_CONTROL_LOCATION","ORG_PERMISSIONS","AI_ALLOTMENTS_COLLECTION","AI_ALLOTMENT_ORG_SUBJECT","AI_ALLOTMENT_WARN_SHARE","AI_ALLOTMENT_MAX_CREDITS","AI_ALLOTMENT_MAX_MODELS","ID_SEGMENT","aiAllotmentSubjectId","input","segment","value","test","Error","scope","uid","hostId","parseAiAllotmentSubject","id","parts","split","some","part","length","aiAllotmentCredits","parsed","Number","NaN","isFinite","Math","min","floor","aiAllotmentModels","Array","isArray","models","Set","filter","entry","map","trim","Boolean","slice","aiAllotmentFrom","raw","subject","alertedRaw","threshold","credits","mode","setBy","alerted","month","aiAllotmentState","used","aiAllotmentThreshold","state","aiAllotmentAdmits","standing","estimateCredits","estimate","SCOPE_ORDER","scopeRank","indexOf","aiAllotmentVerdict","standings","ordered","sort","a","b","refusal","find","binding","alerts","flatMap","aiAllotmentModelsAllowed","allotments","lists","allotment","reduce","kept","list","includes","billingManageLabel","definition","key","label","aiAllotmentRefusalText","managers","aiAllotmentAlertCopy","who","name","whose","where","figures","toLocaleString","title","body","round"],"mappings":"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"}

package/src/lib/model/ai-automation-draft.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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 { HostAction } from '@aglyn/aglyn/app-utils/actions';
+import { type AutomationPlaceholder } from '@aglyn/aglyn/app-utils/automation-placeholders';
+import type { AiAutomationAnswer } from '../tools/ai-workflow-tool';
+/**
+ * An answer made into the automation the workflows plugin stores (AGL-2919).
+ *
+ * The answer names each record in WORDS. Here, in code and after the answer,
+ * each is looked up among the site's own records: a list, a campaign, a
+ * workflow, a webhook, a dataset, a form or a deal stage the words name
+ * without doubt becomes that record's id; words that name none, or name more
+ * than one, become a placeholder — the words in square brackets where the
+ * record belongs — for the person to pick in the Actions editor. Nothing is
+ * guessed, and the model never saw the records it was matched against beyond
+ * what the site inventory already sends.
+ */
+/** One record a description may name. */
+export interface AiAutomationNamedRecord {
+    id: string;
+    name: string;
+}
+/** A form, with the fields its submissions carry. */
+export interface AiAutomationForm extends AiAutomationNamedRecord {
+    fields: string[];
+}
+/** The site's records an automation's words are looked up among. */
+export interface AiAutomationRecords {
+    forms: AiAutomationForm[];
+    datasets: AiAutomationNamedRecord[];
+    lists: AiAutomationNamedRecord[];
+    campaigns: AiAutomationNamedRecord[];
+    workflows: AiAutomationNamedRecord[];
+    webhooks: AiAutomationNamedRecord[];
+    /** Every stage of every pipeline the site may see. */
+    stages: AiAutomationNamedRecord[];
+}
+export declare function emptyAiAutomationRecords(): AiAutomationRecords;
+/**
+ * The one record `words` name, or `null`: its id written whole; else the one
+ * record whose name is the same words; else the one record whose name holds
+ * every word, or whose every word the words hold. Two records that fit
+ * equally well name neither — a placeholder is better than a coin toss.
+ */
+export declare function aiMatchNamedRecord<T extends AiAutomationNamedRecord>(words: string, records: readonly T[], noun: string): T | null;
+/** The name an automation is drafted under when the answer gave none. */
+export declare const AI_AUTOMATION_DEFAULT_NAME = "New automation";
+export interface AiAutomationDraft {
+    /** The automation as the workflows plugin stores it: OFF. */
+    action: HostAction;
+    /** What a person still has to supply before switching it on. */
+    placeholders: AutomationPlaceholder[];
+}
+/** An answer as the automation to store, with every record it names looked up. */
+export declare function aiAutomationDraft(answer: AiAutomationAnswer, records: AiAutomationRecords): AiAutomationDraft;
+/**
+ * What a drafted automation's output tells a person: that it is off, what to
+ * fill in before switching it on, and what the answer said needs deciding.
+ */
+export declare function aiAutomationDraftNote(draft: AiAutomationDraft, notes: readonly string[]): string;