@cat-factory/server 0.215.0 → 0.217.0

package/dist/runtime/spendAlerts.js

@@ -0,0 +1,173 @@
+import { distinctAccountIds, spendThresholdCardContent } from '@cat-factory/orchestration';
+import { describeError } from '@cat-factory/kernel';
+import { mergeSpendAlertStates, spendAlertEscalated, spendAlertFiring } from '@cat-factory/spend';
+// Runtime-neutral spend-alert sweep: the PROACTIVE half of the spend safeguard, shared by both
+// facades' periodic sweeps (the Worker's cron `scheduled` handler and the Node `setInterval`
+// sweeper) exactly like `sweepPlatformHealth`.
+//
+// The safeguard itself only ever speaks once the money is gone: `isOverBudget` pauses a run at
+// the ceiling and a `budget_paused` card appears. That is the worst possible moment to learn a
+// budget was running out, so this sweep evaluates each workspace's (and its account's) forward
+// position (burn rate, month-end projection) and raises a `budget_threshold` card while there
+// is still time to raise the limit or stop a runaway.
+//
+// Nothing here can gate anything. The forecast is advisory by construction (see
+// `@cat-factory/spend`'s `forecast.logic.ts`), so a projection bug costs a wrong card and never
+// a paused or unpaused run.
+//
+// TWO reads serve the whole deployment: the ledger aggregates are batched per scope set, and the
+// per-workspace notified state is one chunked `listLatestByType`. A point read per workspace
+// would be the banned N+1, run every few minutes across every tenant.
+/**
+ * How often a pass runs on both facades. Spend is a slow signal: the burn rate is measured over
+ * a week and a budget is monthly, so a tighter cadence would buy nothing and cost four aggregate
+ * queries per tenant set. Shared rather than per-facade so the Worker's stateless cron window and
+ * the Node timer cannot drift into meaning different things.
+ */
+export const SPEND_ALERT_INTERVAL_MS = 15 * 60_000;
+/**
+ * One pass. Returns how many workspaces a card was raised on.
+ *
+ * A no-op when the notifications module is not wired (tests, mothership local nodes). Unlike the
+ * platform-health sweep there is no opt-in flag: a budget is something a deployment configured on
+ * purpose, and a safeguard that warns only when an operator remembered to switch the warning on
+ * is the silent pause this exists to replace.
+ *
+ * Best-effort per workspace: one workspace's failed raise is logged and skipped, never aborting
+ * the rest. This sweep must not become the silent background failure it exists to prevent.
+ */
+export async function sweepSpendAlerts(container, now, logger) {
+    const notifications = container.notifications;
+    if (!notifications)
+        return { raised: 0 };
+    const workspaces = await container.workspaceService.list(null);
+    if (workspaces.length === 0)
+        return { raised: 0 };
+    const workspaceIds = workspaces.map((ws) => ws.id);
+    const spend = container.spendService;
+    // The account tier is evaluated ONCE per account and fanned out to its workspaces, matching
+    // the scope its rollup is computed at. Legacy null-account boards contribute nothing here and
+    // are still forecast on their own workspace tier.
+    const [byWorkspace, byAccount, lastNotified] = await Promise.all([
+        spend.forecastWorkspaces(workspaceIds, now),
+        spend.forecastAccounts(distinctAccountIds(workspaces), now),
+        notifications.service.listLatestByType(workspaceIds, 'budget_threshold'),
+    ]);
+    let raised = 0;
+    for (const workspace of workspaces) {
+        try {
+            if (await settleWorkspace({ container, logger }, { workspace, byWorkspace, byAccount, lastNotified })) {
+                raised += 1;
+            }
+        }
+        catch (error) {
+            logger?.warn('spend-alerts: failed to evaluate workspace', {
+                scope: 'spend-alerts',
+                workspaceId: workspace.id,
+                ...describeError(error),
+            });
+        }
+    }
+    return { raised };
+}
+/**
+ * Evaluate ONE workspace and raise its card when the alert state has ESCALATED. Returns whether
+ * a card was raised.
+ *
+ * There is deliberately no clearing counterpart. A crossed threshold does not un-cross in any
+ * way worth telling anyone about (spend only rises within a period), and the card auto-expires
+ * with the period: the next period's first crossing raises a new one because the payload's
+ * `budgetPeriodStart` differs. Auto-dismissing on a fall-back would only be possible for the
+ * projection, and would make the card flicker as the burn rate wobbles around the limit.
+ */
+async function settleWorkspace(deps, input) {
+    const { workspace, byWorkspace, byAccount, lastNotified } = input;
+    // Built workspace-tier-first, because the alert list is part of the card's dedup identity: an
+    // order that depended on which tier happened to be evaluated first would re-deliver the card on
+    // a refactor that changed nothing a human can see.
+    const firing = [
+        { tier: 'workspace', forecast: byWorkspace.get(workspace.id) },
+        {
+            tier: 'account',
+            forecast: workspace.accountId ? byAccount.get(workspace.accountId) : undefined,
+        },
+    ].filter(isFiring);
+    if (firing.length === 0)
+        return false;
+    // The WORST firing tier owns the HEADLINE. A workspace holds at most one open block-less card
+    // per type, so the two tiers cannot each have one; leading with the worse of them is what keeps
+    // the card honest when both fire.
+    const worst = [...firing].sort(bySeverity)[0];
+    const alerts = firing.map(({ tier, forecast }) => ({
+        tier,
+        threshold: forecast.alert.threshold,
+        projectedOverrun: forecast.alert.projectedOverrun,
+    }));
+    // The ESCALATION decision is made on the FOLD of every firing tier, not on the worst one: the
+    // card being compared against lists them all, so only a fold-versus-fold comparison sees a
+    // SECOND tier starting to fire beside an unchanged first one.
+    const next = mergeSpendAlertStates(worst.forecast.alert.periodStart, alerts);
+    const previous = readNotifiedState(lastNotified.get(workspace.id));
+    if (!spendAlertEscalated(previous, next))
+        return false;
+    const { title, body } = spendThresholdCardContent(alerts, {
+        tier: worst.tier,
+        costLimit: worst.forecast.costLimit,
+        currency: worst.forecast.currency,
+        threshold: worst.forecast.alert.threshold,
+    });
+    await deps.container.notifications?.service.raise(workspace.id, {
+        type: 'budget_threshold',
+        blockId: null,
+        executionId: null,
+        title,
+        body,
+        payload: {
+            budgetPeriodStart: worst.forecast.alert.periodStart,
+            budgetAlerts: alerts,
+        },
+    });
+    deps.logger?.info('spend-alerts: raised a budget threshold card', {
+        scope: 'spend-alerts',
+        workspaceId: workspace.id,
+        // The tiers and their STATE, never the amounts: a log line naming a workspace's spend puts a
+        // per-tenant financial figure into the deployment's operational log.
+        tiers: alerts.map((a) => a.tier).join(','),
+        // The FOLD, matching what the escalation test acted on: logging the worst tier's own signals
+        // would omit the account overrun that is sometimes the sole reason this card was raised.
+        threshold: next.threshold,
+        projectedOverrun: next.projectedOverrun,
+    });
+    return true;
+}
+/** Narrowing predicate: a tier whose forecast is present AND firing. */
+function isFiring(entry) {
+    return entry.forecast != null && spendAlertFiring(entry.forecast.alert);
+}
+/**
+ * Worst-first: a crossed threshold outranks a bare projection, and a higher crossed threshold
+ * outranks a lower one. Total, so the sort is deterministic when both tiers are in the same state.
+ */
+function bySeverity(a, b) {
+    return (b.forecast.alert.threshold ?? 0) - (a.forecast.alert.threshold ?? 0);
+}
+/**
+ * The state a workspace was last notified at, read back off its most recent card.
+ *
+ * The card row IS the sweep's alert store: it is persisted, shared by every replica, and
+ * survives a restart, which an in-process "already notified" flag would not on a multi-node
+ * deployment. A card with no period stamped (nothing was ever raised, or a card written before
+ * this payload existed) reads as "never notified", so the next firing state escalates, which is the safe
+ * direction, since the cost is one extra card rather than a missed warning.
+ *
+ * Folded through the SAME `mergeSpendAlertStates` the sweep folds this pass's tiers with, so the
+ * two sides of the escalation test can never come to mean different things.
+ */
+function readNotifiedState(card) {
+    const payload = card?.payload;
+    const periodStart = payload?.budgetPeriodStart;
+    if (typeof periodStart !== 'number')
+        return null;
+    return mergeSpendAlertStates(periodStart, payload?.budgetAlerts ?? []);
+}
+//# sourceMappingURL=spendAlerts.js.map

package/dist/runtime/spendAlerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spendAlerts.js","sourceRoot":"","sources":["../../src/runtime/spendAlerts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/server",
-  "version": "0.215.0",
+  "version": "0.217.0",
   "description": "Runtime-neutral HTTP layer for the Agent Architecture Board: the Hono controllers, middleware (auth/authz/CORS/error), request helpers and the gateway seams shared by every deployment facade (Cloudflare Worker, Node service).",
   "repository": {
     "type": "git",
@@ -30,14 +30,14 @@
     "hono": "^4.12.33",
     "pino": "^10.3.1",
     "valibot": "^1.4.2",
-    "@cat-factory/agents": "0.110.7",
-    "@cat-factory/contracts": "0.236.0",
-    "@cat-factory/integrations": "0.126.2",
-    "@cat-factory/kernel": "0.236.0",
-    "@cat-factory/mcp-server": "0.6.0",
-    "@cat-factory/orchestration": "0.203.0",
-    "@cat-factory/prompt-fragments": "0.15.62",
-    "@cat-factory/spend": "0.14.14"
+    "@cat-factory/agents": "0.110.9",
+    "@cat-factory/contracts": "0.238.0",
+    "@cat-factory/kernel": "0.237.0",
+    "@cat-factory/integrations": "0.127.0",
+    "@cat-factory/mcp-server": "0.7.0",
+    "@cat-factory/orchestration": "0.205.0",
+    "@cat-factory/spend": "0.15.0",
+    "@cat-factory/prompt-fragments": "0.15.64"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",