@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/jobs/ai-jobs-beat.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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 SweepAiJobsResult } from './ai-jobs';
+/**
+ * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).
+ *
+ * A job's first step runs inline in the console route when it can; every
+ * step after it, every step too long for an inline door, and any step a
+ * budget cut short, runs here. The sweep bounds itself at
+ * `AI_JOB_SWEEP_BUDGET_MS` of wall clock and hands the rest to the next beat
+ * — the ordering of the queue is the cursor, so nothing is stored between
+ * beats and nothing can be skipped.
+ *
+ * ## Why the console runs it
+ *
+ * A step calls the AI provider, and the provider's key is held by the
+ * console alone: the tenant app serves every published site, and a
+ * credential it holds is one request-handling bug away from a visitor. So
+ * the beat is a console route (`server/ai-jobs-beat-route.ts`, registered
+ * by the console surface), driven every minute by its own Cloud Scheduler
+ * job in `cloud/functions` on the console's cron secret — the reason the
+ * sending-domain sweep is a console route and not a job on the tenant's
+ * platform beat. A beat must resolve to the minute: a step handed back by
+ * a budget, or a page pass waiting on the next, should resume on the next
+ * minute, not the next quarter hour.
+ *
+ * ## The kill switch
+ *
+ * `ai-generate` on the staff lockdown page is the lever for a provider
+ * incident or a spend runaway on the generative doors, and this beat is the
+ * one generative caller with no request to refuse. So it asks the same
+ * feature verdict a door would — the platform scope and then the feature
+ * document — and does nothing while either is locked. A job it leaves
+ * queued stays queued: its lease is not taken, so nothing expires and
+ * nothing is lost, and the first beat after the lock lifts picks it up.
+ *
+ * The same switch paused for ONE workspace (AGL-3037) holds that workspace's
+ * jobs and no other's: `runAiJobStep` asks the verdict with the job's org
+ * before it claims a step, and leaves a paused workspace's job queued.
+ */
+/** The beat's row in `SCHEDULED_JOBS`, and the mark it leaves for `/api/health/crons`. */
+export declare const AI_JOBS_BEAT_CRON_ID = "ai-jobs-beat";
+/**
+ * The console path the beat is registered at: the one path this plugin
+ * registers outside its own prefixes. `/api/admin/` is where the console's
+ * scheduled sweeps live, and the console's edge lets a request past its bot
+ * challenge there when it carries the cron secret's header — a route
+ * anywhere else would need a firewall rule of its own before a scheduler
+ * could reach it. The console app serves this exact path from a named route
+ * with the sweep's function time, so the plugin dispatcher never serves it.
+ */
+export declare const AI_JOBS_BEAT_PATH = "admin/ai-jobs-beat";
+/** What one beat did: nothing while `ai-generate` is locked, else the sweep's account. */
+export type AiJobsBeatResult = {
+    held: true;
+} | ({
+    held: false;
+} & SweepAiJobsResult);
+/**
+ * One beat: the switch, then one sweep under its own lease owner. The owner
+ * is fresh per beat and fixed for the whole sweep, so two beats overlapping
+ * inside a lease never read each other's lease as their own.
+ */
+export declare function runAiJobsBeat(): Promise<AiJobsBeatResult>;

package/src/lib/jobs/ai-jobs-beat.js

@@ -0,0 +1,93 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { randomUUID } from "crypto";
+import { featureLockdownRefusal, firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs } from "./ai-jobs.js";
+/**
+ * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).
+ *
+ * A job's first step runs inline in the console route when it can; every
+ * step after it, every step too long for an inline door, and any step a
+ * budget cut short, runs here. The sweep bounds itself at
+ * `AI_JOB_SWEEP_BUDGET_MS` of wall clock and hands the rest to the next beat
+ * — the ordering of the queue is the cursor, so nothing is stored between
+ * beats and nothing can be skipped.
+ *
+ * ## Why the console runs it
+ *
+ * A step calls the AI provider, and the provider's key is held by the
+ * console alone: the tenant app serves every published site, and a
+ * credential it holds is one request-handling bug away from a visitor. So
+ * the beat is a console route (`server/ai-jobs-beat-route.ts`, registered
+ * by the console surface), driven every minute by its own Cloud Scheduler
+ * job in `cloud/functions` on the console's cron secret — the reason the
+ * sending-domain sweep is a console route and not a job on the tenant's
+ * platform beat. A beat must resolve to the minute: a step handed back by
+ * a budget, or a page pass waiting on the next, should resume on the next
+ * minute, not the next quarter hour.
+ *
+ * ## The kill switch
+ *
+ * `ai-generate` on the staff lockdown page is the lever for a provider
+ * incident or a spend runaway on the generative doors, and this beat is the
+ * one generative caller with no request to refuse. So it asks the same
+ * feature verdict a door would — the platform scope and then the feature
+ * document — and does nothing while either is locked. A job it leaves
+ * queued stays queued: its lease is not taken, so nothing expires and
+ * nothing is lost, and the first beat after the lock lifts picks it up.
+ *
+ * The same switch paused for ONE workspace (AGL-3037) holds that workspace's
+ * jobs and no other's: `runAiJobStep` asks the verdict with the job's org
+ * before it claims a step, and leaves a paused workspace's job queued.
+ */ /** The beat's row in `SCHEDULED_JOBS`, and the mark it leaves for `/api/health/crons`. */ export const AI_JOBS_BEAT_CRON_ID = 'ai-jobs-beat';
+/**
+ * The console path the beat is registered at: the one path this plugin
+ * registers outside its own prefixes. `/api/admin/` is where the console's
+ * scheduled sweeps live, and the console's edge lets a request past its bot
+ * challenge there when it carries the cron secret's header — a route
+ * anywhere else would need a firewall rule of its own before a scheduler
+ * could reach it. The console app serves this exact path from a named route
+ * with the sweep's function time, so the plugin dispatcher never serves it.
+ */ export const AI_JOBS_BEAT_PATH = 'admin/ai-jobs-beat';
+/**
+ * One beat: the switch, then one sweep under its own lease owner. The owner
+ * is fresh per beat and fixed for the whole sweep, so two beats overlapping
+ * inside a lease never read each other's lease as their own.
+ */ export async function runAiJobsBeat() {
+    const locked = await featureLockdownRefusal({
+        feature: 'ai-generate'
+    });
+    if (locked) {
+        console.warn('ai jobs beat held: ai-generate is locked');
+        return {
+            held: true
+        };
+    }
+    const result = await sweepAiJobs({
+        firestore: firebaseAdmin.app().firestore(),
+        owner: `beat:${randomUUID()}`,
+        budgetMs: AI_JOB_SWEEP_BUDGET_MS
+    });
+    if (result.due) {
+        console.info(`ai jobs: ${result.ran} step(s) run, ${result.skipped} skipped, ` + `${result.paused} held by a workspace's AI pause, ` + `${result.remaining} left for the next beat` + (result.budgetExhausted ? ' (budget exhausted)' : ''));
+    }
+    return _extends({
+        held: false
+    }, result);
+}
+
+//# sourceMappingURL=ai-jobs-beat.js.map

package/src/lib/jobs/ai-jobs-beat.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-beat.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 { randomUUID } from 'crypto'\nimport { featureLockdownRefusal, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { AI_JOB_SWEEP_BUDGET_MS, sweepAiJobs, type SweepAiJobsResult } from './ai-jobs'\n\n/**\n * Resume AI generation jobs on the AI jobs beat (AGL-2904, AGL-3026).\n *\n * A job's first step runs inline in the console route when it can; every\n * step after it, every step too long for an inline door, and any step a\n * budget cut short, runs here. The sweep bounds itself at\n * `AI_JOB_SWEEP_BUDGET_MS` of wall clock and hands the rest to the next beat\n * — the ordering of the queue is the cursor, so nothing is stored between\n * beats and nothing can be skipped.\n *\n * ## Why the console runs it\n *\n * A step calls the AI provider, and the provider's key is held by the\n * console alone: the tenant app serves every published site, and a\n * credential it holds is one request-handling bug away from a visitor. So\n * the beat is a console route (`server/ai-jobs-beat-route.ts`, registered\n * by the console surface), driven every minute by its own Cloud Scheduler\n * job in `cloud/functions` on the console's cron secret — the reason the\n * sending-domain sweep is a console route and not a job on the tenant's\n * platform beat. A beat must resolve to the minute: a step handed back by\n * a budget, or a page pass waiting on the next, should resume on the next\n * minute, not the next quarter hour.\n *\n * ## The kill switch\n *\n * `ai-generate` on the staff lockdown page is the lever for a provider\n * incident or a spend runaway on the generative doors, and this beat is the\n * one generative caller with no request to refuse. So it asks the same\n * feature verdict a door would — the platform scope and then the feature\n * document — and does nothing while either is locked. A job it leaves\n * queued stays queued: its lease is not taken, so nothing expires and\n * nothing is lost, and the first beat after the lock lifts picks it up.\n *\n * The same switch paused for ONE workspace (AGL-3037) holds that workspace's\n * jobs and no other's: `runAiJobStep` asks the verdict with the job's org\n * before it claims a step, and leaves a paused workspace's job queued.\n */\n\n/** The beat's row in `SCHEDULED_JOBS`, and the mark it leaves for `/api/health/crons`. */\nexport const AI_JOBS_BEAT_CRON_ID = 'ai-jobs-beat'\n\n/**\n * The console path the beat is registered at: the one path this plugin\n * registers outside its own prefixes. `/api/admin/` is where the console's\n * scheduled sweeps live, and the console's edge lets a request past its bot\n * challenge there when it carries the cron secret's header — a route\n * anywhere else would need a firewall rule of its own before a scheduler\n * could reach it. The console app serves this exact path from a named route\n * with the sweep's function time, so the plugin dispatcher never serves it.\n */\nexport const AI_JOBS_BEAT_PATH = 'admin/ai-jobs-beat'\n\n/** What one beat did: nothing while `ai-generate` is locked, else the sweep's account. */\nexport type AiJobsBeatResult =\n  | { held: true }\n  | ({ held: false } & SweepAiJobsResult)\n\n/**\n * One beat: the switch, then one sweep under its own lease owner. The owner\n * is fresh per beat and fixed for the whole sweep, so two beats overlapping\n * inside a lease never read each other's lease as their own.\n */\nexport async function runAiJobsBeat(): Promise<AiJobsBeatResult> {\n  const locked = await featureLockdownRefusal({ feature: 'ai-generate' })\n  if (locked) {\n    console.warn('ai jobs beat held: ai-generate is locked')\n    return { held: true }\n  }\n  const result = await sweepAiJobs({\n    firestore: firebaseAdmin.app().firestore(),\n    owner: `beat:${randomUUID()}`,\n    budgetMs: AI_JOB_SWEEP_BUDGET_MS,\n  })\n  if (result.due) {\n    console.info(\n      `ai jobs: ${result.ran} step(s) run, ${result.skipped} skipped, ` +\n        `${result.paused} held by a workspace's AI pause, ` +\n        `${result.remaining} left for the next beat` +\n        (result.budgetExhausted ? ' (budget exhausted)' : ''),\n    )\n  }\n  return { held: false, ...result }\n}\n"],"names":["randomUUID","featureLockdownRefusal","firebaseAdmin","AI_JOB_SWEEP_BUDGET_MS","sweepAiJobs","AI_JOBS_BEAT_CRON_ID","AI_JOBS_BEAT_PATH","runAiJobsBeat","locked","feature","console","warn","held","result","firestore","app","owner","budgetMs","due","info","ran","skipped","paused","remaining","budgetExhausted"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,SAAQ;AACnC,SAASC,sBAAsB,EAAEC,aAAa,QAAQ,2BAA0B;AAChF,SAASC,sBAAsB,EAAEC,WAAW,QAAgC,eAAW;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCC,GAED,wFAAwF,GACxF,OAAO,MAAMC,uBAAuB,eAAc;AAElD;;;;;;;;CAQC,GACD,OAAO,MAAMC,oBAAoB,qBAAoB;AAOrD;;;;CAIC,GACD,OAAO,eAAeC;IACpB,MAAMC,SAAS,MAAMP,uBAAuB;QAAEQ,SAAS;IAAc;IACrE,IAAID,QAAQ;QACVE,QAAQC,IAAI,CAAC;QACb,OAAO;YAAEC,MAAM;QAAK;IACtB;IACA,MAAMC,SAAS,MAAMT,YAAY;QAC/BU,WAAWZ,cAAca,GAAG,GAAGD,SAAS;QACxCE,OAAO,CAAC,KAAK,EAAEhB,cAAc;QAC7BiB,UAAUd;IACZ;IACA,IAAIU,OAAOK,GAAG,EAAE;QACdR,QAAQS,IAAI,CACV,CAAC,SAAS,EAAEN,OAAOO,GAAG,CAAC,cAAc,EAAEP,OAAOQ,OAAO,CAAC,UAAU,CAAC,GAC/D,GAAGR,OAAOS,MAAM,CAAC,iCAAiC,CAAC,GACnD,GAAGT,OAAOU,SAAS,CAAC,uBAAuB,CAAC,GAC3CV,CAAAA,OAAOW,eAAe,GAAG,wBAAwB,EAAC;IAEzD;IACA,OAAO;QAAEZ,MAAM;OAAUC;AAC3B"}

package/src/lib/jobs/ai-jobs-pause.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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.
+ */
+/**
+ * A workspace whose AI staff have paused runs none of its queued AI jobs
+ * (AGL-3037).
+ *
+ * The staff org page's Pause AI writes `ai-generate` for ONE workspace on the
+ * lockdown carrier (`feature--ai-generate--org--{orgId}`), and every jobs door
+ * refuses a request for that workspace through `featureLockdownRefusal`, the
+ * rung of the gate ladder. A job queued before the pause has no request to
+ * refuse, so the machine asks the same verdict, with the same arguments,
+ * before it claims a step: the platform lock, then `ai-generate`
+ * platform-wide, then the pause for the job's workspace — with the staff
+ * bypass the ladder grants, which only an inline door's caller can carry.
+ *
+ * Registered by a call from the console surface, the one app that runs jobs,
+ * so the machine itself never loads the Admin SDK the lockdown reads run on.
+ */
+export declare function isAiGenerationPausedFor(input: {
+    orgId: string;
+    staff: boolean;
+}): Promise<boolean>;
+/** Registers the pause the jobs machine asks before it claims a step. */
+export declare function registerAiJobsPause(): void;

package/src/lib/jobs/ai-jobs-pause.js

@@ -0,0 +1,45 @@
+/**
+ * @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 { featureLockdownRefusal } from "@aglyn/tenant-data-admin/server/lockdown";
+import { registerAiJobPauseReader } from "./ai-jobs.js";
+/**
+ * A workspace whose AI staff have paused runs none of its queued AI jobs
+ * (AGL-3037).
+ *
+ * The staff org page's Pause AI writes `ai-generate` for ONE workspace on the
+ * lockdown carrier (`feature--ai-generate--org--{orgId}`), and every jobs door
+ * refuses a request for that workspace through `featureLockdownRefusal`, the
+ * rung of the gate ladder. A job queued before the pause has no request to
+ * refuse, so the machine asks the same verdict, with the same arguments,
+ * before it claims a step: the platform lock, then `ai-generate`
+ * platform-wide, then the pause for the job's workspace — with the staff
+ * bypass the ladder grants, which only an inline door's caller can carry.
+ *
+ * Registered by a call from the console surface, the one app that runs jobs,
+ * so the machine itself never loads the Admin SDK the lockdown reads run on.
+ */ export async function isAiGenerationPausedFor(input) {
+    const refusal = await featureLockdownRefusal({
+        feature: 'ai-generate',
+        staff: input.staff,
+        orgId: input.orgId
+    });
+    return refusal !== null;
+}
+/** Registers the pause the jobs machine asks before it claims a step. */ export function registerAiJobsPause() {
+    registerAiJobPauseReader(isAiGenerationPausedFor);
+}
+
+//# sourceMappingURL=ai-jobs-pause.js.map

package/src/lib/jobs/ai-jobs-pause.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-pause.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 { featureLockdownRefusal } from '@aglyn/tenant-data-admin/server/lockdown'\nimport { registerAiJobPauseReader } from './ai-jobs'\n\n/**\n * A workspace whose AI staff have paused runs none of its queued AI jobs\n * (AGL-3037).\n *\n * The staff org page's Pause AI writes `ai-generate` for ONE workspace on the\n * lockdown carrier (`feature--ai-generate--org--{orgId}`), and every jobs door\n * refuses a request for that workspace through `featureLockdownRefusal`, the\n * rung of the gate ladder. A job queued before the pause has no request to\n * refuse, so the machine asks the same verdict, with the same arguments,\n * before it claims a step: the platform lock, then `ai-generate`\n * platform-wide, then the pause for the job's workspace — with the staff\n * bypass the ladder grants, which only an inline door's caller can carry.\n *\n * Registered by a call from the console surface, the one app that runs jobs,\n * so the machine itself never loads the Admin SDK the lockdown reads run on.\n */\nexport async function isAiGenerationPausedFor(input: {\n  orgId: string\n  staff: boolean\n}): Promise<boolean> {\n  const refusal = await featureLockdownRefusal({\n    feature: 'ai-generate',\n    staff: input.staff,\n    orgId: input.orgId,\n  })\n  return refusal !== null\n}\n\n/** Registers the pause the jobs machine asks before it claims a step. */\nexport function registerAiJobsPause(): void {\n  registerAiJobPauseReader(isAiGenerationPausedFor)\n}\n"],"names":["featureLockdownRefusal","registerAiJobPauseReader","isAiGenerationPausedFor","input","refusal","feature","staff","orgId","registerAiJobsPause"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,2CAA0C;AACjF,SAASC,wBAAwB,QAAQ,eAAW;AAEpD;;;;;;;;;;;;;;;CAeC,GACD,OAAO,eAAeC,wBAAwBC,KAG7C;IACC,MAAMC,UAAU,MAAMJ,uBAAuB;QAC3CK,SAAS;QACTC,OAAOH,MAAMG,KAAK;QAClBC,OAAOJ,MAAMI,KAAK;IACpB;IACA,OAAOH,YAAY;AACrB;AAEA,uEAAuE,GACvE,OAAO,SAASI;IACdP,yBAAyBC;AAC3B"}