crewly 1.20.185 → 1.20.187

package/dist/backend/backend/src/services/spend/spend-cap.gate.js

@@ -0,0 +1,71 @@
+/**
+ * Spend cap gate — the process-wide hook the delivery and wake paths ask
+ * "may this agent start a new turn?". Kept apart from the service so the
+ * hot paths (agent registration, the orc queue processor, the owner-message
+ * watchdog) import a tiny module with no dependencies of its own.
+ *
+ * specs/2026-10-02-spend-cap.md
+ *
+ * @module services/spend/spend-cap.gate
+ */
+let gate = null;
+/**
+ * Install (or clear) the gate.
+ *
+ * @param next - Gate, or null
+ */
+export function setSpendCapGate(next) {
+    gate = next;
+}
+/**
+ * The stop in force for a session. Never throws: a broken gate lets the
+ * agent run rather than silently dropping its work.
+ *
+ * @param session - Agent session
+ * @returns Stop, or null
+ */
+export function spendCapStopOf(session) {
+    try {
+        return gate?.stopOf(session) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Owner-facing name of a session.
+ *
+ * @param session - Agent session
+ * @returns Name (the session name when unknown)
+ */
+export function spendCapNameOf(session) {
+    try {
+        return gate?.displayNameOf?.(session) || session;
+    }
+    catch {
+        return session;
+    }
+}
+/**
+ * USD for owner text.
+ *
+ * @param usd - Amount
+ * @returns e.g. `$5.00`
+ */
+export function formatUsd(usd) {
+    return `$${(Math.round(usd * 100) / 100).toFixed(2)}`;
+}
+/**
+ * The one-line reason, e.g. "Orc hit its daily spend cap ($5.00)".
+ *
+ * @param stop - The stop
+ * @param name - Owner-facing name (default: looked up)
+ * @returns Reason text
+ */
+export function spendCapReason(stop, name = spendCapNameOf(stop.session)) {
+    if (stop.scope === 'total') {
+        return `${name} is stopped: all agents together hit the daily total spend cap (${formatUsd(stop.capUsd)})`;
+    }
+    return `${name} hit its daily spend cap (${formatUsd(stop.capUsd)})`;
+}
+//# sourceMappingURL=spend-cap.gate.js.map

package/dist/backend/backend/src/services/spend/spend-cap.gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-cap.gate.js","sourceRoot":"","sources":["../../../../../../backend/src/services/spend/spend-cap.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH,IAAI,IAAI,GAAwB,IAAI,CAAC;AAErC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAyB;IACvD,IAAI,GAAG,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,aAAa,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe,EAAE,OAAe,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;IACzF,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,GAAG,IAAI,mEAAmE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IAC7G,CAAC;IACD,OAAO,GAAG,IAAI,6BAA6B,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;AACvE,CAAC"}

package/dist/backend/backend/src/services/spend/spend-cap.service.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Per-agent daily spend cap with a hard stop.
+ *
+ * - Caps are the owner's own limits (unlike the runtime fallback, which
+ *   reacts to a provider's usage limit). All are OFF until the owner sets
+ *   one: a default per-agent cap, per-agent overrides, and an optional
+ *   all-agents daily total.
+ * - At {@link SPEND_CAP_CONSTANTS.WARN_FRACTION} of a cap the owner gets ONE
+ *   heads-up.
+ * - At 100% the agent is hard-stopped: {@link stopOf} answers the delivery
+ *   and wake gates, so no new turn starts (the current one may finish) and
+ *   messages stay queued. The owner gets ONE decision card: "Raise to $Y
+ *   today" / "Keep stopped".
+ * - Local midnight resets everything; raises last for the day they were
+ *   made. When a stop lifts (midnight, raise, cap change) the queued
+ *   messages are released.
+ *
+ * Spend comes from {@link SpendLedger} (the shared token ledger and its one
+ * cost computation).
+ *
+ * specs/2026-10-02-spend-cap.md
+ *
+ * @module services/spend/spend-cap.service
+ */
+import type { OwnerDecision } from '../../types/decision.types.js';
+import type { SystemAskInput } from '../decisions/decision.service.js';
+import { type SpendCapGate, type SpendStop } from './spend-cap.gate.js';
+import { type SpendLedger, type SpendSummary } from './spend-ledger.service.js';
+import { type SpendCapConfig, type SpendCapStoreLike } from './spend-cap.store.js';
+/** Minimal logger. */
+export interface SpendCapLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+/** The decision-card calls the service makes. */
+export interface SpendCapDecisions {
+    askSystem(input: SystemAskInput): Promise<OwnerDecision>;
+    replyInThread(id: string, text: string): Promise<boolean>;
+}
+/** Collaborators. */
+export interface SpendCapServiceDeps {
+    store: SpendCapStoreLike;
+    ledger: Pick<SpendLedger, 'spentToday' | 'totalToday' | 'summarize' | 'invalidate'>;
+    /** One line to the owner (Slack DM from this machine's orc bot); false/throw = not sent */
+    notifyOwner: (text: string) => Promise<unknown>;
+    /** Decision cards (null before they are wired: the stop is then a plain notice) */
+    decisions?: () => SpendCapDecisions | null;
+    /** Owner-facing name of a session ("Orc", "Ella") */
+    displayNameOf?: (session: string) => string;
+    /** Sessions the owner configured (orc + team members), for the caps view */
+    knownSessions?: () => Promise<string[]>;
+    /** Stops lifted: deliver what was queued for these sessions */
+    onReleased?: (sessions: string[]) => Promise<void>;
+    now?: () => Date;
+    logger?: SpendCapLogger;
+}
+/** Body of `PUT /api/system/spend/caps`. */
+export interface SpendCapPatch {
+    /** Default per-agent cap (USD); null turns it off */
+    defaultAgentCapUsd?: number | null;
+    /** All-agents total cap (USD); null turns it off */
+    totalCapUsd?: number | null;
+    /** Session → cap (USD), `null` = no cap for this agent, `"default"` = drop the override */
+    agents?: Record<string, number | null | 'default'>;
+}
+/** A rejected cap change. */
+export declare class SpendCapError extends Error {
+    readonly status: number;
+    /**
+     * @param status - HTTP status
+     * @param message - Owner-facing reason
+     */
+    constructor(status: number, message: string);
+}
+/** One agent in the view. */
+export interface SpendCapAgentView {
+    session: string;
+    name: string;
+    runtimes: string[];
+    todayUsd: number;
+    windowUsd: number;
+    daily: number[];
+    /** Cap in force today (USD), null = none */
+    capUsd: number | null;
+    /** Where the cap comes from */
+    capSource: 'override' | 'default' | 'raised' | 'none' | 'exempt';
+    /** Stopped right now, and why */
+    stopped: boolean;
+    stopReason?: string;
+}
+/** What `GET /api/system/spend` returns. */
+export interface SpendView extends Omit<SpendSummary, 'agents'> {
+    agents: SpendCapAgentView[];
+    caps: SpendCapConfig;
+    /** Raises in force today: target → USD */
+    raisedToday: Record<string, number>;
+    /** Total cap in force today (raise included), null = off */
+    totalCapTodayUsd: number | null;
+    /** Suggested default per-agent cap: last window's p90 agent-day, rounded up to whole dollars (null = no data) */
+    suggestedAgentCapUsd: number | null;
+    /** All agents together stopped by the total cap */
+    totalStopped: boolean;
+}
+/**
+ * The "Raise to $Y today" amount: the cap times RAISE_FACTOR, rounded up to
+ * whole dollars, and always above what was already spent.
+ *
+ * @param capUsd - Cap in force
+ * @param spentUsd - Spent today
+ * @returns USD
+ */
+export declare function suggestedRaise(capUsd: number, spentUsd: number): number;
+/**
+ * Read the amount out of a "Raise to $Y today" option label.
+ *
+ * @param label - Option label
+ * @returns USD, or null when the label is not a raise
+ */
+export declare function raiseAmountOf(label: string | undefined): number | null;
+/**
+ * Per-agent daily spend cap service.
+ */
+export declare class SpendCapService implements SpendCapGate {
+    private readonly deps;
+    private file;
+    private readonly now;
+    private readonly logger;
+    private timer;
+    /** Sessions stopped at the last evaluation (to release them when the stop lifts) */
+    private lastStopped;
+    /** Evaluation passes run one after another */
+    private chain;
+    private queuedPass;
+    /**
+     * @param deps - Collaborators
+     */
+    constructor(deps: SpendCapServiceDeps);
+    /** Start the enforcement tick. */
+    start(): void;
+    /** Stop the tick. */
+    stop(): void;
+    /** @returns The owner's caps (a copy) */
+    getConfig(): SpendCapConfig;
+    /**
+     * Change caps. Takes effect at once (a stop can lift or start).
+     *
+     * @param patch - Changes
+     * @returns The new caps
+     * @throws SpendCapError on a bad value
+     */
+    setCaps(patch: SpendCapPatch): Promise<SpendCapConfig>;
+    /**
+     * Lift a cap for today only.
+     *
+     * @param target - Agent session, or `*` for the all-agents total
+     * @param usd - New cap for today (must be above today's spend)
+     * @returns The new cap for today
+     * @throws SpendCapError when the amount is not above today's spend
+     */
+    raiseToday(target: string, usd: unknown): Promise<number>;
+    /**
+     * The stop in force for a session (the delivery / wake gate). Synchronous
+     * and live: it reads today's spend now, not at the last tick.
+     *
+     * @param session - Agent session
+     * @returns Stop, or null when the agent may run
+     */
+    stopOf(session: string): SpendStop | null;
+    /**
+     * Owner-facing name.
+     *
+     * @param session - Agent session
+     * @returns Name
+     */
+    displayNameOf(session: string): string;
+    /**
+     * Cap in force today for a target, and where it comes from.
+     *
+     * @param target - Agent session, or `*`
+     * @returns Cap (null = none) and source
+     */
+    capOf(target: string): {
+        capUsd: number | null;
+        source: SpendCapAgentView['capSource'];
+    };
+    /**
+     * Spend plus caps for the API / Settings panel.
+     *
+     * @param days - Window
+     * @returns View
+     */
+    view(days?: number): Promise<SpendView>;
+    /**
+     * One enforcement pass: day roll, 80% notices, stop announcements (one
+     * card per stop), and releasing agents whose stop lifted. Passes run
+     * one at a time; a call during a pass gets another pass after it.
+     */
+    evaluate(): Promise<void>;
+    /**
+     * React to a settled "cap reached" card (decision kind `spend_cap`).
+     *
+     * @param d - The settled decision
+     * @returns Always null (nobody else is told)
+     */
+    onSettled(d: OwnerDecision): Promise<null>;
+    private evaluateOnce;
+    private checkThresholds;
+    private announceStop;
+    private anyCap;
+    private computeStop;
+    private stopKey;
+    private scheduleEvaluate;
+    /** Reset today's bookkeeping when the local day changed. */
+    private rollDay;
+    private nextMidnight;
+    private nameOf;
+    private notify;
+    private reply;
+    private persist;
+}
+/** @returns The backend's service, or null before it is wired */
+export declare function getSpendCapService(): SpendCapService | null;
+/** @param service - Instance (null clears) */
+export declare function setSpendCapService(service: SpendCapService | null): void;
+//# sourceMappingURL=spend-cap.service.d.ts.map

package/dist/backend/backend/src/services/spend/spend-cap.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-cap.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/spend/spend-cap.service.ts"],"names":[],"mappings":"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"}