@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/usage/ai-usage-wire.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @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 AiUsageByUserMonth } from '../model/ai-usage-by-user';
+import { type AiAllotmentMode, type AiCreditAllotmentScope } from '../model/ai-allotments';
+/**
+ * What `/api/ai/usage` answers (AGL-2928), shared by the route and the
+ * console surfaces that read it — the Usage table, the roster column, the
+ * site collaborators card and the member card. Dependency-free on purpose:
+ * the route imports the Admin SDK and a client component may not.
+ */
+/** Header naming the row count the export undertook to send. */
+export declare const AI_USAGE_EXPORT_ROWS_HEADER = "X-Aglyn-Export-Rows";
+/** A row as a customer sees it — credits and a share, never `estCostUsd`. */
+export interface OrgAiUsageRowWire {
+    uid: string;
+    /** The roster's name — display name, else email, else the uid. */
+    name: string;
+    email: string | null;
+    role: string | null;
+    credits: number;
+    /** Of the workspace's measured spend for the month, in `[0, 1]`. */
+    share: number;
+    requests: number;
+    refusals: number;
+    byKind: Record<string, number>;
+    byHost: Record<string, number>;
+    /** Credits on the site the request named, when it named one. */
+    hostCredits?: number;
+}
+export interface OrgAiUsageTableWire {
+    month: string;
+    /** The months a reader may ask for, newest first. */
+    months: string[];
+    /** The workspace's own credits for the month — the pool the shares are of. */
+    orgCredits: number;
+    rows: OrgAiUsageRowWire[];
+}
+/** One person's month, as the member card reads it. */
+export interface UserAiUsageMonthWire {
+    month: string;
+    credits: number;
+    share: number;
+    requests: number;
+    refusals: number;
+    byKind: Record<string, number>;
+    byHost: Record<string, number>;
+}
+export interface UserAiUsageWire {
+    uid: string;
+    /** Newest first. */
+    months: UserAiUsageMonthWire[];
+}
+/** The roster's month, joined and shared, projected onto the wire. */
+export declare function toAiUsageWireRow(row: AiUsageByUserMonth & {
+    name: string;
+    email: string | null;
+    role: string | null;
+    share: number;
+}, hostId: string): OrgAiUsageRowWire;
+/** The CSV's columns, in order. */
+export declare const AI_USAGE_CSV_HEADER: readonly ["Member", "Email", "Role", "Credits", "Share", "Requests", "Refusals", "Top kinds", "Sites"];
+/** A share as the table and the file print it: one decimal of a percent. */
+export declare function formatAiUsageShare(share: number): string;
+export declare function aiUsageCsvLine(row: OrgAiUsageRowWire): string;
+/**
+ * THE USAGE STRIP'S ENVELOPE (AGL-2942): what every AI door adds to the
+ * answer it already sends — the chat door's `done` event, the copy
+ * assistant's JSON, a job's create response, and each door's quota refusal —
+ * so the strip in the panel and the generation dialogs updates with no read
+ * of its own.
+ *
+ * Credits only. `pool` is the workspace's month against its band; `mine` is
+ * the caller's own month, measured against the allotment that binds them
+ * when one does — for a site allotment, the site's month, because that is
+ * the line the next request meets.
+ */
+export type AiUsageMeterState = 'ok' | 'warn' | 'capped';
+export interface AiUsageMeterWire {
+    month: string;
+    pool: {
+        used: number;
+        limit: number | null;
+    };
+    mine: {
+        used: number;
+        limit: number | null;
+        mode: AiAllotmentMode | null;
+        scope: AiCreditAllotmentScope | null;
+    };
+    /** Credits the exchange this envelope answers cost; `null` when no model ran. */
+    last: number | null;
+    /** True when the envelope rides a refusal. */
+    refused: boolean;
+    state: AiUsageMeterState;
+    /** The model that answered, as the catalog names it. */
+    model: {
+        id: string;
+        label: string;
+        auto: boolean;
+    } | null;
+}
+/**
+ * `capped` when a hard allotment is spent or the request was refused, `warn`
+ * from 80% of the allotment that binds or of the pool, `ok` otherwise.
+ */
+export declare function aiUsageMeterState(meter: Pick<AiUsageMeterWire, 'pool' | 'mine' | 'refused'>): AiUsageMeterState;
+/**
+ * What `/api/ai/allotments` answers (AGL-2942): the allotments a reader may
+ * see, each with what its subject drew this month, and the roster, sites
+ * and models the editors pick from. Credits only.
+ */
+export interface AiAllotmentRowWire {
+    subject: string;
+    scope: 'member' | 'collab' | 'host' | 'org';
+    uid: string | null;
+    hostId: string | null;
+    credits: number | null;
+    mode: AiAllotmentMode;
+    models: string[] | null;
+    /** Credits the subject drew this month — the figure the gate measures. */
+    used: number;
+}
+export interface AiAllotmentsMemberWire {
+    uid: string;
+    name: string;
+    email: string | null;
+    role: string | null;
+    /** False for a site collaborator, whose allotments are per site. */
+    orgWide: boolean;
+    /** Credits this month, every site. */
+    credits: number;
+    /** Credits this month by site. */
+    byHost: Record<string, number>;
+}
+export interface AiAllotmentsHostWire {
+    hostId: string;
+    name: string;
+    /** The site's credits this month, everyone on it. */
+    credits: number;
+}
+export interface AiAllotmentsWire {
+    /** The org the answer is about — resolved from the site when only one was named. */
+    orgId: string;
+    month: string;
+    pool: {
+        used: number;
+        limit: number | null;
+    };
+    allotments: AiAllotmentRowWire[];
+    members: AiAllotmentsMemberWire[];
+    hosts: AiAllotmentsHostWire[];
+    /** The catalog models this deployment serves, for an allowlist. */
+    models: Array<{
+        id: string;
+        label: string;
+        tier: string;
+    }>;
+    /** Whether the plan lets the workspace restrict models org-wide. */
+    restrictionAvailable: boolean;
+    canEdit: {
+        /** Members, sites and the restriction: `billing.manage`. */
+        billing: boolean;
+        /** Collaborators on the site asked about: `billing.manage`, or its admin. */
+        collaborators: boolean;
+    };
+    /** Who is reading, so an editor can refuse to offer a self-raise. */
+    callerUid: string;
+}
+/** `2026-09` as a reader says it, on the UTC calendar the key is cut from. */
+export declare function aiUsageMonthLabel(month: string): string;

package/src/lib/usage/ai-usage-wire.js

@@ -0,0 +1,98 @@
+/**
+ * @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.
+ */ // By their own entry points rather than the barrel: the route that serves
+// this shape imports it on the server, where the whole library is dead weight.
+import { topAiUsageKinds } from "../model/ai-usage-by-user.js";
+import { AI_ALLOTMENT_WARN_SHARE } from "../model/ai-allotments.js";
+import { csvCell } from "@aglyn/aglyn/app-utils/csv-import";
+/**
+ * What `/api/ai/usage` answers (AGL-2928), shared by the route and the
+ * console surfaces that read it — the Usage table, the roster column, the
+ * site collaborators card and the member card. Dependency-free on purpose:
+ * the route imports the Admin SDK and a client component may not.
+ */ /** Header naming the row count the export undertook to send. */ export const AI_USAGE_EXPORT_ROWS_HEADER = 'X-Aglyn-Export-Rows';
+/** The roster's month, joined and shared, projected onto the wire. */ export function toAiUsageWireRow(row, hostId) {
+    var _row_byHost_hostId;
+    const wire = {
+        uid: row.uid,
+        name: row.name,
+        email: row.email,
+        role: row.role,
+        credits: row.credits,
+        share: row.share,
+        requests: row.requests,
+        refusals: row.refusals,
+        byKind: row.byKind,
+        byHost: row.byHost
+    };
+    if (hostId) wire.hostCredits = (_row_byHost_hostId = row.byHost[hostId]) != null ? _row_byHost_hostId : 0;
+    return wire;
+}
+/** The CSV's columns, in order. */ export const AI_USAGE_CSV_HEADER = [
+    'Member',
+    'Email',
+    'Role',
+    'Credits',
+    'Share',
+    'Requests',
+    'Refusals',
+    'Top kinds',
+    'Sites'
+];
+/** A share as the table and the file print it: one decimal of a percent. */ export function formatAiUsageShare(share) {
+    return `${Math.round(share * 1000) / 10}%`;
+}
+export function aiUsageCsvLine(row) {
+    var _row_email, _row_role;
+    const kinds = topAiUsageKinds(row.byKind, 3).map((entry)=>`${entry.kind} ${entry.credits}`).join('; ');
+    const sites = Object.entries(row.byHost).sort((a, b)=>b[1] - a[1]).map(([hostId, credits])=>`${hostId} ${credits}`).join('; ');
+    return [
+        row.name,
+        (_row_email = row.email) != null ? _row_email : '',
+        (_row_role = row.role) != null ? _row_role : '',
+        row.credits,
+        formatAiUsageShare(row.share),
+        row.requests,
+        row.refusals,
+        kinds,
+        sites
+    ].map(csvCell).join(',');
+}
+/**
+ * `capped` when a hard allotment is spent or the request was refused, `warn`
+ * from 80% of the allotment that binds or of the pool, `ok` otherwise.
+ */ export function aiUsageMeterState(meter) {
+    const { mine, pool } = meter;
+    if (meter.refused) return 'capped';
+    if (mine.limit !== null && mine.mode === 'hard' && mine.used >= mine.limit) return 'capped';
+    const past = (used, limit)=>limit !== null && limit > 0 && used >= limit * AI_ALLOTMENT_WARN_SHARE;
+    return past(mine.used, mine.limit) || past(pool.used, pool.limit) ? 'warn' : 'ok';
+}
+/** `2026-09` as a reader says it, on the UTC calendar the key is cut from. */ export function aiUsageMonthLabel(month) {
+    const [year, monthOfYear] = month.split('-').map(Number);
+    if (!year || !monthOfYear) return month;
+    try {
+        return new Date(Date.UTC(year, monthOfYear - 1, 1)).toLocaleDateString(undefined, {
+            month: 'long',
+            year: 'numeric',
+            timeZone: 'UTC'
+        });
+    } catch (unused) {
+        return month;
+    }
+}
+
+//# sourceMappingURL=ai-usage-wire.js.map

package/src/lib/usage/ai-usage-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-wire.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\n// By their own entry points rather than the barrel: the route that serves\n// this shape imports it on the server, where the whole library is dead weight.\nimport {\n  topAiUsageKinds,\n  type AiUsageByUserMonth,\n} from '../model/ai-usage-by-user'\nimport {\n  AI_ALLOTMENT_WARN_SHARE,\n  type AiAllotmentMode,\n  type AiCreditAllotmentScope,\n} from '../model/ai-allotments'\nimport { csvCell } from '@aglyn/aglyn/app-utils/csv-import'\n\n/**\n * What `/api/ai/usage` answers (AGL-2928), shared by the route and the\n * console surfaces that read it — the Usage table, the roster column, the\n * site collaborators card and the member card. Dependency-free on purpose:\n * the route imports the Admin SDK and a client component may not.\n */\n\n/** Header naming the row count the export undertook to send. */\nexport const AI_USAGE_EXPORT_ROWS_HEADER = 'X-Aglyn-Export-Rows'\n\n/** A row as a customer sees it — credits and a share, never `estCostUsd`. */\nexport interface OrgAiUsageRowWire {\n  uid: string\n  /** The roster's name — display name, else email, else the uid. */\n  name: string\n  email: string | null\n  role: string | null\n  credits: number\n  /** Of the workspace's measured spend for the month, in `[0, 1]`. */\n  share: number\n  requests: number\n  refusals: number\n  byKind: Record<string, number>\n  byHost: Record<string, number>\n  /** Credits on the site the request named, when it named one. */\n  hostCredits?: number\n}\n\nexport interface OrgAiUsageTableWire {\n  month: string\n  /** The months a reader may ask for, newest first. */\n  months: string[]\n  /** The workspace's own credits for the month — the pool the shares are of. */\n  orgCredits: number\n  rows: OrgAiUsageRowWire[]\n}\n\n/** One person's month, as the member card reads it. */\nexport interface UserAiUsageMonthWire {\n  month: string\n  credits: number\n  share: number\n  requests: number\n  refusals: number\n  byKind: Record<string, number>\n  byHost: Record<string, number>\n}\n\nexport interface UserAiUsageWire {\n  uid: string\n  /** Newest first. */\n  months: UserAiUsageMonthWire[]\n}\n\n/** The roster's month, joined and shared, projected onto the wire. */\nexport function toAiUsageWireRow(\n  row: AiUsageByUserMonth & {\n    name: string\n    email: string | null\n    role: string | null\n    share: number\n  },\n  hostId: string,\n): OrgAiUsageRowWire {\n  const wire: OrgAiUsageRowWire = {\n    uid: row.uid,\n    name: row.name,\n    email: row.email,\n    role: row.role,\n    credits: row.credits,\n    share: row.share,\n    requests: row.requests,\n    refusals: row.refusals,\n    byKind: row.byKind,\n    byHost: row.byHost,\n  }\n  if (hostId) wire.hostCredits = row.byHost[hostId] ?? 0\n  return wire\n}\n\n/** The CSV's columns, in order. */\nexport const AI_USAGE_CSV_HEADER = [\n  'Member',\n  'Email',\n  'Role',\n  'Credits',\n  'Share',\n  'Requests',\n  'Refusals',\n  'Top kinds',\n  'Sites',\n] as const\n\n/** A share as the table and the file print it: one decimal of a percent. */\nexport function formatAiUsageShare(share: number): string {\n  return `${Math.round(share * 1000) / 10}%`\n}\n\nexport function aiUsageCsvLine(row: OrgAiUsageRowWire): string {\n  const kinds = topAiUsageKinds(row.byKind, 3)\n    .map((entry) => `${entry.kind} ${entry.credits}`)\n    .join('; ')\n  const sites = Object.entries(row.byHost)\n    .sort((a, b) => b[1] - a[1])\n    .map(([hostId, credits]) => `${hostId} ${credits}`)\n    .join('; ')\n  return [\n    row.name,\n    row.email ?? '',\n    row.role ?? '',\n    row.credits,\n    formatAiUsageShare(row.share),\n    row.requests,\n    row.refusals,\n    kinds,\n    sites,\n  ]\n    .map(csvCell)\n    .join(',')\n}\n\n/**\n * THE USAGE STRIP'S ENVELOPE (AGL-2942): what every AI door adds to the\n * answer it already sends — the chat door's `done` event, the copy\n * assistant's JSON, a job's create response, and each door's quota refusal —\n * so the strip in the panel and the generation dialogs updates with no read\n * of its own.\n *\n * Credits only. `pool` is the workspace's month against its band; `mine` is\n * the caller's own month, measured against the allotment that binds them\n * when one does — for a site allotment, the site's month, because that is\n * the line the next request meets.\n */\nexport type AiUsageMeterState = 'ok' | 'warn' | 'capped'\n\nexport interface AiUsageMeterWire {\n  month: string\n  pool: { used: number; limit: number | null }\n  mine: {\n    used: number\n    limit: number | null\n    mode: AiAllotmentMode | null\n    scope: AiCreditAllotmentScope | null\n  }\n  /** Credits the exchange this envelope answers cost; `null` when no model ran. */\n  last: number | null\n  /** True when the envelope rides a refusal. */\n  refused: boolean\n  state: AiUsageMeterState\n  /** The model that answered, as the catalog names it. */\n  model: { id: string; label: string; auto: boolean } | null\n}\n\n/**\n * `capped` when a hard allotment is spent or the request was refused, `warn`\n * from 80% of the allotment that binds or of the pool, `ok` otherwise.\n */\nexport function aiUsageMeterState(\n  meter: Pick<AiUsageMeterWire, 'pool' | 'mine' | 'refused'>,\n): AiUsageMeterState {\n  const { mine, pool } = meter\n  if (meter.refused) return 'capped'\n  if (mine.limit !== null && mine.mode === 'hard' && mine.used >= mine.limit) return 'capped'\n  const past = (used: number, limit: number | null) =>\n    limit !== null && limit > 0 && used >= limit * AI_ALLOTMENT_WARN_SHARE\n  return past(mine.used, mine.limit) || past(pool.used, pool.limit) ? 'warn' : 'ok'\n}\n\n/**\n * What `/api/ai/allotments` answers (AGL-2942): the allotments a reader may\n * see, each with what its subject drew this month, and the roster, sites\n * and models the editors pick from. Credits only.\n */\nexport interface AiAllotmentRowWire {\n  subject: string\n  scope: 'member' | 'collab' | 'host' | 'org'\n  uid: string | null\n  hostId: string | null\n  credits: number | null\n  mode: AiAllotmentMode\n  models: string[] | null\n  /** Credits the subject drew this month — the figure the gate measures. */\n  used: number\n}\n\nexport interface AiAllotmentsMemberWire {\n  uid: string\n  name: string\n  email: string | null\n  role: string | null\n  /** False for a site collaborator, whose allotments are per site. */\n  orgWide: boolean\n  /** Credits this month, every site. */\n  credits: number\n  /** Credits this month by site. */\n  byHost: Record<string, number>\n}\n\nexport interface AiAllotmentsHostWire {\n  hostId: string\n  name: string\n  /** The site's credits this month, everyone on it. */\n  credits: number\n}\n\nexport interface AiAllotmentsWire {\n  /** The org the answer is about — resolved from the site when only one was named. */\n  orgId: string\n  month: string\n  pool: { used: number; limit: number | null }\n  allotments: AiAllotmentRowWire[]\n  members: AiAllotmentsMemberWire[]\n  hosts: AiAllotmentsHostWire[]\n  /** The catalog models this deployment serves, for an allowlist. */\n  models: Array<{ id: string; label: string; tier: string }>\n  /** Whether the plan lets the workspace restrict models org-wide. */\n  restrictionAvailable: boolean\n  canEdit: {\n    /** Members, sites and the restriction: `billing.manage`. */\n    billing: boolean\n    /** Collaborators on the site asked about: `billing.manage`, or its admin. */\n    collaborators: boolean\n  }\n  /** Who is reading, so an editor can refuse to offer a self-raise. */\n  callerUid: string\n}\n\n/** `2026-09` as a reader says it, on the UTC calendar the key is cut from. */\nexport function aiUsageMonthLabel(month: string): string {\n  const [year, monthOfYear] = month.split('-').map(Number)\n  if (!year || !monthOfYear) return month\n  try {\n    return new Date(Date.UTC(year, monthOfYear - 1, 1)).toLocaleDateString(undefined, {\n      month: 'long',\n      year: 'numeric',\n      timeZone: 'UTC',\n    })\n  } catch {\n    return month\n  }\n}\n"],"names":["topAiUsageKinds","AI_ALLOTMENT_WARN_SHARE","csvCell","AI_USAGE_EXPORT_ROWS_HEADER","toAiUsageWireRow","row","hostId","wire","uid","name","email","role","credits","share","requests","refusals","byKind","byHost","hostCredits","AI_USAGE_CSV_HEADER","formatAiUsageShare","Math","round","aiUsageCsvLine","kinds","map","entry","kind","join","sites","Object","entries","sort","a","b","aiUsageMeterState","meter","mine","pool","refused","limit","mode","used","past","aiUsageMonthLabel","month","year","monthOfYear","split","Number","Date","UTC","toLocaleDateString","undefined","timeZone"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,0EAA0E;AAC1E,+EAA+E;AAC/E,SACEA,eAAe,QAEV,+BAA2B;AAClC,SACEC,uBAAuB,QAGlB,4BAAwB;AAC/B,SAASC,OAAO,QAAQ,oCAAmC;AAE3D;;;;;CAKC,GAED,8DAA8D,GAC9D,OAAO,MAAMC,8BAA8B,sBAAqB;AA8ChE,oEAAoE,GACpE,OAAO,SAASC,iBACdC,GAKC,EACDC,MAAc;QAciBD;IAZ/B,MAAME,OAA0B;QAC9BC,KAAKH,IAAIG,GAAG;QACZC,MAAMJ,IAAII,IAAI;QACdC,OAAOL,IAAIK,KAAK;QAChBC,MAAMN,IAAIM,IAAI;QACdC,SAASP,IAAIO,OAAO;QACpBC,OAAOR,IAAIQ,KAAK;QAChBC,UAAUT,IAAIS,QAAQ;QACtBC,UAAUV,IAAIU,QAAQ;QACtBC,QAAQX,IAAIW,MAAM;QAClBC,QAAQZ,IAAIY,MAAM;IACpB;IACA,IAAIX,QAAQC,KAAKW,WAAW,IAAGb,qBAAAA,IAAIY,MAAM,CAACX,OAAO,YAAlBD,qBAAsB;IACrD,OAAOE;AACT;AAEA,iCAAiC,GACjC,OAAO,MAAMY,sBAAsB;IACjC;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAS;AAEV,0EAA0E,GAC1E,OAAO,SAASC,mBAAmBP,KAAa;IAC9C,OAAO,GAAGQ,KAAKC,KAAK,CAACT,QAAQ,QAAQ,GAAG,CAAC,CAAC;AAC5C;AAEA,OAAO,SAASU,eAAelB,GAAsB;QAUjDA,YACAA;IAVF,MAAMmB,QAAQxB,gBAAgBK,IAAIW,MAAM,EAAE,GACvCS,GAAG,CAAC,CAACC,QAAU,GAAGA,MAAMC,IAAI,CAAC,CAAC,EAAED,MAAMd,OAAO,EAAE,EAC/CgB,IAAI,CAAC;IACR,MAAMC,QAAQC,OAAOC,OAAO,CAAC1B,IAAIY,MAAM,EACpCe,IAAI,CAAC,CAACC,GAAGC,IAAMA,CAAC,CAAC,EAAE,GAAGD,CAAC,CAAC,EAAE,EAC1BR,GAAG,CAAC,CAAC,CAACnB,QAAQM,QAAQ,GAAK,GAAGN,OAAO,CAAC,EAAEM,SAAS,EACjDgB,IAAI,CAAC;IACR,OAAO;QACLvB,IAAII,IAAI;SACRJ,aAAAA,IAAIK,KAAK,YAATL,aAAa;SACbA,YAAAA,IAAIM,IAAI,YAARN,YAAY;QACZA,IAAIO,OAAO;QACXQ,mBAAmBf,IAAIQ,KAAK;QAC5BR,IAAIS,QAAQ;QACZT,IAAIU,QAAQ;QACZS;QACAK;KACD,CACEJ,GAAG,CAACvB,SACJ0B,IAAI,CAAC;AACV;AAkCA;;;CAGC,GACD,OAAO,SAASO,kBACdC,KAA0D;IAE1D,MAAM,EAAEC,IAAI,EAAEC,IAAI,EAAE,GAAGF;IACvB,IAAIA,MAAMG,OAAO,EAAE,OAAO;IAC1B,IAAIF,KAAKG,KAAK,KAAK,QAAQH,KAAKI,IAAI,KAAK,UAAUJ,KAAKK,IAAI,IAAIL,KAAKG,KAAK,EAAE,OAAO;IACnF,MAAMG,OAAO,CAACD,MAAcF,QAC1BA,UAAU,QAAQA,QAAQ,KAAKE,QAAQF,QAAQvC;IACjD,OAAO0C,KAAKN,KAAKK,IAAI,EAAEL,KAAKG,KAAK,KAAKG,KAAKL,KAAKI,IAAI,EAAEJ,KAAKE,KAAK,IAAI,SAAS;AAC/E;AA6DA,4EAA4E,GAC5E,OAAO,SAASI,kBAAkBC,KAAa;IAC7C,MAAM,CAACC,MAAMC,YAAY,GAAGF,MAAMG,KAAK,CAAC,KAAKvB,GAAG,CAACwB;IACjD,IAAI,CAACH,QAAQ,CAACC,aAAa,OAAOF;IAClC,IAAI;QACF,OAAO,IAAIK,KAAKA,KAAKC,GAAG,CAACL,MAAMC,cAAc,GAAG,IAAIK,kBAAkB,CAACC,WAAW;YAChFR,OAAO;YACPC,MAAM;YACNQ,UAAU;QACZ;IACF,EAAE,eAAM;QACN,OAAOT;IACT;AACF"}

package/src/lib/usage/assist-ceiling.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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 { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
+/**
+ * The ceiling one reservation is actually measured against, given the org's
+ * plan band.
+ *
+ * ## Why the repo default must not bind an org that has a band
+ *
+ * `ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD` (in `usage-budget.ts`, beside
+ * the alert that announces the ceiling) is $40, which was sized as a
+ * runaway guard back when every org's assist spend was bounded by a message
+ * cap. It is BELOW what Agency and Enterprise include, so applying it to a
+ * plan band would refuse those workspaces partway through capacity they are
+ * paying for. The rule is not about which tiers happen to clear $40 today: a
+ * band that is sold is a product limit, and a default nobody typed is not
+ * allowed to undercut one at any size.
+ *
+ * ## Why an operator's explicit figure still does
+ *
+ * A self-hoster paying their own provider bill, or an operator responding to
+ * an incident, sets `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` on purpose. The lower
+ * of the two wins there, because that is what setting it means.
+ *
+ * `off` removes the operator's ceiling and does NOT remove a plan band: the
+ * word turns off a backstop, and the band is not one.
+ *
+ * An org with no band (`budgetUsd === null`) is unchanged in every case: it
+ * gets exactly the ceiling it got before, default and all. Since AGL-3203
+ * every plan row carries a band, so this is an org whose band was overridden
+ * to zero rather than a tier that sells none.
+ *
+ * ## When the band is a line rather than a wall (AGL-2653)
+ *
+ * `bandRefuses` is `assistBandRefuses(org)`: false on a plan that sells
+ * credits past its band unless the org's `assistOverage.hardCap` is on. A
+ * band that does not refuse is not a ceiling, so it drops out of the
+ * composition and the operator's explicit figure is the only thing left that
+ * can bind — the repo default stays off, for the reason above, and `off`
+ * leaves nothing. The message cap is still there either way, so a workspace
+ * buying overage is bounded by messages a month rather than by nothing; the
+ * overage it buys is priced by `report-usage` at the plan's rate.
+ *
+ * ## An uncapped staff comp (AGL-3049)
+ *
+ * `uncapped` is `isUncappedPlanComp(org)`. Its band resolves `null` — there
+ * is no band — but it is not a workspace that was never sold one, so the
+ * repo default must not stand in for a band here any more than it may
+ * undercut a sold one: a $40 wall on the workspace staff uncapped is exactly
+ * the cap uncapping removes. It composes like a band that does not refuse:
+ * the operator's explicit figure binds, because that is an incident
+ * decision about every workspace, and nothing else does. The message cap
+ * still applies, as it does to every entitled workspace.
+ */
+export declare function assistMonthlyCeilingUsd(budgetUsd: number | null, bandRefuses?: boolean, uncapped?: boolean): number | null;
+/**
+ * The dollar ceiling this org's reservations refuse at that is NOT its own
+ * band, or `null` where none applies — the operator backstop as it binds
+ * this workspace.
+ *
+ * A reservation measured against a band that refuses is the workspace's own
+ * product limit, refused as `band` and told to the customer by the credits
+ * alert. Every other finite ceiling the reservation compares against is a
+ * backstop, refused as `budget`, and that is the stop staff are told about.
+ * Which one applies is `assistMonthlyCeilingUsd`'s decision, so:
+ *
+ *  - a workspace with no band gets the repo default or the operator's figure;
+ *  - a band sold past, or an uncapped staff comp (AGL-3049), gets only an
+ *    operator's explicit figure, and nothing when none is set;
+ *  - a band that is a wall gets the operator's figure only where it sits
+ *    below the band, because only then is the operator's figure what refuses.
+ */
+export declare function assistBackstopCeilingUsd(org: Partial<AglynOrgBilling> | null | undefined): number | null;

package/src/lib/usage/assist-ceiling.js

@@ -0,0 +1,110 @@
+/**
+ * @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 { assistBandRefuses, resolveAssistBudgetUsd } from "@aglyn/aglyn/app-utils/assist-credits";
+import { isUncappedPlanComp } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { assistOperatorCeilingUsd, assistOrgMonthlyCostLimitUsd } from "@aglyn/aglyn/app-utils/usage-budget";
+/*
+ * THE MONTHLY DOLLAR CEILING an assist reservation is measured against, apart
+ * from the reservation itself: pure arithmetic over the org document and the
+ * operator's setting, with nothing that writes. The reservation resolves it
+ * before its transaction opens, and the staff alert that announces a refusal
+ * reads the same composition, so the figure announced is the figure enforced.
+ */ /**
+ * The ceiling one reservation is actually measured against, given the org's
+ * plan band.
+ *
+ * ## Why the repo default must not bind an org that has a band
+ *
+ * `ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD` (in `usage-budget.ts`, beside
+ * the alert that announces the ceiling) is $40, which was sized as a
+ * runaway guard back when every org's assist spend was bounded by a message
+ * cap. It is BELOW what Agency and Enterprise include, so applying it to a
+ * plan band would refuse those workspaces partway through capacity they are
+ * paying for. The rule is not about which tiers happen to clear $40 today: a
+ * band that is sold is a product limit, and a default nobody typed is not
+ * allowed to undercut one at any size.
+ *
+ * ## Why an operator's explicit figure still does
+ *
+ * A self-hoster paying their own provider bill, or an operator responding to
+ * an incident, sets `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` on purpose. The lower
+ * of the two wins there, because that is what setting it means.
+ *
+ * `off` removes the operator's ceiling and does NOT remove a plan band: the
+ * word turns off a backstop, and the band is not one.
+ *
+ * An org with no band (`budgetUsd === null`) is unchanged in every case: it
+ * gets exactly the ceiling it got before, default and all. Since AGL-3203
+ * every plan row carries a band, so this is an org whose band was overridden
+ * to zero rather than a tier that sells none.
+ *
+ * ## When the band is a line rather than a wall (AGL-2653)
+ *
+ * `bandRefuses` is `assistBandRefuses(org)`: false on a plan that sells
+ * credits past its band unless the org's `assistOverage.hardCap` is on. A
+ * band that does not refuse is not a ceiling, so it drops out of the
+ * composition and the operator's explicit figure is the only thing left that
+ * can bind — the repo default stays off, for the reason above, and `off`
+ * leaves nothing. The message cap is still there either way, so a workspace
+ * buying overage is bounded by messages a month rather than by nothing; the
+ * overage it buys is priced by `report-usage` at the plan's rate.
+ *
+ * ## An uncapped staff comp (AGL-3049)
+ *
+ * `uncapped` is `isUncappedPlanComp(org)`. Its band resolves `null` — there
+ * is no band — but it is not a workspace that was never sold one, so the
+ * repo default must not stand in for a band here any more than it may
+ * undercut a sold one: a $40 wall on the workspace staff uncapped is exactly
+ * the cap uncapping removes. It composes like a band that does not refuse:
+ * the operator's explicit figure binds, because that is an incident
+ * decision about every workspace, and nothing else does. The message cap
+ * still applies, as it does to every entitled workspace.
+ */ export function assistMonthlyCeilingUsd(budgetUsd, bandRefuses = true, uncapped = false) {
+    const configured = process.env.ASSIST_ORG_MONTHLY_COGS_LIMIT_USD;
+    if (uncapped) {
+        const operator = assistOperatorCeilingUsd(configured);
+        return typeof operator === 'number' ? operator : null;
+    }
+    if (budgetUsd === null) return assistOrgMonthlyCostLimitUsd(configured);
+    const operator = assistOperatorCeilingUsd(configured);
+    if (!bandRefuses) return typeof operator === 'number' ? operator : null;
+    return typeof operator === 'number' ? Math.min(budgetUsd, operator) : budgetUsd;
+}
+/**
+ * The dollar ceiling this org's reservations refuse at that is NOT its own
+ * band, or `null` where none applies — the operator backstop as it binds
+ * this workspace.
+ *
+ * A reservation measured against a band that refuses is the workspace's own
+ * product limit, refused as `band` and told to the customer by the credits
+ * alert. Every other finite ceiling the reservation compares against is a
+ * backstop, refused as `budget`, and that is the stop staff are told about.
+ * Which one applies is `assistMonthlyCeilingUsd`'s decision, so:
+ *
+ *  - a workspace with no band gets the repo default or the operator's figure;
+ *  - a band sold past, or an uncapped staff comp (AGL-3049), gets only an
+ *    operator's explicit figure, and nothing when none is set;
+ *  - a band that is a wall gets the operator's figure only where it sits
+ *    below the band, because only then is the operator's figure what refuses.
+ */ export function assistBackstopCeilingUsd(org) {
+    const budgetUsd = resolveAssistBudgetUsd(org);
+    const bandRefuses = assistBandRefuses(org);
+    const ceilingUsd = assistMonthlyCeilingUsd(budgetUsd, bandRefuses, isUncappedPlanComp(org));
+    const ceilingIsBand = bandRefuses && budgetUsd !== null && ceilingUsd === budgetUsd;
+    return ceilingIsBand ? null : ceilingUsd;
+}
+
+//# sourceMappingURL=assist-ceiling.js.map

package/src/lib/usage/assist-ceiling.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/assist-ceiling.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  assistBandRefuses,\n  resolveAssistBudgetUsd,\n} from '@aglyn/aglyn/app-utils/assist-credits'\nimport { isUncappedPlanComp } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport {\n  assistOperatorCeilingUsd,\n  assistOrgMonthlyCostLimitUsd,\n} from '@aglyn/aglyn/app-utils/usage-budget'\nimport type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\n\n/*\n * THE MONTHLY DOLLAR CEILING an assist reservation is measured against, apart\n * from the reservation itself: pure arithmetic over the org document and the\n * operator's setting, with nothing that writes. The reservation resolves it\n * before its transaction opens, and the staff alert that announces a refusal\n * reads the same composition, so the figure announced is the figure enforced.\n */\n\n/**\n * The ceiling one reservation is actually measured against, given the org's\n * plan band.\n *\n * ## Why the repo default must not bind an org that has a band\n *\n * `ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD` (in `usage-budget.ts`, beside\n * the alert that announces the ceiling) is $40, which was sized as a\n * runaway guard back when every org's assist spend was bounded by a message\n * cap. It is BELOW what Agency and Enterprise include, so applying it to a\n * plan band would refuse those workspaces partway through capacity they are\n * paying for. The rule is not about which tiers happen to clear $40 today: a\n * band that is sold is a product limit, and a default nobody typed is not\n * allowed to undercut one at any size.\n *\n * ## Why an operator's explicit figure still does\n *\n * A self-hoster paying their own provider bill, or an operator responding to\n * an incident, sets `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` on purpose. The lower\n * of the two wins there, because that is what setting it means.\n *\n * `off` removes the operator's ceiling and does NOT remove a plan band: the\n * word turns off a backstop, and the band is not one.\n *\n * An org with no band (`budgetUsd === null`) is unchanged in every case: it\n * gets exactly the ceiling it got before, default and all. Since AGL-3203\n * every plan row carries a band, so this is an org whose band was overridden\n * to zero rather than a tier that sells none.\n *\n * ## When the band is a line rather than a wall (AGL-2653)\n *\n * `bandRefuses` is `assistBandRefuses(org)`: false on a plan that sells\n * credits past its band unless the org's `assistOverage.hardCap` is on. A\n * band that does not refuse is not a ceiling, so it drops out of the\n * composition and the operator's explicit figure is the only thing left that\n * can bind — the repo default stays off, for the reason above, and `off`\n * leaves nothing. The message cap is still there either way, so a workspace\n * buying overage is bounded by messages a month rather than by nothing; the\n * overage it buys is priced by `report-usage` at the plan's rate.\n *\n * ## An uncapped staff comp (AGL-3049)\n *\n * `uncapped` is `isUncappedPlanComp(org)`. Its band resolves `null` — there\n * is no band — but it is not a workspace that was never sold one, so the\n * repo default must not stand in for a band here any more than it may\n * undercut a sold one: a $40 wall on the workspace staff uncapped is exactly\n * the cap uncapping removes. It composes like a band that does not refuse:\n * the operator's explicit figure binds, because that is an incident\n * decision about every workspace, and nothing else does. The message cap\n * still applies, as it does to every entitled workspace.\n */\nexport function assistMonthlyCeilingUsd(\n  budgetUsd: number | null,\n  bandRefuses = true,\n  uncapped = false,\n): number | null {\n  const configured = process.env.ASSIST_ORG_MONTHLY_COGS_LIMIT_USD\n  if (uncapped) {\n    const operator = assistOperatorCeilingUsd(configured)\n    return typeof operator === 'number' ? operator : null\n  }\n  if (budgetUsd === null) return assistOrgMonthlyCostLimitUsd(configured)\n  const operator = assistOperatorCeilingUsd(configured)\n  if (!bandRefuses) return typeof operator === 'number' ? operator : null\n  return typeof operator === 'number'\n    ? Math.min(budgetUsd, operator)\n    : budgetUsd\n}\n\n/**\n * The dollar ceiling this org's reservations refuse at that is NOT its own\n * band, or `null` where none applies — the operator backstop as it binds\n * this workspace.\n *\n * A reservation measured against a band that refuses is the workspace's own\n * product limit, refused as `band` and told to the customer by the credits\n * alert. Every other finite ceiling the reservation compares against is a\n * backstop, refused as `budget`, and that is the stop staff are told about.\n * Which one applies is `assistMonthlyCeilingUsd`'s decision, so:\n *\n *  - a workspace with no band gets the repo default or the operator's figure;\n *  - a band sold past, or an uncapped staff comp (AGL-3049), gets only an\n *    operator's explicit figure, and nothing when none is set;\n *  - a band that is a wall gets the operator's figure only where it sits\n *    below the band, because only then is the operator's figure what refuses.\n */\nexport function assistBackstopCeilingUsd(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): number | null {\n  const budgetUsd = resolveAssistBudgetUsd(org)\n  const bandRefuses = assistBandRefuses(org)\n  const ceilingUsd = assistMonthlyCeilingUsd(\n    budgetUsd,\n    bandRefuses,\n    isUncappedPlanComp(org),\n  )\n  const ceilingIsBand =\n    bandRefuses && budgetUsd !== null && ceilingUsd === budgetUsd\n  return ceilingIsBand ? null : ceilingUsd\n}\n"],"names":["assistBandRefuses","resolveAssistBudgetUsd","isUncappedPlanComp","assistOperatorCeilingUsd","assistOrgMonthlyCostLimitUsd","assistMonthlyCeilingUsd","budgetUsd","bandRefuses","uncapped","configured","process","env","ASSIST_ORG_MONTHLY_COGS_LIMIT_USD","operator","Math","min","assistBackstopCeilingUsd","org","ceilingUsd","ceilingIsBand"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,iBAAiB,EACjBC,sBAAsB,QACjB,wCAAuC;AAC9C,SAASC,kBAAkB,QAAQ,2CAA0C;AAC7E,SACEC,wBAAwB,EACxBC,4BAA4B,QACvB,sCAAqC;AAG5C;;;;;;CAMC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDC,GACD,OAAO,SAASC,wBACdC,SAAwB,EACxBC,cAAc,IAAI,EAClBC,WAAW,KAAK;IAEhB,MAAMC,aAAaC,QAAQC,GAAG,CAACC,iCAAiC;IAChE,IAAIJ,UAAU;QACZ,MAAMK,WAAWV,yBAAyBM;QAC1C,OAAO,OAAOI,aAAa,WAAWA,WAAW;IACnD;IACA,IAAIP,cAAc,MAAM,OAAOF,6BAA6BK;IAC5D,MAAMI,WAAWV,yBAAyBM;IAC1C,IAAI,CAACF,aAAa,OAAO,OAAOM,aAAa,WAAWA,WAAW;IACnE,OAAO,OAAOA,aAAa,WACvBC,KAAKC,GAAG,CAACT,WAAWO,YACpBP;AACN;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASU,yBACdC,GAAgD;IAEhD,MAAMX,YAAYL,uBAAuBgB;IACzC,MAAMV,cAAcP,kBAAkBiB;IACtC,MAAMC,aAAab,wBACjBC,WACAC,aACAL,mBAAmBe;IAErB,MAAME,gBACJZ,eAAeD,cAAc,QAAQY,eAAeZ;IACtD,OAAOa,gBAAgB,OAAOD;AAChC"}