@aglyn/plugins-ai 1.0.0-beta.237 → 1.0.0-beta.238

package/src/lib/server/ai-jobs-cancel.d.ts

@@ -15,11 +15,19 @@
  * limitations under the License.
  */
 /**
- * Cancel a job (AGL-2904). Idempotent: a job already terminal answers as
- * it is, unchanged. A step in flight is not interrupted — the runner that
- * holds its lease records what it cost and finds the job canceled when it
- * goes to complete it — so a cancel is never a way to spend tokens the
- * document does not show. Audited per cancel that changed something.
+ * Cancel a job (AGL-2904, AGL-3616). `POST /api/ai/jobs/{jobId}/cancel`
+ * `{ orgId }`.
+ *
+ * Who may: a member who holds `ai.generate` on the job's site (the
+ * permission that started it), or staff, member or not. Anyone else is
+ * refused 403 and the job is untouched.
+ *
+ * What it does is `cancelAiJob`'s, in one transaction: a job no step holds
+ * ends `canceled` now; a job whose step is in flight records the cancel and
+ * ends `canceled` when that step finishes or aborts, which the answer's
+ * `job.cancelRequested` says. Idempotent: a job already done, failed or
+ * canceled answers as it is, `changed: false`. Audited per cancel that
+ * changed something.
  */
 export declare function POST(request: Request, context: {
     params: Promise<{

package/src/lib/server/ai-jobs-cancel.js

@@ -1,3 +1,4 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
 /**
  * @license
  * Copyright 2026 Aglyn LLC
@@ -15,13 +16,22 @@
  * limitations under the License.
  */ // lockdown-423: via libs/plugins/ai/src/lib/server/ai-jobs-gate.ts
 import { aiJobSummary, cancelAiJob, getAiJob, writeAiJobAudit } from "../jobs/ai-jobs.js";
+import { memberHasPermissionOnHost, permissionRefusal } from "@aglyn/tenant-data-admin/server/organizations";
 import { aiJobsGate } from "./ai-jobs-gate.js";
 /**
- * Cancel a job (AGL-2904). Idempotent: a job already terminal answers as
- * it is, unchanged. A step in flight is not interrupted — the runner that
- * holds its lease records what it cost and finds the job canceled when it
- * goes to complete it — so a cancel is never a way to spend tokens the
- * document does not show. Audited per cancel that changed something.
+ * Cancel a job (AGL-2904, AGL-3616). `POST /api/ai/jobs/{jobId}/cancel`
+ * `{ orgId }`.
+ *
+ * Who may: a member who holds `ai.generate` on the job's site (the
+ * permission that started it), or staff, member or not. Anyone else is
+ * refused 403 and the job is untouched.
+ *
+ * What it does is `cancelAiJob`'s, in one transaction: a job no step holds
+ * ends `canceled` now; a job whose step is in flight records the cancel and
+ * ends `canceled` when that step finishes or aborts, which the answer's
+ * `job.cancelRequested` says. Idempotent: a job already done, failed or
+ * canceled answers as it is, `changed: false`. Audited per cancel that
+ * changed something.
  */ export async function POST(request, context) {
     var _ref, _gate_decoded_email;
     let payload;
@@ -30,7 +40,9 @@ import { aiJobsGate } from "./ai-jobs-gate.js";
     } catch (unused) {
         payload = null;
     }
-    const gate = await aiJobsGate(request, String((_ref = payload == null ? void 0 : payload.orgId) != null ? _ref : ''));
+    const gate = await aiJobsGate(request, String((_ref = payload == null ? void 0 : payload.orgId) != null ? _ref : ''), {
+        staffWithoutMembership: true
+    });
     if (gate instanceof Response) return gate;
     const { jobId } = await context.params;
     const existing = await getAiJob(gate.firestore, gate.orgId, jobId);
@@ -39,6 +51,10 @@ import { aiJobsGate } from "./ai-jobs-gate.js";
     }, {
         status: 404
     });
+    // The job's own permission, on the job's own site (AGL-3616).
+    if (!gate.staff && !await memberHasPermissionOnHost(gate.orgId, existing.hostId, gate.member, 'ai.generate')) {
+        return permissionRefusal('ai.generate');
+    }
     const now = new Date();
     // The machine writes the org feed's row with this actor when the cancel
     // changed something; the staff audit row below is this route's own.
@@ -54,11 +70,13 @@ import { aiJobsGate } from "./ai-jobs-gate.js";
             actorEmail: (_gate_decoded_email1 = gate.decoded.email) != null ? _gate_decoded_email1 : null,
             orgId: gate.orgId,
             jobId,
-            after: {
-                status: 'canceled',
+            after: _extends({
+                status: job.status,
                 wasStatus: existing.status,
                 kind: existing.kind
-            }
+            }, gate.staff ? {
+                staff: true
+            } : {})
         });
     }
     return Response.json({

package/src/lib/server/ai-jobs-cancel.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-jobs-cancel.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// lockdown-423: via libs/plugins/ai/src/lib/server/ai-jobs-gate.ts\n\nimport {\n  aiJobSummary,\n  cancelAiJob,\n  getAiJob,\n  writeAiJobAudit,\n} from '../jobs/ai-jobs'\nimport { aiJobsGate } from './ai-jobs-gate'\n\n/**\n * Cancel a job (AGL-2904). Idempotent: a job already terminal answers as\n * it is, unchanged. A step in flight is not interrupted — the runner that\n * holds its lease records what it cost and finds the job canceled when it\n * goes to complete it — so a cancel is never a way to spend tokens the\n * document does not show. Audited per cancel that changed something.\n */\nexport async function POST(\n  request: Request,\n  context: { params: Promise<{ jobId: string }> },\n): Promise<Response> {\n  let payload: Record<string, unknown> | null\n  try {\n    payload = (await request.json()) as Record<string, unknown>\n  } catch {\n    payload = null\n  }\n  const gate = await aiJobsGate(request, String(payload?.orgId ?? ''))\n  if (gate instanceof Response) return gate\n  const { jobId } = await context.params\n  const existing = await getAiJob(gate.firestore, gate.orgId, jobId)\n  if (!existing) return Response.json({ error: 'Unknown job' }, { status: 404 })\n  const now = new Date()\n  // The machine writes the org feed's row with this actor when the cancel\n  // changed something; the staff audit row below is this route's own.\n  const { job, changed } = await cancelAiJob(gate.firestore, gate.orgId, jobId, now, {\n    uid: gate.uid,\n    email: gate.decoded.email ?? null,\n  })\n  if (changed) {\n    await writeAiJobAudit(gate.firestore, {\n      action: 'ai.job.cancel',\n      actorUid: gate.uid,\n      actorEmail: gate.decoded.email ?? null,\n      orgId: gate.orgId,\n      jobId,\n      after: { status: 'canceled', wasStatus: existing.status, kind: existing.kind },\n    })\n  }\n  return Response.json({ job: aiJobSummary(job, now), changed }, { status: 200 })\n}\n\nexport const dynamic = 'force-dynamic'\nexport const maxDuration = 60\n"],"names":["aiJobSummary","cancelAiJob","getAiJob","writeAiJobAudit","aiJobsGate","POST","request","context","gate","payload","json","String","orgId","Response","jobId","params","existing","firestore","error","status","now","Date","job","changed","uid","email","decoded","action","actorUid","actorEmail","after","wasStatus","kind","dynamic","maxDuration"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,mEAAmE;AAEnE,SACEA,YAAY,EACZC,WAAW,EACXC,QAAQ,EACRC,eAAe,QACV,qBAAiB;AACxB,SAASC,UAAU,QAAQ,oBAAgB;AAE3C;;;;;;CAMC,GACD,OAAO,eAAeC,KACpBC,OAAgB,EAChBC,OAA+C;cAkBtCC;IAhBT,IAAIC;IACJ,IAAI;QACFA,UAAW,MAAMH,QAAQI,IAAI;IAC/B,EAAE,eAAM;QACND,UAAU;IACZ;IACA,MAAMD,OAAO,MAAMJ,WAAWE,SAASK,eAAOF,2BAAAA,QAASG,KAAK,mBAAI;IAChE,IAAIJ,gBAAgBK,UAAU,OAAOL;IACrC,MAAM,EAAEM,KAAK,EAAE,GAAG,MAAMP,QAAQQ,MAAM;IACtC,MAAMC,WAAW,MAAMd,SAASM,KAAKS,SAAS,EAAET,KAAKI,KAAK,EAAEE;IAC5D,IAAI,CAACE,UAAU,OAAOH,SAASH,IAAI,CAAC;QAAEQ,OAAO;IAAc,GAAG;QAAEC,QAAQ;IAAI;IAC5E,MAAMC,MAAM,IAAIC;IAChB,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,EAAEC,GAAG,EAAEC,OAAO,EAAE,GAAG,MAAMtB,YAAYO,KAAKS,SAAS,EAAET,KAAKI,KAAK,EAAEE,OAAOM,KAAK;QACjFI,KAAKhB,KAAKgB,GAAG;QACbC,KAAK,GAAEjB,sBAAAA,KAAKkB,OAAO,CAACD,KAAK,YAAlBjB,sBAAsB;IAC/B;IACA,IAAIe,SAAS;YAIGf;QAHd,MAAML,gBAAgBK,KAAKS,SAAS,EAAE;YACpCU,QAAQ;YACRC,UAAUpB,KAAKgB,GAAG;YAClBK,UAAU,GAAErB,uBAAAA,KAAKkB,OAAO,CAACD,KAAK,YAAlBjB,uBAAsB;YAClCI,OAAOJ,KAAKI,KAAK;YACjBE;YACAgB,OAAO;gBAAEX,QAAQ;gBAAYY,WAAWf,SAASG,MAAM;gBAAEa,MAAMhB,SAASgB,IAAI;YAAC;QAC/E;IACF;IACA,OAAOnB,SAASH,IAAI,CAAC;QAAEY,KAAKtB,aAAasB,KAAKF;QAAMG;IAAQ,GAAG;QAAEJ,QAAQ;IAAI;AAC/E;AAEA,OAAO,MAAMc,UAAU,gBAAe;AACtC,OAAO,MAAMC,cAAc,GAAE"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-jobs-cancel.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// lockdown-423: via libs/plugins/ai/src/lib/server/ai-jobs-gate.ts\n\nimport {\n  aiJobSummary,\n  cancelAiJob,\n  getAiJob,\n  writeAiJobAudit,\n} from '../jobs/ai-jobs'\nimport { memberHasPermissionOnHost, permissionRefusal } from '@aglyn/tenant-data-admin/server/organizations'\nimport { aiJobsGate } from './ai-jobs-gate'\n\n/**\n * Cancel a job (AGL-2904, AGL-3616). `POST /api/ai/jobs/{jobId}/cancel`\n * `{ orgId }`.\n *\n * Who may: a member who holds `ai.generate` on the job's site (the\n * permission that started it), or staff, member or not. Anyone else is\n * refused 403 and the job is untouched.\n *\n * What it does is `cancelAiJob`'s, in one transaction: a job no step holds\n * ends `canceled` now; a job whose step is in flight records the cancel and\n * ends `canceled` when that step finishes or aborts, which the answer's\n * `job.cancelRequested` says. Idempotent: a job already done, failed or\n * canceled answers as it is, `changed: false`. Audited per cancel that\n * changed something.\n */\nexport async function POST(\n  request: Request,\n  context: { params: Promise<{ jobId: string }> },\n): Promise<Response> {\n  let payload: Record<string, unknown> | null\n  try {\n    payload = (await request.json()) as Record<string, unknown>\n  } catch {\n    payload = null\n  }\n  const gate = await aiJobsGate(request, String(payload?.orgId ?? ''), { staffWithoutMembership: true })\n  if (gate instanceof Response) return gate\n  const { jobId } = await context.params\n  const existing = await getAiJob(gate.firestore, gate.orgId, jobId)\n  if (!existing) return Response.json({ error: 'Unknown job' }, { status: 404 })\n  // The job's own permission, on the job's own site (AGL-3616).\n  if (!gate.staff && !(await memberHasPermissionOnHost(gate.orgId, existing.hostId, gate.member, 'ai.generate'))) {\n    return permissionRefusal('ai.generate')\n  }\n  const now = new Date()\n  // The machine writes the org feed's row with this actor when the cancel\n  // changed something; the staff audit row below is this route's own.\n  const { job, changed } = await cancelAiJob(gate.firestore, gate.orgId, jobId, now, {\n    uid: gate.uid,\n    email: gate.decoded.email ?? null,\n  })\n  if (changed) {\n    await writeAiJobAudit(gate.firestore, {\n      action: 'ai.job.cancel',\n      actorUid: gate.uid,\n      actorEmail: gate.decoded.email ?? null,\n      orgId: gate.orgId,\n      jobId,\n      after: {\n        status: job.status,\n        wasStatus: existing.status,\n        kind: existing.kind,\n        ...(gate.staff ? { staff: true } : {}),\n      },\n    })\n  }\n  return Response.json({ job: aiJobSummary(job, now), changed }, { status: 200 })\n}\n\nexport const dynamic = 'force-dynamic'\nexport const maxDuration = 60\n"],"names":["aiJobSummary","cancelAiJob","getAiJob","writeAiJobAudit","memberHasPermissionOnHost","permissionRefusal","aiJobsGate","POST","request","context","gate","payload","json","String","orgId","staffWithoutMembership","Response","jobId","params","existing","firestore","error","status","staff","hostId","member","now","Date","job","changed","uid","email","decoded","action","actorUid","actorEmail","after","wasStatus","kind","dynamic","maxDuration"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,mEAAmE;AAEnE,SACEA,YAAY,EACZC,WAAW,EACXC,QAAQ,EACRC,eAAe,QACV,qBAAiB;AACxB,SAASC,yBAAyB,EAAEC,iBAAiB,QAAQ,gDAA+C;AAC5G,SAASC,UAAU,QAAQ,oBAAgB;AAE3C;;;;;;;;;;;;;;CAcC,GACD,OAAO,eAAeC,KACpBC,OAAgB,EAChBC,OAA+C;cAsBtCC;IApBT,IAAIC;IACJ,IAAI;QACFA,UAAW,MAAMH,QAAQI,IAAI;IAC/B,EAAE,eAAM;QACND,UAAU;IACZ;IACA,MAAMD,OAAO,MAAMJ,WAAWE,SAASK,eAAOF,2BAAAA,QAASG,KAAK,mBAAI,KAAK;QAAEC,wBAAwB;IAAK;IACpG,IAAIL,gBAAgBM,UAAU,OAAON;IACrC,MAAM,EAAEO,KAAK,EAAE,GAAG,MAAMR,QAAQS,MAAM;IACtC,MAAMC,WAAW,MAAMjB,SAASQ,KAAKU,SAAS,EAAEV,KAAKI,KAAK,EAAEG;IAC5D,IAAI,CAACE,UAAU,OAAOH,SAASJ,IAAI,CAAC;QAAES,OAAO;IAAc,GAAG;QAAEC,QAAQ;IAAI;IAC5E,8DAA8D;IAC9D,IAAI,CAACZ,KAAKa,KAAK,IAAI,CAAE,MAAMnB,0BAA0BM,KAAKI,KAAK,EAAEK,SAASK,MAAM,EAAEd,KAAKe,MAAM,EAAE,gBAAiB;QAC9G,OAAOpB,kBAAkB;IAC3B;IACA,MAAMqB,MAAM,IAAIC;IAChB,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,EAAEC,GAAG,EAAEC,OAAO,EAAE,GAAG,MAAM5B,YAAYS,KAAKU,SAAS,EAAEV,KAAKI,KAAK,EAAEG,OAAOS,KAAK;QACjFI,KAAKpB,KAAKoB,GAAG;QACbC,KAAK,GAAErB,sBAAAA,KAAKsB,OAAO,CAACD,KAAK,YAAlBrB,sBAAsB;IAC/B;IACA,IAAImB,SAAS;YAIGnB;QAHd,MAAMP,gBAAgBO,KAAKU,SAAS,EAAE;YACpCa,QAAQ;YACRC,UAAUxB,KAAKoB,GAAG;YAClBK,UAAU,GAAEzB,uBAAAA,KAAKsB,OAAO,CAACD,KAAK,YAAlBrB,uBAAsB;YAClCI,OAAOJ,KAAKI,KAAK;YACjBG;YACAmB,OAAO;gBACLd,QAAQM,IAAIN,MAAM;gBAClBe,WAAWlB,SAASG,MAAM;gBAC1BgB,MAAMnB,SAASmB,IAAI;eACf5B,KAAKa,KAAK,GAAG;gBAAEA,OAAO;YAAK,IAAI,CAAC;QAExC;IACF;IACA,OAAOP,SAASJ,IAAI,CAAC;QAAEgB,KAAK5B,aAAa4B,KAAKF;QAAMG;IAAQ,GAAG;QAAEP,QAAQ;IAAI;AAC/E;AAEA,OAAO,MAAMiB,UAAU,gBAAe;AACtC,OAAO,MAAMC,cAAc,GAAE"}

package/src/lib/server/ai-jobs-gate.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import type { DecodedIdToken } from 'firebase-admin/auth';
-import type { AglynOrganization } from '@aglyn/aglyn/foundation/definitions/organization.types';
+import type { AglynOrganization, AglynOrgMember } from '@aglyn/aglyn/foundation/definitions/organization.types';
 /**
  * The gate the READ and CANCEL doors of AI jobs climb (AGL-2904).
  *
@@ -42,6 +42,16 @@ export interface AiJobsGateContext {
     staff: boolean;
     orgId: string;
     org: Partial<AglynOrganization>;
+    /** The caller's membership; `null` only for staff let in by `staffWithoutMembership`. */
+    member: AglynOrgMember | null;
     firestore: FirebaseFirestore.Firestore;
 }
-export declare function aiJobsGate(request: Request, rawOrgId: string): Promise<Response | AiJobsGateContext>;
+export interface AiJobsGateOptions {
+    /**
+     * A verified staff claim passes the membership rung for an org it is not a
+     * member of (AGL-3616): staff stop a customer's job from the job's own
+     * page. Every rung after it is climbed as for anyone else.
+     */
+    staffWithoutMembership?: boolean;
+}
+export declare function aiJobsGate(request: Request, rawOrgId: string, options?: AiJobsGateOptions): Promise<Response | AiJobsGateContext>;

package/src/lib/server/ai-jobs-gate.js

@@ -28,8 +28,7 @@ function bearerToken(request) {
     const authorization = (_request_headers_get = request.headers.get('authorization')) != null ? _request_headers_get : '';
     return authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
 }
-export async function aiJobsGate(request, rawOrgId) {
-    var _resolved_org;
+export async function aiJobsGate(request, rawOrgId, options = {}) {
     const idToken = bearerToken(request);
     if (!idToken) {
         return Response.json({
@@ -63,14 +62,25 @@ export async function aiJobsGate(request, rawOrgId) {
         });
     }
     const resolved = await getOrgForUser(decoded.uid, orgId);
-    if (!resolved || resolved.orgId !== orgId) {
-        return Response.json({
-            error: 'You are not a member of that organization'
-        }, {
-            status: 403
-        });
+    let org;
+    let member;
+    if (resolved && resolved.orgId === orgId) {
+        var _resolved_org, _resolved_member;
+        org = (_resolved_org = resolved.org) != null ? _resolved_org : {};
+        member = (_resolved_member = resolved.member) != null ? _resolved_member : null;
+    } else {
+        var _staffOrg_data;
+        const staffOrg = staff && options.staffWithoutMembership ? await app.firestore().collection('orgs').doc(orgId).get() : null;
+        if (!(staffOrg == null ? void 0 : staffOrg.exists)) {
+            return Response.json({
+                error: 'You are not a member of that organization'
+            }, {
+                status: 403
+            });
+        }
+        org = (_staffOrg_data = staffOrg.data()) != null ? _staffOrg_data : {};
+        member = null;
     }
-    const org = (_resolved_org = resolved.org) != null ? _resolved_org : {};
     if (!staff && !await isServerReleaseFlagOnForOrg('release_ai_generative', orgId)) {
         return Response.json({
             error: 'Not found'
@@ -99,6 +109,7 @@ export async function aiJobsGate(request, rawOrgId) {
         staff,
         orgId,
         org,
+        member,
         firestore: app.firestore()
     };
 }

package/src/lib/server/ai-jobs-gate.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-jobs-gate.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 { DecodedIdToken } from 'firebase-admin/auth'\nimport { checkEntitlement } from '@aglyn/aglyn/server'\nimport type { AglynOrganization } from '@aglyn/aglyn/foundation/definitions/organization.types'\n// By their own entry points rather than the barrel, for the reason the chat\n// route gives for the runtime: the route specs replace the barrel with a\n// closed-world factory, and a leaf that is mocked at its own seam is one\n// the spec can drive rung by rung.\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { lockdownRefusal } from '@aglyn/tenant-data-admin/server/lockdown'\nimport { getOrgForUser } from '@aglyn/tenant-data-admin/server/organizations'\nimport { isServerReleaseFlagOnForOrg } from '@aglyn/tenant-data-admin/server/release-flags'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\n\n/**\n * The gate the READ and CANCEL doors of AI jobs climb (AGL-2904).\n *\n * `aiGateLadder` is the ladder a door that SPENDS climbs: it is POST-only\n * and ends by taking a reservation, because its whole purpose is to bound\n * provider spend. Listing a workspace's jobs, watching one, or canceling\n * one spends nothing and answers a GET, so those doors climb the same\n * rungs up to the lockdown verdict and stop there — no rate window and no\n * reservation. The rungs are in the ladder's order, for the ladder's\n * reason: each one refused discloses nothing a lower rung would.\n *\n *   401  no bearer token, or a token the verifier refused\n *   403  email unverified (an impersonation session is exempt)\n *   400  the request did not NAME the org (AGL-1934)\n *   403  the caller is not a member of that org\n *   404  the release flag is off — a released-off feature does not exist;\n *        a verified staff claim previews through it\n *   403  the org's plan lacks `aiGenerative`\n *   423  lockdown: the scope verdict (platform/org/user)\n */\nexport interface AiJobsGateContext {\n  uid: string\n  decoded: DecodedIdToken\n  staff: boolean\n  orgId: string\n  org: Partial<AglynOrganization>\n  firestore: FirebaseFirestore.Firestore\n}\n\nfunction bearerToken(request: Request): string | undefined {\n  const authorization = request.headers.get('authorization') ?? ''\n  return authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n}\n\nexport async function aiJobsGate(\n  request: Request,\n  rawOrgId: string,\n): Promise<Response | AiJobsGateContext> {\n  const idToken = bearerToken(request)\n  if (!idToken) {\n    return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n  }\n  const app = firebaseAdmin.app()\n  let decoded: DecodedIdToken\n  try {\n    decoded = await app.auth().verifyIdToken(idToken)\n  } catch (error) {\n    // A refused credential is the caller's fault and a 401; anything else\n    // is ours and propagates so the door answers 500 rather than telling\n    // every user their credential is bad during an outage (AGL-1993).\n    const unauthenticated = invalidIdTokenResponse(error)\n    if (unauthenticated) return unauthenticated\n    throw error\n  }\n  if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n    return emailUnverifiedResponse()\n  }\n  const staff = decoded['staff'] === true\n\n  const orgId = rawOrgId.trim()\n  if (!orgId) {\n    return Response.json(\n      { error: 'Open a workspace before using this feature' },\n      { status: 400 },\n    )\n  }\n  const resolved = await getOrgForUser(decoded.uid, orgId)\n  if (!resolved || resolved.orgId !== orgId) {\n    return Response.json(\n      { error: 'You are not a member of that organization' },\n      { status: 403 },\n    )\n  }\n  const org = resolved.org ?? {}\n\n  if (!staff && !(await isServerReleaseFlagOnForOrg('release_ai_generative', orgId))) {\n    return Response.json({ error: 'Not found' }, { status: 404 })\n  }\n  if (!checkEntitlement(org, 'aiGenerative')) {\n    return Response.json(\n      {\n        error: \"This workspace's plan does not include that feature\",\n        reason: 'entitlement',\n      },\n      { status: 403 },\n    )\n  }\n  const locked = await lockdownRefusal({\n    request,\n    staff,\n    uid: decoded.uid,\n    org: org as Record<string, unknown>,\n  })\n  if (locked) return locked\n\n  return {\n    uid: decoded.uid,\n    decoded,\n    staff,\n    orgId,\n    org,\n    firestore: app.firestore(),\n  }\n}\n"],"names":["checkEntitlement","emailUnverifiedResponse","firebaseAdmin","isImpersonationSession","lockdownRefusal","getOrgForUser","isServerReleaseFlagOnForOrg","invalidIdTokenResponse","bearerToken","request","authorization","headers","get","startsWith","slice","length","undefined","aiJobsGate","rawOrgId","resolved","idToken","Response","json","error","status","app","decoded","auth","verifyIdToken","unauthenticated","email_verified","staff","orgId","trim","uid","org","reason","locked","firestore"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,gBAAgB,QAAQ,sBAAqB;AAEtD,4EAA4E;AAC5E,yEAAyE;AACzE,yEAAyE;AACzE,mCAAmC;AACnC,SACEC,uBAAuB,EACvBC,aAAa,EACbC,sBAAsB,QACjB,iDAAgD;AACvD,SAASC,eAAe,QAAQ,2CAA0C;AAC1E,SAASC,aAAa,QAAQ,gDAA+C;AAC7E,SAASC,2BAA2B,QAAQ,gDAA+C;AAC3F,SAASC,sBAAsB,QAAQ,mDAAkD;AA+BzF,SAASC,YAAYC,OAAgB;QACbA;IAAtB,MAAMC,iBAAgBD,uBAAAA,QAAQE,OAAO,CAACC,GAAG,CAAC,4BAApBH,uBAAwC;IAC9D,OAAOC,cAAcG,UAAU,CAAC,aAC5BH,cAAcI,KAAK,CAAC,UAAUC,MAAM,IACpCC;AACN;AAEA,OAAO,eAAeC,WACpBR,OAAgB,EAChBS,QAAgB;QAqCJC;IAnCZ,MAAMC,UAAUZ,YAAYC;IAC5B,IAAI,CAACW,SAAS;QACZ,OAAOC,SAASC,IAAI,CAAC;YAAEC,OAAO;QAAkB,GAAG;YAAEC,QAAQ;QAAI;IACnE;IACA,MAAMC,MAAMvB,cAAcuB,GAAG;IAC7B,IAAIC;IACJ,IAAI;QACFA,UAAU,MAAMD,IAAIE,IAAI,GAAGC,aAAa,CAACR;IAC3C,EAAE,OAAOG,OAAO;QACd,sEAAsE;QACtE,qEAAqE;QACrE,kEAAkE;QAClE,MAAMM,kBAAkBtB,uBAAuBgB;QAC/C,IAAIM,iBAAiB,OAAOA;QAC5B,MAAMN;IACR;IACA,IAAI,CAACG,QAAQI,cAAc,IAAI,CAAC3B,uBAAuBuB,UAAU;QAC/D,OAAOzB;IACT;IACA,MAAM8B,QAAQL,OAAO,CAAC,QAAQ,KAAK;IAEnC,MAAMM,QAAQd,SAASe,IAAI;IAC3B,IAAI,CAACD,OAAO;QACV,OAAOX,SAASC,IAAI,CAClB;YAAEC,OAAO;QAA6C,GACtD;YAAEC,QAAQ;QAAI;IAElB;IACA,MAAML,WAAW,MAAMd,cAAcqB,QAAQQ,GAAG,EAAEF;IAClD,IAAI,CAACb,YAAYA,SAASa,KAAK,KAAKA,OAAO;QACzC,OAAOX,SAASC,IAAI,CAClB;YAAEC,OAAO;QAA4C,GACrD;YAAEC,QAAQ;QAAI;IAElB;IACA,MAAMW,OAAMhB,gBAAAA,SAASgB,GAAG,YAAZhB,gBAAgB,CAAC;IAE7B,IAAI,CAACY,SAAS,CAAE,MAAMzB,4BAA4B,yBAAyB0B,QAAS;QAClF,OAAOX,SAASC,IAAI,CAAC;YAAEC,OAAO;QAAY,GAAG;YAAEC,QAAQ;QAAI;IAC7D;IACA,IAAI,CAACxB,iBAAiBmC,KAAK,iBAAiB;QAC1C,OAAOd,SAASC,IAAI,CAClB;YACEC,OAAO;YACPa,QAAQ;QACV,GACA;YAAEZ,QAAQ;QAAI;IAElB;IACA,MAAMa,SAAS,MAAMjC,gBAAgB;QACnCK;QACAsB;QACAG,KAAKR,QAAQQ,GAAG;QAChBC,KAAKA;IACP;IACA,IAAIE,QAAQ,OAAOA;IAEnB,OAAO;QACLH,KAAKR,QAAQQ,GAAG;QAChBR;QACAK;QACAC;QACAG;QACAG,WAAWb,IAAIa,SAAS;IAC1B;AACF"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-jobs-gate.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 { DecodedIdToken } from 'firebase-admin/auth'\nimport { checkEntitlement } from '@aglyn/aglyn/server'\nimport type { AglynOrganization, AglynOrgMember } from '@aglyn/aglyn/foundation/definitions/organization.types'\n// By their own entry points rather than the barrel, for the reason the chat\n// route gives for the runtime: the route specs replace the barrel with a\n// closed-world factory, and a leaf that is mocked at its own seam is one\n// the spec can drive rung by rung.\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { lockdownRefusal } from '@aglyn/tenant-data-admin/server/lockdown'\nimport { getOrgForUser } from '@aglyn/tenant-data-admin/server/organizations'\nimport { isServerReleaseFlagOnForOrg } from '@aglyn/tenant-data-admin/server/release-flags'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\n\n/**\n * The gate the READ and CANCEL doors of AI jobs climb (AGL-2904).\n *\n * `aiGateLadder` is the ladder a door that SPENDS climbs: it is POST-only\n * and ends by taking a reservation, because its whole purpose is to bound\n * provider spend. Listing a workspace's jobs, watching one, or canceling\n * one spends nothing and answers a GET, so those doors climb the same\n * rungs up to the lockdown verdict and stop there — no rate window and no\n * reservation. The rungs are in the ladder's order, for the ladder's\n * reason: each one refused discloses nothing a lower rung would.\n *\n *   401  no bearer token, or a token the verifier refused\n *   403  email unverified (an impersonation session is exempt)\n *   400  the request did not NAME the org (AGL-1934)\n *   403  the caller is not a member of that org\n *   404  the release flag is off — a released-off feature does not exist;\n *        a verified staff claim previews through it\n *   403  the org's plan lacks `aiGenerative`\n *   423  lockdown: the scope verdict (platform/org/user)\n */\nexport interface AiJobsGateContext {\n  uid: string\n  decoded: DecodedIdToken\n  staff: boolean\n  orgId: string\n  org: Partial<AglynOrganization>\n  /** The caller's membership; `null` only for staff let in by `staffWithoutMembership`. */\n  member: AglynOrgMember | null\n  firestore: FirebaseFirestore.Firestore\n}\n\nexport interface AiJobsGateOptions {\n  /**\n   * A verified staff claim passes the membership rung for an org it is not a\n   * member of (AGL-3616): staff stop a customer's job from the job's own\n   * page. Every rung after it is climbed as for anyone else.\n   */\n  staffWithoutMembership?: boolean\n}\n\nfunction bearerToken(request: Request): string | undefined {\n  const authorization = request.headers.get('authorization') ?? ''\n  return authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n}\n\nexport async function aiJobsGate(\n  request: Request,\n  rawOrgId: string,\n  options: AiJobsGateOptions = {},\n): Promise<Response | AiJobsGateContext> {\n  const idToken = bearerToken(request)\n  if (!idToken) {\n    return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n  }\n  const app = firebaseAdmin.app()\n  let decoded: DecodedIdToken\n  try {\n    decoded = await app.auth().verifyIdToken(idToken)\n  } catch (error) {\n    // A refused credential is the caller's fault and a 401; anything else\n    // is ours and propagates so the door answers 500 rather than telling\n    // every user their credential is bad during an outage (AGL-1993).\n    const unauthenticated = invalidIdTokenResponse(error)\n    if (unauthenticated) return unauthenticated\n    throw error\n  }\n  if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n    return emailUnverifiedResponse()\n  }\n  const staff = decoded['staff'] === true\n\n  const orgId = rawOrgId.trim()\n  if (!orgId) {\n    return Response.json(\n      { error: 'Open a workspace before using this feature' },\n      { status: 400 },\n    )\n  }\n  const resolved = await getOrgForUser(decoded.uid, orgId)\n  let org: Partial<AglynOrganization>\n  let member: AglynOrgMember | null\n  if (resolved && resolved.orgId === orgId) {\n    org = resolved.org ?? {}\n    member = resolved.member ?? null\n  } else {\n    const staffOrg =\n      staff && options.staffWithoutMembership\n        ? await app.firestore().collection('orgs').doc(orgId).get()\n        : null\n    if (!staffOrg?.exists) {\n      return Response.json(\n        { error: 'You are not a member of that organization' },\n        { status: 403 },\n      )\n    }\n    org = (staffOrg.data() ?? {}) as Partial<AglynOrganization>\n    member = null\n  }\n\n  if (!staff && !(await isServerReleaseFlagOnForOrg('release_ai_generative', orgId))) {\n    return Response.json({ error: 'Not found' }, { status: 404 })\n  }\n  if (!checkEntitlement(org, 'aiGenerative')) {\n    return Response.json(\n      {\n        error: \"This workspace's plan does not include that feature\",\n        reason: 'entitlement',\n      },\n      { status: 403 },\n    )\n  }\n  const locked = await lockdownRefusal({\n    request,\n    staff,\n    uid: decoded.uid,\n    org: org as Record<string, unknown>,\n  })\n  if (locked) return locked\n\n  return {\n    uid: decoded.uid,\n    decoded,\n    staff,\n    orgId,\n    org,\n    member,\n    firestore: app.firestore(),\n  }\n}\n"],"names":["checkEntitlement","emailUnverifiedResponse","firebaseAdmin","isImpersonationSession","lockdownRefusal","getOrgForUser","isServerReleaseFlagOnForOrg","invalidIdTokenResponse","bearerToken","request","authorization","headers","get","startsWith","slice","length","undefined","aiJobsGate","rawOrgId","options","idToken","Response","json","error","status","app","decoded","auth","verifyIdToken","unauthenticated","email_verified","staff","orgId","trim","resolved","uid","org","member","staffOrg","staffWithoutMembership","firestore","collection","doc","exists","data","reason","locked"],"mappings":"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"}

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

@@ -25,7 +25,8 @@ import { type AiUsageMeterWire } from './ai-usage-wire';
  * Every figure is credits. The pool comes through `publicAssistQuota`, the
  * one projection allowed to turn our provider bill into a customer figure;
  * the caller's month comes off the allotment gate, which the meter wrote in
- * credits in the first place.
+ * credits in the first place — or, on the Free plan, off the person's Free
+ * allowance the reservation read, net of give-backs (AGL-3722).
  *
  * `last` is added to both months, because the reservation measured them
  * BEFORE this exchange and the strip is read after it.

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

@@ -16,6 +16,8 @@
  */ import { aiCatalogEntry } from "../providers/catalog.js";
 import { publicAssistQuota } from "./assist-usage.js";
 import { aiUsageMeterState } from "./ai-usage-wire.js";
+import { assistCreditsFromUsd } from "./assist-credits.js";
+import { FREE_AI_TASTE_CREDITS_PER_MONTH } from "../plan-entitlements.js";
 /**
  * The usage strip's envelope from what a door already holds (AGL-2942): the
  * reservation it took and, once the provider answered, what the exchange
@@ -25,7 +27,8 @@ import { aiUsageMeterState } from "./ai-usage-wire.js";
  * Every figure is credits. The pool comes through `publicAssistQuota`, the
  * one projection allowed to turn our provider bill into a customer figure;
  * the caller's month comes off the allotment gate, which the meter wrote in
- * credits in the first place.
+ * credits in the first place — or, on the Free plan, off the person's Free
+ * allowance the reservation read, net of give-backs (AGL-3722).
  *
  * `last` is added to both months, because the reservation measured them
  * BEFORE this exchange and the strip is read after it.
@@ -50,11 +53,24 @@ import { aiUsageMeterState } from "./ai-usage-wire.js";
     }
     const gate = (_reservation_allotment = reservation.allotment) != null ? _reservation_allotment : null;
     const binding = (_ref = gate == null ? void 0 : gate.binding) != null ? _ref : null;
+    // On the Free plan the person's own line is their Free allowance (AGL-3722):
+    // 300 credits a month across every Free workspace they hold, net of
+    // give-backs — the wall the reservation refuses at. The workspace's
+    // per-member row it used to read is gross (a refund or a staff reset never
+    // reaches it) and this workspace's alone, so it said "You: 401 credits this
+    // month" to a person with 48 of their 300 left (2026-10-10).
+    const freeAccountUsd = reservation.free ? reservation.freeAccountCostUsd : null;
     const mine = binding ? {
         used: binding.used + spent,
         limit: binding.credits,
         mode: binding.mode,
         scope: binding.scope
+    } : typeof freeAccountUsd === 'number' && Number.isFinite(freeAccountUsd) ? {
+        used: assistCreditsFromUsd(freeAccountUsd) + spent,
+        limit: FREE_AI_TASTE_CREDITS_PER_MONTH,
+        mode: 'hard',
+        scope: null,
+        free: true
     } : {
         used: ((_ref1 = gate == null ? void 0 : gate.personalCredits) != null ? _ref1 : 0) + spent,
         limit: null,

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-meter.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 { aiCatalogEntry } from '../providers/catalog'\nimport { publicAssistQuota, type AssistReservation } from './assist-usage'\nimport { aiUsageMeterState, type AiUsageMeterWire } from './ai-usage-wire'\n\n/**\n * The usage strip's envelope from what a door already holds (AGL-2942): the\n * reservation it took and, once the provider answered, what the exchange\n * cost. No read — the reservation measured the pool and the caller's month\n * inside the transaction it already runs.\n *\n * Every figure is credits. The pool comes through `publicAssistQuota`, the\n * one projection allowed to turn our provider bill into a customer figure;\n * the caller's month comes off the allotment gate, which the meter wrote in\n * credits in the first place.\n *\n * `last` is added to both months, because the reservation measured them\n * BEFORE this exchange and the strip is read after it.\n */\nexport function aiUsageMeter(\n  reservation: Pick<AssistReservation, 'monthKey' | 'allowed'> &\n    Partial<AssistReservation>,\n  extra: {\n    lastCredits?: number | null\n    model?: { id: string; auto: boolean } | null\n  } = {},\n): AiUsageMeterWire {\n  const last =\n    typeof extra.lastCredits === 'number' && Number.isFinite(extra.lastCredits)\n      ? Math.max(0, Math.ceil(extra.lastCredits))\n      : null\n  const spent = last ?? 0\n  let pool: AiUsageMeterWire['pool'] = { used: spent, limit: null }\n  try {\n    const credits = publicAssistQuota(reservation as AssistReservation)?.credits\n    if (credits) pool = { used: credits.used + spent, limit: credits.limit }\n  } catch {\n    // A reservation without its dollar figures (a double, a refusal taken\n    // before the month was read) reports the exchange alone.\n  }\n  const gate = reservation.allotment ?? null\n  const binding = gate?.binding ?? null\n  const mine: AiUsageMeterWire['mine'] = binding\n    ? {\n        used: binding.used + spent,\n        limit: binding.credits,\n        mode: binding.mode,\n        scope: binding.scope,\n      }\n    : {\n        used: (gate?.personalCredits ?? 0) + spent,\n        limit: null,\n        mode: null,\n        scope: null,\n      }\n  const refused = !reservation.allowed\n  const entry = extra.model ? aiCatalogEntry(extra.model.id) : undefined\n  return {\n    month: reservation.monthKey,\n    pool,\n    mine,\n    last,\n    refused,\n    state: aiUsageMeterState({ pool, mine, refused }),\n    model:\n      extra.model && entry\n        ? { id: entry.id, label: entry.label, auto: extra.model.auto }\n        : null,\n  }\n}\n"],"names":["aiCatalogEntry","publicAssistQuota","aiUsageMeterState","aiUsageMeter","reservation","extra","last","lastCredits","Number","isFinite","Math","max","ceil","spent","pool","used","limit","credits","gate","allotment","binding","mine","mode","scope","personalCredits","refused","allowed","entry","model","id","undefined","month","monthKey","state","label","auto"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,0BAAsB;AACrD,SAASC,iBAAiB,QAAgC,oBAAgB;AAC1E,SAASC,iBAAiB,QAA+B,qBAAiB;AAE1E;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,aACdC,WAC4B,EAC5BC,QAGI,CAAC,CAAC;QAeOD;IAbb,MAAME,OACJ,OAAOD,MAAME,WAAW,KAAK,YAAYC,OAAOC,QAAQ,CAACJ,MAAME,WAAW,IACtEG,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAACP,MAAME,WAAW,KACvC;IACN,MAAMM,QAAQP,eAAAA,OAAQ;IACtB,IAAIQ,OAAiC;QAAEC,MAAMF;QAAOG,OAAO;IAAK;IAChE,IAAI;YACcf;QAAhB,MAAMgB,WAAUhB,qBAAAA,kBAAkBG,iCAAlBH,mBAAqDgB,OAAO;QAC5E,IAAIA,SAASH,OAAO;YAAEC,MAAME,QAAQF,IAAI,GAAGF;YAAOG,OAAOC,QAAQD,KAAK;QAAC;IACzE,EAAE,eAAM;IACN,sEAAsE;IACtE,yDAAyD;IAC3D;IACA,MAAME,QAAOd,yBAAAA,YAAYe,SAAS,YAArBf,yBAAyB;IACtC,MAAMgB,kBAAUF,wBAAAA,KAAME,OAAO,mBAAI;IACjC,MAAMC,OAAiCD,UACnC;QACEL,MAAMK,QAAQL,IAAI,GAAGF;QACrBG,OAAOI,QAAQH,OAAO;QACtBK,MAAMF,QAAQE,IAAI;QAClBC,OAAOH,QAAQG,KAAK;IACtB,IACA;QACER,MAAM,UAACG,wBAAAA,KAAMM,eAAe,oBAAI,KAAKX;QACrCG,OAAO;QACPM,MAAM;QACNC,OAAO;IACT;IACJ,MAAME,UAAU,CAACrB,YAAYsB,OAAO;IACpC,MAAMC,QAAQtB,MAAMuB,KAAK,GAAG5B,eAAeK,MAAMuB,KAAK,CAACC,EAAE,IAAIC;IAC7D,OAAO;QACLC,OAAO3B,YAAY4B,QAAQ;QAC3BlB;QACAO;QACAf;QACAmB;QACAQ,OAAO/B,kBAAkB;YAAEY;YAAMO;YAAMI;QAAQ;QAC/CG,OACEvB,MAAMuB,KAAK,IAAID,QACX;YAAEE,IAAIF,MAAME,EAAE;YAAEK,OAAOP,MAAMO,KAAK;YAAEC,MAAM9B,MAAMuB,KAAK,CAACO,IAAI;QAAC,IAC3D;IACR;AACF"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-meter.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 { aiCatalogEntry } from '../providers/catalog'\nimport { publicAssistQuota, type AssistReservation } from './assist-usage'\nimport { aiUsageMeterState, type AiUsageMeterWire } from './ai-usage-wire'\nimport { assistCreditsFromUsd } from './assist-credits'\nimport { FREE_AI_TASTE_CREDITS_PER_MONTH } from '../plan-entitlements'\n\n/**\n * The usage strip's envelope from what a door already holds (AGL-2942): the\n * reservation it took and, once the provider answered, what the exchange\n * cost. No read — the reservation measured the pool and the caller's month\n * inside the transaction it already runs.\n *\n * Every figure is credits. The pool comes through `publicAssistQuota`, the\n * one projection allowed to turn our provider bill into a customer figure;\n * the caller's month comes off the allotment gate, which the meter wrote in\n * credits in the first place — or, on the Free plan, off the person's Free\n * allowance the reservation read, net of give-backs (AGL-3722).\n *\n * `last` is added to both months, because the reservation measured them\n * BEFORE this exchange and the strip is read after it.\n */\nexport function aiUsageMeter(\n  reservation: Pick<AssistReservation, 'monthKey' | 'allowed'> &\n    Partial<AssistReservation>,\n  extra: {\n    lastCredits?: number | null\n    model?: { id: string; auto: boolean } | null\n  } = {},\n): AiUsageMeterWire {\n  const last =\n    typeof extra.lastCredits === 'number' && Number.isFinite(extra.lastCredits)\n      ? Math.max(0, Math.ceil(extra.lastCredits))\n      : null\n  const spent = last ?? 0\n  let pool: AiUsageMeterWire['pool'] = { used: spent, limit: null }\n  try {\n    const credits = publicAssistQuota(reservation as AssistReservation)?.credits\n    if (credits) pool = { used: credits.used + spent, limit: credits.limit }\n  } catch {\n    // A reservation without its dollar figures (a double, a refusal taken\n    // before the month was read) reports the exchange alone.\n  }\n  const gate = reservation.allotment ?? null\n  const binding = gate?.binding ?? null\n  // On the Free plan the person's own line is their Free allowance (AGL-3722):\n  // 300 credits a month across every Free workspace they hold, net of\n  // give-backs — the wall the reservation refuses at. The workspace's\n  // per-member row it used to read is gross (a refund or a staff reset never\n  // reaches it) and this workspace's alone, so it said \"You: 401 credits this\n  // month\" to a person with 48 of their 300 left (2026-10-10).\n  const freeAccountUsd = reservation.free ? reservation.freeAccountCostUsd : null\n  const mine: AiUsageMeterWire['mine'] = binding\n    ? {\n        used: binding.used + spent,\n        limit: binding.credits,\n        mode: binding.mode,\n        scope: binding.scope,\n      }\n    : typeof freeAccountUsd === 'number' && Number.isFinite(freeAccountUsd)\n      ? {\n          used: assistCreditsFromUsd(freeAccountUsd) + spent,\n          limit: FREE_AI_TASTE_CREDITS_PER_MONTH,\n          mode: 'hard',\n          scope: null,\n          free: true,\n        }\n      : {\n          used: (gate?.personalCredits ?? 0) + spent,\n          limit: null,\n          mode: null,\n          scope: null,\n        }\n  const refused = !reservation.allowed\n  const entry = extra.model ? aiCatalogEntry(extra.model.id) : undefined\n  return {\n    month: reservation.monthKey,\n    pool,\n    mine,\n    last,\n    refused,\n    state: aiUsageMeterState({ pool, mine, refused }),\n    model:\n      extra.model && entry\n        ? { id: entry.id, label: entry.label, auto: extra.model.auto }\n        : null,\n  }\n}\n"],"names":["aiCatalogEntry","publicAssistQuota","aiUsageMeterState","assistCreditsFromUsd","FREE_AI_TASTE_CREDITS_PER_MONTH","aiUsageMeter","reservation","extra","last","lastCredits","Number","isFinite","Math","max","ceil","spent","pool","used","limit","credits","gate","allotment","binding","freeAccountUsd","free","freeAccountCostUsd","mine","mode","scope","personalCredits","refused","allowed","entry","model","id","undefined","month","monthKey","state","label","auto"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,0BAAsB;AACrD,SAASC,iBAAiB,QAAgC,oBAAgB;AAC1E,SAASC,iBAAiB,QAA+B,qBAAiB;AAC1E,SAASC,oBAAoB,QAAQ,sBAAkB;AACvD,SAASC,+BAA+B,QAAQ,0BAAsB;AAEtE;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,aACdC,WAC4B,EAC5BC,QAGI,CAAC,CAAC;QAeOD;IAbb,MAAME,OACJ,OAAOD,MAAME,WAAW,KAAK,YAAYC,OAAOC,QAAQ,CAACJ,MAAME,WAAW,IACtEG,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAACP,MAAME,WAAW,KACvC;IACN,MAAMM,QAAQP,eAAAA,OAAQ;IACtB,IAAIQ,OAAiC;QAAEC,MAAMF;QAAOG,OAAO;IAAK;IAChE,IAAI;YACcjB;QAAhB,MAAMkB,WAAUlB,qBAAAA,kBAAkBK,iCAAlBL,mBAAqDkB,OAAO;QAC5E,IAAIA,SAASH,OAAO;YAAEC,MAAME,QAAQF,IAAI,GAAGF;YAAOG,OAAOC,QAAQD,KAAK;QAAC;IACzE,EAAE,eAAM;IACN,sEAAsE;IACtE,yDAAyD;IAC3D;IACA,MAAME,QAAOd,yBAAAA,YAAYe,SAAS,YAArBf,yBAAyB;IACtC,MAAMgB,kBAAUF,wBAAAA,KAAME,OAAO,mBAAI;IACjC,6EAA6E;IAC7E,oEAAoE;IACpE,oEAAoE;IACpE,2EAA2E;IAC3E,4EAA4E;IAC5E,6DAA6D;IAC7D,MAAMC,iBAAiBjB,YAAYkB,IAAI,GAAGlB,YAAYmB,kBAAkB,GAAG;IAC3E,MAAMC,OAAiCJ,UACnC;QACEL,MAAMK,QAAQL,IAAI,GAAGF;QACrBG,OAAOI,QAAQH,OAAO;QACtBQ,MAAML,QAAQK,IAAI;QAClBC,OAAON,QAAQM,KAAK;IACtB,IACA,OAAOL,mBAAmB,YAAYb,OAAOC,QAAQ,CAACY,kBACpD;QACEN,MAAMd,qBAAqBoB,kBAAkBR;QAC7CG,OAAOd;QACPuB,MAAM;QACNC,OAAO;QACPJ,MAAM;IACR,IACA;QACEP,MAAM,UAACG,wBAAAA,KAAMS,eAAe,oBAAI,KAAKd;QACrCG,OAAO;QACPS,MAAM;QACNC,OAAO;IACT;IACN,MAAME,UAAU,CAACxB,YAAYyB,OAAO;IACpC,MAAMC,QAAQzB,MAAM0B,KAAK,GAAGjC,eAAeO,MAAM0B,KAAK,CAACC,EAAE,IAAIC;IAC7D,OAAO;QACLC,OAAO9B,YAAY+B,QAAQ;QAC3BrB;QACAU;QACAlB;QACAsB;QACAQ,OAAOpC,kBAAkB;YAAEc;YAAMU;YAAMI;QAAQ;QAC/CG,OACE1B,MAAM0B,KAAK,IAAID,QACX;YAAEE,IAAIF,MAAME,EAAE;YAAEK,OAAOP,MAAMO,KAAK;YAAEC,MAAMjC,MAAM0B,KAAK,CAACO,IAAI;QAAC,IAC3D;IACR;AACF"}

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

@@ -100,6 +100,12 @@ export interface AiUsageMeterWire {
         limit: number | null;
         mode: AiAllotmentMode | null;
         scope: AiCreditAllotmentScope | null;
+        /**
+         * `mine` is the person's Free allowance (AGL-3722): `used` of the 300
+         * free credits a month every Free workspace they hold draws on, net of
+         * give-backs. Absent on a paid workspace.
+         */
+        free?: boolean;
     };
     /** Credits the exchange this envelope answers cost; `null` when no model ran. */
     last: number | null;

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

@@ -1 +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":"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"}
+{"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     * `mine` is the person's Free allowance (AGL-3722): `used` of the 300\n     * free credits a month every Free workspace they hold draws on, net of\n     * give-backs. Absent on a paid workspace.\n     */\n    free?: boolean\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":"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"}

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

@@ -269,6 +269,13 @@ export interface AssistReservation extends AssistQuotaVerdict {
      * on, and the record must charge that account and no other.
      */
     free: FreeAssistAccount | null;
+    /**
+     * The Free account's month in billed USD, net of give-backs, as read inside
+     * the transaction (AGL-3722) — the allowance every Free workspace of the
+     * person draws on. `null` for a paid workspace and for a reservation that
+     * did not read it. Optional so a double without it reads as not read.
+     */
+    freeAccountCostUsd?: number | null;
     /**
      * Measured provider spend for `monthKey` in USD as read inside the
      * transaction, or `null` when the transaction did not consult it.

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

@@ -414,6 +414,9 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
         // Net of any credits given back this month (AGL-3595), so a give-back
         // re-opens the band it was meant to re-open.
         const costUsd = monthlySnapshot ? assistSpendAfterReturnsUsd(monthlySnapshot.get('estCostUsd'), monthlySnapshot.get(ASSIST_RETURNED_USD_FIELD)) : null;
+        // The person's Free allowance, net of give-backs (AGL-3722): what the
+        // usage strip says is theirs, never the workspace's gross per-member row.
+        const freeAccountCostUsd = accountSnapshot ? assistSpendAfterReturnsUsd(accountSnapshot.get('estCostUsd'), accountSnapshot.get(ASSIST_RETURNED_USD_FIELD)) : null;
         if (!(used < limit)) {
             recordAssistRefusal(firestore, orgId, month, 'messages');
             return {
@@ -428,7 +431,8 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costUsd,
                 costLimitUsd,
                 budgetUsd,
-                free
+                free,
+                freeAccountCostUsd
             };
         }
         // The dollar ceiling, checked AFTER the message cap so the cheaper and
@@ -449,7 +453,8 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costUsd,
                 costLimitUsd,
                 budgetUsd,
-                free
+                free,
+                freeAccountCostUsd
             };
         }
         // The org's ceiling on its OVERAGE (AGL-2898), checked after the band
@@ -478,7 +483,8 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costUsd,
                 costLimitUsd,
                 budgetUsd,
-                free
+                free,
+                freeAccountCostUsd
             };
         }
         // AGLYN'S OWN OVERAGE GUARDS (AGL-3011), after the workspace's own
@@ -518,7 +524,8 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costUsd,
                 costLimitUsd,
                 budgetUsd,
-                free
+                free,
+                freeAccountCostUsd
             };
         }
         // The allotments that apply to the person asking (AGL-2942): read only
@@ -541,6 +548,7 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costLimitUsd,
                 budgetUsd,
                 free,
+                freeAccountCostUsd,
                 allotment
             };
         }
@@ -563,6 +571,7 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
                 costLimitUsd,
                 budgetUsd,
                 free,
+                freeAccountCostUsd,
                 allotment
             };
         }
@@ -602,6 +611,7 @@ async function reserveInTransaction(firestore, orgId, entitled, now, org, subjec
             costLimitUsd,
             budgetUsd,
             free,
+            freeAccountCostUsd,
             allotment
         };
     });