@wardby/cli 0.2.1 → 0.3.0

package/dist/core/budget-groups.js

@@ -1,4 +1,6 @@
+import { loadCodingConcurrencyConfig } from "../config/providers.js";
 import { logger } from "./logger.js";
+import { HEARTBEAT_TIMEOUT_MS, RECONCILE_INTERVAL_MS } from "./timing.js";
 const budgetGroupLog = logger.child({ module: "budget-groups" });
 /**
  * Calendar-aligned UTC period start. "week" is the ISO week: Monday 00:00
@@ -20,6 +22,44 @@ export function periodStart(period, now) {
 function toNullableNumber(value) {
     return value === null || value === undefined ? null : Number(value);
 }
+const IN_FLIGHT = new Set(["pending", "running"]);
+/**
+ * How long a run's last heartbeat keeps its hold alive: the reconciler's
+ * heartbeat timeout plus one reconcile interval, so a managed run is reaped
+ * (or re-claimed, which refreshes heartbeatAt) before its hold lapses.
+ * Managed native runs beat every HEARTBEAT_INTERVAL_MS (InProcessExecutor,
+ * DbosExecutor), as do `wardby run` and native sub-agent children
+ * (withRunHeartbeat); a coding run beats while its job is polled.
+ */
+export const HOLD_HEARTBEAT_TTL_MS = HEARTBEAT_TIMEOUT_MS + RECONCILE_INTERVAL_MS;
+/** Slack past a coding run's queue + run timeout before its hold lapses (matches the sub-agent wait grace). */
+export const CODING_HOLD_GRACE_SEC = 60;
+/** Smallest amount worth holding or reserving: CodingRun.budgetReservedUsd has 6 decimal places. */
+export const MIN_RESERVATION_USD = 0.000001;
+/**
+ * Whether an in-flight row still holds budget. A run holds while its last
+ * sign of life (heartbeatAt, or startedAt before its first beat) is within
+ * HOLD_HEARTBEAT_TTL_MS. A coding run also holds, beat or not, until its
+ * queue timeout + run timeout + grace have passed since dispatch: a queued
+ * coding run does not beat, and nothing can legitimately spend past that.
+ */
+export function isHoldLive(run, now, codingQueueTimeoutSec) {
+    if (!IN_FLIGHT.has(run.status))
+        return false;
+    const lastSign = (run.heartbeatAt ?? run.startedAt).getTime();
+    if (now.getTime() - lastSign <= HOLD_HEARTBEAT_TTL_MS)
+        return true;
+    if (run.codingRun) {
+        const deadlineMs = run.startedAt.getTime() + (codingQueueTimeoutSec + run.codingRun.timeoutSec + CODING_HOLD_GRACE_SEC) * 1000;
+        return now.getTime() <= deadlineMs;
+    }
+    return false;
+}
+function isOrderedBefore(run, other) {
+    const a = run.startedAt.getTime();
+    const b = other.startedAt.getTime();
+    return a < b || (a === b && run.id < other.id);
+}
 /**
  * Live per-period spend for whichever of a group's daily/weekly/monthly
  * caps are actually set -- unset periods are omitted from the result, not
@@ -27,7 +67,7 @@ function toNullableNumber(value) {
  * (month contains week contains day), bucketed in JS, rather than a
  * separate DB round trip per period.
  */
-export async function computeGroupSpend(db, group, memberAgentIds, now = new Date()) {
+export async function computeGroupSpend(db, group, members, now = new Date(), options = {}) {
     const caps = [
         { period: "day", capUsd: toNullableNumber(group.dailyBudgetUsd) },
         { period: "week", capUsd: toNullableNumber(group.weeklyBudgetUsd) },
@@ -42,28 +82,56 @@ export async function computeGroupSpend(db, group, memberAgentIds, now = new Dat
     // query itself as a cheap no-op; an empty `agentId: { in: [] }` would
     // match nothing anyway.
     const widestStart = periodStart("month", now);
-    const runs = memberAgentIds.length === 0
+    const memberBudgets = new Map(members.map((m) => [m.id, Number(m.budgetUsd)]));
+    const excluded = new Set(options.excludeReservationRunIds ?? []);
+    const queueTimeoutSec = options.codingQueueTimeoutSec ?? loadCodingConcurrencyConfig().queueTimeoutSec;
+    const runs = members.length === 0
         ? []
         : await db.run.findMany({
-            where: { agentId: { in: memberAgentIds }, startedAt: { gte: widestStart } },
-            select: { costUsd: true, startedAt: true },
+            where: { agentId: { in: [...memberBudgets.keys()] }, startedAt: { gte: widestStart } },
+            select: {
+                id: true,
+                agentId: true,
+                status: true,
+                costUsd: true,
+                startedAt: true,
+                heartbeatAt: true,
+                codingRun: { select: { budgetReservedUsd: true, timeoutSec: true } },
+            },
         });
+    const accounted = runs.map((r) => {
+        const costUsd = Number(r.costUsd);
+        let reservedUsd = 0;
+        const holds = !excluded.has(r.id) &&
+            (options.holdsBefore === undefined || isOrderedBefore(r, options.holdsBefore)) &&
+            isHoldLive(r, now, queueTimeoutSec);
+        if (holds) {
+            // A coding run holds exactly what dispatch reserved. A native run (or
+            // a coding run whose CodingRun row is missing) holds its agent's
+            // per-run budget: never less than what it can actually spend.
+            const reservation = r.codingRun != null ? Number(r.codingRun.budgetReservedUsd) : (memberBudgets.get(r.agentId) ?? 0);
+            reservedUsd = Math.max(0, reservation - costUsd);
+        }
+        return { startedAt: r.startedAt, costUsd, reservedUsd };
+    });
     return configured.map(({ period, capUsd }) => {
         const start = periodStart(period, now);
-        const spentUsd = runs.filter((r) => r.startedAt >= start).reduce((sum, r) => sum + Number(r.costUsd), 0);
-        return { period, capUsd, spentUsd, remainingUsd: Math.max(0, capUsd - spentUsd) };
+        const inPeriod = accounted.filter((r) => r.startedAt >= start);
+        const spentUsd = inPeriod.reduce((sum, r) => sum + r.costUsd, 0);
+        const reservedUsd = inPeriod.reduce((sum, r) => sum + r.reservedUsd, 0);
+        return { period, capUsd, spentUsd, reservedUsd, remainingUsd: Math.max(0, capUsd - spentUsd - reservedUsd) };
     });
 }
 /** Walks parentRunId upward from `runId` to the tree's root (parentRunId null). */
 async function findRootRun(db, runId) {
     let current = await db.run.findUniqueOrThrow({
         where: { id: runId },
-        select: { id: true, agentId: true, parentRunId: true },
+        select: { id: true, agentId: true, parentRunId: true, startedAt: true },
     });
     while (current.parentRunId) {
         current = await db.run.findUniqueOrThrow({
             where: { id: current.parentRunId },
-            select: { id: true, agentId: true, parentRunId: true },
+            select: { id: true, agentId: true, parentRunId: true, startedAt: true },
         });
     }
     return current;
@@ -88,9 +156,17 @@ async function collectTreeRunIds(db, rootRunId) {
  * spent so far. The root's ceiling is recomputed fresh here, not pinned
  * from whatever it was when the root run started — consistent with
  * BudgetGroup periods already always being live-recomputed rather than
- * snapshotted.
+ * snapshotted. That group check sees the group as the root did when it
+ * loaded: the tree's own holds are left out (the tree spends inside the
+ * root's hold, so counting it again would leave the tree nothing), and so
+ * are holds of runs that started after the root (they already counted the
+ * root's hold).
  */
 export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
+    const { rootRunId, capUsd, spentUsd, remainingUsd } = await runTreeSpend(db, parentRunId, now);
+    return { rootRunId, capUsd, spentUsd, remainingUsd };
+}
+async function runTreeSpend(db, parentRunId, now) {
     const root = await findRootRun(db, parentRunId);
     const treeRunIds = await collectTreeRunIds(db, root.id);
     const rows = await db.run.findMany({ where: { id: { in: treeRunIds } }, select: { costUsd: true } });
@@ -99,11 +175,23 @@ export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
         where: { id: root.agentId },
         select: { id: true, budgetGroupId: true, budgetUsd: true },
     });
+    const rootOrder = { id: root.id, startedAt: root.startedAt };
     // Root has no parentRunId of its own, so this terminates in one level —
     // no unbounded recursion regardless of how deep `parentRunId` itself was.
-    const rootCeiling = await effectiveBudgetForRun(db, rootAgent, now);
+    const rootCeiling = await groupCappedBudget(db, rootAgent, now, {
+        excludeReservationRunIds: treeRunIds,
+        holdsBefore: rootOrder,
+    });
     const capUsd = rootCeiling.effectiveBudgetUsd;
-    return { rootRunId: root.id, capUsd, spentUsd, remainingUsd: Math.max(0, capUsd - spentUsd) };
+    return {
+        rootRunId: root.id,
+        capUsd,
+        spentUsd,
+        remainingUsd: Math.max(0, capUsd - spentUsd),
+        treeRunIds,
+        root: rootOrder,
+        rootBudgetGroupId: rootAgent.budgetGroupId,
+    };
 }
 /**
  * The per-run budget ceiling to actually use for `agent`: its own
@@ -116,17 +204,35 @@ export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
  * with no caps configured is returned unchanged. Also logs a warning
  * (never blocks, never throws) once a period's spend crosses the group's
  * own warnThresholdRatio.
+ *
+ * A sub-agent in the root's own budget group spends inside the root's hold,
+ * so its group check is the root's: the tree's holds and the holds of runs
+ * after the root are left out. A sub-agent in any other group is an
+ * ordinary member of that group and counts every earlier live hold there,
+ * the tree's included.
  */
-export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId) {
+export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId, options = {}) {
+    const self = options.self;
+    const ownSpend = { excludeReservationRunIds: self ? [self.id] : [], holdsBefore: self };
+    if (!parentRunId)
+        return groupCappedBudget(db, agent, now, ownSpend);
+    const tree = await runTreeSpend(db, parentRunId, now);
+    const sharesRootGroup = agent.budgetGroupId !== null && agent.budgetGroupId === tree.rootBudgetGroupId;
+    const spend = sharesRootGroup
+        ? { excludeReservationRunIds: [...tree.treeRunIds, ...(self ? [self.id] : [])], holdsBefore: tree.root }
+        : ownSpend;
+    return groupCappedBudget(db, agent, now, spend, { value: tree.remainingUsd, reason: "run-tree" });
+}
+async function groupCappedBudget(db, agent, now, spendOptions, extra) {
     const ownBudgetUsd = Number(agent.budgetUsd);
     const candidates = [];
     if (agent.budgetGroupId) {
         const group = await db.budgetGroup.findUnique({
             where: { id: agent.budgetGroupId },
-            include: { agents: { select: { id: true } } },
+            include: { agents: { select: { id: true, budgetUsd: true } } },
         });
         if (group) {
-            const spend = await computeGroupSpend(db, group, group.agents.map((a) => a.id), now);
+            const spend = await computeGroupSpend(db, group, group.agents, now, spendOptions);
             const warnThresholdRatio = Number(group.warnThresholdRatio);
             for (const s of spend) {
                 candidates.push({ value: s.remainingUsd, reason: s.period });
@@ -137,13 +243,13 @@ export async function effectiveBudgetForRun(db, agent, now = new Date(), parentR
             }
         }
     }
-    if (parentRunId) {
-        const tree = await computeRunTreeSpend(db, parentRunId, now);
-        candidates.push({ value: tree.remainingUsd, reason: "run-tree" });
-    }
+    if (extra)
+        candidates.push(extra);
     if (candidates.length === 0)
         return { effectiveBudgetUsd: ownBudgetUsd, constrainedBy: [] };
     const constrainedBy = candidates.filter((c) => c.value < ownBudgetUsd).map((c) => c.reason);
     const effectiveBudgetUsd = Math.min(ownBudgetUsd, ...candidates.map((c) => c.value));
-    return { effectiveBudgetUsd, constrainedBy };
+    // Less than the smallest reservable amount is nothing left.
+    const exhausted = candidates.find((c) => c.value < MIN_RESERVATION_USD);
+    return { effectiveBudgetUsd, constrainedBy, ...(exhausted ? { exhaustedBy: exhausted.reason } : {}) };
 }

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

@@ -0,0 +1,22 @@
+/**
+ * The one sentence a host (a PR comment, a check summary) is told when a run
+ * ran out of budget, or could not start for lack of it. Public repositories
+ * read these, so it names amounts and the budget group only: never error
+ * text, token counts, or ids.
+ */
+import type { PrismaClient } from "#prisma";
+export interface BudgetFacts {
+    /** The run's own budget (a coding run's reservation); falls back to the agent's. */
+    runBudgetUsd?: number | null;
+    agentBudgetUsd: number;
+    budgetGroupName?: string | null;
+    /** The run was refused before it started. */
+    refused?: boolean;
+}
+export declare function budgetSentence(facts: BudgetFacts): string;
+/**
+ * The sentence for a finished run, read from the database: a coding run's
+ * reserved budget, otherwise the agent's. Falls back to a sentence without
+ * amounts when they cannot be read. Never throws.
+ */
+export declare function loadBudgetSentence(db: Pick<PrismaClient, "run">, runId: string, status: string): Promise<string>;

package/dist/core/budget-wording.js

@@ -0,0 +1,55 @@
+const MAX_GROUP_NAME_CHARS = 64;
+const usd = (amount) => `$${amount.toFixed(2)}`;
+/** A group name is operator-chosen text; keep it to one short, quote-free line. */
+function groupName(name) {
+    const cleaned = (name ?? "").replace(/["`]/g, "").replace(/\s+/g, " ").trim().slice(0, MAX_GROUP_NAME_CHARS);
+    return cleaned || null;
+}
+export function budgetSentence(facts) {
+    const group = groupName(facts.budgetGroupName);
+    if (facts.refused) {
+        const within = `this run could not start within its ${usd(facts.runBudgetUsd ?? facts.agentBudgetUsd)} budget`;
+        return group
+            ? `Out of budget: ${within} or what the "${group}" budget group had left of its limit.`
+            : `Out of budget: ${within}.`;
+    }
+    const runBudget = facts.runBudgetUsd ?? facts.agentBudgetUsd;
+    const used = `Out of budget: this run's ${usd(runBudget)} budget was used up`;
+    // A run reserved less than the agent's own budget: its group had only that much left.
+    if (group && runBudget < facts.agentBudgetUsd) {
+        return `${used} (the "${group}" budget group had only that much left of its limit).`;
+    }
+    return `${used}.`;
+}
+/**
+ * The sentence for a finished run, read from the database: a coding run's
+ * reserved budget, otherwise the agent's. Falls back to a sentence without
+ * amounts when they cannot be read. Never throws.
+ */
+export async function loadBudgetSentence(db, runId, status) {
+    const refused = status === "refused";
+    try {
+        const row = await db.run.findUnique({
+            where: { id: runId },
+            select: {
+                agent: { select: { budgetUsd: true, budgetGroup: { select: { name: true } } } },
+                codingRun: { select: { budgetReservedUsd: true } },
+            },
+        });
+        const agentBudgetUsd = Number(row?.agent?.budgetUsd);
+        if (!row?.agent || !Number.isFinite(agentBudgetUsd))
+            throw new Error("budget_facts_unavailable");
+        const reserved = row.codingRun ? Number(row.codingRun.budgetReservedUsd) : NaN;
+        return budgetSentence({
+            runBudgetUsd: Number.isFinite(reserved) ? reserved : null,
+            agentBudgetUsd,
+            budgetGroupName: row.agent.budgetGroup?.name ?? null,
+            refused,
+        });
+    }
+    catch {
+        return refused
+            ? "Out of budget: this run could not start within its budget."
+            : "Out of budget: this run's budget was used up.";
+    }
+}

package/dist/core/datastores.js

@@ -25,9 +25,25 @@ export async function attachDatastore(agentId, datastoreId, db, boundName) {
 export async function detachDatastore(agentId, boundName, db) {
     await db.agentDatastore.deleteMany({ where: { agentId, boundName } });
 }
+/**
+ * Owner rule (resource-sharing grants spec §3.4.1): a binding resolves only
+ * while the datastore's owner is the agent's CURRENT owner, both non-null.
+ * A cross-owner binding (written before that rule, or left behind by
+ * make_owner) and every binding on an owner-less agent resolve like an
+ * unattached boundName, so one owner's store never reaches another owner's
+ * agent (A2/S2-2, R2-1).
+ */
 async function resolveDatastoreId(agentId, boundName, db) {
-    const attachment = await db.agentDatastore.findFirst({ where: { agentId, boundName } });
-    return attachment?.datastoreId;
+    const attachment = await db.agentDatastore.findFirst({
+        where: { agentId, boundName },
+        include: { datastore: { select: { ownerId: true } }, agent: { select: { ownerId: true } } },
+    });
+    if (!attachment)
+        return undefined;
+    const owner = attachment.agent.ownerId;
+    if (owner === null || attachment.datastore.ownerId !== owner)
+        return undefined;
+    return attachment.datastoreId;
 }
 /**
  * Resolves `boundName` to the Datastore attached to this agent under that

package/dist/core/db.d.ts

@@ -32,5 +32,9 @@ export declare function poolSettings(connectionString: string): PoolSettings;
  * The one way wardby builds a Prisma client. `url` defaults to DATABASE_URL
  * as read at call time.
  */
-export declare function createPrismaClient(url?: string | undefined): PrismaClient;
+/** `poolMax` overrides the pool size for a caller that sizes its own pools
+ *  (the coding proxy keeps its ledger and its package registry apart). */
+export declare function createPrismaClient(url?: string | undefined, options?: {
+    poolMax?: number;
+}): PrismaClient;
 export declare const prisma: PrismaClient;

package/dist/core/db.js

@@ -60,9 +60,15 @@ class MissingUrlAdapter extends PrismaPg {
  * The one way wardby builds a Prisma client. `url` defaults to DATABASE_URL
  * as read at call time.
  */
-export function createPrismaClient(url = process.env.DATABASE_URL) {
+/** `poolMax` overrides the pool size for a caller that sizes its own pools
+ *  (the coding proxy keeps its ledger and its package registry apart). */
+export function createPrismaClient(url = process.env.DATABASE_URL, options = {}) {
     const adapter = url
-        ? new PrismaPg({ connectionString: url, ...poolSettings(url) })
+        ? new PrismaPg({
+            connectionString: url,
+            ...poolSettings(url),
+            ...(options.poolMax !== undefined ? { max: options.poolMax } : {}),
+        })
         : new MissingUrlAdapter({ connectionString: "" });
     return new PrismaClient({ adapter });
 }

package/dist/core/dispatch.d.ts

@@ -1,7 +1,8 @@
 import type { Prisma, PrismaClient, Run, RunTrigger, Task } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
-export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$transaction" | "$queryRaw">;
-type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "codingRun" | "task" | "webhook" | "$queryRaw">;
+import { type BudgetConstraint } from "./budget-groups.js";
+export type DispatchDb = Pick<PrismaClient, "agent" | "run" | "runHostCheck" | "codingRun" | "task" | "webhook" | "budgetGroup" | "$transaction" | "$queryRaw">;
+export type DispatchTx = Pick<Prisma.TransactionClient, "agent" | "run" | "runHostCheck" | "runHostStatus" | "codingRun" | "codingService" | "task" | "webhook" | "budgetGroup" | "resourceGrant" | "$queryRaw" | "$executeRawUnsafe">;
 type DispatchAgent = Prisma.AgentGetPayload<{
     include: {
         codingProfile: true;
@@ -32,6 +33,19 @@ export interface DispatchRunOptions {
         ttlMs: number;
     };
     beforePersist?: (tx: DispatchTx, agent: DispatchAgent) => Promise<boolean>;
+    /**
+     * Runs inside the persist transaction right after the run row is created,
+     * before the executor is started — for rows that must exist before the run
+     * can observe them (e.g. RunHostCheck, see core/host-events.ts).
+     */
+    afterPersist?: (tx: DispatchTx, run: Run) => Promise<void>;
+    /**
+     * Who the run is visible to besides the agent owner (Run.triggeredById,
+     * resource-sharing grants spec §3.5): the trigger_agent caller, a
+     * webhook's creator, a sub-agent's parent triggerer. Omit/null for
+     * scheduled and host-event runs, which only the owner sees.
+     */
+    triggeredById?: string | null;
     /** Sub-agent dispatch (see AgentSubAgent): links this run into a run tree. */
     parentRunId?: string;
     grantedParentMemoryKeys?: string[];
@@ -42,10 +56,10 @@ export interface DispatchRunOptions {
      */
     taskOverride?: string;
     /**
-     * Overrides `agent.budgetUsd` for this run's coding budget reservation —
-     * used by sub-agent dispatch to apply the run-tree's tightened effective
-     * budget (see src/core/budget-groups.ts) instead of the agent's raw
-     * per-run ceiling, the same composability already applied to native runs.
+     * Replaces `agent.budgetUsd` as the requested ceiling for this run's coding
+     * budget reservation. The reservation is still tightened by the agent's
+     * budget group and, with `parentRunId`, the run tree (see
+     * src/core/budget-groups.ts), computed inside the persist transaction.
      * Ignored for native agents, which compute their own effective budget
      * inside executeRun's load step.
      */
@@ -87,6 +101,19 @@ export declare function isSerializationConflict(err: unknown): boolean;
  * than overwrite whatever landed in between.
  */
 export declare function markRunFailedFromExecutorError(db: Pick<DispatchDb, "run">, runId: string, err: unknown): Promise<void>;
+/**
+ * The `Run.error` of a coding run refused at dispatch because a budget
+ * constraint has nothing left: `budget_group_exhausted:<period>` or
+ * `run_tree_exhausted`, then a sentence for people.
+ */
+export declare function budgetExhaustedError(constraint: BudgetConstraint): string;
+/**
+ * Attempts for the persist transaction, and the jittered backoff between
+ * them, for serialization failures and deadlocks.
+ *
+ * @internal Exported only for the real-PostgreSQL tests.
+ */
+export declare const PERSIST_ATTEMPTS = 8;
 /**
  * Persists every detached run input in one transaction, then invokes the
  * executor only after commit. A null result means the caller's transactional