@wardby/cli 0.3.0 → 0.4.1

package/dist/viewer/graph.js

@@ -0,0 +1,243 @@
+import { periodStart } from "../core/budget-groups.js";
+import { publicCodingRunResult } from "../coding/protocol.js";
+export const DEFAULT_GRAPH_LIMIT = 500;
+export const MAX_GRAPH_LIMIT = 2000;
+const DEFAULT_SINCE_MS = 60 * 60 * 1000;
+const RELATIVE_SINCE_MS = {
+    "15m": 15 * 60 * 1000,
+    "1h": 60 * 60 * 1000,
+    "6h": 6 * 60 * 60 * 1000,
+    "24h": 24 * 60 * 60 * 1000,
+    "7d": 7 * 24 * 60 * 60 * 1000,
+};
+/** Accepts "15m" | "1h" | "6h" | "24h" | "7d" or an ISO-8601 timestamp; null defaults to 1h. Throws otherwise. */
+export function parseSince(value, now) {
+    if (value === null)
+        return new Date(now.getTime() - DEFAULT_SINCE_MS);
+    if (Object.hasOwn(RELATIVE_SINCE_MS, value))
+        return new Date(now.getTime() - RELATIVE_SINCE_MS[value]);
+    if (/^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed;
+    }
+    throw new Error(`invalid since "${value}": use 15m, 1h, 6h, 24h, 7d or an ISO-8601 timestamp`);
+}
+const runInclude = {
+    agent: true,
+    codingRun: { select: { result: true, provider: true, model: true, services: true } },
+    hostCheck: true,
+    hostStatus: true,
+    issueStatus: true,
+    serviceStatuses: { orderBy: { createdAt: "asc" } },
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Name and version of each service in a coding run's resolved services snapshot. */
+function declaredServices(snapshot) {
+    if (!Array.isArray(snapshot))
+        return [];
+    return snapshot.filter(isRecord).map((s) => ({ name: String(s.name), version: String(s.version) }));
+}
+const iso = (date) => (date ? date.toISOString() : null);
+function triggerFor(row) {
+    switch (row.trigger) {
+        case "scheduled":
+            return { kind: "scheduled", schedule: row.agent.schedule };
+        case "webhook":
+            return { kind: "webhook" };
+        case "subagent":
+            return { kind: "subagent" };
+        case "manual":
+            return { kind: "manual" };
+        case "host_event":
+            if (row.issueStatus) {
+                return { kind: "issue", provider: row.issueStatus.provider, issueKey: row.issueStatus.issueKey };
+            }
+            if (row.hostStatus) {
+                return {
+                    kind: "code_host",
+                    provider: row.hostStatus.provider,
+                    repository: row.hostStatus.repository,
+                    number: row.hostStatus.number,
+                    event: "mention",
+                };
+            }
+            if (row.hostCheck) {
+                return {
+                    kind: "code_host",
+                    provider: row.hostCheck.provider,
+                    repository: row.hostCheck.repository,
+                    number: row.hostCheck.prNumber,
+                    event: "review",
+                };
+            }
+            return { kind: "host_event" };
+    }
+}
+function outcomesFor(row, pullRequests) {
+    const outcomes = pullRequests.map((pr) => ({
+        kind: "pull_request",
+        provider: pr.codeProvider,
+        repository: pr.repository,
+        number: pr.number,
+        url: pr.url,
+        state: pr.state,
+        at: pr.createdAt.toISOString(),
+    }));
+    const result = publicCodingRunResult(row.codingRun?.result);
+    if (result?.pullRequestUrl &&
+        result.pullRequestNumber &&
+        !pullRequests.some((pr) => pr.url === result.pullRequestUrl)) {
+        outcomes.push({
+            kind: "pull_request",
+            provider: "github",
+            repository: result.repository,
+            number: result.pullRequestNumber,
+            url: result.pullRequestUrl,
+            state: null,
+            at: iso(row.finishedAt),
+        });
+    }
+    if (row.hostStatus?.commentId) {
+        outcomes.push({
+            kind: "code_host_comment",
+            provider: row.hostStatus.provider,
+            repository: row.hostStatus.repository,
+            number: row.hostStatus.number,
+            at: (row.hostStatus.completedAt ?? row.hostStatus.createdAt).toISOString(),
+        });
+    }
+    if (row.issueStatus?.commentId) {
+        outcomes.push({
+            kind: "issue_comment",
+            provider: row.issueStatus.provider,
+            issueKey: row.issueStatus.issueKey,
+            at: (row.issueStatus.completedAt ?? row.issueStatus.createdAt).toISOString(),
+        });
+    }
+    if (row.hostCheck) {
+        outcomes.push({
+            kind: "check",
+            provider: row.hostCheck.provider,
+            repository: row.hostCheck.repository,
+            number: row.hostCheck.prNumber,
+            completed: row.hostCheck.completedAt !== null,
+            at: iso(row.hostCheck.completedAt),
+        });
+    }
+    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) {
+    return {
+        id: row.id,
+        parentRunId: row.parentRunId,
+        agentId: row.agentId,
+        agentName: row.agent.name,
+        agentKind: row.agent.kind,
+        model: row.codingRun?.model ?? row.agent.model,
+        codingProvider: row.codingRun?.provider ?? null,
+        status: row.status,
+        trigger: triggerFor(row),
+        turns: row.turns,
+        tokensIn: row.tokensIn,
+        tokensOut: row.tokensOut,
+        costUsd: Number(row.costUsd),
+        budgetUsd: Number(row.agent.budgetUsd),
+        startedAt: row.startedAt.toISOString(),
+        finishedAt: iso(row.finishedAt),
+        heartbeatAt: iso(row.heartbeatAt),
+        outcomes: outcomesFor(row, pullRequests),
+        declaredServices: declaredServices(row.codingRun?.services),
+        services: row.serviceStatuses.map((s) => ({
+            name: s.name,
+            state: s.state,
+            attempts: s.attempts,
+            reason: s.reason,
+            readyAt: iso(s.readyAt),
+            failedAt: iso(s.failedAt),
+            createdAt: s.createdAt.toISOString(),
+        })),
+    };
+}
+async function mapRows(db, rows) {
+    if (rows.length === 0)
+        return [];
+    const pullRequests = await db.issuePullRequest.findMany({
+        where: { openedByRunId: { in: rows.map((r) => r.id) } },
+        orderBy: { createdAt: "asc" },
+    });
+    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) ?? []));
+}
+/** Loads the given runs as GraphRuns (shared with run detail); unknown ids are skipped. */
+export async function loadGraphRuns(db, runIds) {
+    if (runIds.length === 0)
+        return [];
+    const rows = await db.run.findMany({ where: { id: { in: [...runIds] } }, include: runInclude });
+    return mapRows(db, rows);
+}
+export async function loadGraph(db, options) {
+    const now = options.now ?? new Date();
+    // Window rule: started inside the window, or still in flight (a long run started earlier stays visible).
+    const windowed = await db.run.findMany({
+        where: { OR: [{ startedAt: { gte: options.since } }, { status: { in: ["pending", "running"] } }] },
+        orderBy: [{ startedAt: "desc" }, { id: "desc" }],
+        take: options.limit + 1,
+        include: runInclude,
+    });
+    const truncated = windowed.length > options.limit;
+    const rows = windowed.slice(0, options.limit);
+    // Ancestor rule: every ancestor of a windowed run is included, one batch per level, never capped.
+    const known = new Set(rows.map((r) => r.id));
+    let frontier = rows;
+    for (;;) {
+        const missing = [
+            ...new Set(frontier.map((r) => r.parentRunId).filter((p) => p !== null && !known.has(p))),
+        ];
+        if (missing.length === 0)
+            break;
+        frontier = await db.run.findMany({ where: { id: { in: missing } }, include: runInclude });
+        for (const r of frontier) {
+            known.add(r.id);
+            rows.push(r);
+        }
+    }
+    const dayStart = periodStart("day", now);
+    const [runs, today, groups] = await Promise.all([
+        mapRows(db, rows),
+        db.run.aggregate({ where: { startedAt: { gte: dayStart } }, _sum: { costUsd: true } }),
+        db.budgetGroup.findMany({
+            where: { dailyBudgetUsd: { not: null } },
+            select: { id: true, name: true, dailyBudgetUsd: true, agents: { select: { id: true } } },
+            orderBy: { name: "asc" },
+        }),
+    ]);
+    const memberAgents = groups.flatMap((g) => g.agents.map((a) => a.id));
+    const spendByAgent = memberAgents.length
+        ? await db.run.groupBy({
+            by: ["agentId"],
+            where: { agentId: { in: memberAgents }, startedAt: { gte: dayStart } },
+            _sum: { costUsd: true },
+        })
+        : [];
+    const spent = new Map(spendByAgent.map((s) => [s.agentId, Number(s._sum.costUsd ?? 0)]));
+    return {
+        generatedAt: now.toISOString(),
+        since: options.since.toISOString(),
+        limit: options.limit,
+        truncated,
+        runs,
+        spend: {
+            todayUsd: Number(today._sum.costUsd ?? 0),
+            groups: groups.map((g) => ({
+                id: g.id,
+                name: g.name,
+                dailyBudgetUsd: g.dailyBudgetUsd === null ? null : Number(g.dailyBudgetUsd),
+                spentTodayUsd: g.agents.reduce((sum, a) => sum + (spent.get(a.id) ?? 0), 0),
+            })),
+        },
+    };
+}

package/dist/viewer/http.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Viewer HTTP routes: GET /admin/api/graph, /admin/api/runs/:id 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
+ * the server's catch (401/403 + WWW-Authenticate).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PrismaClient } from "#prisma";
+import type { McpRequestContext } from "../mcp/context.js";
+import type { ViewerEventBus } from "./event-bus.js";
+export declare const VIEWER_API_PREFIX = "/admin/api/";
+export declare const SSE_HEARTBEAT_MS = 15000;
+/** A stream whose unsent backlog exceeds this is ended; the client reconnects and resyncs. */
+export declare const SSE_MAX_BUFFERED_BYTES: number;
+export interface ViewerApiDeps {
+    db: PrismaClient;
+    bus: ViewerEventBus;
+    authenticate: (authorization: string | undefined) => Promise<McpRequestContext>;
+    canonicalUri: string;
+    heartbeatMs?: number;
+    maxBufferedBytes?: number;
+}
+export interface ViewerApi {
+    /** Returns false when the path is not a viewer route (caller falls through to 404). */
+    handle(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
+    /** Ends every open event stream (server shutdown). */
+    closeStreams(): void;
+}
+export declare function createViewerApi(deps: ViewerApiDeps): ViewerApi;

package/dist/viewer/http.js

@@ -0,0 +1,133 @@
+import { requireScope } from "../mcp/auth/resource-server.js";
+import { sendJson } from "../mcp/transport/streamable-http.js";
+import { DEFAULT_GRAPH_LIMIT, MAX_GRAPH_LIMIT, loadGraph, parseSince } from "./graph.js";
+import { loadRunDetail } from "./run-detail.js";
+export const VIEWER_API_PREFIX = "/admin/api/";
+export const SSE_HEARTBEAT_MS = 15_000;
+/** A stream whose unsent backlog exceeds this is ended; the client reconnects and resyncs. */
+export const SSE_MAX_BUFFERED_BYTES = 1024 * 1024;
+const RUN_ID = /^[A-Za-z0-9_-]{1,64}$/;
+export function createViewerApi(deps) {
+    const heartbeatMs = deps.heartbeatMs ?? SSE_HEARTBEAT_MS;
+    const maxBufferedBytes = deps.maxBufferedBytes ?? SSE_MAX_BUFFERED_BYTES;
+    const streams = new Set();
+    let nextEventId = 0;
+    function openStream(req, res) {
+        // The client may have gone while we awaited authentication; its close
+        // events already fired and will not fire again, so subscribing now would leak.
+        if (req.destroyed || res.destroyed || res.writableEnded)
+            return;
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-store",
+            connection: "keep-alive",
+            "x-accel-buffering": "no",
+        });
+        let done = false;
+        // A client that stops reading (or reads too slowly) must not grow server
+        // memory without bound: past the limit, drop the stream (its backlog with
+        // it); the client reconnects and resyncs.
+        const send = (frame) => {
+            if (done)
+                return;
+            res.write(frame);
+            if (res.writableLength > maxBufferedBytes) {
+                cleanup();
+                res.destroy();
+            }
+        };
+        res.write("retry: 3000\n\n");
+        res.write(`event: hello\ndata: ${JSON.stringify({ connected: deps.bus.connected() })}\n\n`);
+        const unsubscribe = deps.bus.subscribe((event) => {
+            send(`id: ${++nextEventId}\nevent: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`);
+        });
+        // Every transition to live (including the bus's first connect, which
+        // usually lands just after this stream opens) may follow missed events, so
+        // tell the client to refetch the graph. Going down only changes status.
+        const unstate = deps.bus.onState((live) => {
+            send(`event: status\ndata: ${JSON.stringify({ connected: live })}\n\n`);
+            if (live)
+                send("event: resync\ndata: {}\n\n");
+        });
+        const heartbeat = setInterval(() => send(": ping\n\n"), heartbeatMs);
+        const cleanup = () => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(heartbeat);
+            unsubscribe();
+            unstate();
+            streams.delete(close);
+        };
+        const close = () => {
+            cleanup();
+            // Close the connection with the stream, so shutdown never waits for the
+            // keep-alive timeout.
+            res.shouldKeepAlive = false;
+            res.end();
+        };
+        streams.add(close);
+        req.on("close", cleanup);
+        res.on("close", cleanup);
+        res.on("error", cleanup);
+    }
+    return {
+        async handle(req, res, url) {
+            const path = url.pathname;
+            const runMatch = /^\/admin\/api\/runs\/([^/]*)$/.exec(path);
+            const isGraph = path === "/admin/api/graph";
+            const isEvents = path === "/admin/api/events";
+            if (!isGraph && !isEvents && !runMatch)
+                return false;
+            const ctx = await deps.authenticate(req.headers.authorization);
+            requireScope(ctx, deps.canonicalUri, "admin:view");
+            if (req.method !== "GET") {
+                sendJson(res, 405, { error: "method_not_allowed" }, { allow: "GET" });
+                return true;
+            }
+            if (isGraph) {
+                const limitParam = url.searchParams.get("limit");
+                let limit = DEFAULT_GRAPH_LIMIT;
+                if (limitParam !== null) {
+                    limit = /^\d{1,6}$/.test(limitParam) ? Number(limitParam) : 0;
+                    if (limit < 1 || limit > MAX_GRAPH_LIMIT) {
+                        sendJson(res, 400, { error: "invalid_limit" });
+                        return true;
+                    }
+                }
+                const now = new Date();
+                let since;
+                try {
+                    since = parseSince(url.searchParams.get("since"), now);
+                }
+                catch {
+                    sendJson(res, 400, { error: "invalid_since" });
+                    return true;
+                }
+                sendJson(res, 200, await loadGraph(deps.db, { since, limit, now }));
+                return true;
+            }
+            if (runMatch) {
+                let id = "";
+                try {
+                    id = decodeURIComponent(runMatch[1]);
+                }
+                catch {
+                    /* malformed escape: fails the id check below */
+                }
+                const detail = RUN_ID.test(id) ? await loadRunDetail(deps.db, id) : null;
+                if (!detail)
+                    sendJson(res, 404, { error: "not_found" });
+                else
+                    sendJson(res, 200, detail);
+                return true;
+            }
+            openStream(req, res);
+            return true;
+        },
+        closeStreams() {
+            for (const close of [...streams])
+                close();
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+/** 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>;

package/dist/viewer/run-detail.js

@@ -0,0 +1,61 @@
+import { loadGraphRuns } from "./graph.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Reads the CodingRun.services snapshot. Env values are never copied: names only, and serviceEnv is never read. */
+function serviceDetails(snapshot) {
+    if (!Array.isArray(snapshot))
+        return [];
+    return snapshot.filter(isRecord).map((s) => ({
+        name: String(s.name),
+        version: String(s.version),
+        image: String(s.image),
+        envNames: isRecord(s.testEnv) ? Object.keys(s.testEnv).sort() : [],
+    }));
+}
+export async function loadRunDetail(db, runId) {
+    const [graphRun] = await loadGraphRuns(db, [runId]);
+    if (!graphRun)
+        return null;
+    const [row, children] = await Promise.all([
+        db.run.findUniqueOrThrow({
+            where: { id: runId },
+            select: {
+                error: true,
+                finalText: true,
+                codingRun: {
+                    select: {
+                        provider: true,
+                        repository: true,
+                        baseRef: true,
+                        headRef: true,
+                        queuedAt: true,
+                        failureCategory: true,
+                        services: true,
+                    },
+                },
+            },
+        }),
+        db.run.findMany({
+            where: { parentRunId: runId },
+            select: { id: true },
+            orderBy: [{ startedAt: "asc" }, { id: "asc" }],
+        }),
+    ]);
+    const coding = row.codingRun;
+    return {
+        ...graphRun,
+        error: row.error,
+        finalText: row.finalText,
+        childRunIds: children.map((c) => c.id),
+        coding: coding
+            ? {
+                provider: coding.provider,
+                repository: coding.repository,
+                baseRef: coding.baseRef,
+                headRef: coding.headRef,
+                queuedAt: coding.queuedAt ? coding.queuedAt.toISOString() : null,
+                failureCategory: coding.failureCategory,
+                services: serviceDetails(coding.services),
+            }
+            : null,
+    };
+}

package/dist/wardby-bin.js

@@ -42,6 +42,11 @@ async function main() {
         const { helpCommand } = await import("./help/cli.js");
         await helpCommand(process.argv.slice(3));
     }
+    else if (command === "knowledge") {
+        // Offline bundle validation: no environment, database, or HTTP runtime.
+        const { knowledgeCommand } = await import("./knowledge/cli.js");
+        await knowledgeCommand(process.argv.slice(3));
+    }
     else {
         await import("./cli.js");
     }

package/docs/README.md

@@ -8,8 +8,16 @@
   configures an existing OAuth/OIDC provider to protect remote MCP access.
 - [Runtime architecture](architecture-runtime.md) explains the control-plane,
   provider, persistence, and execution boundaries.
+- [Models and pricing](models.md) covers the model catalog: the shipped models,
+  adding or overriding one with `set_model`, disabling and resetting, and how
+  runs are billed.
+- [Agent recipes](agent-recipes.md) gives two copyable setups, an architecture
+  keeper and a per-language builder, with the prerequisites each needs.
 - [Coding-agent setup](coding-agent-setup.md) configures the local trusted proxy
   and isolated Codex or Claude Code workers.
+- [Architecture knowledge bundles](knowledge.md) covers `docs/knowledge/`: the
+  concept format, how coding runs and reviewers use it, `wardby knowledge check`,
+  and the scheduled architecture agent.
 - [Coding-worker isolation](coding-worker-isolation.md) documents the threat
   model and enforced worker boundary.
 - [Bring-your-own worker images](coding-worker-byo-images.md) explains how to
@@ -19,6 +27,8 @@
 - [Services for coding runs](coding-services.md) gives coding runs fresh
   PostgreSQL, Redis or MySQL instances declared in `.wardby/services.yaml`:
   the catalog, per-agent permission, variables, and errors.
+- [Jira agents](jira-agents.md) connects wardby to Jira Cloud with a service
+  account and webhook, and links agents to projects.
 - [Observability](observability.md) covers Prometheus metrics, Grafana, cloud
   collectors, retention, and production ownership.
 - [Release verification](release-verification.md) lists the automated and live