@wardby/cli 0.3.0 → 0.4.1

package/dist/core/attribution.js

@@ -0,0 +1,208 @@
+import { ISSUE_KEY, ISSUE_TRACKER_PROVIDERS, projectOf, } from "../providers/issue-tracker/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "attribution" });
+/** A WorkItem snapshotted this recently is reused as-is, without calling the tracker. */
+export const SNAPSHOT_CACHE_MS = 10 * 60 * 1000;
+export const SNAPSHOT_TIMEOUT_MS = 3000;
+/**
+ * Snapshot budget for a caller that is answering a request (a webhook, an
+ * MCP tool call, a host event): a short timeout and no 429 retry, so a slow
+ * or rate-limited tracker degrades to key-only attribution instead of
+ * stalling the response.
+ */
+export const RESPONSE_PATH_SNAPSHOT_BUDGET = { timeoutMs: 2000, retryOn429: false };
+/**
+ * The work item a new attribution points at, snapshotted from the tracker
+ * unless a fresh snapshot is already stored. Never throws: a failed lookup or
+ * snapshot attributes by key only.
+ */
+export async function resolveWorkItem(db, trackers, provider, key, opts = {}) {
+    const now = opts.now ?? new Date();
+    const keyOnly = (scopeKey = projectOf(key)) => ({ provider, key, scopeKey, snapshot: null });
+    let existing;
+    try {
+        existing = await db.workItem.findUnique({
+            where: { provider_key: { provider, key } },
+            select: { refreshedAt: true, scopeKey: true },
+        });
+    }
+    catch (err) {
+        log.warn({ err, provider, key }, "work item lookup failed; attributing by key only");
+        return keyOnly();
+    }
+    if (existing?.refreshedAt && now.getTime() - existing.refreshedAt.getTime() < SNAPSHOT_CACHE_MS) {
+        return keyOnly(existing.scopeKey);
+    }
+    const tracker = trackers?.[provider];
+    if (!tracker)
+        return keyOnly(existing?.scopeKey);
+    try {
+        const snapshot = await tracker.snapshotIssue(key, {
+            timeoutMs: opts.timeoutMs ?? SNAPSHOT_TIMEOUT_MS,
+            retryOn429: opts.retryOn429,
+        });
+        return { provider, key, scopeKey: snapshot.scopeKey, snapshot };
+    }
+    catch (err) {
+        log.warn({ err, provider, key }, "issue snapshot failed; attributing by key only");
+        return keyOnly(existing?.scopeKey);
+    }
+}
+/** Upserts the item (and its parent) and returns the item's id and the parent to freeze. A key-only result never clobbers stored fields. */
+async function upsertWorkItem(tx, item, now) {
+    const s = item.snapshot;
+    if (s?.parent) {
+        // The parent's own type/scope/title are refreshed when it is snapshotted itself; here only make sure it exists
+        // and take a title we were handed for free.
+        await tx.workItem.upsert({
+            where: { provider_key: { provider: item.provider, key: s.parent.key } },
+            create: {
+                provider: item.provider,
+                key: s.parent.key,
+                scopeKey: projectOf(s.parent.key),
+                ...(s.parent.title ? { title: s.parent.title } : {}),
+            },
+            update: s.parent.title ? { title: s.parent.title } : {},
+        });
+    }
+    const snapshotFields = s
+        ? {
+            title: s.title ?? null,
+            type: s.type ?? null,
+            url: s.url,
+            scopeKey: s.scopeKey,
+            parentKey: s.parent?.key ?? null,
+            parentKind: s.parent?.kind ?? null,
+            refreshedAt: now,
+        }
+        : {};
+    const row = await tx.workItem.upsert({
+        where: { provider_key: { provider: item.provider, key: item.key } },
+        create: { provider: item.provider, key: item.key, scopeKey: item.scopeKey, ...snapshotFields },
+        update: snapshotFields,
+        select: { id: true, parentKey: true },
+    });
+    return row;
+}
+/**
+ * Covers runs created before attribution existed (no backfill): a continued
+ * coding run that already carries CodingRun.issueKey, else a direct parent
+ * with a RunIssueStatus. Grandchildren then inherit the child's new
+ * RunAttribution, so only the direct parent is checked.
+ */
+async function legacyIssue(tx, from) {
+    if (from.continuesCodingRunId) {
+        const prior = await tx.codingRun.findUnique({
+            where: { runId: from.continuesCodingRunId },
+            select: { issueProvider: true, issueKey: true },
+        });
+        if (prior?.issueProvider && prior.issueKey)
+            return { provider: prior.issueProvider, key: prior.issueKey };
+    }
+    if (from.parentRunId) {
+        const status = await tx.runIssueStatus.findUnique({
+            where: { runId: from.parentRunId },
+            select: { provider: true, issueKey: true },
+        });
+        if (status)
+            return { provider: status.provider, key: status.issueKey };
+    }
+    return null;
+}
+/**
+ * Writes the run's attribution inside dispatch's persist transaction.
+ * Precedence: the parent run's attribution, then the continued coding run's,
+ * then a pre-attribution issue (legacyIssue), then the caller's intent. Returns the item's provider/key (for
+ * CodingRun.issueProvider/issueKey), or null when the run is unattributed.
+ */
+export async function attributeRun(tx, runId, from, now = new Date()) {
+    for (const ancestorId of [from.parentRunId, from.continuesCodingRunId]) {
+        if (!ancestorId)
+            continue;
+        const inherited = await tx.runAttribution.findUnique({
+            where: { runId: ancestorId },
+            select: { workItemId: true, parentKeyAtRun: true, workItem: { select: { provider: true, key: true } } },
+        });
+        if (!inherited)
+            continue;
+        await tx.runAttribution.create({
+            data: { runId, workItemId: inherited.workItemId, parentKeyAtRun: inherited.parentKeyAtRun, source: "inherited" },
+        });
+        return { provider: inherited.workItem.provider, key: inherited.workItem.key };
+    }
+    const legacy = await legacyIssue(tx, from);
+    if (legacy) {
+        const item = { ...legacy, scopeKey: projectOf(legacy.key), snapshot: null };
+        const { id, parentKey } = await upsertWorkItem(tx, item, now);
+        await tx.runAttribution.create({ data: { runId, workItemId: id, parentKeyAtRun: parentKey, source: "inherited" } });
+        return legacy;
+    }
+    if (!from.intent)
+        return null;
+    const { id, parentKey } = await upsertWorkItem(tx, from.intent.item, now);
+    await tx.runAttribution.create({
+        data: { runId, workItemId: id, parentKeyAtRun: parentKey, source: from.intent.source },
+    });
+    return { provider: from.intent.item.provider, key: from.intent.item.key };
+}
+/** The issue a pull request was opened for (phase-3 IssuePullRequest); the earliest link when several exist. */
+export async function linkedPullRequestIssue(db, pr) {
+    try {
+        const row = await db.issuePullRequest.findFirst({
+            where: { codeProvider: pr.codeProvider, repository: pr.repository, number: pr.number },
+            orderBy: { createdAt: "asc" },
+            select: { issueProvider: true, issueKey: true },
+        });
+        return row ? { provider: row.issueProvider, key: row.issueKey } : null;
+    }
+    catch (err) {
+        log.warn({ err, ...pr }, "linked issue lookup failed; the run is unattributed");
+        return null;
+    }
+}
+/** Attribution for a run on a pull request that was opened for an issue; undefined when it has none. */
+export async function linkedPullRequestAttribution(db, trackers, pr, opts) {
+    const issue = await linkedPullRequestIssue(db, pr);
+    if (!issue)
+        return undefined;
+    return { source: "linked_pr", item: await resolveWorkItem(db, trackers, issue.provider, issue.key, opts) };
+}
+/** A refusal whose message is safe to return to the caller. */
+export class AttributionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AttributionError";
+    }
+}
+/**
+ * An issue a caller names on trigger_agent or a webhook. It decides whose
+ * cost this run counts toward, so it must be well formed and in a project the
+ * agent is linked to (AgentIssueProject) — otherwise the dispatch is refused.
+ * Issue keys are uppercase, so a key that differs only by case or surrounding
+ * spaces ("pay-241") is corrected rather than refused. `field` is the caller's
+ * name for the value (trigger_agent: issue; webhooks: wardbyIssue), so
+ * refusals name the field the caller actually sent.
+ */
+export async function validateExplicitIssue(db, agentId, issue, field = "issue") {
+    const candidate = issue && typeof issue === "object" ? issue : {};
+    const provider = candidate.provider;
+    const key = typeof candidate.key === "string" ? candidate.key.trim().toUpperCase() : candidate.key;
+    if (typeof provider !== "string" || !ISSUE_TRACKER_PROVIDERS.includes(provider)) {
+        throw new AttributionError(`${field}.provider must be one of: ${ISSUE_TRACKER_PROVIDERS.join(", ")}.`);
+    }
+    if (typeof key !== "string" || !ISSUE_KEY.test(key)) {
+        throw new AttributionError(`${field}.key must be an issue key such as PROJ-123.`);
+    }
+    const link = await db.agentIssueProject.findUnique({
+        where: { agentId_provider_projectKey: { agentId, provider, projectKey: projectOf(key) } },
+        select: { agentId: true },
+    });
+    if (!link)
+        throw new AttributionError(`This agent is not linked to ${provider} project ${projectOf(key)}.`);
+    return { provider: provider, key };
+}
+export async function explicitAttribution(db, trackers, agentId, issue, opts) {
+    const { field, ...budget } = opts ?? {};
+    const { provider, key } = await validateExplicitIssue(db, agentId, issue, field);
+    return { source: "explicit", item: await resolveWorkItem(db, trackers, provider, key, budget) };
+}

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

@@ -69,6 +69,12 @@ export interface SpendOptions {
      * whose hold already covers it.
      */
     excludeReservationRunIds?: readonly string[];
+    /**
+     * Runs left out of the group's spend entirely, real cost and hold alike:
+     * the run tree when computing the tree's own ceiling, whose spend is
+     * subtracted from that ceiling separately and must count only once.
+     */
+    excludeRunIds?: readonly string[];
     /**
      * First come, first served: count only the holds of runs ordered strictly
      * before this one. Unset (a coding dispatch, whose row does not exist yet)
@@ -125,16 +131,17 @@ export interface RunTreeSpend {
 /**
  * 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. 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).
+ * the root's own budgetUsd, itself tightened by the root agent's BudgetGroup
+ * if any — minus everything every run in the tree has spent so far. The
+ * 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. Its group check leaves the
+ * tree's runs out entirely, cost and hold alike: the tree's spend is
+ * subtracted once, below, so counting it in the group too would charge it
+ * twice, and the tree spends inside the root's hold, so counting that hold
+ * would leave the tree nothing. It also leaves out holds of runs that started
+ * after the root (they already counted the root's hold). capUsd is therefore
+ * the tree's whole ceiling, and remainingUsd = capUsd - spentUsd.
  */
 export declare function computeRunTreeSpend(db: BudgetGroupsDb, parentRunId: string, now?: Date): Promise<RunTreeSpend>;
 export type BudgetConstraint = Period | "run-tree";

package/dist/core/budget-groups.js

@@ -84,6 +84,7 @@ export async function computeGroupSpend(db, group, members, now = new Date(), op
     const widestStart = periodStart("month", now);
     const memberBudgets = new Map(members.map((m) => [m.id, Number(m.budgetUsd)]));
     const excluded = new Set(options.excludeReservationRunIds ?? []);
+    const dropped = new Set(options.excludeRunIds ?? []);
     const queueTimeoutSec = options.codingQueueTimeoutSec ?? loadCodingConcurrencyConfig().queueTimeoutSec;
     const runs = members.length === 0
         ? []
@@ -99,7 +100,8 @@ export async function computeGroupSpend(db, group, members, now = new Date(), op
                 codingRun: { select: { budgetReservedUsd: true, timeoutSec: true } },
             },
         });
-    const accounted = runs.map((r) => {
+    const counted = runs.filter((r) => !dropped.has(r.id));
+    const accounted = counted.map((r) => {
         const costUsd = Number(r.costUsd);
         let reservedUsd = 0;
         const holds = !excluded.has(r.id) &&
@@ -151,16 +153,17 @@ async function collectTreeRunIds(db, rootRunId) {
 /**
  * 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. 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).
+ * the root's own budgetUsd, itself tightened by the root agent's BudgetGroup
+ * if any — minus everything every run in the tree has spent so far. The
+ * 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. Its group check leaves the
+ * tree's runs out entirely, cost and hold alike: the tree's spend is
+ * subtracted once, below, so counting it in the group too would charge it
+ * twice, and the tree spends inside the root's hold, so counting that hold
+ * would leave the tree nothing. It also leaves out holds of runs that started
+ * after the root (they already counted the root's hold). capUsd is therefore
+ * the tree's whole ceiling, and remainingUsd = capUsd - spentUsd.
  */
 export async function computeRunTreeSpend(db, parentRunId, now = new Date()) {
     const { rootRunId, capUsd, spentUsd, remainingUsd } = await runTreeSpend(db, parentRunId, now);
@@ -179,7 +182,7 @@ async function runTreeSpend(db, parentRunId, now) {
     // 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 groupCappedBudget(db, rootAgent, now, {
-        excludeReservationRunIds: treeRunIds,
+        excludeRunIds: treeRunIds,
         holdsBefore: rootOrder,
     });
     const capUsd = rootCeiling.effectiveBudgetUsd;

package/dist/core/coding-queue.d.ts

@@ -16,6 +16,7 @@
  */
 import type { PrismaClient } from "#prisma";
 import type { Executor } from "../providers/executor/types.js";
+import { type SelfDefectSink } from "./self-defects.js";
 export declare const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
 export type CodingQueueDb = Pick<PrismaClient, "run" | "codingRun" | "$transaction">;
 export interface DrainCodingQueueOptions {
@@ -24,6 +25,8 @@ export interface DrainCodingQueueOptions {
     maxConcurrent: number;
     queueTimeoutSec: number;
     now?: () => Date;
+    /** Files a self-defect for each run this drain fails (queue timeout or start failure). Optional. */
+    selfDefects?: SelfDefectSink;
 }
 export interface DrainCodingQueueResult {
     timedOut: number;

package/dist/core/coding-queue.js

@@ -1,5 +1,6 @@
 import { markRunFailedFromExecutorError } from "./dispatch.js";
 import { logger } from "./logger.js";
+import { fileSelfDefectForRun } from "./self-defects.js";
 const queueLog = logger.child({ module: "coding-queue" });
 export const CODING_QUEUE_TIMEOUT_ERROR = "coding_queue_timeout";
 export async function drainCodingQueue(options) {
@@ -25,8 +26,11 @@ export async function drainCodingQueue(options) {
             await tx.codingRun.update({ where: { runId }, data: { failureCategory: CODING_QUEUE_TIMEOUT_ERROR } });
             return true;
         });
-        if (didTimeOut)
+        if (didTimeOut) {
             timedOut += 1;
+            // Only this drain made the row failed (a concurrent drain matched zero rows); bounded, never throws.
+            await fileSelfDefectForRun(options.selfDefects, runId);
+        }
     }
     const active = await db.codingRun.count({
         where: { jobBackend: { not: null }, run: { status: { in: ["pending", "running"] } } },
@@ -48,7 +52,7 @@ export async function drainCodingQueue(options) {
         // drainCodingQueue's own call stack.
         void Promise.resolve()
             .then(() => executor.start(runId))
-            .catch((err) => markRunFailedFromExecutorError(db, runId, err).catch((err2) => queueLog.error({ err: err2, runId }, "failed to persist queued-run start failure")));
+            .catch((err) => markRunFailedFromExecutorError(db, runId, err, options.selfDefects).catch((err2) => queueLog.error({ err: err2, runId }, "failed to persist queued-run start failure")));
     }
     return { timedOut, started: next.map((row) => row.runId) };
 }

package/dist/core/coding-service-status.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Persists launcher-observed coding-run service states (CodingRunServiceStatus, one row per
+ * run x service) for the viewer. Composed into the job launchers by
+ * providers/executor/composition.ts; launchers call it through reportServiceState, which drops
+ * its errors.
+ */
+import type { PrismaClient } from "#prisma";
+import type { ServiceStateReporter } from "../providers/jobs/service-state.js";
+type ServiceStatusDb = Pick<PrismaClient, "codingRunServiceStatus">;
+export declare function prismaServiceStateReporter(db: ServiceStatusDb, now?: () => Date): ServiceStateReporter;
+export {};

package/dist/core/coding-service-status.js

@@ -0,0 +1,17 @@
+export function prismaServiceStateReporter(db, now = () => new Date()) {
+    return async ({ runId, name, state, attempts, reason }) => {
+        const at = now();
+        const data = {
+            state,
+            attempts: attempts ?? null,
+            reason: reason ?? null,
+            readyAt: state === "ready" ? at : null,
+            failedAt: state === "failed" ? at : null,
+        };
+        await db.codingRunServiceStatus.upsert({
+            where: { runId_name: { runId, name } },
+            create: { runId, name, ...data },
+            update: data,
+        });
+    };
+}

package/dist/core/cost-report.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Cost by issue / parent / scope / agent / model / run over a time window
+ * (docs/private/2026-10-01-issue-cost-attribution-design.md §7). Rows count
+ * attributed runs only; unattributed spend is reported separately so the gap
+ * is visible. Money is summed as NUMERIC in SQL and returned as strings; tokens
+ * are always by priced kind, never one total.
+ */
+import { type PrismaClient } from "#prisma";
+export type CostGroupBy = "issue" | "parent" | "scope" | "agent" | "model" | "run";
+export declare class CostReportInputError extends Error {
+    constructor(message: string);
+}
+export interface CostReportQuery {
+    groupBy: CostGroupBy;
+    from: Date;
+    to: Date;
+    provider?: string;
+    scopeKey?: string;
+    parentKey?: string;
+    issueKey?: string;
+    agentId?: string;
+    limit: number;
+}
+export declare function parseCostReportQuery(raw: unknown, now?: Date): CostReportQuery;
+/** Which runs the caller may count: null = all (stdio operator). */
+export interface CostVisibility {
+    ownedAgentIds: string[];
+    principalId: string;
+}
+export interface TokenKinds {
+    freshInput: number;
+    cachedInput: number;
+    cacheWrite: number;
+    output: number;
+}
+export interface CostRow {
+    key: string;
+    title: string | null;
+    kind: string | null;
+    provider: string | null;
+    runs: number;
+    inProgressRuns: number;
+    costUsd: string;
+    tokens: TokenKinds;
+    byModel: Array<{
+        model: string;
+        costUsd: string;
+        tokens: TokenKinds;
+    }>;
+    bySource: {
+        issue_event: string;
+        linked_pr: string;
+        explicit: string;
+        inherited: string;
+    };
+    firstRunAt: string;
+    lastRunAt: string;
+}
+export interface CostReport {
+    currency: "USD";
+    groupBy: CostGroupBy;
+    from: string;
+    to: string;
+    rows: CostRow[];
+    truncated: boolean;
+    totals: {
+        runs: number;
+        costUsd: string;
+        tokens: TokenKinds;
+    };
+    unattributed: {
+        runs: number;
+        costUsd: string;
+    };
+}
+/**
+ * How long one report may take. Prisma's interactive-transaction default (5 s)
+ * is too short for a wide window over a large Run table; the same limit is set
+ * as the transaction's statement_timeout so Postgres stops the work too, not
+ * only the client.
+ */
+export declare const COST_REPORT_TIMEOUT_MS = 30000;
+/**
+ * Every query runs in one read-only REPEATABLE READ transaction, so the rows,
+ * the totals and the unattributed figure all come from the same snapshot even
+ * while runs are finishing.
+ */
+export declare function costReport(db: Pick<PrismaClient, "$queryRaw" | "$transaction">, q: CostReportQuery, visibility: CostVisibility | null): Promise<CostReport>;