@wardby/cli 0.5.3 → 0.7.0

package/dist/core/budget-events.js

@@ -0,0 +1,346 @@
+import { logger } from "./logger.js";
+import { groupName, overrunPercent } from "./budget-wording.js";
+const log = logger.child({ module: "budget-events" });
+const usd = (amount) => `$${amount.toFixed(2)}`;
+const PERIOD_ADJECTIVE = { day: "daily", week: "weekly", month: "monthly" };
+function periodAdjective(limit) {
+    return PERIOD_ADJECTIVE[limit] ?? limit;
+}
+/** `the "name" group`, or a neutral phrase when the name could not be read. */
+function groupPhrase(details) {
+    const name = groupName(details.groupName);
+    return name ? `the "${name}" group` : "the budget group";
+}
+/** Below this, two amounts are the same (CodingRun's 6 decimal places). */
+const SAME_USD = 0.000001;
+/**
+ * The run's budget as the proxy enforced it: its base, and how much of its
+ * allowed overrun it had been granted. An older run without a recorded limit
+ * had its whole overrun reserved, so its budget is the limit.
+ */
+function budgetPhrase(details) {
+    const granted = details.budgetUsd;
+    const base = details.baseBudgetUsd;
+    const percent = overrunPercent(base, details.limitUsd ?? granted);
+    if (percent === null || base === undefined || granted <= base + SAME_USD)
+        return `${usd(granted)} budget`;
+    if (details.limitUsd === undefined || granted >= details.limitUsd - SAME_USD) {
+        return `${usd(base)} budget and its ${percent}% allowed overrun (${usd(granted)} in all)`;
+    }
+    return `${usd(base)} budget and ${usd(granted - base)} of its ${percent}% allowed overrun (${usd(granted)} in all)`;
+}
+/** What the proxy refused, and what was left: `{subject} needed a $X hold, but only $Y of ... was left (...)`. */
+function proxyFacts(details, subject) {
+    const held = details.heldReservedUsd + details.heldUncertainUsd;
+    const left = Math.max(0, details.budgetUsd - details.spentUsd - held);
+    const heldPart = held > 0 ? `, ${usd(held)} held by requests in flight` : "";
+    const budget = budgetPhrase(details);
+    return (`${subject} needed a ${usd(details.refusedHoldUsd)} hold, but only ${usd(left)} of this run's ` +
+        `${budget} was left (${usd(details.spentUsd)} spent${heldPart}).`);
+}
+function periodCapSentence(limit, details) {
+    const phrase = groupPhrase(details);
+    return `${phrase.charAt(0).toUpperCase()}${phrase.slice(1)}'s ${periodAdjective(limit)} cap limited this run to ${usd(details.budgetUsd)}.`;
+}
+/**
+ * Why the run's allowed overrun was not (all) there: `Its 10% allowed overrun
+ * wasn't available because the "X" group had nothing left of its daily cap.`,
+ * or `Only $0.40 of its 10% allowed overrun was available because ...` when
+ * the run got part of it. A top-up takes whatever room there is, so the run is
+ * refused only once nothing is left.
+ * `lead` names the lead for a run-tree limit (owner sentences only).
+ */
+function overrunUnavailableSentence(overrun, lead) {
+    const { details, limit } = overrun;
+    const percent = overrunPercent(details.baseBudgetUsd, details.limitUsd);
+    const allowed = `${percent === null ? "" : `${percent}% `}allowed overrun`;
+    const where = limit === "run-tree" ? (lead ? `the lead's (${lead}) run tree` : "the lead's run tree") : groupPhrase(details);
+    const of = limit === "run-tree" ? `of its ${usd(details.capUsd)} budget` : `of its ${periodAdjective(limit)} cap`;
+    const got = details.grantedUsd - details.baseBudgetUsd;
+    if (got >= SAME_USD)
+        return `Only ${usd(got)} of its ${allowed} was available because ${where} had no more left ${of}.`;
+    return `Its ${allowed} wasn't available because ${where} had nothing left ${of}.`;
+}
+/** What to raise when the overrun was what ran out: the full group's cap, or the lead's budget. */
+function overrunContinueSentence(overrun, lead) {
+    return overrun.limit === "run-tree"
+        ? `To continue, raise budgetUsd on ${lead}.`
+        : `To continue, raise the group's ${periodAdjective(overrun.limit)} cap.`;
+}
+function dispatchPeriodSentence(limit, details) {
+    const left = Math.max(0, details.capUsd - details.spentUsd - details.heldUsd);
+    return (`${groupPhrase(details)} had ${usd(left)} left of its ${usd(details.capUsd)} ${periodAdjective(limit)} cap ` +
+        `(${usd(details.spentUsd)} spent, ${usd(details.heldUsd)} held by ${details.heldRuns} running run(s)).`);
+}
+/** Sentence for the run owner (run error, lead's sub-agent result, get_run consumers). */
+export function ownerBudgetSentence(event, agentName) {
+    const { details, limit } = event;
+    if (details.source === "top-up") {
+        return overrunUnavailableSentence({ limit, details }, details.leadAgentName ?? "lead agent");
+    }
+    if (details.source === "dispatch") {
+        if (limit === "run-tree") {
+            const lead = details.leadAgentName ?? "lead agent";
+            return `Could not start: the lead's (${lead}) run tree had nothing left of its ${usd(details.capUsd)} budget (${usd(details.spentUsd)} spent).`;
+        }
+        return `Could not start: ${dispatchPeriodSentence(limit, details)}`;
+    }
+    const lead = details.leadAgentName ?? event.overrun?.details.leadAgentName ?? "lead agent";
+    const overrun = event.overrun ? ` ${overrunUnavailableSentence(event.overrun, lead)}` : "";
+    const first = `Stopped before turn ${details.turn}: ${proxyFacts(details, "the next request")}${overrun}`;
+    if (limit === "run") {
+        if (event.overrun)
+            return `${first} ${overrunContinueSentence(event.overrun, lead)}`;
+        const overran = overrunPercent(details.baseBudgetUsd, details.limitUsd ?? details.budgetUsd) !== null;
+        return `${first} To continue, raise ${overran ? "budgetUsd or allowedOverrunPercent" : "budgetUsd"} on ${agentName}.`;
+    }
+    if (limit === "run-tree") {
+        return (`${first} The lead's (${lead}) remaining budget limited this run to ${usd(details.budgetUsd)}. ` +
+            `To continue, raise budgetUsd on ${lead}.`);
+    }
+    return `${first} ${periodCapSentence(limit, details)} To continue, raise the group's ${periodAdjective(limit)} cap.`;
+}
+/** Sentence for a host comment: amounts and group name only. */
+export function hostBudgetSentence(event) {
+    const { details, limit } = event;
+    if (details.source === "top-up")
+        return `Out of budget: ${overrunUnavailableSentence({ limit, details })}`;
+    if (details.source === "dispatch") {
+        if (limit === "run-tree") {
+            return `Out of budget: could not start: the lead's run tree had nothing left of its ${usd(details.capUsd)} budget (${usd(details.spentUsd)} spent).`;
+        }
+        return `Out of budget: could not start: ${dispatchPeriodSentence(limit, details)}`;
+    }
+    const overrun = event.overrun ? ` ${overrunUnavailableSentence(event.overrun)}` : "";
+    const first = `Out of budget: ${proxyFacts(details, "the next model request")}${overrun}`;
+    if (limit === "run" || limit === "run-tree")
+        return first;
+    return `${first} ${periodCapSentence(limit, details)} To continue, raise the group's ${periodAdjective(limit)} cap.`;
+}
+/** Records a refusal; best effort, never throws (a record must not change the refusal). */
+export async function recordBudgetEvent(db, runId, limit, details) {
+    try {
+        await db.runBudgetEvent.create({
+            data: { runId, kind: "refused", limit, details: details },
+        });
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not record a budget event");
+    }
+}
+const BUDGET_LIMITS = new Set(["run", "run-tree", "day", "week", "month"]);
+const MODEL_ID = /^[A-Za-z0-9._:/-]{1,128}$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isCount = (value) => Number.isInteger(value) && value >= 0;
+/**
+ * A proxy refusal rebuilt from only its stored amounts, model and turn, or
+ * null when any is missing or malformed. The proxy (a less-trusted role)
+ * writes the source record, so nothing else it wrote is kept: names are
+ * filled at read time from the database.
+ */
+export function proxyRefusalDetails(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { budgetUsd, spentUsd, heldReservedUsd, heldUncertainUsd, refusedHoldUsd, turn, model } = raw;
+    if (![budgetUsd, spentUsd, heldReservedUsd, heldUncertainUsd, refusedHoldUsd].every(isFiniteNumber))
+        return null;
+    if (!isCount(turn) || typeof model !== "string" || !MODEL_ID.test(model))
+        return null;
+    const result = {
+        source: "proxy",
+        budgetUsd: budgetUsd,
+        spentUsd: spentUsd,
+        heldReservedUsd: heldReservedUsd,
+        heldUncertainUsd: heldUncertainUsd,
+        refusedHoldUsd: refusedHoldUsd,
+        model,
+        turn,
+    };
+    const basis = raw.refusedHoldBasis;
+    const ceiling = raw.refusedHoldCeilingUsd;
+    return {
+        ...result,
+        ...(basis === "cached" || basis === "full" ? { refusedHoldBasis: basis } : {}),
+        ...(isFiniteNumber(ceiling) ? { refusedHoldCeilingUsd: ceiling } : {}),
+    };
+}
+/** A dispatch refusal rebuilt from only its stored amounts, or null when any is missing or malformed. */
+function dispatchRefusalDetails(raw) {
+    const { capUsd, spentUsd, heldUsd, heldRuns } = raw;
+    if (![capUsd, spentUsd, heldUsd].every(isFiniteNumber) || !isCount(heldRuns))
+        return null;
+    return {
+        source: "dispatch",
+        capUsd: capUsd,
+        spentUsd: spentUsd,
+        heldUsd: heldUsd,
+        heldRuns,
+    };
+}
+/** A top-up refusal rebuilt from only its stored amounts and group name, or null when any is missing or malformed. */
+function topUpRefusalDetails(raw) {
+    const { capUsd, spentUsd, heldUsd, leftUsd, baseBudgetUsd, grantedUsd, limitUsd, groupName } = raw;
+    if (![capUsd, spentUsd, heldUsd, leftUsd, baseBudgetUsd, grantedUsd, limitUsd].every(isFiniteNumber))
+        return null;
+    return {
+        source: "top-up",
+        capUsd: capUsd,
+        spentUsd: spentUsd,
+        heldUsd: heldUsd,
+        leftUsd: leftUsd,
+        baseBudgetUsd: baseBudgetUsd,
+        grantedUsd: grantedUsd,
+        limitUsd: limitUsd,
+        ...(typeof groupName === "string" && groupName ? { groupName } : {}),
+    };
+}
+/** A stored row as a view, or null when its limit or details fail the shape check (so no sentence can throw). */
+function budgetEventView(row) {
+    if (!BUDGET_LIMITS.has(row.limit) || !isRecord(row.details))
+        return null;
+    const at = row.at.toISOString();
+    const limit = row.limit;
+    if (row.kind === "overrun_unavailable") {
+        const details = row.details.source === "top-up" ? topUpRefusalDetails(row.details) : null;
+        return details ? { kind: "overrun_unavailable", limit, at, details } : null;
+    }
+    if (row.kind !== "refused")
+        return null;
+    const details = row.details.source === "proxy"
+        ? proxyRefusalDetails(row.details)
+        : row.details.source === "dispatch"
+            ? dispatchRefusalDetails(row.details)
+            : null;
+    if (!details)
+        return null;
+    return { kind: "refused", limit, at, details };
+}
+/** The run's latest well-formed budget event of `kind`, or null. Never throws. */
+async function latestEvent(db, runId, kind) {
+    try {
+        const row = await db.runBudgetEvent.findFirst({ where: { runId, kind }, orderBy: { at: "desc" } });
+        return row ? budgetEventView(row) : null;
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not read the latest budget event");
+        return null;
+    }
+}
+/** The run's latest well-formed budget refusal, or null. Never throws. */
+export async function latestBudgetEvent(db, runId) {
+    return latestEvent(db, runId, "refused");
+}
+/**
+ * Loads the run, its agent and budget group once and, when `withLead`, walks
+ * `parentRunId` (bounded) to the tree root once.
+ */
+async function budgetEventNames(db, runId, withLead) {
+    const run = await db.run.findUnique({
+        where: { id: runId },
+        select: {
+            parentRunId: true,
+            agent: { select: { name: true, budgetUsd: true, budgetGroup: { select: { name: true } } } },
+            codingRun: { select: { budgetBaseUsd: true, budgetLimitUsd: true } },
+        },
+    });
+    const names = {};
+    if (!run)
+        return names;
+    if (run.agent) {
+        names.agentName = run.agent.name;
+        const budget = Number(run.agent.budgetUsd);
+        if (Number.isFinite(budget))
+            names.agentBudgetUsd = budget;
+        if (run.agent.budgetGroup?.name)
+            names.groupName = run.agent.budgetGroup.name;
+    }
+    const base = run.codingRun?.budgetBaseUsd == null ? NaN : Number(run.codingRun.budgetBaseUsd);
+    if (Number.isFinite(base))
+        names.baseBudgetUsd = base;
+    const limit = run.codingRun?.budgetLimitUsd == null ? NaN : Number(run.codingRun.budgetLimitUsd);
+    if (Number.isFinite(limit))
+        names.limitUsd = limit;
+    if (withLead) {
+        let lead = run.agent?.name;
+        let id = run.parentRunId;
+        for (let hops = 1; id && hops < 32; hops++) {
+            const row = await db.run.findUnique({
+                where: { id },
+                select: { parentRunId: true, agent: { select: { name: true } } },
+            });
+            if (!row)
+                break;
+            lead = row.agent?.name ?? lead;
+            id = row.parentRunId;
+        }
+        if (lead)
+            names.leadAgentName = lead;
+    }
+    return names;
+}
+/**
+ * The event with its names filled: the group, the agent budget (proxy refusals) and the lead (run-tree).
+ * A top-up refusal keeps the group it recorded: the full cap can be the lead's group, not the run's.
+ */
+function withNames(event, names) {
+    const details = { ...event.details };
+    if (names.groupName && details.source !== "top-up")
+        details.groupName = names.groupName;
+    if (details.source === "proxy" && names.agentBudgetUsd !== undefined)
+        details.agentBudgetUsd = names.agentBudgetUsd;
+    if (details.source === "proxy" && names.baseBudgetUsd !== undefined)
+        details.baseBudgetUsd = names.baseBudgetUsd;
+    if (details.source === "proxy" && names.limitUsd !== undefined)
+        details.limitUsd = names.limitUsd;
+    if (event.limit === "run-tree" && names.leadAgentName)
+        details.leadAgentName = names.leadAgentName;
+    if (!event.overrun)
+        return { ...event, details };
+    const overrun = { limit: event.overrun.limit, details: { ...event.overrun.details } };
+    if (overrun.limit === "run-tree" && names.leadAgentName)
+        overrun.details.leadAgentName = names.leadAgentName;
+    return { ...event, details, overrun };
+}
+/**
+ * The run's latest budget refusal with names filled in from its agent, budget
+ * group and (for a run-tree limit) the tree root. A proxy refusal carries the
+ * run's overrun_unavailable event, when its overrun top-up found no room.
+ * Never throws; null when there is none.
+ */
+export async function loadBudgetEvent(db, runId) {
+    try {
+        const refusal = await latestBudgetEvent(db, runId);
+        if (!refusal)
+            return null;
+        const overrun = refusal.details.source === "proxy" ? await latestEvent(db, runId, "overrun_unavailable") : null;
+        const event = overrun?.details.source === "top-up"
+            ? { ...refusal, overrun: { limit: overrun.limit, details: overrun.details } }
+            : refusal;
+        const names = await budgetEventNames(db, runId, event.limit === "run-tree" || event.overrun?.limit === "run-tree");
+        return { event: withNames(event, names), agentName: names.agentName ?? "this agent" };
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not load the budget event");
+        return null;
+    }
+}
+/**
+ * Every well-formed budget event of the run, oldest first, with names filled
+ * in as loadBudgetEvent does (the run and tree are read once for all of
+ * them). If the names cannot be read the events are returned without them.
+ */
+export async function loadBudgetEvents(db, runId) {
+    const rows = await db.runBudgetEvent.findMany({ where: { runId }, orderBy: { at: "asc" } });
+    const events = rows.map(budgetEventView).filter((event) => event !== null);
+    if (events.length === 0)
+        return events;
+    try {
+        const names = await budgetEventNames(db, runId, events.some((event) => event.limit === "run-tree"));
+        return events.map((event) => withNames(event, names));
+    }
+    catch (err) {
+        log.warn({ err, runId }, "could not read the budget event names");
+        return events;
+    }
+}

package/dist/core/budget-groups.d.ts

@@ -51,6 +51,8 @@ export interface PeriodSpend {
     reservedUsd: number;
     /** capUsd - spentUsd - reservedUsd, never below zero. */
     remainingUsd: number;
+    /** How many of the period's runs hold something (reservedUsd > 0 each). */
+    heldRuns: number;
 }
 /** A group member as computeGroupSpend needs it: a native run in flight holds its agent's budgetUsd. */
 export interface GroupMember {
@@ -120,6 +122,18 @@ export declare function isHoldLive(run: HoldRow, now: Date, codingQueueTimeoutSe
  * returned with a null cap. One query at the widest configured window
  * (month contains week contains day), bucketed in JS, rather than a
  * separate DB round trip per period.
+ *
+ * A delegated run tree is held once, at its root. A sub-run whose tree root
+ * is a counted run of this group with a live, counted hold spends inside the
+ * root's hold, so it holds nothing (its cost still counts as spent), and the
+ * root holds its reservation minus the cost of every run in its tree, or the
+ * unspent holds of its tree's live runs when that is more (a coding run's
+ * grant can grow past the root's budget through overrun top-ups). A sub-run
+ * whose root is in another group, has finished, or whose hold is left out
+ * here (excludeReservationRunIds, holdsBefore) holds its own reservation. So
+ * does a sub-run in a period its root did not start in (a root that started
+ * yesterday, a child today: today's daily cap still holds the child's own
+ * reservation, since the root's hold falls in yesterday's bucket).
  */
 export declare function computeGroupSpend(db: BudgetGroupsDb, group: Pick<BudgetGroup, "dailyBudgetUsd" | "weeklyBudgetUsd" | "monthlyBudgetUsd">, members: readonly GroupMember[], now?: Date, options?: SpendOptions): Promise<PeriodSpend[]>;
 export interface RunTreeSpend {
@@ -148,11 +162,21 @@ export interface RunTreeSpend {
 export declare function computeRunTreeSpend(db: BudgetGroupsDb, parentRunId: string, now?: Date): Promise<RunTreeSpend>;
 export type BudgetConstraint = Period | "run-tree";
 export interface EffectiveBudgetResult {
+    /** The ceiling to use. */
     effectiveBudgetUsd: number;
-    /** Which constraint(s), if any, are tighter than the agent's own budgetUsd right now. */
+    /** Which constraint(s), if any, are tighter right now than the agent's own budgetUsd. */
     constrainedBy: BudgetConstraint[];
     /** The first constraint with nothing left (< MIN_RESERVATION_USD), set only when there is one. */
     exhaustedBy?: BudgetConstraint;
+    /** The constraint whose value equals effectiveBudgetUsd, when that is below the agent's own budgetUsd. */
+    limitedBy?: BudgetConstraint;
+    /** The numbers behind exhaustedBy, for the dispatch refusal record. */
+    exhaustedDetail?: {
+        capUsd: number;
+        spentUsd: number;
+        heldUsd: number;
+        heldRuns: number;
+    };
 }
 export interface EffectiveBudgetOptions {
     /**
@@ -181,4 +205,29 @@ export interface EffectiveBudgetOptions {
  * the tree's included.
  */
 export declare function effectiveBudgetForRun(db: BudgetGroupsDb, agent: Pick<Agent, "id" | "budgetGroupId" | "budgetUsd">, now?: Date, parentRunId?: string, options?: EffectiveBudgetOptions): Promise<EffectiveBudgetResult>;
+/** What limits a coding run's next overrun top-up: the room left, and the constraint with the least. */
+export interface TopUpRoom {
+    /** The most a top-up may add now; Infinity when no group or run tree constrains the run. */
+    roomUsd: number;
+    limitedBy?: BudgetConstraint;
+    /** The numbers behind limitedBy. */
+    detail?: {
+        capUsd: number;
+        spentUsd: number;
+        heldUsd: number;
+    };
+    /** The budget group whose cap limits it, when limitedBy is a period. */
+    groupName?: string;
+}
+/**
+ * Room for a coding run's overrun top-up (budget-topup.ts): the least of what
+ * its budget group, its run tree's root group, and its run tree's
+ * overrun-raised ceiling have left right now. Each group is seen whole: every
+ * live hold counts, this run's own grant (or its tree's hold) included, with
+ * no first-come-first-served ordering, because a top-up is new money that runs
+ * started later did not count when they reserved. A grant of at most roomUsd
+ * raises each group's and the tree's committed total by at most that much, so
+ * caps and ceilings stay hard. Callers hold the group dispatch lock.
+ */
+export declare function codingTopUpRoom(db: BudgetGroupsDb, runId: string, now?: Date): Promise<TopUpRoom>;
 export {};