@wardby/cli 0.1.0

package/dist/config/providers.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Provider selection from the environment.
+ *
+ * Which adapter backs each seam is pure configuration — swapping the default
+ * (portable) deployment for a native cloud deployment is a config change, not a
+ * code change. The `assembleProviders` factory (which constructs the concrete
+ * adapters) is added once the adapters exist.
+ */
+import { type KubernetesPlatform } from "../providers/jobs/kubernetes-platform.js";
+export type JobLauncherKind = "local" | "docker" | "kubernetes";
+export type EmailProviderKind = "smtp" | "ses";
+export type SecretCipherKind = "app-key" | "kms";
+export type AuthProviderKind = "delegating" | "self-hosted";
+export type BlobStoreKind = "local" | "s3";
+export type ExecutorKind = "in-process" | "dbos";
+export type DatastoreKind = "postgres";
+export type EngineKind = "native" | "langgraph";
+export type VcsProviderKind = "github";
+export interface ProviderConfig {
+    jobs: JobLauncherKind;
+    email: EmailProviderKind;
+    secrets: SecretCipherKind;
+    auth: AuthProviderKind;
+    storage: BlobStoreKind;
+    executor: ExecutorKind;
+    datastore: DatastoreKind;
+    engine: EngineKind;
+    vcs: VcsProviderKind;
+}
+/** Read provider selection from environment variables, defaulting to portable. */
+export declare function loadProviderConfig(env?: NodeJS.ProcessEnv): ProviderConfig;
+export interface GitHubVcsConfig {
+    appId?: string;
+    privateKey?: string;
+    workRoot?: string;
+    apiVersion?: string;
+    maxChangedFiles?: number;
+    maxDiffBytes?: number;
+}
+export declare function loadGitHubVcsConfig(env?: NodeJS.ProcessEnv): GitHubVcsConfig;
+export interface ContainerExecutorConfig {
+    workerImage?: string;
+    claudeWorkerImage?: string;
+    claudeToolRunnerImage?: string;
+    proxyContainer?: string;
+    stateRoot?: string;
+    artifactRoot?: string;
+    credentialRef: string;
+    anthropicCredentialRef: string;
+    cpus: number;
+    memoryMb: number;
+    pids: number;
+    diskMb: number;
+    /**
+     * Operator ceiling on the per-agent CodingProfile.workspaceDiskMb (Task 9):
+     * without it, any agents:write caller could size the RAM-backed Docker
+     * tmpfs (and keeper memory) up to 32 GiB per run, times CODING_MAX_CONCURRENT.
+     */
+    maxDiskMb: number;
+    additionalWorkerImages: Record<string, Record<string, string>>;
+}
+export declare function loadContainerExecutorConfig(env?: NodeJS.ProcessEnv): ContainerExecutorConfig;
+/**
+ * Caps coding runs holding a concurrency slot across every control-plane
+ * replica (enforced in Postgres, see PrismaContainerExecutionStore), and how
+ * long a run may wait for one before failing with coding_queue_timeout.
+ */
+export interface CodingConcurrencyConfig {
+    maxConcurrent: number;
+    queueTimeoutSec: number;
+}
+export declare function loadCodingConcurrencyConfig(env?: NodeJS.ProcessEnv): CodingConcurrencyConfig;
+/** JOB_LAUNCHER=kubernetes: where coding-run pods go, how they reach the in-cluster proxy, and which platform's admission rules apply. */
+export interface KubernetesJobConfig {
+    namespace: string;
+    context?: string;
+    proxyService: string;
+    runtimeClassName?: string;
+    platform: KubernetesPlatform;
+    /**
+     * Bound for the whole cluster preflight (canary pod scheduling included) and for how long a
+     * launch waits for the keeper. Both default to the launcher's own values (90 s / 120 s), which
+     * a cold managed cluster scheduling a sandboxed pod and pulling an image routinely exceeds.
+     */
+    preflightTimeoutMs?: number;
+    readyTimeoutMs?: number;
+}
+export declare function loadKubernetesJobConfig(env?: NodeJS.ProcessEnv): KubernetesJobConfig;
+export interface McpConfig {
+    allowedOrigins?: string[];
+    transport: "http" | "stdio";
+    httpBind?: {
+        host: string;
+        port: number;
+    };
+    canonicalUri?: string;
+    localPrincipal: string;
+    /**
+     * Use the MCP spec's own multi-round-trip URL-mode elicitation
+     * (`InputRequiredResult`) for interactive secret entry, instead of the
+     * plain-text "here's a link, call me again" fallback. Off by default:
+     * as of Claude Code 2.1.263, this stdio client doesn't declare the
+     * elicitation capability for local project servers, so the protocol
+     * path fails outright ("did not declare the required capability").
+     * Flip this on once that's fixed client-side — no server code changes
+     * needed, both paths share the same signed-token/browser-form core.
+     */
+    secretElicitationProtocol: boolean;
+}
+/** Read MCP server transport/binding config from the environment. */
+export declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+export interface AuthConfig {
+    /** Delegating mode: the external IdP's issuer URL. */
+    issuer?: string;
+    /** Delegating mode: JWKS endpoint for signature verification. */
+    jwksUri?: string;
+    /** Both modes: the audience a token must carry to be accepted (wardby's canonical URI). */
+    audience?: string;
+    /** Self-hosted mode: independent 32-byte hex keys. */
+    signingKey?: string;
+    credentialHashKey?: string;
+    maxClients?: number;
+}
+/** Read auth-adapter config (issuer/JWKS/audience/signing key) from the environment. */
+export declare function loadAuthConfig(env?: NodeJS.ProcessEnv): AuthConfig;
+export interface SecretConfig {
+    /** app-key mode: 32-byte hex-encoded AES-256-GCM master key. */
+    appKey?: string;
+}
+/** Read secret-cipher config (the app-key master key) from the environment. */
+export declare function loadSecretConfig(env?: NodeJS.ProcessEnv): SecretConfig;
+export interface DbosConfig {
+    /**
+     * Where DBOS keeps its workflow/step tables. Defaults to DATABASE_URL —
+     * the tables live in their own schema (`schemaName`), so Prisma's `public`
+     * schema and the migration drift check are untouched.
+     */
+    systemDatabaseUrl: string | undefined;
+    schemaName: string;
+    /**
+     * Stable per-*process* executor identity. At launch DBOS re-drives every
+     * PENDING workflow that this id owned, so a restarted process picks up its
+     * own interrupted runs — which also means two processes sharing an id each
+     * re-drive the other's live workflows. There is deliberately no default:
+     * `DbosExecutor` refuses to construct without one (a default would silently
+     * give the scheduler and the MCP server the same identity).
+     *
+     * Defaults to a freshly generated UUID per call (per process) when unset
+     * — not left undefined — so two replicas of a horizontally-scaled
+     * deployment (e.g. a Cloud Run service with min_instance_count > 1) never
+     * silently share an identity just because no one set one explicitly. An
+     * explicit DBOS_EXECUTOR_ID still always wins, for local dev or a small
+     * deployment wanting a stable, human-readable id across restarts.
+     */
+    executorId: string | undefined;
+}
+/** Read DBOS executor config from the environment (only used when EXECUTOR=dbos). */
+export declare function loadDbosConfig(env?: NodeJS.ProcessEnv): DbosConfig;

package/dist/config/providers.js

@@ -0,0 +1,162 @@
+/**
+ * Provider selection from the environment.
+ *
+ * Which adapter backs each seam is pure configuration — swapping the default
+ * (portable) deployment for a native cloud deployment is a config change, not a
+ * code change. The `assembleProviders` factory (which constructs the concrete
+ * adapters) is added once the adapters exist.
+ */
+import { KUBERNETES_PLATFORMS } from "../providers/jobs/kubernetes-platform.js";
+/** Read provider selection from environment variables, defaulting to portable. */
+export function loadProviderConfig(env = process.env) {
+    return {
+        jobs: env.JOB_LAUNCHER ?? "local",
+        email: env.EMAIL_PROVIDER ?? "smtp",
+        secrets: env.SECRET_CIPHER ?? "app-key",
+        auth: env.AUTH_PROVIDER ?? "delegating",
+        storage: env.BLOB_STORE ?? "local",
+        executor: env.EXECUTOR ?? "in-process",
+        datastore: env.DATASTORE ?? "postgres",
+        engine: env.ENGINE ?? "native",
+        vcs: env.VCS_PROVIDER ?? "github",
+    };
+}
+function optionalPositiveInteger(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive integer.`);
+    return parsed;
+}
+export function loadGitHubVcsConfig(env = process.env) {
+    return {
+        appId: env.GITHUB_APP_ID,
+        privateKey: env.GITHUB_APP_PRIVATE_KEY,
+        workRoot: env.VCS_WORK_ROOT,
+        apiVersion: env.GITHUB_API_VERSION,
+        maxChangedFiles: optionalPositiveInteger(env.VCS_MAX_CHANGED_FILES, "VCS_MAX_CHANGED_FILES"),
+        maxDiffBytes: optionalPositiveInteger(env.VCS_MAX_DIFF_BYTES, "VCS_MAX_DIFF_BYTES"),
+    };
+}
+function optionalPositiveNumber(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive number.`);
+    return parsed;
+}
+function optionalBoundedInteger(value, name, min, max) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max}.`);
+    }
+    return parsed;
+}
+export function loadContainerExecutorConfig(env = process.env) {
+    const additionalWorkerImages = {};
+    if (env.CODING_WORKER_IMAGE_NODE_PYTHON_3_12) {
+        additionalWorkerImages["node-python"] = { "3.12": env.CODING_WORKER_IMAGE_NODE_PYTHON_3_12 };
+    }
+    const diskMb = optionalPositiveInteger(env.CODING_DISK_MB, "CODING_DISK_MB") ?? 2048;
+    // Defaults to the effective diskMb: raising the ceiling an agents:write caller can request is an
+    // explicit operator choice, so upgrading with an unchanged environment changes nothing.
+    const maxDiskMb = optionalBoundedInteger(env.CODING_MAX_DISK_MB, "CODING_MAX_DISK_MB", 64, 32_768) ?? diskMb;
+    if (maxDiskMb < diskMb) {
+        throw new Error(`CODING_MAX_DISK_MB (${maxDiskMb}) must be at least the effective CODING_DISK_MB (${diskMb}).`);
+    }
+    return {
+        workerImage: env.CODING_WORKER_IMAGE,
+        claudeWorkerImage: env.CODING_CLAUDE_WORKER_IMAGE,
+        claudeToolRunnerImage: env.CODING_CLAUDE_TOOL_RUNNER_IMAGE,
+        proxyContainer: env.CODING_PROXY_CONTAINER,
+        stateRoot: env.CODING_JOB_STATE_ROOT,
+        artifactRoot: env.CODING_ARTIFACT_ROOT,
+        credentialRef: env.CODING_OPENAI_CREDENTIAL_REF ?? "env:OPENAI_API_KEY",
+        anthropicCredentialRef: env.CODING_ANTHROPIC_CREDENTIAL_REF ?? "env:ANTHROPIC_API_KEY",
+        cpus: optionalPositiveNumber(env.CODING_CPUS, "CODING_CPUS", 1),
+        memoryMb: optionalPositiveInteger(env.CODING_MEMORY_MB, "CODING_MEMORY_MB") ?? 2048,
+        pids: optionalPositiveInteger(env.CODING_PIDS, "CODING_PIDS") ?? 128,
+        diskMb,
+        maxDiskMb,
+        additionalWorkerImages,
+    };
+}
+export function loadCodingConcurrencyConfig(env = process.env) {
+    return {
+        maxConcurrent: optionalPositiveInteger(env.CODING_MAX_CONCURRENT, "CODING_MAX_CONCURRENT") ?? 4,
+        queueTimeoutSec: optionalPositiveInteger(env.CODING_QUEUE_TIMEOUT_SEC, "CODING_QUEUE_TIMEOUT_SEC") ?? 3600,
+    };
+}
+const DNS_1123_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function dnsLabel(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!DNS_1123_LABEL.test(value))
+        throw new Error(`${name} must be a DNS-1123 label.`);
+    return value;
+}
+export function loadKubernetesJobConfig(env = process.env) {
+    const platform = (env.KUBERNETES_PLATFORM ?? "generic");
+    if (!KUBERNETES_PLATFORMS.includes(platform)) {
+        throw new Error(`KUBERNETES_PLATFORM must be one of: ${KUBERNETES_PLATFORMS.join(", ")}.`);
+    }
+    const config = {
+        namespace: dnsLabel(env.KUBERNETES_NAMESPACE, "KUBERNETES_NAMESPACE", "wardby-coding"),
+        proxyService: dnsLabel(env.KUBERNETES_PROXY_SERVICE, "KUBERNETES_PROXY_SERVICE", "wardby-coding-proxy"),
+        platform,
+    };
+    if (env.KUBERNETES_CONTEXT)
+        config.context = env.KUBERNETES_CONTEXT;
+    if (env.KUBERNETES_RUNTIME_CLASS) {
+        config.runtimeClassName = dnsLabel(env.KUBERNETES_RUNTIME_CLASS, "KUBERNETES_RUNTIME_CLASS", "");
+    }
+    const preflightTimeoutMs = optionalBoundedInteger(env.KUBERNETES_PREFLIGHT_TIMEOUT_MS, "KUBERNETES_PREFLIGHT_TIMEOUT_MS", 1_000, 900_000);
+    const readyTimeoutMs = optionalBoundedInteger(env.KUBERNETES_READY_TIMEOUT_MS, "KUBERNETES_READY_TIMEOUT_MS", 1_000, 900_000);
+    if (preflightTimeoutMs !== undefined)
+        config.preflightTimeoutMs = preflightTimeoutMs;
+    if (readyTimeoutMs !== undefined)
+        config.readyTimeoutMs = readyTimeoutMs;
+    return config;
+}
+/** Read MCP server transport/binding config from the environment. */
+export function loadMcpConfig(env = process.env) {
+    const transport = env.MCP_TRANSPORT ?? "stdio";
+    const bind = env.MCP_HTTP_BIND?.split(":");
+    return {
+        transport,
+        httpBind: bind ? { host: bind[0], port: Number(bind[1]) } : undefined,
+        canonicalUri: env.MCP_CANONICAL_URI,
+        allowedOrigins: env.MCP_ALLOWED_ORIGINS ? env.MCP_ALLOWED_ORIGINS.split(",").map((s) => s.trim()) : undefined,
+        localPrincipal: env.LOCAL_PRINCIPAL ?? "local",
+        secretElicitationProtocol: env.MCP_SECRET_ELICITATION_PROTOCOL === "true",
+    };
+}
+/** Read auth-adapter config (issuer/JWKS/audience/signing key) from the environment. */
+export function loadAuthConfig(env = process.env) {
+    return {
+        issuer: env.AUTH_ISSUER,
+        jwksUri: env.AUTH_JWKS_URI,
+        audience: env.AUTH_AUDIENCE,
+        signingKey: env.AUTH_SIGNING_KEY,
+        credentialHashKey: env.AUTH_CREDENTIAL_HASH_KEY,
+        maxClients: env.AUTH_MAX_CLIENTS ? Number(env.AUTH_MAX_CLIENTS) : undefined,
+    };
+}
+/** Read secret-cipher config (the app-key master key) from the environment. */
+export function loadSecretConfig(env = process.env) {
+    return {
+        appKey: env.SECRET_APP_KEY,
+    };
+}
+/** Read DBOS executor config from the environment (only used when EXECUTOR=dbos). */
+export function loadDbosConfig(env = process.env) {
+    return {
+        systemDatabaseUrl: env.DBOS_SYSTEM_DATABASE_URL ?? env.DATABASE_URL,
+        schemaName: env.DBOS_SCHEMA ?? "dbos",
+        executorId: env.DBOS_EXECUTOR_ID ?? crypto.randomUUID(),
+    };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Daily/weekly/monthly spend caps for a *group* of agents (BudgetGroup),
+ * layered on top of each agent's own per-run Agent.budgetUsd. Unlike
+ * budget.ts (pure, no DB, no network), this module queries Postgres: it
+ * computes how much of a group's remaining period budget a given agent
+ * should be allowed to spend on its next run, and hands back an
+ * *effective* per-run budget the caller uses in place of the agent's raw
+ * budgetUsd. The engine's existing turn-by-turn machinery (pre-flight
+ * refuse, mid-stream cutoff, wind-down — see engine-native.ts) then
+ * enforces that tightened ceiling with no changes of its own: a group
+ * whose period budget is already exhausted simply produces an effective
+ * budget of 0, which the engine's turn-1 gate already refuses exactly
+ * like any other zero/negative budget.
+ */
+import type { Agent, BudgetGroup, PrismaClient } from "@prisma/client";
+export type Period = "day" | "week" | "month";
+export type BudgetGroupsDb = Pick<PrismaClient, "budgetGroup" | "run" | "agent">;
+/**
+ * Calendar-aligned UTC period start. "week" is the ISO week: Monday 00:00
+ * UTC. `now`'s own time-of-day/day-of-week is truncated away, never
+ * rounded up -- a period start is always <= now.
+ */
+export declare function periodStart(period: Period, now: Date): Date;
+export interface PeriodSpend {
+    period: Period;
+    capUsd: number;
+    spentUsd: number;
+    remainingUsd: number;
+}
+/**
+ * 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
+ * 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.
+ */
+export declare function computeGroupSpend(db: BudgetGroupsDb, group: Pick<BudgetGroup, "dailyBudgetUsd" | "weeklyBudgetUsd" | "monthlyBudgetUsd">, memberAgentIds: string[], now?: Date): Promise<PeriodSpend[]>;
+export interface RunTreeSpend {
+    rootRunId: string;
+    capUsd: number;
+    spentUsd: number;
+    remainingUsd: number;
+}
+/**
+ * Real-time shared budget scope for a sub-agent dispatch: the whole run tree
+ * rooted at `parentRunId`'s ultimate ancestor shares one ceiling —
+ * the root's own effective budget (its own budgetUsd, itself tightened by
+ * its own BudgetGroup if any) minus everything every run in the tree has
+ * 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.
+ */
+export declare function computeRunTreeSpend(db: BudgetGroupsDb, parentRunId: string, now?: Date): Promise<RunTreeSpend>;
+export interface EffectiveBudgetResult {
+    effectiveBudgetUsd: number;
+    /** Which constraint(s), if any, are tighter than the agent's own budgetUsd right now. */
+    constrainedBy: (Period | "run-tree")[];
+}
+/**
+ * The per-run budget ceiling to actually use for `agent`: its own
+ * budgetUsd, tightened to whatever's left of its budget group's
+ * daily/weekly/monthly caps (whichever are set) AND, when `parentRunId` is
+ * given (this run was dispatched as a sub-agent — see AgentSubAgent),
+ * whatever's left of its run tree's shared ceiling. These are independent,
+ * composable constraints: the final ceiling is the minimum of all that
+ * apply, never one replacing another. An ungrouped, top-level agent run
+ * 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.
+ */
+export declare function effectiveBudgetForRun(db: BudgetGroupsDb, agent: Pick<Agent, "id" | "budgetGroupId" | "budgetUsd">, now?: Date, parentRunId?: string): Promise<EffectiveBudgetResult>;

package/dist/core/budget-groups.js

@@ -0,0 +1,149 @@
+import { logger } from "./logger.js";
+const budgetGroupLog = logger.child({ module: "budget-groups" });
+/**
+ * Calendar-aligned UTC period start. "week" is the ISO week: Monday 00:00
+ * UTC. `now`'s own time-of-day/day-of-week is truncated away, never
+ * rounded up -- a period start is always <= now.
+ */
+export function periodStart(period, now) {
+    if (period === "day") {
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+    }
+    if (period === "month") {
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    }
+    // getUTCDay(): Sunday=0 .. Saturday=6. Treat Sunday as 7 so "days since
+    // Monday" is always 0-6.
+    const daysSinceMonday = (now.getUTCDay() || 7) - 1;
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - daysSinceMonday));
+}
+function toNullableNumber(value) {
+    return value === null || value === undefined ? null : Number(value);
+}
+/**
+ * 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
+ * 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.
+ */
+export async function computeGroupSpend(db, group, memberAgentIds, now = new Date()) {
+    const caps = [
+        { period: "day", capUsd: toNullableNumber(group.dailyBudgetUsd) },
+        { period: "week", capUsd: toNullableNumber(group.weeklyBudgetUsd) },
+        { period: "month", capUsd: toNullableNumber(group.monthlyBudgetUsd) },
+    ];
+    const configured = caps.filter((c) => c.capUsd !== null);
+    if (configured.length === 0)
+        return [];
+    // A cap can be configured before any agent is ever attached to the group
+    // (e.g. right after create_budget_group) -- that's still a real,
+    // reportable state (spentUsd: 0), not "nothing to report." Only skip the
+    // 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
+        ? []
+        : await db.run.findMany({
+            where: { agentId: { in: memberAgentIds }, startedAt: { gte: widestStart } },
+            select: { costUsd: true, startedAt: true },
+        });
+    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) };
+    });
+}
+/** 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 },
+    });
+    while (current.parentRunId) {
+        current = await db.run.findUniqueOrThrow({
+            where: { id: current.parentRunId },
+            select: { id: true, agentId: true, parentRunId: true },
+        });
+    }
+    return current;
+}
+/** Breadth-first walk down childRuns from `rootRunId`, collecting every run id in the tree. */
+async function collectTreeRunIds(db, rootRunId) {
+    const all = [rootRunId];
+    let frontier = [rootRunId];
+    while (frontier.length > 0) {
+        const children = await db.run.findMany({ where: { parentRunId: { in: frontier } }, select: { id: true } });
+        const childIds = children.map((c) => c.id);
+        all.push(...childIds);
+        frontier = childIds;
+    }
+    return all;
+}
+/**
+ * Real-time shared budget scope for a sub-agent dispatch: the whole run tree
+ * rooted at `parentRunId`'s ultimate ancestor shares one ceiling —
+ * the root's own effective budget (its own budgetUsd, itself tightened by
+ * its own BudgetGroup if any) minus everything every run in the tree has
+ * 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.
+ */
+export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
+    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 } });
+    const spentUsd = rows.reduce((sum, r) => sum + Number(r.costUsd), 0);
+    const rootAgent = await db.agent.findUniqueOrThrow({
+        where: { id: root.agentId },
+        select: { id: true, budgetGroupId: true, budgetUsd: true },
+    });
+    // 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 capUsd = rootCeiling.effectiveBudgetUsd;
+    return { rootRunId: root.id, capUsd, spentUsd, remainingUsd: Math.max(0, capUsd - spentUsd) };
+}
+/**
+ * The per-run budget ceiling to actually use for `agent`: its own
+ * budgetUsd, tightened to whatever's left of its budget group's
+ * daily/weekly/monthly caps (whichever are set) AND, when `parentRunId` is
+ * given (this run was dispatched as a sub-agent — see AgentSubAgent),
+ * whatever's left of its run tree's shared ceiling. These are independent,
+ * composable constraints: the final ceiling is the minimum of all that
+ * apply, never one replacing another. An ungrouped, top-level agent run
+ * 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.
+ */
+export async function effectiveBudgetForRun(db, agent, now = new Date(), parentRunId) {
+    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 } } },
+        });
+        if (group) {
+            const spend = await computeGroupSpend(db, group, group.agents.map((a) => a.id), now);
+            const warnThresholdRatio = Number(group.warnThresholdRatio);
+            for (const s of spend) {
+                candidates.push({ value: s.remainingUsd, reason: s.period });
+                if (s.spentUsd >= s.capUsd * warnThresholdRatio) {
+                    budgetGroupLog.warn({ groupId: group.id, groupName: group.name, period: s.period, capUsd: s.capUsd, spentUsd: s.spentUsd }, `budget group "${group.name}"'s ${s.period} spend ($${s.spentUsd.toFixed(4)}) has reached ` +
+                        `${(warnThresholdRatio * 100).toFixed(0)}% of its $${s.capUsd.toFixed(4)} cap`);
+                }
+            }
+        }
+    }
+    if (parentRunId) {
+        const tree = await computeRunTreeSpend(db, parentRunId, now);
+        candidates.push({ value: tree.remainingUsd, reason: "run-tree" });
+    }
+    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 };
+}

package/dist/core/budget.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Budget guardrail — wardby's differentiator. Pure functions only: no
+ * network, no DB, so the math is unit-testable in isolation. The runner
+ * composes these with a live `LlmProvider` for the pre-flight refuse and the
+ * mid-stream cutoff.
+ */
+import type { LlmMessage, LlmProvider, LlmToolDef } from "../providers/index.js";
+export interface BudgetAgent {
+    model: string;
+    budgetUsd: number;
+}
+export interface InputEstimate {
+    tokens: number;
+    costUsd: number;
+}
+/**
+ * Input-only cost estimate: `countTokens` -> `priceUsd` with zero output
+ * tokens. `tools` must be passed whenever the turn being estimated will
+ * actually send them — a provider bills the serialized tool schemas as
+ * input tokens, so omitting them here when the real call includes them
+ * under-counts (this was a real bug: a turn-1 refuse with tools attached
+ * could admit a run whose real input cost already exceeded budget).
+ *
+ * `cacheRatio` is the fraction of input tokens expected to be served from
+ * a provider-side cache (e.g. observed from a prior turn's real usage),
+ * clamped to [0,1] and defaulting to 0 — today's full-rate behavior, where
+ * every input token is priced fresh.
+ */
+export declare function estimateInputCost(agent: BudgetAgent, messages: LlmMessage[], llm: LlmProvider, tools?: LlmToolDef[], cacheRatio?: number): Promise<InputEstimate>;
+/**
+ * Shared refuse/cutoff threshold: a projected cost that has reached the
+ * budget is treated as over budget, not just exceeded past it — the run
+ * must stop at the edge, not one token past it.
+ */
+export declare function isOverBudget(costUsd: number, budgetUsd: number): boolean;
+/**
+ * The pre-flight estimate is a local, un-verified tokenizer count — it must
+ * never let an over-budget run start because it happened to undercount.
+ * Rather than trust that the estimate is always biased high (measured once
+ * against a real call: 40 estimated vs. 38 actual for gpt-5.6-luna — high,
+ * but only one data point across one model/message shape), pad the refuse
+ * decision by a fixed margin. `checkTokenCalibration` below is how drift
+ * beyond this margin gets surfaced, so the margin can be tightened with
+ * evidence instead of guesswork.
+ */
+export declare const PREFLIGHT_SAFETY_MARGIN_RATIO = 0.1;
+export declare function applyPreflightSafetyMargin(costUsd: number): number;
+export interface TokenCalibration {
+    estimatedTokens: number;
+    actualTokens: number;
+    /** (estimated - actual) / actual. Positive = overestimated (safe). Negative = underestimated (dangerous). */
+    deltaRatio: number;
+    diverged: boolean;
+}
+/**
+ * Compares the local pre-flight token estimate against the provider's
+ * authoritative post-call usage. This is calibration, not a runtime gate:
+ * the estimate is inherently approximate (fixed per-message overhead
+ * constants, possible encoding mismatch), so divergence should be logged
+ * for a human to investigate, never used to fail or block a run that
+ * already has real, authoritative usage numbers.
+ */
+export declare function checkTokenCalibration(estimatedTokens: number, actualTokens: number, thresholdRatio?: number): TokenCalibration;

package/dist/core/budget.js

@@ -0,0 +1,69 @@
+/**
+ * Budget guardrail — wardby's differentiator. Pure functions only: no
+ * network, no DB, so the math is unit-testable in isolation. The runner
+ * composes these with a live `LlmProvider` for the pre-flight refuse and the
+ * mid-stream cutoff.
+ */
+/**
+ * Input-only cost estimate: `countTokens` -> `priceUsd` with zero output
+ * tokens. `tools` must be passed whenever the turn being estimated will
+ * actually send them — a provider bills the serialized tool schemas as
+ * input tokens, so omitting them here when the real call includes them
+ * under-counts (this was a real bug: a turn-1 refuse with tools attached
+ * could admit a run whose real input cost already exceeded budget).
+ *
+ * `cacheRatio` is the fraction of input tokens expected to be served from
+ * a provider-side cache (e.g. observed from a prior turn's real usage),
+ * clamped to [0,1] and defaulting to 0 — today's full-rate behavior, where
+ * every input token is priced fresh.
+ */
+export async function estimateInputCost(agent, messages, llm, tools, cacheRatio = 0) {
+    const tokens = await llm.countTokens(agent.model, messages, tools);
+    const cachedInputTokens = Math.round(tokens * Math.min(Math.max(cacheRatio, 0), 1));
+    const costUsd = llm.priceUsd(agent.model, {
+        inputTokens: tokens,
+        outputTokens: 0,
+        cachedInputTokens,
+    });
+    return { tokens, costUsd };
+}
+/**
+ * Shared refuse/cutoff threshold: a projected cost that has reached the
+ * budget is treated as over budget, not just exceeded past it — the run
+ * must stop at the edge, not one token past it.
+ */
+export function isOverBudget(costUsd, budgetUsd) {
+    return costUsd >= budgetUsd;
+}
+/**
+ * The pre-flight estimate is a local, un-verified tokenizer count — it must
+ * never let an over-budget run start because it happened to undercount.
+ * Rather than trust that the estimate is always biased high (measured once
+ * against a real call: 40 estimated vs. 38 actual for gpt-5.6-luna — high,
+ * but only one data point across one model/message shape), pad the refuse
+ * decision by a fixed margin. `checkTokenCalibration` below is how drift
+ * beyond this margin gets surfaced, so the margin can be tightened with
+ * evidence instead of guesswork.
+ */
+export const PREFLIGHT_SAFETY_MARGIN_RATIO = 0.1;
+export function applyPreflightSafetyMargin(costUsd) {
+    return costUsd * (1 + PREFLIGHT_SAFETY_MARGIN_RATIO);
+}
+const CALIBRATION_DIVERGENCE_THRESHOLD = 0.1;
+/**
+ * Compares the local pre-flight token estimate against the provider's
+ * authoritative post-call usage. This is calibration, not a runtime gate:
+ * the estimate is inherently approximate (fixed per-message overhead
+ * constants, possible encoding mismatch), so divergence should be logged
+ * for a human to investigate, never used to fail or block a run that
+ * already has real, authoritative usage numbers.
+ */
+export function checkTokenCalibration(estimatedTokens, actualTokens, thresholdRatio = CALIBRATION_DIVERGENCE_THRESHOLD) {
+    const deltaRatio = actualTokens === 0 ? 0 : (estimatedTokens - actualTokens) / actualTokens;
+    return {
+        estimatedTokens,
+        actualTokens,
+        deltaRatio,
+        diverged: Math.abs(deltaRatio) > thresholdRatio,
+    };
+}