@wardby/cli 0.4.0 → 0.5.0

package/dist/viewer/graph.js

@@ -39,7 +39,15 @@ function declaredServices(snapshot) {
     return snapshot.filter(isRecord).map((s) => ({ name: String(s.name), version: String(s.version) }));
 }
 const iso = (date) => (date ? date.toISOString() : null);
-function triggerFor(row) {
+/** The tracker's page for an issue (and, with a comment id, that comment); null without a known site. */
+export function issueUrl(sites, provider, issueKey, commentId) {
+    const site = sites[provider];
+    if (!site || provider !== "jira")
+        return null;
+    const page = `${site}/browse/${encodeURIComponent(issueKey)}`;
+    return commentId ? `${page}?focusedCommentId=${encodeURIComponent(commentId)}` : page;
+}
+function triggerFor(row, sites) {
     switch (row.trigger) {
         case "scheduled":
             return { kind: "scheduled", schedule: row.agent.schedule };
@@ -51,7 +59,12 @@ function triggerFor(row) {
             return { kind: "manual" };
         case "host_event":
             if (row.issueStatus) {
-                return { kind: "issue", provider: row.issueStatus.provider, issueKey: row.issueStatus.issueKey };
+                return {
+                    kind: "issue",
+                    provider: row.issueStatus.provider,
+                    issueKey: row.issueStatus.issueKey,
+                    url: issueUrl(sites, row.issueStatus.provider, row.issueStatus.issueKey),
+                };
             }
             if (row.hostStatus) {
                 return {
@@ -74,7 +87,7 @@ function triggerFor(row) {
             return { kind: "host_event" };
     }
 }
-function outcomesFor(row, pullRequests) {
+function outcomesFor(row, pullRequests, sites) {
     const outcomes = pullRequests.map((pr) => ({
         kind: "pull_request",
         provider: pr.codeProvider,
@@ -112,6 +125,7 @@ function outcomesFor(row, pullRequests) {
             kind: "issue_comment",
             provider: row.issueStatus.provider,
             issueKey: row.issueStatus.issueKey,
+            url: issueUrl(sites, row.issueStatus.provider, row.issueStatus.issueKey, row.issueStatus.commentId),
             at: (row.issueStatus.completedAt ?? row.issueStatus.createdAt).toISOString(),
         });
     }
@@ -128,7 +142,7 @@ function outcomesFor(row, pullRequests) {
     return outcomes;
 }
 /** The one row -> GraphRun mapping (also used by run detail). `pullRequests` are the IssuePullRequest rows this run opened. */
-export function toGraphRun(row, pullRequests) {
+export function toGraphRun(row, pullRequests, sites = {}) {
     return {
         id: row.id,
         parentRunId: row.parentRunId,
@@ -138,7 +152,7 @@ export function toGraphRun(row, pullRequests) {
         model: row.codingRun?.model ?? row.agent.model,
         codingProvider: row.codingRun?.provider ?? null,
         status: row.status,
-        trigger: triggerFor(row),
+        trigger: triggerFor(row, sites),
         turns: row.turns,
         tokensIn: row.tokensIn,
         tokensOut: row.tokensOut,
@@ -147,7 +161,7 @@ export function toGraphRun(row, pullRequests) {
         startedAt: row.startedAt.toISOString(),
         finishedAt: iso(row.finishedAt),
         heartbeatAt: iso(row.heartbeatAt),
-        outcomes: outcomesFor(row, pullRequests),
+        outcomes: outcomesFor(row, pullRequests, sites),
         declaredServices: declaredServices(row.codingRun?.services),
         services: row.serviceStatuses.map((s) => ({
             name: s.name,
@@ -160,7 +174,7 @@ export function toGraphRun(row, pullRequests) {
         })),
     };
 }
-async function mapRows(db, rows) {
+async function mapRows(db, rows, sites) {
     if (rows.length === 0)
         return [];
     const pullRequests = await db.issuePullRequest.findMany({
@@ -170,14 +184,14 @@ async function mapRows(db, rows) {
     const byRun = new Map();
     for (const pr of pullRequests)
         byRun.set(pr.openedByRunId, [...(byRun.get(pr.openedByRunId) ?? []), pr]);
-    return rows.map((row) => toGraphRun(row, byRun.get(row.id) ?? []));
+    return rows.map((row) => toGraphRun(row, byRun.get(row.id) ?? [], sites));
 }
 /** Loads the given runs as GraphRuns (shared with run detail); unknown ids are skipped. */
-export async function loadGraphRuns(db, runIds) {
+export async function loadGraphRuns(db, runIds, sites = {}) {
     if (runIds.length === 0)
         return [];
     const rows = await db.run.findMany({ where: { id: { in: [...runIds] } }, include: runInclude });
-    return mapRows(db, rows);
+    return mapRows(db, rows, sites);
 }
 export async function loadGraph(db, options) {
     const now = options.now ?? new Date();
@@ -207,7 +221,7 @@ export async function loadGraph(db, options) {
     }
     const dayStart = periodStart("day", now);
     const [runs, today, groups] = await Promise.all([
-        mapRows(db, rows),
+        mapRows(db, rows, options.issueSites ?? {}),
         db.run.aggregate({ where: { startedAt: { gte: dayStart } }, _sum: { costUsd: true } }),
         db.budgetGroup.findMany({
             where: { dailyBudgetUsd: { not: null } },

package/dist/viewer/http.d.ts

@@ -1,5 +1,5 @@
 /**
- * Viewer HTTP routes: GET /admin/api/graph, /admin/api/runs/:id and the
+ * Viewer HTTP routes: GET /admin/api/graph, /admin/api/runs/:id, /admin/api/infra and the
  * /admin/api/events SSE stream. Read-only and deployment-wide, so every route
  * authenticates and then requires the privileged `admin:view` scope (admin role
  * only) BEFORE touching the database or the event bus. McpErrors propagate to
@@ -8,6 +8,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { PrismaClient } from "#prisma";
 import type { McpRequestContext } from "../mcp/context.js";
+import type { InfraInfo } from "./api-schema.js";
+import { type IssueSites } from "./graph.js";
 import type { ViewerEventBus } from "./event-bus.js";
 export declare const VIEWER_API_PREFIX = "/admin/api/";
 export declare const SSE_HEARTBEAT_MS = 15000;
@@ -18,6 +20,10 @@ export interface ViewerApiDeps {
     bus: ViewerEventBus;
     authenticate: (authorization: string | undefined) => Promise<McpRequestContext>;
     canonicalUri: string;
+    /** How this deployment runs coding jobs (built once at startup; GET /admin/api/infra). */
+    infra: InfraInfo;
+    /** Issue-tracker site origins by provider, for issue and comment links (empty when none is configured). */
+    issueSites?: IssueSites;
     heartbeatMs?: number;
     maxBufferedBytes?: number;
 }

package/dist/viewer/http.js

@@ -77,7 +77,8 @@ export function createViewerApi(deps) {
             const runMatch = /^\/admin\/api\/runs\/([^/]*)$/.exec(path);
             const isGraph = path === "/admin/api/graph";
             const isEvents = path === "/admin/api/events";
-            if (!isGraph && !isEvents && !runMatch)
+            const isInfra = path === "/admin/api/infra";
+            if (!isGraph && !isEvents && !isInfra && !runMatch)
                 return false;
             const ctx = await deps.authenticate(req.headers.authorization);
             requireScope(ctx, deps.canonicalUri, "admin:view");
@@ -85,6 +86,10 @@ export function createViewerApi(deps) {
                 sendJson(res, 405, { error: "method_not_allowed" }, { allow: "GET" });
                 return true;
             }
+            if (isInfra) {
+                sendJson(res, 200, deps.infra);
+                return true;
+            }
             if (isGraph) {
                 const limitParam = url.searchParams.get("limit");
                 let limit = DEFAULT_GRAPH_LIMIT;
@@ -104,7 +109,7 @@ export function createViewerApi(deps) {
                     sendJson(res, 400, { error: "invalid_since" });
                     return true;
                 }
-                sendJson(res, 200, await loadGraph(deps.db, { since, limit, now }));
+                sendJson(res, 200, await loadGraph(deps.db, { since, limit, now, issueSites: deps.issueSites }));
                 return true;
             }
             if (runMatch) {
@@ -115,7 +120,7 @@ export function createViewerApi(deps) {
                 catch {
                     /* malformed escape: fails the id check below */
                 }
-                const detail = RUN_ID.test(id) ? await loadRunDetail(deps.db, id) : null;
+                const detail = RUN_ID.test(id) ? await loadRunDetail(deps.db, id, deps.issueSites) : null;
                 if (!detail)
                     sendJson(res, 404, { error: "not_found" });
                 else

package/dist/viewer/infra.d.ts

@@ -0,0 +1,2 @@
+import type { InfraInfo } from "./api-schema.js";
+export declare function buildInfraInfo(env?: NodeJS.ProcessEnv): InfraInfo;

package/dist/viewer/infra.js

@@ -0,0 +1,23 @@
+/** The read model behind GET /admin/api/infra (docs/viewer-api.md): built once at startup, no cluster reads. */
+import { loadKubernetesJobConfig, loadProviderConfig } from "../config/providers.js";
+import { RUN_COMPONENT_LABEL, RUN_MANAGED_BY_LABEL, RUN_SHA_CHARS, RUN_SHA_LABEL, } from "../providers/jobs/kubernetes-isolation.js";
+export function buildInfraInfo(env = process.env) {
+    const raw = loadProviderConfig(env).jobs;
+    const launcher = raw === "docker" || raw === "kubernetes" ? raw : "local";
+    if (launcher !== "kubernetes")
+        return { launcher, kubernetes: null };
+    const k8s = loadKubernetesJobConfig(env);
+    return {
+        launcher,
+        kubernetes: {
+            namespace: k8s.namespace,
+            platform: k8s.platform,
+            runtimeClass: k8s.runtimeClassName ?? null,
+            proxyService: k8s.proxyService,
+            runLabel: RUN_SHA_LABEL,
+            runLabelHashChars: RUN_SHA_CHARS,
+            componentLabel: { ...RUN_COMPONENT_LABEL },
+            managedByLabel: { ...RUN_MANAGED_BY_LABEL },
+        },
+    };
+}

package/dist/viewer/run-detail.d.ts

@@ -1,4 +1,5 @@
 /** The run detail read model behind GET /admin/api/runs/:id (docs/viewer-api.md). */
 import type { PrismaClient } from "#prisma";
 import type { RunDetail } from "./api-schema.js";
-export declare function loadRunDetail(db: PrismaClient, runId: string): Promise<RunDetail | null>;
+import { type IssueSites } from "./graph.js";
+export declare function loadRunDetail(db: PrismaClient, runId: string, issueSites?: IssueSites): Promise<RunDetail | null>;

package/dist/viewer/run-detail.js

@@ -11,8 +11,8 @@ function serviceDetails(snapshot) {
         envNames: isRecord(s.testEnv) ? Object.keys(s.testEnv).sort() : [],
     }));
 }
-export async function loadRunDetail(db, runId) {
-    const [graphRun] = await loadGraphRuns(db, [runId]);
+export async function loadRunDetail(db, runId, issueSites = {}) {
+    const [graphRun] = await loadGraphRuns(db, [runId], issueSites);
     if (!graphRun)
         return null;
     const [row, children] = await Promise.all([

package/docs/agent-recipes.md

@@ -48,7 +48,7 @@ These recipes go beyond the quickstart. Check each item.
    [GKE](getting-started-gke.md). Scheduled and manually triggered runs need no
    webhook.
 5. **App events.** Tick the events each trigger needs in the App's settings:
-   Pull request and Check run for reviews; Issue comment, Pull request review
+   Pull request, Check run, and Check suite for reviews; Issue comment, Pull request review
    comment, and Issues for mentions; and **Push** for the merge watcher. Each is
    its own checkbox
    ([registering the App](code-review-agents.md#registering-the-github-app)).
@@ -358,6 +358,125 @@ pip use inside the same run, and `packageAllowlist` has no entry for other
 ecosystems. If services are allowed, the image must be built on driver v11 or
 later.
 
+### Fanning out to several builders
+
+A router delegates once per run by default: it routes a request to exactly one
+sub-agent and never retries into a second. To have one native agent split a
+request across several repositories, attach one builder per repository and set
+the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
+`update_agent`:
+
+```json
+{ "id": "<lead agent id>", "maxDelegationsPerRun": 6 }
+```
+
+- Each `delegate_to_<name>` call still goes to a different sub-agent; a second
+  call to the same one in the same run is refused with `already_dispatched`.
+  A delegation waiting for budget (see below) also holds its place against
+  `maxDelegationsPerRun`: a call beyond the limit is refused with
+  `already_dispatched` and a message naming both counts, e.g. "This run
+  reached its limit of 6 delegations: 4 made and 2 waiting for budget."
+- By default the calls run one after another, in the order the lead makes
+  them. To run them at the same time, also set `parallelDelegations`:
+
+  ```json
+  { "id": "<lead agent id>", "maxDelegationsPerRun": 6, "parallelDelegations": true }
+  ```
+
+  Only the **consecutive** `delegate_to_*` calls of one model turn start
+  together: `[delegate_a, delegate_b]` starts both at once, but
+  `[delegate_a, jira_comment, delegate_b]` runs `delegate_a`, then the
+  `jira_comment` call, then `delegate_b` one at a time — nothing is
+  reordered, and a non-delegation call between two delegations splits them
+  into separate steps. The lead gets every call's result, in the same order
+  the calls were made, before its next turn. Tell the lead to make all of
+  its independent delegations consecutively, in one turn, with no other
+  tool call between them. A prompt that asks for delegations "in dependency
+  order", one per turn, still runs them one after another. Use
+  `parallelDelegations` only when every builder's task already carries the
+  whole cross-repository contract, so no builder needs another's output.
+
+- With `parallelDelegations`, builders compete for coding slots: runs beyond
+  `CODING_MAX_CONCURRENT` (or beyond a Kubernetes quota set with
+  `KUBERNETES_RESOURCE_QUOTA`) wait in the queue and start as others finish.
+  A builder that waits longer than `CODING_QUEUE_TIMEOUT_SEC` fails with
+  `coding_queue_timeout`, and the lead sees that in its result.
+- Each coding sub-agent's result tells the lead its `status`, its summary
+  (`finalText`), cost and tokens, and, when it opened or pushed to a pull
+  request, `pullRequest` (`outcome` `opened` or `updated`, `repository`,
+  `number`, `url`) taken from Wardby's own record of the run. A lead prompt can
+  ask the agent to report those links.
+- The whole run tree shares one budget: give the lead a `budgetUsd` that
+  covers every builder it may start, plus its own planning. Builders started
+  together each reserve their own `budgetUsd` up front, so the ones admitted
+  last get what the earlier ones leave. A builder admitted after the tree's
+  budget is spent waits for a still-running sibling to finish and free its
+  reservation, then retries — up to its own normal wait bound, so the total
+  wait can run to roughly twice that bound before it gives up. With no
+  sibling still running, it is refused immediately with `run_tree_exhausted`.
+  The check behind that wait is an estimate, so a retry can still end in the
+  same refusal. Size the lead for the sum of its builders' budgets.
+- Each builder works only in its own repository and can't see the others, so
+  the lead's task to each one must carry everything that crosses a repository
+  boundary (routes, field names and types, error codes), word for word the same.
+- Wardby adds a **Related pull requests** section to each pull request the
+  builders open, listing the others with links, states (open, draft, merged,
+  closed) and the originating issue. With a Jira issue, the list covers every
+  pull request recorded for that issue in any run. Open ones are numbered as a
+  **Suggested merge order** — the order the lead delegated in, not a
+  guarantee; merged and closed ones are listed separately as context. A pull
+  request lists the ones opened before it as soon as it is opened; when the
+  lead run finishes, and whenever a later run pushes to one of them, every
+  open one is rewritten with the full list. Text you add inside the section is
+  replaced; the rest of the description is not touched. Only pull requests the
+  App opened and that are still open are edited.
+- The section, and the follow-up hints below, list every pull request in the
+  set by repository name and number. A request that spans repositories of
+  different visibility can therefore show a private repository's name in a
+  public repository's pull request: if you mix public and private
+  repositories, keep that work in separate requests (separate Jira issues, or
+  separate lead agents).
+
+#### Follow-ups across the set
+
+A human-triggered follow-up task (an `@<app-slug>` mention, or a Jira issue
+event — never an automatic review fix round) lists every open sibling pull
+request in the set, each as `owner/name#n (url): … pass continuePriorRun set
+to exactly "<run id>"`. Recommend this line in your lead agent's own prompt
+too:
+
+    Continue the pull request you were asked about, and any listed open
+    sibling the change requires; never open a new pull request in a
+    repository that already has an open sibling for this request.
+
+The usual delegation rails still apply on top of this: `maxDelegationsPerRun`
+caps calls per run; a second `delegate_to_<name>` call to the same sub-agent
+in one run is refused with `already_dispatched`; dispatch re-checks every
+`continuePriorRun` id (refusing with `continuation_refused` when this
+deployment can't continue the run it names — for example it belongs to a
+different owner's agent); every push to a sibling pull request still gets its
+own review; and fix rounds stay capped and run one at a time per pull
+request. A continuation whose pull request has since been merged or closed
+fails with category `continuation_closed` and pushes nothing — see
+[Continuation's pull request is no longer open](../help/errors/continuation-closed.md).
+
+#### Limits
+
+- Cancelling the lead run does not stop a native sub-agent that is already
+  running; it keeps running to completion. A coding sub-agent is stopped.
+- If Wardby restarts mid-batch, the batch's delegation calls replay and each
+  one already dispatched reports `already_dispatched`, so the lead does not
+  get those sub-agents' results. A native sub-agent that was running stops
+  with the restart and is marked `lost`, as is a coding sub-agent whose
+  replica crashed. Check the run tree with `get_run` and re-trigger the lead.
+- The lead's own remaining (unspent) budget is not reserved against its
+  children's dispatch, so give the lead's `budgetUsd` headroom beyond the
+  plain sum of its builders' budgets, not just that sum exactly.
+- With nested fan-out — a native sub-agent that itself has
+  `parallelDelegations` and delegates further — two branches dispatching at
+  the same time can briefly both see the same remaining run-tree budget and
+  both be admitted against it.
+
 ### Together with Recipe A
 
 Coding runs automatically receive the repository's knowledge index and base
@@ -371,7 +490,9 @@ bundle current.
 A mention from someone with write access gets a "Working on it" status comment
 from the App. The router either asks a question or delegates, the builder
 pushes a unique branch and opens at most one draft pull request, and the App
-edits the status comment with the pull request link or the failure. A person
+edits the status comment with the pull request link or the failure. The
+link carries ⚠️ instead of ✅ when any of the builder's own checks failed in
+the run; the pull request description says which. A person
 reviews and merges; Wardby never merges for you. A later mention on that pull
 request continues the same branch.