@aglyn/plugins-ai 1.0.0-beta.219 → 1.0.0-beta.220

package/src/lib/usage-axes.js

@@ -13,7 +13,8 @@
  * 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_CREDIT_COST_USD, ASSIST_PROVIDER_COST_FIELD } from "@aglyn/aglyn/app-utils/assist-credits";
+ */ import { AI_USAGE_METER_ID } from "./constants.js";
+import { ASSIST_CREDIT_COST_USD, ASSIST_PROVIDER_COST_FIELD } from "./usage/assist-credits.js";
 /**
  * THE AI PLUGIN'S METER (AGL-3080): provider spend, in the platform's cost
  * model and against the credit band in its utilization table. Compiled into
@@ -34,7 +35,16 @@
  * The band is sold in credits, and a credit is `ASSIST_CREDIT_COST_USD` of
  * spend, so what was used is the dollars over that — rounded up, the one
  * conversion the customer's own meter uses.
- */ export function aiUsageAxes() {
+ *
+ * On the usage BUDGET the month's spend is the billed figure (`estCostUsd`),
+ * shown to the customer in credits and never in dollars: the dollars are our
+ * cost, and publishing them would put our model choice and our margin on a
+ * billing page. It counts toward the budget only from the month
+ * `BILL_ASSIST_TOKENS_FROM` names, because assist is a plan entitlement with
+ * no per-token price until then, and a budget that added it would be a
+ * surprise bill invented by a notification.
+ */ /** The AI plugin's line of a workspace's monthly spend, by the id it declares. */ export const AI_ASSIST_SPEND_LINE_ID = 'assist';
+export function aiUsageAxes() {
     return {
         costAxes: [
             {
@@ -43,6 +53,14 @@
                 fields: [
                     'assistCostUsd'
                 ],
+                // The month's credit draw and the overage that entered `billedCents`
+                // (AGL-2930), which the usage sweep writes beside the spend: the
+                // staff usage table's AI columns, `null` on a rollup written before
+                // the sweep recorded credits, and never a cost.
+                staffFields: [
+                    'assistCredits',
+                    'assistOverageUsd'
+                ],
                 live: {
                     collection: 'assistUsage',
                     fields: [
@@ -63,6 +81,26 @@
                 entitlement: 'assistCreditsPerMonth',
                 unitCostUsd: ASSIST_CREDIT_COST_USD
             }
+        ],
+        meters: [
+            {
+                id: AI_USAGE_METER_ID
+            }
+        ],
+        spendLines: [
+            {
+                id: AI_ASSIST_SPEND_LINE_ID,
+                label: 'Assist',
+                live: {
+                    collection: 'assistUsage',
+                    field: 'estCostUsd'
+                },
+                billedFromEnv: 'BILL_ASSIST_TOKENS_FROM',
+                unit: {
+                    costUsd: ASSIST_CREDIT_COST_USD,
+                    label: 'Assist credits'
+                }
+            }
         ]
     };
 }

package/src/lib/usage-axes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/plugins/ai/src/lib/usage-axes.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 { PluginUsageAxesDeclaration } from '@aglyn/aglyn/plugin-manager/plugin-usage-axes'\nimport {\n  ASSIST_CREDIT_COST_USD,\n  ASSIST_PROVIDER_COST_FIELD,\n} from '@aglyn/aglyn/app-utils/assist-credits'\n\n/**\n * THE AI PLUGIN'S METER (AGL-3080): provider spend, in the platform's cost\n * model and against the credit band in its utilization table. Compiled into\n * core by the manifest generator (`register.usageAxes`).\n *\n * The rollup records `assistCostUsd` — what the month's tokens cost US, at\n * the provider's rates (AGL-3015) — so the axis enters the cost model at ×1\n * and names no rate. It is the one line on the platform whose unit cost is\n * real money paid to a third party, and the only one that can clear the\n * $2/site floor on its own, which is why a margin surface that could not see\n * it would rate a token-heavy workspace exactly as it rates an idle one.\n *\n * LIVE, because the rollup is a snapshot from when the cron ran and assist\n * keeps spending after it: a reader that fetches the month's\n * `assistUsage/{month}` document takes the provider figure, or the billed\n * one on a month closed before the two were split, over the snapshot.\n *\n * The band is sold in credits, and a credit is `ASSIST_CREDIT_COST_USD` of\n * spend, so what was used is the dollars over that — rounded up, the one\n * conversion the customer's own meter uses.\n */\nexport function aiUsageAxes(): PluginUsageAxesDeclaration {\n  return {\n    costAxes: [\n      {\n        id: 'assist',\n        order: 80,\n        fields: ['assistCostUsd'],\n        live: {\n          collection: 'assistUsage',\n          fields: [ASSIST_PROVIDER_COST_FIELD, 'estCostUsd'],\n        },\n      },\n    ],\n    bands: [\n      {\n        id: 'assistCredits',\n        label: 'Assist credits',\n        order: 90,\n        fields: ['assistCostUsd'],\n        entitlement: 'assistCreditsPerMonth',\n        unitCostUsd: ASSIST_CREDIT_COST_USD,\n      },\n    ],\n  }\n}\n"],"names":["ASSIST_CREDIT_COST_USD","ASSIST_PROVIDER_COST_FIELD","aiUsageAxes","costAxes","id","order","fields","live","collection","bands","label","entitlement","unitCostUsd"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SACEA,sBAAsB,EACtBC,0BAA0B,QACrB,wCAAuC;AAE9C;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC;IACd,OAAO;QACLC,UAAU;YACR;gBACEC,IAAI;gBACJC,OAAO;gBACPC,QAAQ;oBAAC;iBAAgB;gBACzBC,MAAM;oBACJC,YAAY;oBACZF,QAAQ;wBAACL;wBAA4B;qBAAa;gBACpD;YACF;SACD;QACDQ,OAAO;YACL;gBACEL,IAAI;gBACJM,OAAO;gBACPL,OAAO;gBACPC,QAAQ;oBAAC;iBAAgB;gBACzBK,aAAa;gBACbC,aAAaZ;YACf;SACD;IACH;AACF"}
+{"version":3,"sources":["../../../../../../libs/plugins/ai/src/lib/usage-axes.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 { PluginUsageAxesDeclaration } from '@aglyn/aglyn/plugin-manager/plugin-usage-axes'\nimport { AI_USAGE_METER_ID } from './constants'\nimport {\n  ASSIST_CREDIT_COST_USD,\n  ASSIST_PROVIDER_COST_FIELD,\n} from './usage/assist-credits'\n\n/**\n * THE AI PLUGIN'S METER (AGL-3080): provider spend, in the platform's cost\n * model and against the credit band in its utilization table. Compiled into\n * core by the manifest generator (`register.usageAxes`).\n *\n * The rollup records `assistCostUsd` — what the month's tokens cost US, at\n * the provider's rates (AGL-3015) — so the axis enters the cost model at ×1\n * and names no rate. It is the one line on the platform whose unit cost is\n * real money paid to a third party, and the only one that can clear the\n * $2/site floor on its own, which is why a margin surface that could not see\n * it would rate a token-heavy workspace exactly as it rates an idle one.\n *\n * LIVE, because the rollup is a snapshot from when the cron ran and assist\n * keeps spending after it: a reader that fetches the month's\n * `assistUsage/{month}` document takes the provider figure, or the billed\n * one on a month closed before the two were split, over the snapshot.\n *\n * The band is sold in credits, and a credit is `ASSIST_CREDIT_COST_USD` of\n * spend, so what was used is the dollars over that — rounded up, the one\n * conversion the customer's own meter uses.\n *\n * On the usage BUDGET the month's spend is the billed figure (`estCostUsd`),\n * shown to the customer in credits and never in dollars: the dollars are our\n * cost, and publishing them would put our model choice and our margin on a\n * billing page. It counts toward the budget only from the month\n * `BILL_ASSIST_TOKENS_FROM` names, because assist is a plan entitlement with\n * no per-token price until then, and a budget that added it would be a\n * surprise bill invented by a notification.\n */\n/** The AI plugin's line of a workspace's monthly spend, by the id it declares. */\nexport const AI_ASSIST_SPEND_LINE_ID = 'assist'\n\nexport function aiUsageAxes(): PluginUsageAxesDeclaration {\n  return {\n    costAxes: [\n      {\n        id: 'assist',\n        order: 80,\n        fields: ['assistCostUsd'],\n        // The month's credit draw and the overage that entered `billedCents`\n        // (AGL-2930), which the usage sweep writes beside the spend: the\n        // staff usage table's AI columns, `null` on a rollup written before\n        // the sweep recorded credits, and never a cost.\n        staffFields: ['assistCredits', 'assistOverageUsd'],\n        live: {\n          collection: 'assistUsage',\n          fields: [ASSIST_PROVIDER_COST_FIELD, 'estCostUsd'],\n        },\n      },\n    ],\n    bands: [\n      {\n        id: 'assistCredits',\n        label: 'Assist credits',\n        order: 90,\n        fields: ['assistCostUsd'],\n        entitlement: 'assistCreditsPerMonth',\n        unitCostUsd: ASSIST_CREDIT_COST_USD,\n      },\n    ],\n    meters: [{ id: AI_USAGE_METER_ID }],\n    spendLines: [\n      {\n        id: AI_ASSIST_SPEND_LINE_ID,\n        label: 'Assist',\n        live: { collection: 'assistUsage', field: 'estCostUsd' },\n        billedFromEnv: 'BILL_ASSIST_TOKENS_FROM',\n        unit: { costUsd: ASSIST_CREDIT_COST_USD, label: 'Assist credits' },\n      },\n    ],\n  }\n}\n"],"names":["AI_USAGE_METER_ID","ASSIST_CREDIT_COST_USD","ASSIST_PROVIDER_COST_FIELD","AI_ASSIST_SPEND_LINE_ID","aiUsageAxes","costAxes","id","order","fields","staffFields","live","collection","bands","label","entitlement","unitCostUsd","meters","spendLines","field","billedFromEnv","unit","costUsd"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,iBAAiB,QAAQ,iBAAa;AAC/C,SACEC,sBAAsB,EACtBC,0BAA0B,QACrB,4BAAwB;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,gFAAgF,GAChF,OAAO,MAAMC,0BAA0B,SAAQ;AAE/C,OAAO,SAASC;IACd,OAAO;QACLC,UAAU;YACR;gBACEC,IAAI;gBACJC,OAAO;gBACPC,QAAQ;oBAAC;iBAAgB;gBACzB,qEAAqE;gBACrE,iEAAiE;gBACjE,oEAAoE;gBACpE,gDAAgD;gBAChDC,aAAa;oBAAC;oBAAiB;iBAAmB;gBAClDC,MAAM;oBACJC,YAAY;oBACZH,QAAQ;wBAACN;wBAA4B;qBAAa;gBACpD;YACF;SACD;QACDU,OAAO;YACL;gBACEN,IAAI;gBACJO,OAAO;gBACPN,OAAO;gBACPC,QAAQ;oBAAC;iBAAgB;gBACzBM,aAAa;gBACbC,aAAad;YACf;SACD;QACDe,QAAQ;YAAC;gBAAEV,IAAIN;YAAkB;SAAE;QACnCiB,YAAY;YACV;gBACEX,IAAIH;gBACJU,OAAO;gBACPH,MAAM;oBAAEC,YAAY;oBAAeO,OAAO;gBAAa;gBACvDC,eAAe;gBACfC,MAAM;oBAAEC,SAASpB;oBAAwBY,OAAO;gBAAiB;YACnE;SACD;IACH;AACF"}