-
Arthur engine · prompt versioning
+
+ {data.arthurEnabled ? "Arthur engine · prompt versioning" : "In-code defaults · prompt versioning"}
+
Prompt registry
@@ -338,16 +274,18 @@ export function PromptsScreen() {
-
-
-
p.tags.includes("production")).length.toString()} sub="serving traffic" />
- p.tags.includes("ab-test")).length.toString()} sub="live experiments" />
-
+
+
+
);
diff --git a/apps/dashboard/lib/api/fallbacks.ts b/apps/dashboard/lib/api/fallbacks.ts
index d7c81cb..d0eec95 100644
--- a/apps/dashboard/lib/api/fallbacks.ts
+++ b/apps/dashboard/lib/api/fallbacks.ts
@@ -1,6 +1,9 @@
import type {
KpisResponse,
EvalHealthResponse,
+ EvalsResponse,
+ CostResponse,
+ PromptsResponse,
RunsResponse,
RunDetailResponse,
LiveRunsResponse,
@@ -42,3 +45,23 @@ export function liveRunsFallback(now: string): LiveRunsResponse {
export function workflowsFallback(now: string): WorkflowsResponse {
return { generatedAt: now, rows: [], total: 0 };
}
+
+export function evalsFallback(now: string): EvalsResponse {
+ return { available: false, generatedAt: now, reason: "Worker unavailable." };
+}
+
+export function costFallback(now: string): CostResponse {
+ return {
+ generatedAt: now,
+ available: false,
+ window: { start: now, end: now },
+ totals: { totalTokenCost: 0, totalTokens: 0, traceCount: 0, costPerRun: 0 },
+ byModel: [],
+ byWorkflow: [],
+ daily: [],
+ };
+}
+
+export function promptsFallback(now: string): PromptsResponse {
+ return { generatedAt: now, available: false, arthurEnabled: false, rows: [], total: 0 };
+}
diff --git a/apps/shared/contracts/api.ts b/apps/shared/contracts/api.ts
index 32eecbc..4f3d171 100644
--- a/apps/shared/contracts/api.ts
+++ b/apps/shared/contracts/api.ts
@@ -1,4 +1,4 @@
-import type { Run, RunDetail, RunStep, Workflow } from "./domain.js";
+import type { PromptDef, Run, RunDetail, RunStep, Workflow } from "./domain.js";
export interface ErrorEnvelope {
error: { code: string; message: string; details?: unknown };
@@ -24,6 +24,90 @@ export type EvalHealthResponse =
}
| { available: false; reason: string };
+export type EvalsResponse =
+ | {
+ available: true;
+ generatedAt: string;
+ windowHours: number;
+ /** continuous_eval_success_rate × 100, fleet-wide. */
+ score: number;
+ /** Σ eval_count across tasks — "spans graded" in the window. */
+ spansGraded: number;
+ /** Σ trace_count across tasks. */
+ traceCount: number;
+ }
+ | { available: false; generatedAt: string; reason: string };
+
+export interface CostByModelEntry {
+ /** Arthur span model_name. */
+ model: string;
+ /** USD, summed total_token_cost over the window. */
+ cost: number;
+ /** Summed total_token_count over the window. */
+ tokens: number;
+}
+
+export interface CostByWorkflowEntry {
+ /** Arthur task_id (per ticket-run, e.g. "AWT-42" / "AWT-42.1"). */
+ taskId: string;
+ /** Arthur task name (= the ticket-run identifier). */
+ name: string;
+ /** trace_count for the task. */
+ runs: number;
+ /** trace_token_count. */
+ tokens: number;
+ /** trace_token_cost (USD). */
+ cost: number;
+ /** cost / max(1, runs). */
+ costPerRun: number;
+}
+
+export interface CostResponse {
+ generatedAt: string;
+ /**
+ * false when Arthur is unconfigured/unreachable or returns nothing. The
+ * screen renders its empty/N-A state.
+ */
+ available: boolean;
+ /** Window the figures cover (the request's start_time/end_time). ISO. */
+ window: { start: string; end: string };
+ totals: {
+ /** USD, Σ overviews[].trace_token_cost. */
+ totalTokenCost: number;
+ /** Σ overviews[].trace_token_count. */
+ totalTokens: number;
+ /** Σ overviews[].trace_count. */
+ traceCount: number;
+ /** totalTokenCost / max(1, traceCount). */
+ costPerRun: number;
+ };
+ byModel: CostByModelEntry[];
+ /** Per-task (= per ticket-run) breakdown from /traces/overview. */
+ byWorkflow: CostByWorkflowEntry[];
+ /** Per-day spend, oldest→newest, merged across tasks from the timeseries. */
+ daily: { date: string; cost: number; tokens: number }[];
+}
+
+export interface PromptsResponse {
+ generatedAt: string;
+ /** `false` when the worker can't resolve prompts (degrades to empty list). */
+ available: boolean;
+ /**
+ * Whether Arthur is configured (key + endpoint + task id all set). When
+ * false, every prompt's `source` is "fallback" and `versions` is empty.
+ */
+ arthurEnabled: boolean;
+ rows: PromptDef[];
+ total: number;
+}
+
+/** On-demand body for a single historical Arthur version. */
+export interface PromptVersionBodyResponse {
+ generatedAt: string;
+ available: boolean;
+ body: string | null;
+}
+
export interface LiveRunsResponse {
generatedAt: string;
rows: Run[];
diff --git a/apps/shared/contracts/domain.ts b/apps/shared/contracts/domain.ts
index 6aba292..d4868a4 100644
--- a/apps/shared/contracts/domain.ts
+++ b/apps/shared/contracts/domain.ts
@@ -133,3 +133,36 @@ export interface HourPoint {
p95: number;
errors: number;
}
+
+/** One Arthur version of a named prompt (metadata; body fetched on demand). */
+export interface PromptVersion {
+ /** Arthur integer version number. */
+ version: number;
+ /** ISO timestamp the version was created. */
+ createdAt: string;
+ /** Real Arthur tags on this version, e.g. ["production"]. */
+ tags: string[];
+ modelProvider: string;
+ modelName: string;
+ numMessages: number;
+ numTools: number;
+ /** Body text. Present only for the production version (eager); other
+ * versions are fetched on demand via the by-version endpoint. */
+ body?: string;
+}
+
+/** A workflow phase prompt as resolved by the worker at runtime. */
+export interface PromptDef {
+ /** Stable Arthur/fallback key: "research-plan" | "implement" | "review". */
+ name: string;
+ /** Human label for the workflow phase, e.g. "Research & Plan". */
+ phase: string;
+ /** Resolved production prompt body (Arthur production tag, or in-code fallback). */
+ body: string;
+ /** Where the resolved `body` came from. */
+ source: "arthur" | "fallback";
+ /** Model the agent runs this prompt with (env-derived). */
+ model: string;
+ /** Real Arthur version history, newest first. Empty when source is "fallback". */
+ versions: PromptVersion[];
+}
diff --git a/apps/worker/src/lib/overview/collect-cost.test.ts b/apps/worker/src/lib/overview/collect-cost.test.ts
new file mode 100644
index 0000000..f0d9736
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-cost.test.ts
@@ -0,0 +1,186 @@
+import { describe, it, expect, vi } from "vitest";
+import { collectCost, type CostArthurClient } from "./collect-cost.js";
+import type {
+ TraceOverviewListResponse,
+ TraceTimeseriesPoint,
+ ModelTokenCost,
+} from "../../sandbox/arthur-client.js";
+
+const NOW = new Date("2026-06-08T12:00:00.000Z");
+
+function makeClient(opts: {
+ overview: TraceOverviewListResponse;
+ timeseries: Record
;
+ byModel: ModelTokenCost[];
+}): CostArthurClient {
+ return {
+ getTracesOverview: vi.fn().mockResolvedValue(opts.overview),
+ getTracesTimeseries: vi
+ .fn()
+ .mockImplementation((taskId: string) =>
+ Promise.resolve(opts.timeseries[taskId] ?? []),
+ ),
+ aggregateSpanTokensByModel: vi.fn().mockResolvedValue(opts.byModel),
+ };
+}
+
+describe("collectCost", () => {
+ it("aggregates totals, per-task breakdown, by-model, and merged daily series", async () => {
+ const client = makeClient({
+ overview: {
+ count: 2,
+ overviews: [
+ {
+ task_id: "t1",
+ trace_count: 4,
+ trace_token_count: 1000,
+ trace_token_cost: 2.0,
+ eval_count: 0,
+ continuous_eval_success_rate: 1,
+ last_active: "2026-06-08",
+ },
+ {
+ task_id: "t2",
+ trace_count: 6,
+ trace_token_count: 3000,
+ trace_token_cost: 4.0,
+ eval_count: 0,
+ continuous_eval_success_rate: 1,
+ },
+ ],
+ },
+ timeseries: {
+ t1: [
+ { timestamp: "2026-06-06", trace_count: 2, trace_token_count: 500, trace_token_cost: 1.0 },
+ { timestamp: "2026-06-07", trace_count: 2, trace_token_count: 500, trace_token_cost: 1.0 },
+ ],
+ t2: [
+ { timestamp: "2026-06-07", trace_count: 3, trace_token_count: 1500, trace_token_cost: 2.0 },
+ { timestamp: "2026-06-08", trace_count: 3, trace_token_count: 1500, trace_token_cost: 2.0 },
+ ],
+ },
+ byModel: [
+ { model: "claude-opus-4-6", tokens: 3000, cost: 5.0 },
+ { model: "claude-haiku", tokens: 1000, cost: 1.0 },
+ ],
+ });
+
+ const data = await collectCost(client, { now: NOW, bucketSize: "day" });
+
+ // totals
+ expect(data.totals).toEqual({
+ totalTokenCost: 6.0,
+ totalTokens: 4000,
+ traceCount: 10,
+ costPerRun: 0.6,
+ });
+
+ // window = calendar MTD
+ expect(data.window.start).toBe("2026-06-01T00:00:00.000Z");
+ expect(data.window.end).toBe(NOW.toISOString());
+
+ // byWorkflow = per-task, with costPerRun guarded
+ expect(data.byWorkflow).toEqual([
+ { taskId: "t1", name: "t1", runs: 4, tokens: 1000, cost: 2.0, costPerRun: 0.5 },
+ { taskId: "t2", name: "t2", runs: 6, tokens: 3000, cost: 4.0, costPerRun: 4 / 6 },
+ ]);
+
+ // byModel passthrough mapped to contract shape
+ expect(data.byModel).toEqual([
+ { model: "claude-opus-4-6", cost: 5.0, tokens: 3000 },
+ { model: "claude-haiku", cost: 1.0, tokens: 1000 },
+ ]);
+
+ // daily merged by timestamp, oldest -> newest
+ expect(data.daily).toEqual([
+ { date: "2026-06-06", cost: 1.0, tokens: 500 },
+ { date: "2026-06-07", cost: 3.0, tokens: 2000 },
+ { date: "2026-06-08", cost: 2.0, tokens: 1500 },
+ ]);
+ });
+
+ it("treats null trace_token_cost as 0 and guards divide-by-zero", async () => {
+ const client = makeClient({
+ overview: {
+ count: 1,
+ overviews: [
+ {
+ task_id: "t1",
+ trace_count: 0,
+ trace_token_count: 0,
+ trace_token_cost: null,
+ eval_count: 0,
+ continuous_eval_success_rate: 0,
+ },
+ ],
+ },
+ timeseries: { t1: [] },
+ byModel: [],
+ });
+
+ const data = await collectCost(client, { now: NOW, bucketSize: "day" });
+
+ expect(data.totals).toEqual({
+ totalTokenCost: 0,
+ totalTokens: 0,
+ traceCount: 0,
+ costPerRun: 0,
+ });
+ expect(data.byWorkflow).toEqual([
+ { taskId: "t1", name: "t1", runs: 0, tokens: 0, cost: 0, costPerRun: 0 },
+ ]);
+ expect(data.byModel).toEqual([]);
+ expect(data.daily).toEqual([]);
+ });
+
+ it("returns empty aggregates when Arthur has no tasks", async () => {
+ const client = makeClient({
+ overview: { count: 0, overviews: [] },
+ timeseries: {},
+ byModel: [],
+ });
+
+ const data = await collectCost(client, { now: NOW, bucketSize: "day" });
+
+ expect(data.totals).toEqual({
+ totalTokenCost: 0,
+ totalTokens: 0,
+ traceCount: 0,
+ costPerRun: 0,
+ });
+ expect(data.byWorkflow).toEqual([]);
+ expect(data.byModel).toEqual([]);
+ expect(data.daily).toEqual([]);
+ // No tasks -> no per-task timeseries fan-out.
+ expect(client.getTracesTimeseries).not.toHaveBeenCalled();
+ });
+
+ it("caps the daily timeseries fan-out to the 50 most-active tasks", async () => {
+ // 60 tasks, each with a distinct trace_count so the top-50 are deterministic.
+ const overviews = Array.from({ length: 60 }, (_, i) => ({
+ task_id: `t${i}`,
+ trace_count: i, // t59 most active, t0 least
+ trace_token_count: 0,
+ trace_token_cost: 0,
+ eval_count: 0,
+ continuous_eval_success_rate: 0,
+ }));
+ const client = makeClient({
+ overview: { count: overviews.length, overviews },
+ timeseries: {},
+ byModel: [],
+ });
+
+ await collectCost(client, { now: NOW, bucketSize: "day" });
+
+ // Only the 50 highest-trace_count tasks are queried (t10..t59).
+ expect(client.getTracesTimeseries).toHaveBeenCalledTimes(50);
+ const queried = (client.getTracesTimeseries as ReturnType).mock.calls.map(
+ (c) => c[0],
+ );
+ expect(queried).not.toContain("t0");
+ expect(queried).not.toContain("t9");
+ expect(queried).toContain("t10");
+ expect(queried).toContain("t59");
+ });
+});
diff --git a/apps/worker/src/lib/overview/collect-cost.ts b/apps/worker/src/lib/overview/collect-cost.ts
new file mode 100644
index 0000000..258cb0e
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-cost.ts
@@ -0,0 +1,142 @@
+import type { CostResponse } from "@shared/contracts";
+import { logger } from "../logger.js";
+import type {
+ TraceOverviewListResponse,
+ TraceTimeseriesPoint,
+ ModelTokenCost,
+} from "../../sandbox/arthur-client.js";
+
+/**
+ * The slice of `ArthurClient` the cost collector depends on. The real object is
+ * an `ArthurClient`; this narrow interface keeps the aggregation testable with a
+ * fake (mirrors `RunsLister` for the run-store collectors).
+ */
+export interface CostArthurClient {
+ getTracesOverview(
+ taskIds: string[],
+ startTime: string,
+ endTime: string,
+ ): Promise;
+ getTracesTimeseries(
+ taskId: string,
+ startTime: string,
+ endTime: string,
+ bucketSize: string,
+ ): Promise;
+ aggregateSpanTokensByModel(
+ taskIds: string[],
+ startTime: string,
+ endTime: string,
+ ): Promise;
+}
+
+export interface CollectCostOptions {
+ now: Date;
+ /** Bucket granularity for the daily-spend timeseries. */
+ bucketSize: string;
+}
+
+/**
+ * Shapes a `CostResponse` (minus `generatedAt`/`available`) from Arthur's
+ * pre-aggregated token/cost data. Cost comes straight from Arthur's
+ * `*_token_cost` fields — no client-side pricing.
+ *
+ * - `totals` + `byWorkflow` come from one `getTracesOverview` call. Arthur tasks
+ * ARE the workflow grouping (per ticket-run), so each overview row is one
+ * `byWorkflow` entry.
+ * - `byModel` comes from `aggregateSpanTokensByModel` (the one client-side
+ * grouping, since Arthur has no per-model overview).
+ * - `daily` fans out one `getTracesTimeseries` call per task that appears in the
+ * overview and merges points by bucket timestamp.
+ */
+export async function collectCost(
+ client: CostArthurClient,
+ opts: CollectCostOptions,
+): Promise> {
+ const { now, bucketSize } = opts;
+ // Assumption: calendar month-to-date (matches the original "MTD" framing).
+ // TODO(arthur-verify): confirm the intended window (calendar MTD vs rolling 30d/24h).
+ const start = startOfMonthUTC(now).toISOString();
+ const end = now.toISOString();
+
+ // TODO(arthur-verify): empty `task_ids` is assumed to mean org-wide. If Arthur
+ // requires explicit ids, enumerate the org's tasks and pass them instead.
+ const { overviews } = await client.getTracesOverview([], start, end);
+
+ let totalTokenCost = 0;
+ let totalTokens = 0;
+ let traceCount = 0;
+ const byWorkflow = overviews.map((o) => {
+ // trace_token_cost is null when Arthur has no cost data — treat as 0.
+ const cost = o.trace_token_cost ?? 0;
+ totalTokenCost += cost;
+ totalTokens += o.trace_token_count;
+ traceCount += o.trace_count;
+ return {
+ taskId: o.task_id,
+ // Arthur task name = the ticket-run identifier; overview omits it, so the
+ // task_id (which IS that identifier) doubles as the display name.
+ // TODO(arthur-verify): task->workflow mapping — rows stay per-task.
+ name: o.task_id,
+ runs: o.trace_count,
+ tokens: o.trace_token_count,
+ cost,
+ costPerRun: o.trace_count > 0 ? cost / o.trace_count : 0,
+ };
+ });
+
+ const totals = {
+ totalTokenCost,
+ totalTokens,
+ traceCount,
+ costPerRun: traceCount > 0 ? totalTokenCost / traceCount : 0,
+ };
+
+ const byModelRaw = await client.aggregateSpanTokensByModel([], start, end);
+ const byModel = byModelRaw.map((m) => ({
+ model: m.model,
+ cost: m.cost,
+ tokens: m.tokens,
+ }));
+
+ // Fan out one timeseries call per task that has data, then merge by bucket.
+ // Tasks are per-ticket-run, so a busy month can be hundreds — cap the fan-out
+ // to the most-active tasks to avoid an unbounded burst of requests.
+ // TODO(arthur-verify): cap is by trace_count, on the assumption the highest-
+ // traffic tasks dominate the daily-spend curve; revisit if the chart looks short.
+ const DAILY_FANOUT_CAP = 50;
+ const sortedByActivity = [...overviews].sort((a, b) => b.trace_count - a.trace_count);
+ const fanoutTasks = sortedByActivity.slice(0, DAILY_FANOUT_CAP);
+ if (sortedByActivity.length > DAILY_FANOUT_CAP) {
+ logger.info(
+ {
+ total: sortedByActivity.length,
+ capped: DAILY_FANOUT_CAP,
+ dropped: sortedByActivity.slice(DAILY_FANOUT_CAP).map((o) => o.task_id),
+ },
+ "cost_daily_fanout_capped",
+ );
+ }
+ const taskIds = fanoutTasks.map((o) => o.task_id);
+ const series = await Promise.all(
+ taskIds.map((id) => client.getTracesTimeseries(id, start, end, bucketSize)),
+ );
+ const merged = new Map();
+ for (const points of series) {
+ for (const p of points) {
+ const row = merged.get(p.timestamp) ?? { cost: 0, tokens: 0 };
+ row.cost += p.trace_token_cost ?? 0;
+ row.tokens += p.trace_token_count;
+ merged.set(p.timestamp, row);
+ }
+ }
+ const daily = [...merged.entries()]
+ .map(([date, v]) => ({ date, cost: v.cost, tokens: v.tokens }))
+ .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+
+ return { window: { start, end }, totals, byModel, byWorkflow, daily };
+}
+
+function startOfMonthUTC(now: Date): Date {
+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}
diff --git a/apps/worker/src/lib/overview/collect-evals.test.ts b/apps/worker/src/lib/overview/collect-evals.test.ts
new file mode 100644
index 0000000..1b40a6f
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-evals.test.ts
@@ -0,0 +1,95 @@
+import { describe, it, expect, vi } from "vitest";
+import { collectEvals } from "./collect-evals.js";
+import type { TraceOverview } from "../../sandbox/arthur-client.js";
+
+const NOW = new Date("2026-06-08T12:00:00.000Z");
+
+function makeClient(overviews: TraceOverview[]) {
+ return { getTracesOverview: vi.fn().mockResolvedValue({ overviews }) };
+}
+
+function overview(over: Partial): TraceOverview {
+ return {
+ task_id: "t",
+ trace_count: 0,
+ trace_token_count: 0,
+ trace_token_cost: 0,
+ eval_count: 0,
+ continuous_eval_success_rate: 0,
+ ...over,
+ };
+}
+
+describe("collectEvals", () => {
+ it("sums spansGraded/traceCount and eval-count-weights the score", async () => {
+ const client = makeClient([
+ overview({ task_id: "a", trace_count: 10, eval_count: 8, continuous_eval_success_rate: 1.0 }),
+ overview({ task_id: "b", trace_count: 4, eval_count: 2, continuous_eval_success_rate: 0.5 }),
+ ]);
+
+ const result = await collectEvals({
+ client,
+ taskIds: [],
+ windowHours: 24,
+ now: NOW,
+ });
+
+ expect(result.spansGraded).toBe(10);
+ expect(result.traceCount).toBe(14);
+ // (1.0*8 + 0.5*2) / 10 * 100 = (8 + 1) / 10 * 100 = 90
+ expect(result.score).toBe(90);
+ expect(result.windowHours).toBe(24);
+ });
+
+ it("yields score 0 when nothing is graded (eval_count sums to 0)", async () => {
+ const client = makeClient([
+ overview({ task_id: "a", trace_count: 5, eval_count: 0 }),
+ ]);
+
+ const result = await collectEvals({
+ client,
+ taskIds: [],
+ windowHours: 24,
+ now: NOW,
+ });
+
+ expect(result.spansGraded).toBe(0);
+ expect(result.traceCount).toBe(5);
+ expect(result.score).toBe(0);
+ });
+
+ it("computes the window start from windowHours and passes the ISO range to the client", async () => {
+ const client = makeClient([]);
+
+ await collectEvals({
+ client,
+ taskIds: ["x", "y"],
+ windowHours: 24,
+ now: NOW,
+ });
+
+ expect(client.getTracesOverview).toHaveBeenCalledWith(
+ ["x", "y"],
+ "2026-06-07T12:00:00.000Z",
+ "2026-06-08T12:00:00.000Z",
+ );
+ });
+
+ it("returns zeroed aggregates when no overviews are returned", async () => {
+ const client = makeClient([]);
+
+ const result = await collectEvals({
+ client,
+ taskIds: [],
+ windowHours: 24,
+ now: NOW,
+ });
+
+ expect(result).toEqual({
+ windowHours: 24,
+ score: 0,
+ spansGraded: 0,
+ traceCount: 0,
+ });
+ });
+});
diff --git a/apps/worker/src/lib/overview/collect-evals.ts b/apps/worker/src/lib/overview/collect-evals.ts
new file mode 100644
index 0000000..b144232
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-evals.ts
@@ -0,0 +1,74 @@
+import type { EvalsResponse } from "@shared/contracts";
+import type { TraceOverview } from "../../sandbox/arthur-client.js";
+
+const HOUR = 3_600_000;
+
+/** Fleet aggregate fields the route spreads onto an `available: true` response. */
+export type EvalsAggregate = Pick<
+ Extract,
+ "windowHours" | "score" | "spansGraded" | "traceCount"
+>;
+
+/**
+ * The slice of `ArthurClient` the eval collector depends on. The real object is
+ * an `ArthurClient`; this narrow interface keeps the aggregation testable with a
+ * fake (mirrors `CostArthurClient` for the cost collector).
+ */
+export interface EvalsArthurClient {
+ getTracesOverview(
+ taskIds: string[],
+ startTime: string,
+ endTime: string,
+ ): Promise<{ overviews: TraceOverview[] }>;
+}
+
+export interface CollectEvalsOptions {
+ client: EvalsArthurClient;
+ // TODO(arthur-verify): unconfirmed whether `taskIds: []` means "all org tasks"
+ // on POST /api/v1/traces/overview. If not, the route must enumerate tasks first.
+ taskIds: string[];
+ windowHours: number;
+ now: Date;
+}
+
+/**
+ * Aggregates Arthur's per-task trace overviews into fleet-wide eval health:
+ * eval-count-weighted success rate × 100, summed spans-graded and trace counts
+ * over the window. When `spansGraded` sums to 0 (no continuous evals configured
+ * / nothing graded), `score` is 0 and the route turns that into
+ * `available: false`.
+ */
+export async function collectEvals(
+ opts: CollectEvalsOptions,
+): Promise {
+ const endTime = opts.now.toISOString();
+ const startTime = new Date(
+ opts.now.getTime() - opts.windowHours * HOUR,
+ ).toISOString();
+
+ const { overviews } = await opts.client.getTracesOverview(
+ opts.taskIds,
+ startTime,
+ endTime,
+ );
+
+ const spansGraded = sum(overviews, (o) => o.eval_count);
+ const traceCount = sum(overviews, (o) => o.trace_count);
+ const score =
+ spansGraded === 0
+ ? 0
+ : (sum(overviews, (o) => o.continuous_eval_success_rate * o.eval_count) /
+ spansGraded) *
+ 100;
+
+ return {
+ windowHours: opts.windowHours,
+ score,
+ spansGraded,
+ traceCount,
+ };
+}
+
+function sum(items: T[], pick: (item: T) => number): number {
+ return items.reduce((acc, item) => acc + (pick(item) || 0), 0);
+}
diff --git a/apps/worker/src/lib/overview/collect-prompts.test.ts b/apps/worker/src/lib/overview/collect-prompts.test.ts
new file mode 100644
index 0000000..8d382cb
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-prompts.test.ts
@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../../env.js", () => ({ env: {} }));
+
+const mockGetPromptByTag = vi.fn();
+const mockListPromptVersions = vi.fn();
+vi.mock("../../sandbox/arthur-client.js", () => ({
+ ArthurClient: {
+ fromTraceEndpoint: vi.fn(() => ({
+ getPromptByTag: mockGetPromptByTag,
+ listPromptVersions: mockListPromptVersions,
+ })),
+ },
+}));
+
+import { resolvePrompts } from "./collect-prompts.js";
+import { PROMPT_FALLBACKS } from "../prompts.js";
+
+async function setEnv(partial: Record) {
+ const mod = (await import("../../../env.js")) as unknown as {
+ env: Record;
+ };
+ mod.env = { ...mod.env, ...partial };
+}
+
+function arthurVersion(version: number, tags: string[]) {
+ return {
+ version,
+ created_at: `2026-06-0${version}T00:00:00.000Z`,
+ deleted_at: null,
+ model_provider: "anthropic",
+ model_name: "claude-opus-4-6",
+ tags,
+ num_messages: 1,
+ num_tools: 0,
+ };
+}
+
+describe("resolvePrompts", () => {
+ beforeEach(async () => {
+ mockGetPromptByTag.mockReset();
+ mockListPromptVersions.mockReset();
+ await setEnv({
+ AGENT_KIND: "claude",
+ CLAUDE_MODEL: "claude-opus-4-6",
+ CODEX_MODEL: "gpt-5-codex",
+ GENAI_ENGINE_API_KEY: undefined,
+ GENAI_ENGINE_TRACE_ENDPOINT: undefined,
+ GENAI_ENGINE_PROMPT_TASK_ID: undefined,
+ });
+ });
+
+ it("returns fallbacks with empty versions when Arthur is disabled", async () => {
+ const { arthurEnabled, prompts } = await resolvePrompts({ withVersions: true });
+ expect(arthurEnabled).toBe(false);
+ expect(prompts).toHaveLength(3);
+ expect(prompts.map((p) => p.name)).toEqual(["research-plan", "implement", "review"]);
+ for (const p of prompts) {
+ expect(p.source).toBe("fallback");
+ expect(p.versions).toEqual([]);
+ expect(p.model).toBe("claude-opus-4-6");
+ }
+ expect(prompts[0].body).toBe(PROMPT_FALLBACKS["research-plan"]);
+ expect(prompts[0].phase).toBe("Research & Plan");
+ expect(mockGetPromptByTag).not.toHaveBeenCalled();
+ });
+
+ it("returns fallbacks when PROMPT_TASK_ID is missing even if key+endpoint are set", async () => {
+ await setEnv({
+ GENAI_ENGINE_API_KEY: "k",
+ GENAI_ENGINE_TRACE_ENDPOINT: "https://host/api/v1/traces",
+ GENAI_ENGINE_PROMPT_TASK_ID: undefined,
+ });
+ const { arthurEnabled, prompts } = await resolvePrompts({ withVersions: true });
+ expect(arthurEnabled).toBe(false);
+ expect(prompts[0].source).toBe("fallback");
+ expect(mockGetPromptByTag).not.toHaveBeenCalled();
+ });
+
+ it("resolves Arthur bodies + version history when enabled, attaching the production body", async () => {
+ await setEnv({
+ GENAI_ENGINE_API_KEY: "k",
+ GENAI_ENGINE_TRACE_ENDPOINT: "https://host/api/v1/traces",
+ GENAI_ENGINE_PROMPT_TASK_ID: "00000000-0000-0000-0000-000000000000",
+ });
+ mockGetPromptByTag.mockResolvedValue("arthur body");
+ mockListPromptVersions.mockResolvedValue([
+ arthurVersion(2, ["production"]),
+ arthurVersion(1, []),
+ ]);
+
+ const { arthurEnabled, prompts } = await resolvePrompts({ withVersions: true });
+ expect(arthurEnabled).toBe(true);
+ expect(mockGetPromptByTag).toHaveBeenCalledTimes(3);
+ const research = prompts[0];
+ expect(research.source).toBe("arthur");
+ expect(research.body).toBe("arthur body");
+ expect(research.versions).toHaveLength(2);
+ expect(research.versions[0]).toMatchObject({
+ version: 2,
+ createdAt: "2026-06-02T00:00:00.000Z",
+ tags: ["production"],
+ modelProvider: "anthropic",
+ modelName: "claude-opus-4-6",
+ numMessages: 1,
+ numTools: 0,
+ });
+ // production version carries the eager body; the other does not
+ expect(research.versions[0].body).toBe("arthur body");
+ expect(research.versions[1].body).toBeUndefined();
+ });
+
+ it("falls back per-prompt when the production body is missing but keeps versions", async () => {
+ await setEnv({
+ GENAI_ENGINE_API_KEY: "k",
+ GENAI_ENGINE_TRACE_ENDPOINT: "https://host/api/v1/traces",
+ GENAI_ENGINE_PROMPT_TASK_ID: "00000000-0000-0000-0000-000000000000",
+ });
+ mockGetPromptByTag.mockResolvedValue(null);
+ mockListPromptVersions.mockResolvedValue([arthurVersion(1, [])]);
+
+ const { prompts } = await resolvePrompts({ withVersions: true });
+ expect(prompts[0].source).toBe("fallback");
+ expect(prompts[0].body).toBe(PROMPT_FALLBACKS["research-plan"]);
+ expect(prompts[0].versions).toHaveLength(1);
+ });
+
+ it("degrades a prompt to fallback with empty versions when the body fetch throws", async () => {
+ await setEnv({
+ GENAI_ENGINE_API_KEY: "k",
+ GENAI_ENGINE_TRACE_ENDPOINT: "https://host/api/v1/traces",
+ GENAI_ENGINE_PROMPT_TASK_ID: "00000000-0000-0000-0000-000000000000",
+ });
+ mockGetPromptByTag.mockRejectedValue(new Error("boom"));
+ mockListPromptVersions.mockResolvedValue([]);
+
+ const { prompts } = await resolvePrompts({ withVersions: true });
+ expect(prompts[0].source).toBe("fallback");
+ expect(prompts[0].body).toBe(PROMPT_FALLBACKS["research-plan"]);
+ expect(prompts[0].versions).toEqual([]);
+ });
+
+ it("skips the version fan-out and resolves empty versions when withVersions is false", async () => {
+ await setEnv({
+ GENAI_ENGINE_API_KEY: "k",
+ GENAI_ENGINE_TRACE_ENDPOINT: "https://host/api/v1/traces",
+ GENAI_ENGINE_PROMPT_TASK_ID: "00000000-0000-0000-0000-000000000000",
+ });
+ mockGetPromptByTag.mockResolvedValue("arthur body");
+
+ const { prompts } = await resolvePrompts({ withVersions: false });
+ expect(mockGetPromptByTag).toHaveBeenCalledTimes(3);
+ expect(mockListPromptVersions).not.toHaveBeenCalled();
+ expect(prompts[0].source).toBe("arthur");
+ expect(prompts[0].body).toBe("arthur body");
+ expect(prompts[0].versions).toEqual([]);
+ });
+
+ it("uses the codex model when AGENT_KIND=codex", async () => {
+ await setEnv({ AGENT_KIND: "codex" });
+ const { prompts } = await resolvePrompts({ withVersions: true });
+ expect(prompts[0].model).toBe("gpt-5-codex");
+ });
+});
diff --git a/apps/worker/src/lib/overview/collect-prompts.ts b/apps/worker/src/lib/overview/collect-prompts.ts
new file mode 100644
index 0000000..b36ee40
--- /dev/null
+++ b/apps/worker/src/lib/overview/collect-prompts.ts
@@ -0,0 +1,113 @@
+import type { PromptVersion } from "@shared/contracts";
+import { env } from "../../../env.js";
+import { logger } from "../logger.js";
+import { PROMPT_FALLBACKS, PROMPT_NAMES, type PromptName } from "../prompts.js";
+
+const PHASE_LABEL: Record = {
+ "research-plan": "Research & Plan",
+ "implement": "Implement",
+ "review": "Review",
+};
+
+export interface ResolvedPrompt {
+ name: PromptName;
+ phase: string;
+ body: string;
+ source: "arthur" | "fallback";
+ model: string;
+ versions: PromptVersion[];
+}
+
+export interface ResolvePromptsResult {
+ arthurEnabled: boolean;
+ prompts: ResolvedPrompt[];
+}
+
+/**
+ * Resolve each workflow phase prompt to its production body + (optionally) real
+ * Arthur version history. Shared by the durable `loadPrompts()` step and the
+ * `GET /api/v1/prompts` route so the two never drift.
+ *
+ * Version history is a dashboard-only concern, so `withVersions` lets the
+ * durable step skip the per-prompt `listPromptVersions` fan-out it would
+ * otherwise discard. When false, `versions` resolves to `[]` and only the
+ * production body is fetched.
+ *
+ * When Arthur is unconfigured (`GENAI_ENGINE_*`, incl. `GENAI_ENGINE_PROMPT_TASK_ID`,
+ * unset) every prompt resolves to its in-code `PROMPT_FALLBACKS` string with
+ * `source: "fallback"` and an empty version history.
+ */
+export async function resolvePrompts(opts: { withVersions: boolean }): Promise {
+ const { withVersions } = opts;
+ const model = env.AGENT_KIND === "codex" ? env.CODEX_MODEL : env.CLAUDE_MODEL;
+ const arthurEnabled =
+ !!env.GENAI_ENGINE_API_KEY &&
+ !!env.GENAI_ENGINE_TRACE_ENDPOINT &&
+ !!env.GENAI_ENGINE_PROMPT_TASK_ID;
+
+ const base = (
+ name: PromptName,
+ body: string,
+ source: "arthur" | "fallback",
+ versions: PromptVersion[] = [],
+ ): ResolvedPrompt => ({ name, phase: PHASE_LABEL[name], body, source, model, versions });
+
+ if (!arthurEnabled) {
+ logger.info({ source: "fallback", reason: "arthur_prompts_disabled" }, "prompts_resolved");
+ return {
+ arthurEnabled,
+ prompts: PROMPT_NAMES.map((n) => base(n, PROMPT_FALLBACKS[n], "fallback")),
+ };
+ }
+
+ const { ArthurClient } = await import("../../sandbox/arthur-client.js");
+ const client = ArthurClient.fromTraceEndpoint(
+ env.GENAI_ENGINE_TRACE_ENDPOINT!,
+ env.GENAI_ENGINE_API_KEY!,
+ );
+ const taskId = env.GENAI_ENGINE_PROMPT_TASK_ID!;
+ const TAG = "production";
+
+ async function one(name: PromptName): Promise {
+ try {
+ // TODO(arthur-verify): version-list pagination depth — first page only.
+ let body: string | null;
+ let versions: PromptVersion[] = [];
+ if (withVersions) {
+ const [rawBody, rawVersions] = await Promise.all([
+ client.getPromptByTag(taskId, name, TAG),
+ client.listPromptVersions(taskId, name).catch(() => []),
+ ]);
+ body = rawBody;
+ versions = rawVersions.map((v) => ({
+ version: v.version,
+ createdAt: v.created_at,
+ tags: v.tags,
+ modelProvider: v.model_provider,
+ modelName: v.model_name,
+ numMessages: v.num_messages,
+ numTools: v.num_tools,
+ }));
+ // Attach the eager production body to its matching version entry; other
+ // version bodies are fetched on demand via the by-version route.
+ const prodVersion = versions.find((v) => v.tags.includes(TAG));
+ if (prodVersion && body !== null) prodVersion.body = body;
+ } else {
+ body = await client.getPromptByTag(taskId, name, TAG);
+ }
+
+ if (body === null) {
+ logger.info({ name, source: "fallback", reason: "arthur_prompt_missing" }, "prompts_resolved");
+ return base(name, PROMPT_FALLBACKS[name], "fallback", versions);
+ }
+ logger.info({ name, source: "arthur", versions: versions.length }, "prompts_resolved");
+ return base(name, body, "arthur", versions);
+ } catch (err) {
+ logger.warn({ name, source: "fallback", err: (err as Error).message }, "prompts_resolved");
+ return base(name, PROMPT_FALLBACKS[name], "fallback");
+ }
+ }
+
+ const prompts = await Promise.all(PROMPT_NAMES.map(one));
+ return { arthurEnabled, prompts };
+}
diff --git a/apps/worker/src/routes/api/v1/cost.get.ts b/apps/worker/src/routes/api/v1/cost.get.ts
new file mode 100644
index 0000000..6c51680
--- /dev/null
+++ b/apps/worker/src/routes/api/v1/cost.get.ts
@@ -0,0 +1,43 @@
+import { defineEventHandler, setResponseHeader } from "h3";
+import type { CostResponse } from "@shared/contracts";
+import { env } from "../../../../env.js";
+import { ArthurClient } from "../../../sandbox/arthur-client.js";
+import { collectCost } from "../../../lib/overview/collect-cost.js";
+import { logger } from "../../../lib/logger.js";
+
+const EMPTY: Omit = {
+ window: { start: "", end: "" },
+ totals: { totalTokenCost: 0, totalTokens: 0, traceCount: 0, costPerRun: 0 },
+ byModel: [],
+ byWorkflow: [],
+ daily: [],
+};
+
+export default defineEventHandler(async (event): Promise => {
+ setResponseHeader(
+ event,
+ "Cache-Control",
+ "private, max-age=15, stale-while-revalidate=60",
+ );
+
+ const generatedAt = new Date().toISOString();
+
+ // Arthur unconfigured — degrade to the documented empty state (no crash).
+ if (!env.GENAI_ENGINE_API_KEY || !env.GENAI_ENGINE_TRACE_ENDPOINT) {
+ return { generatedAt, available: false, ...EMPTY, window: { start: generatedAt, end: generatedAt } };
+ }
+
+ try {
+ const client = ArthurClient.fromTraceEndpoint(
+ env.GENAI_ENGINE_TRACE_ENDPOINT,
+ env.GENAI_ENGINE_API_KEY,
+ );
+ // TODO(arthur-verify): bucket_size value ("day") is unconfirmed against a live instance.
+ const data = await collectCost(client, { now: new Date(), bucketSize: "day" });
+ return { generatedAt, available: true, ...data };
+ } catch (err) {
+ // Arthur unreachable / 401 / unexpected shape — degrade like runs.get.ts.
+ logger.warn({ err: (err as Error).message }, "cost_collect_failed");
+ return { generatedAt, available: false, ...EMPTY, window: { start: generatedAt, end: generatedAt } };
+ }
+});
diff --git a/apps/worker/src/routes/api/v1/evals.get.ts b/apps/worker/src/routes/api/v1/evals.get.ts
new file mode 100644
index 0000000..54300d5
--- /dev/null
+++ b/apps/worker/src/routes/api/v1/evals.get.ts
@@ -0,0 +1,68 @@
+import { defineEventHandler, setResponseHeader } from "h3";
+import type { EvalsResponse } from "@shared/contracts";
+import { env } from "../../../../env.js";
+import { ArthurClient } from "../../../sandbox/arthur-client.js";
+import { collectEvals } from "../../../lib/overview/collect-evals.js";
+import { logger } from "../../../lib/logger.js";
+
+const WINDOW_HOURS = 24;
+
+export default defineEventHandler(async (event): Promise => {
+ setResponseHeader(
+ event,
+ "Cache-Control",
+ "private, max-age=15, stale-while-revalidate=60",
+ );
+
+ const generatedAt = new Date().toISOString();
+
+ if (!env.GENAI_ENGINE_API_KEY || !env.GENAI_ENGINE_TRACE_ENDPOINT) {
+ return {
+ available: false,
+ generatedAt,
+ reason: "Arthur GenAI Engine not configured.",
+ };
+ }
+
+ try {
+ const client = ArthurClient.fromTraceEndpoint(
+ env.GENAI_ENGINE_TRACE_ENDPOINT,
+ env.GENAI_ENGINE_API_KEY,
+ );
+ // TODO(arthur-verify): pass [] if empty task_ids === all org tasks on
+ // POST /api/v1/traces/overview; otherwise enumerate via /api/v2/tasks/search.
+ const taskIds: string[] = [];
+
+ const { windowHours, score, spansGraded, traceCount } =
+ await collectEvals({
+ client,
+ taskIds,
+ windowHours: WINDOW_HOURS,
+ now: new Date(),
+ });
+
+ if (spansGraded === 0) {
+ return {
+ available: false,
+ generatedAt,
+ reason: "No graded evals in the last 24h.",
+ };
+ }
+
+ return {
+ available: true,
+ generatedAt,
+ windowHours,
+ score,
+ spansGraded,
+ traceCount,
+ };
+ } catch (err) {
+ logger.warn({ err: (err as Error).message }, "evals_list_failed");
+ return {
+ available: false,
+ generatedAt,
+ reason: "Eval grading not wired up yet.",
+ };
+ }
+});
diff --git a/apps/worker/src/routes/api/v1/prompts.get.ts b/apps/worker/src/routes/api/v1/prompts.get.ts
new file mode 100644
index 0000000..d0686d4
--- /dev/null
+++ b/apps/worker/src/routes/api/v1/prompts.get.ts
@@ -0,0 +1,29 @@
+import { defineEventHandler, setResponseHeader } from "h3";
+import type { PromptsResponse } from "@shared/contracts";
+import { resolvePrompts } from "../../../lib/overview/collect-prompts.js";
+import { logger } from "../../../lib/logger.js";
+
+export default defineEventHandler(async (event): Promise => {
+ setResponseHeader(
+ event,
+ "Cache-Control",
+ "private, max-age=15, stale-while-revalidate=60",
+ );
+
+ const generatedAt = new Date().toISOString();
+ try {
+ const { arthurEnabled, prompts } = await resolvePrompts({ withVersions: true });
+ return {
+ generatedAt,
+ available: true,
+ arthurEnabled,
+ rows: prompts,
+ total: prompts.length,
+ };
+ } catch (err) {
+ // Arthur unreachable / unexpected failure — degrade to the documented empty
+ // state so the dashboard renders its N/A view instead of a 500.
+ logger.warn({ err: (err as Error).message }, "prompts_resolve_failed");
+ return { generatedAt, available: false, arthurEnabled: false, rows: [], total: 0 };
+ }
+});
diff --git a/apps/worker/src/routes/api/v1/prompts/[name]/versions/[version].get.ts b/apps/worker/src/routes/api/v1/prompts/[name]/versions/[version].get.ts
new file mode 100644
index 0000000..c30fffd
--- /dev/null
+++ b/apps/worker/src/routes/api/v1/prompts/[name]/versions/[version].get.ts
@@ -0,0 +1,44 @@
+import { defineEventHandler, getRouterParam, setResponseHeader } from "h3";
+import type { PromptVersionBodyResponse } from "@shared/contracts";
+import { env } from "../../../../../../../env.js";
+import { PROMPT_NAMES, type PromptName } from "../../../../../../lib/prompts.js";
+import { logger } from "../../../../../../lib/logger.js";
+
+// TODO(arthur-verify): lazy-vs-eager body — historical bodies are fetched on
+// demand here; the production body ships eagerly on the list route.
+export default defineEventHandler(async (event): Promise => {
+ setResponseHeader(
+ event,
+ "Cache-Control",
+ "private, max-age=15, stale-while-revalidate=60",
+ );
+ const generatedAt = new Date().toISOString();
+
+ const name = getRouterParam(event, "name") ?? "";
+ const version = getRouterParam(event, "version") ?? "";
+ const arthurEnabled =
+ !!env.GENAI_ENGINE_API_KEY &&
+ !!env.GENAI_ENGINE_TRACE_ENDPOINT &&
+ !!env.GENAI_ENGINE_PROMPT_TASK_ID;
+
+ if (!arthurEnabled || !PROMPT_NAMES.includes(name as PromptName) || !version) {
+ return { generatedAt, available: false, body: null };
+ }
+
+ try {
+ const { ArthurClient } = await import("../../../../../../sandbox/arthur-client.js");
+ const client = ArthurClient.fromTraceEndpoint(
+ env.GENAI_ENGINE_TRACE_ENDPOINT!,
+ env.GENAI_ENGINE_API_KEY!,
+ );
+ const body = await client.getPromptVersionBody(
+ env.GENAI_ENGINE_PROMPT_TASK_ID!,
+ name,
+ version,
+ );
+ return { generatedAt, available: body !== null, body };
+ } catch (err) {
+ logger.warn({ name, version, err: (err as Error).message }, "prompt_version_body_failed");
+ return { generatedAt, available: false, body: null };
+ }
+});
diff --git a/apps/worker/src/sandbox/arthur-client.test.ts b/apps/worker/src/sandbox/arthur-client.test.ts
index a5e4a80..bccd57b 100644
--- a/apps/worker/src/sandbox/arthur-client.test.ts
+++ b/apps/worker/src/sandbox/arthur-client.test.ts
@@ -239,4 +239,197 @@ describe("ArthurClient", () => {
await expect(client.getPromptByTag("t", "x", "production")).rejects.toThrow(/500/);
});
});
+
+ describe("getTracesOverview", () => {
+ it("POSTs task_ids/start/end and returns the parsed list response", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ count: 1,
+ overviews: [
+ {
+ task_id: "AWT-42",
+ trace_count: 3,
+ trace_token_count: 1200,
+ trace_token_cost: 0.42,
+ eval_count: 6,
+ continuous_eval_success_rate: 0.9,
+ last_active: "2026-06-08T00:00:00Z",
+ },
+ ],
+ }));
+ const client = new ArthurClient("http://host", "secret");
+ const res = await client.getTracesOverview(["AWT-42"], "2026-06-01T00:00:00Z", "2026-06-08T00:00:00Z");
+
+ expect(res.count).toBe(1);
+ expect(res.overviews[0].task_id).toBe("AWT-42");
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/traces/overview");
+ expect(init.method).toBe("POST");
+ expect(init.headers.Authorization).toBe("Bearer secret");
+ expect(JSON.parse(init.body)).toEqual({
+ task_ids: ["AWT-42"],
+ start_time: "2026-06-01T00:00:00Z",
+ end_time: "2026-06-08T00:00:00Z",
+ });
+ });
+ });
+
+ describe("getTracesTimeseries", () => {
+ it("POSTs single task_id + bucket_size and unwraps the { points } envelope", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ points: [
+ { timestamp: "2026-06-07T00:00:00Z", trace_count: 1, trace_token_count: 400, trace_token_cost: 0.1 },
+ ],
+ }));
+ const client = new ArthurClient("http://host", "k");
+ const points = await client.getTracesTimeseries("AWT-42", "s", "e", "day");
+
+ expect(points).toHaveLength(1);
+ expect(points[0].trace_token_cost).toBe(0.1);
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/traces/overview/timeseries");
+ expect(init.method).toBe("POST");
+ expect(JSON.parse(init.body)).toEqual({
+ task_id: "AWT-42",
+ start_time: "s",
+ end_time: "e",
+ bucket_size: "day",
+ });
+ });
+
+ it("accepts a bare array response", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse([
+ { timestamp: "t", trace_count: 2, trace_token_count: 10, trace_token_cost: null },
+ ]));
+ const client = new ArthurClient("http://host", "k");
+ const points = await client.getTracesTimeseries("AWT-42", "s", "e", "day");
+ expect(points).toHaveLength(1);
+ });
+ });
+
+ describe("aggregateSpanTokensByModel", () => {
+ it("sums tokens/cost grouped by model_name and skips null models", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ spans: [
+ { model_name: "claude-opus-4-6", total_token_count: 100, total_token_cost: 0.5 },
+ { model_name: "claude-opus-4-6", total_token_count: 50, total_token_cost: 0.25 },
+ { model_name: "gpt-5", total_token_count: 200, total_token_cost: 1.0 },
+ { model_name: null, total_token_count: 999, total_token_cost: 9.0 },
+ ],
+ }));
+ const client = new ArthurClient("http://host", "k");
+ const rows = await client.aggregateSpanTokensByModel(["AWT-42"], "s", "e");
+
+ expect(rows).toEqual([
+ { model: "claude-opus-4-6", tokens: 150, cost: 0.75 },
+ { model: "gpt-5", tokens: 200, cost: 1.0 },
+ ]);
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/traces/spans");
+ expect(JSON.parse(init.body)).toEqual({
+ task_ids: ["AWT-42"],
+ start_time: "s",
+ end_time: "e",
+ limit: 1000,
+ });
+ });
+
+ it("treats null token/cost as 0", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse([
+ { model_name: "m", total_token_count: null, total_token_cost: null },
+ ]));
+ const client = new ArthurClient("http://host", "k");
+ const rows = await client.aggregateSpanTokensByModel([], "s", "e");
+ expect(rows).toEqual([{ model: "m", tokens: 0, cost: 0 }]);
+ });
+ });
+
+ describe("listPromptVersions", () => {
+ it("GETs the versions endpoint and sorts newest-first", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ count: 2,
+ versions: [
+ {
+ version: 1,
+ created_at: "2026-06-01T00:00:00Z",
+ deleted_at: null,
+ model_provider: "anthropic",
+ model_name: "claude-opus-4-6",
+ tags: [],
+ num_messages: 1,
+ num_tools: 0,
+ },
+ {
+ version: 2,
+ created_at: "2026-06-02T00:00:00Z",
+ deleted_at: null,
+ model_provider: "anthropic",
+ model_name: "claude-opus-4-6",
+ tags: ["production"],
+ num_messages: 1,
+ num_tools: 0,
+ },
+ ],
+ }));
+ const client = new ArthurClient("http://host", "k");
+ const versions = await client.listPromptVersions("task-uuid", "research-plan");
+
+ expect(versions.map((v) => v.version)).toEqual([2, 1]);
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/tasks/task-uuid/prompts/research-plan/versions");
+ expect(init.method).toBe("GET");
+ expect(init.headers.Authorization).toBe("Bearer k");
+ });
+
+ it("returns [] on 404", async () => {
+ mockFetch.mockResolvedValueOnce(new Response("not found", { status: 404 }));
+ const client = new ArthurClient("http://host", "k");
+ expect(await client.listPromptVersions("t", "research-plan")).toEqual([]);
+ });
+
+ it("throws on 5xx", async () => {
+ mockFetch.mockResolvedValueOnce(new Response("boom", { status: 500 }));
+ const client = new ArthurClient("http://host", "k");
+ await expect(client.listPromptVersions("t", "x")).rejects.toThrow(/500/);
+ });
+ });
+
+ describe("getPromptVersionBody", () => {
+ it("GETs the by-version endpoint and returns messages[0].content", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ name: "research-plan",
+ version: 3,
+ messages: [{ role: "user", content: "v3 body" }],
+ }));
+ const client = new ArthurClient("http://host", "k");
+ const body = await client.getPromptVersionBody("task-uuid", "research-plan", 3);
+ expect(body).toBe("v3 body");
+ const [url, init] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/tasks/task-uuid/prompts/research-plan/versions/3");
+ expect(init.method).toBe("GET");
+ });
+
+ it("accepts a string version specifier (latest/tag/datetime)", async () => {
+ mockFetch.mockResolvedValueOnce(jsonResponse({
+ name: "implement",
+ messages: [{ role: "user", content: "latest body" }],
+ }));
+ const client = new ArthurClient("http://host", "k");
+ const body = await client.getPromptVersionBody("t", "implement", "latest");
+ expect(body).toBe("latest body");
+ const [url] = mockFetch.mock.calls[0];
+ expect(url).toBe("http://host/api/v1/tasks/t/prompts/implement/versions/latest");
+ });
+
+ it("returns null on 404", async () => {
+ mockFetch.mockResolvedValueOnce(new Response("not found", { status: 404 }));
+ const client = new ArthurClient("http://host", "k");
+ expect(await client.getPromptVersionBody("t", "x", 1)).toBeNull();
+ });
+
+ it("throws on 5xx", async () => {
+ mockFetch.mockResolvedValueOnce(new Response("boom", { status: 500 }));
+ const client = new ArthurClient("http://host", "k");
+ await expect(client.getPromptVersionBody("t", "x", 1)).rejects.toThrow(/500/);
+ });
+ });
});
diff --git a/apps/worker/src/sandbox/arthur-client.ts b/apps/worker/src/sandbox/arthur-client.ts
index 8afc77c..66d8b8f 100644
--- a/apps/worker/src/sandbox/arthur-client.ts
+++ b/apps/worker/src/sandbox/arthur-client.ts
@@ -23,6 +23,68 @@ interface SearchResponse {
tasks: ArthurTask[];
}
+/**
+ * Per-task aggregate over a window from `POST /api/v1/traces/overview`.
+ * Token/cost fields come from Arthur's `TokenCountCostSchema`; `trace_token_cost`
+ * may be null when cost is unavailable. Typed per the documented shape — these
+ * read endpoints are UNVERIFIED against a live instance, so parsing stays
+ * defensive (callers treat null cost as 0).
+ */
+export interface TraceOverview {
+ task_id: string;
+ trace_count: number;
+ trace_token_count: number;
+ trace_token_cost: number | null;
+ eval_count: number;
+ continuous_eval_success_rate: number;
+ last_active?: string;
+}
+
+export interface TraceOverviewListResponse {
+ count: number;
+ overviews: TraceOverview[];
+}
+
+/** One bucket from `POST /api/v1/traces/overview/timeseries` (single task). */
+export interface TraceTimeseriesPoint {
+ timestamp: string;
+ trace_count: number;
+ trace_token_count: number;
+ trace_token_cost: number | null;
+ continuous_eval_success_rate?: number;
+}
+
+/** Token/cost-by-model aggregation result (one row per Arthur `model_name`). */
+export interface ModelTokenCost {
+ model: string;
+ tokens: number;
+ cost: number;
+}
+
+/** A span row from `GET /api/v1/traces/spans` carrying model + token/cost fields. */
+interface SpanTokenCost {
+ model_name: string | null;
+ total_token_count: number | null;
+ total_token_cost: number | null;
+}
+
+/** One Arthur prompt version's metadata (no message body). */
+export interface ArthurPromptVersion {
+ version: number;
+ created_at: string;
+ deleted_at: string | null;
+ model_provider: string;
+ model_name: string;
+ tags: string[];
+ num_messages: number;
+ num_tools: number;
+}
+
+interface AgenticPromptVersionListResponse {
+ count: number;
+ versions: ArthurPromptVersion[];
+}
+
export class ArthurClient {
constructor(
private readonly baseUrl: string,
@@ -56,6 +118,20 @@ export class ArthurClient {
return (await res.json()) as T;
}
+ /** GET that treats 404 as "absent" (returns null) instead of throwing — for the prompt read paths. */
+ private async getAllowing404(path: string): Promise {
+ const res = await fetch(`${this.baseUrl}${path}`, {
+ method: "GET",
+ headers: { Authorization: `Bearer ${this.apiKey}`, "ngrok-skip-browser-warning": "true" },
+ });
+ if (res.status === 404) return null;
+ if (!res.ok) {
+ const body = await res.text().catch(() => "");
+ throw new Error(`Arthur GET ${path} → ${res.status}: ${body.slice(0, 300)}`);
+ }
+ return (await res.json()) as T;
+ }
+
/**
* Return tasks whose name equals `prefix` or matches `^prefix\.\d+$`.
* Arthur's `task_name` search is substring-based, so we post-filter to
@@ -124,21 +200,8 @@ export class ArthurClient {
/** Fetch a tagged prompt version. Returns the first message's content, or null if 404. */
async getPromptByTag(taskId: string, name: string, tag: string): Promise {
const path = `/api/v1/tasks/${encodeURIComponent(taskId)}/prompts/${encodeURIComponent(name)}/versions/tags/${encodeURIComponent(tag)}`;
- const res = await fetch(`${this.baseUrl}${path}`, {
- method: "GET",
- headers: {
- "Authorization": `Bearer ${this.apiKey}`,
- "ngrok-skip-browser-warning": "true",
- },
- });
- if (res.status === 404) return null;
- if (!res.ok) {
- const body = await res.text().catch(() => "");
- throw new Error(`Arthur GET ${path} → ${res.status}: ${body.slice(0, 300)}`);
- }
- const prompt = (await res.json()) as AgenticPrompt;
- const first = prompt.messages?.[0];
- return first?.content ?? null;
+ const prompt = await this.getAllowing404(path);
+ return prompt?.messages?.[0]?.content ?? null;
}
/** Create a new version of a named prompt on a task. Content is sent as a single user message. */
@@ -171,4 +234,110 @@ export class ArthurClient {
},
);
}
+
+ /**
+ * Fleet eval/cost aggregate over a window. One call covers multiple tasks;
+ * sum across `overviews` for fleet totals. `taskIds` may be empty (see the
+ * empty-means-all-org open question in the specs). Shared by /evals + /cost.
+ */
+ async getTracesOverview(
+ taskIds: string[],
+ startTime: string,
+ endTime: string,
+ ): Promise {
+ return this.request("/api/v1/traces/overview", {
+ method: "POST",
+ body: JSON.stringify({
+ task_ids: taskIds,
+ start_time: startTime,
+ end_time: endTime,
+ }),
+ });
+ }
+
+ /**
+ * Per-bucket timeseries for a single task. The caller fans out one call per
+ * task and merges points by timestamp. The response envelope key is
+ * unverified, so accept both a bare array and a `{ points }` wrapper.
+ */
+ async getTracesTimeseries(
+ taskId: string,
+ startTime: string,
+ endTime: string,
+ bucketSize: string,
+ ): Promise {
+ const res = await this.request<{ points?: TraceTimeseriesPoint[] } | TraceTimeseriesPoint[]>(
+ "/api/v1/traces/overview/timeseries",
+ {
+ method: "POST",
+ body: JSON.stringify({
+ task_id: taskId,
+ start_time: startTime,
+ end_time: endTime,
+ bucket_size: bucketSize,
+ }),
+ },
+ );
+ return Array.isArray(res) ? res : (res.points ?? []);
+ }
+
+ /**
+ * By-model token/cost aggregation — Arthur has no per-model overview, so we
+ * fetch span rows (which carry `model_name` + token/cost fields) and sum
+ * grouped by `model_name`. Spans with a null `model_name` are skipped.
+ */
+ async aggregateSpanTokensByModel(
+ taskIds: string[],
+ startTime: string,
+ endTime: string,
+ ): Promise {
+ // TODO(arthur-verify): pagination — first page only, bounded to N spans. The
+ // read endpoints are unverified, so we send a bounded `limit` rather than
+ // looping pages; this makes the ceiling explicit instead of pulling an
+ // unbounded result set and summing it silently in memory.
+ const res = await this.request<{ spans?: SpanTokenCost[] } | SpanTokenCost[]>(
+ "/api/v1/traces/spans",
+ {
+ method: "POST",
+ body: JSON.stringify({
+ task_ids: taskIds,
+ start_time: startTime,
+ end_time: endTime,
+ limit: 1000,
+ }),
+ },
+ );
+ const spans = Array.isArray(res) ? res : (res.spans ?? []);
+ const byModel = new Map();
+ for (const span of spans) {
+ if (!span.model_name) continue;
+ const row = byModel.get(span.model_name) ?? {
+ model: span.model_name,
+ tokens: 0,
+ cost: 0,
+ };
+ row.tokens += span.total_token_count ?? 0;
+ row.cost += span.total_token_cost ?? 0;
+ byModel.set(span.model_name, row);
+ }
+ return [...byModel.values()];
+ }
+
+ /** List version metadata for a named prompt (newest first). First page only. Empty on 404. */
+ async listPromptVersions(taskId: string, name: string): Promise {
+ const path = `/api/v1/tasks/${encodeURIComponent(taskId)}/prompts/${encodeURIComponent(name)}/versions`;
+ const data = await this.getAllowing404(path);
+ return [...(data?.versions ?? [])].sort((a, b) => b.version - a.version);
+ }
+
+ /**
+ * Fetch the body of a specific version. `version` accepts an integer,
+ * `"latest"`, an ISO datetime, or a tag. Returns the first message's content,
+ * or null on 404. Generalizes the by-version GET that `getPromptByTag` uses.
+ */
+ async getPromptVersionBody(taskId: string, name: string, version: number | string): Promise {
+ const path = `/api/v1/tasks/${encodeURIComponent(taskId)}/prompts/${encodeURIComponent(name)}/versions/${encodeURIComponent(String(version))}`;
+ const prompt = await this.getAllowing404(path);
+ return prompt?.messages?.[0]?.content ?? null;
+ }
}
diff --git a/apps/worker/src/workflows/prompts-step.test.ts b/apps/worker/src/workflows/prompts-step.test.ts
index ab09934..4350061 100644
--- a/apps/worker/src/workflows/prompts-step.test.ts
+++ b/apps/worker/src/workflows/prompts-step.test.ts
@@ -3,9 +3,13 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
vi.mock("../../env.js", () => ({ env: {} }));
const mockGetPromptByTag = vi.fn();
+const mockListPromptVersions = vi.fn();
vi.mock("../sandbox/arthur-client.js", () => ({
ArthurClient: {
- fromTraceEndpoint: vi.fn(() => ({ getPromptByTag: mockGetPromptByTag })),
+ fromTraceEndpoint: vi.fn(() => ({
+ getPromptByTag: mockGetPromptByTag,
+ listPromptVersions: mockListPromptVersions,
+ })),
},
}));
@@ -20,6 +24,8 @@ async function setEnv(partial: Record) {
describe("loadPrompts", () => {
beforeEach(async () => {
mockGetPromptByTag.mockReset();
+ mockListPromptVersions.mockReset();
+ mockListPromptVersions.mockResolvedValue([]);
await setEnv({
GENAI_ENGINE_API_KEY: undefined,
GENAI_ENGINE_TRACE_ENDPOINT: undefined,
@@ -65,6 +71,9 @@ describe("loadPrompts", () => {
expect(mockGetPromptByTag).toHaveBeenCalledTimes(3);
const names = mockGetPromptByTag.mock.calls.map((c) => c[1]);
expect(names).toEqual(["research-plan", "implement", "review"]);
+ // The step throws version metadata away, so it must not pay for the
+ // dashboard-only listPromptVersions fan-out.
+ expect(mockListPromptVersions).not.toHaveBeenCalled();
});
it("falls back per-prompt when Arthur returns null or throws", async () => {
diff --git a/apps/worker/src/workflows/prompts-step.ts b/apps/worker/src/workflows/prompts-step.ts
index 9baae40..bc4a44f 100644
--- a/apps/worker/src/workflows/prompts-step.ts
+++ b/apps/worker/src/workflows/prompts-step.ts
@@ -6,53 +6,18 @@ export interface LoadedPrompts {
export async function loadPrompts(): Promise {
"use step";
- const { env } = await import("../../env.js");
- const { logger } = await import("../lib/logger.js");
- const { PROMPT_FALLBACKS } = await import("../lib/prompts.js");
- type PromptName = keyof typeof PROMPT_FALLBACKS;
-
- const arthurEnabled =
- !!env.GENAI_ENGINE_API_KEY &&
- !!env.GENAI_ENGINE_TRACE_ENDPOINT &&
- !!env.GENAI_ENGINE_PROMPT_TASK_ID;
-
- if (!arthurEnabled) {
- logger.info({ source: "fallback", reason: "arthur_prompts_disabled" }, "prompts_loaded");
- return {
- research: PROMPT_FALLBACKS["research-plan"],
- implement: PROMPT_FALLBACKS["implement"],
- review: PROMPT_FALLBACKS["review"],
- };
- }
-
- const { ArthurClient } = await import("../sandbox/arthur-client.js");
- const client = ArthurClient.fromTraceEndpoint(
- env.GENAI_ENGINE_TRACE_ENDPOINT!,
- env.GENAI_ENGINE_API_KEY!,
- );
- const taskId = env.GENAI_ENGINE_PROMPT_TASK_ID!;
- const TAG = "production";
-
- async function one(name: PromptName): Promise {
- try {
- const body = await client.getPromptByTag(taskId, name, TAG);
- if (body === null) {
- logger.info({ name, source: "fallback", reason: "arthur_prompt_missing" }, "prompts_loaded");
- return PROMPT_FALLBACKS[name];
- }
- logger.info({ name, source: "arthur" }, "prompts_loaded");
- return body;
- } catch (err) {
- logger.warn({ name, source: "fallback", err: (err as Error).message }, "prompts_loaded");
- return PROMPT_FALLBACKS[name];
- }
- }
-
- const [research, implement, review] = await Promise.all([
- one("research-plan"),
- one("implement"),
- one("review"),
- ]);
- return { research, implement, review };
+ // Delegate to the shared resolver so the durable step and the
+ // GET /api/v1/prompts route share one source of truth. The resolver carries
+ // the same logger.info/logger.warn (fallback / arthur / per-prompt error)
+ // calls the step used to make. Version history is dashboard-only, so skip the
+ // listPromptVersions fan-out here — the step only consumes prompt bodies.
+ const { resolvePrompts } = await import("../lib/overview/collect-prompts.js");
+ const { prompts } = await resolvePrompts({ withVersions: false });
+ const byName = Object.fromEntries(prompts.map((p) => [p.name, p.body]));
+ return {
+ research: byName["research-plan"],
+ implement: byName["implement"],
+ review: byName["review"],
+ };
}
loadPrompts.maxRetries = 0;
diff --git a/docs/superpowers/plans/2026-06-08-cost-real-data.md b/docs/superpowers/plans/2026-06-08-cost-real-data.md
new file mode 100644
index 0000000..091c029
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-08-cost-real-data.md
@@ -0,0 +1,329 @@
+# `/cost` Real-Data Conversion Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Convert the `/cost` (Cost & Usage) dashboard page from mock data to live worker data, mirroring the overview/runs server-component fetch pattern. Cost + token usage come from **Arthur** (the GenAI Engine), which already aggregates token/cost from the OpenInference traces the workflow ships in. **Single PR** — no persistence, no capture.
+
+**Architecture:** New Arthur read methods (`getTracesOverview`, `getTracesTimeseries`, `aggregateSpanTokensByModel`) on the existing `ArthurClient`. A worker collector `collect-cost.ts` calls them and shapes a `CostResponse` (totals, by-task breakdown, by-model breakdown, merged daily series). A new route `GET /api/v1/cost` exposes it, degrading to empty when Arthur is unconfigured/unreachable. The dashboard fetches it server-side via `getJSON`, falls back to an empty `CostResponse`, and passes `data` to the `CostScreen` client presenter. Thin `page.tsx` wraps `cost-data.tsx` in ``. Identical read-path shape to `overview-data.tsx` / `runs-data.tsx`.
+
+**Tech Stack:** Next.js App Router, React, TypeScript, `@shared/contracts`, h3 worker routes, existing `ArthurClient` (fetch + Bearer). Worker has Vitest (`*.test.ts`); dashboard has none — dashboard verification is `npx tsc --noEmit`, `next lint`, and a manual browser check.
+
+**Spec:** `docs/superpowers/specs/2026-06-08-cost-real-data-design.md`
+
+**Note on commits:** This repo's owner stages commits manually. Do NOT commit unless the user explicitly asks. The final task lists the commit command for when they do.
+
+**Live open questions (resolve with the user; the plan assumes the spec's defaults):** `bucket_size` allowed values for the timeseries; whether empty `task_ids` means org-wide (else enumerate tasks); by-model client aggregation acceptable; task→workflow mapping (breakdown stays per-task); window = calendar MTD. See the spec's "Open questions".
+
+---
+
+### Task 1: Add Arthur read methods + types
+
+**Files:**
+- Modify: `apps/worker/src/sandbox/arthur-client.ts`
+- Modify: `apps/worker/src/sandbox/arthur-client.test.ts`
+
+- [ ] **Step 1: Add response types**
+
+Add interfaces mirroring Arthur's shapes:
+
+```ts
+export interface TraceOverviewEntry {
+ task_id: string;
+ trace_count: number;
+ trace_token_count: number;
+ trace_token_cost: number | null;
+ last_active?: string;
+}
+export interface TraceTimeseriesPoint {
+ timestamp: string;
+ trace_count: number;
+ trace_token_count: number;
+ trace_token_cost: number | null;
+}
+export interface SpanTokenCost {
+ model_name: string | null;
+ total_token_count: number | null;
+ total_token_cost: number | null;
+}
+```
+
+- [ ] **Step 2: Add `getTracesOverview`**
+
+```ts
+async getTracesOverview(taskIds: string[], startTime: string, endTime: string): Promise {
+ const { overviews } = await this.request<{ count: number; overviews: TraceOverviewEntry[] }>(
+ "/api/v1/traces/overview",
+ { method: "POST", body: JSON.stringify({ task_ids: taskIds, start_time: startTime, end_time: endTime }) },
+ );
+ return overviews;
+}
+```
+
+- [ ] **Step 3: Add `getTracesTimeseries`** (single task per call; caller fans out + merges)
+
+```ts
+async getTracesTimeseries(taskId: string, startTime: string, endTime: string, bucketSize: string): Promise {
+ const res = await this.request<{ points?: TraceTimeseriesPoint[] } | TraceTimeseriesPoint[]>(
+ "/api/v1/traces/overview/timeseries",
+ { method: "POST", body: JSON.stringify({ task_id: taskId, start_time: startTime, end_time: endTime, bucket_size: bucketSize }) },
+ );
+ return Array.isArray(res) ? res : (res.points ?? []);
+}
+```
+
+> The response envelope key is unconfirmed — handle both array and `{ points }`. Confirm against a live call.
+
+- [ ] **Step 4: Add `aggregateSpanTokensByModel`** (the one client-side aggregation)
+
+Fetch span rows for the window via `GET /api/v1/traces/spans` (paginate if the API requires it), then sum `total_token_count`/`total_token_cost` grouped by `model_name`. Return `Array<{ model: string; tokens: number; cost: number }>`. Skip rows with null `model_name`.
+
+- [ ] **Step 5: Test**
+
+Run: `cd apps/worker && pnpm vitest run src/sandbox/arthur-client.test.ts`
+Expected: add tests with a stubbed `fetch` asserting each method posts the right body and parses the response (mirror the existing client tests). PASS.
+
+---
+
+### Task 2: Add the `CostResponse` contract
+
+**Files:**
+- Modify: `apps/shared/contracts/api.ts`
+
+- [ ] **Step 1: Add the interfaces**
+
+Add `CostByModelEntry`, `CostByWorkflowEntry`, and `CostResponse` exactly as specified in the spec ("Proposed contract").
+
+- [ ] **Step 2: Typecheck shared**
+
+Run: `cd apps/shared && npx tsc --noEmit` (or root `pnpm -w typecheck` if defined)
+Expected: PASS.
+
+---
+
+### Task 3: Add the `collectCost` aggregator + worker route
+
+**Files:**
+- Create: `apps/worker/src/lib/overview/collect-cost.ts`
+- Create: `apps/worker/src/lib/overview/collect-cost.test.ts`
+- Create: `apps/worker/src/routes/api/v1/cost.get.ts`
+
+- [ ] **Step 1: Write `collectCost`**
+
+Signature: `collectCost(client: ArthurClient, opts: { now: Date; bucketSize: string }): Promise>`.
+
+Logic:
+1. Resolve the window: `start = startOfMonth(now)`, `end = now` (ISO). (Assumption: calendar MTD — see open Q5.)
+2. Resolve `taskIds`: enumerate the org's tasks (assumption from open Q2 — pass ids explicitly). Reuse/extend the client's task listing (`/api/v2/tasks/search`); if a true org-wide overview via empty `task_ids` is confirmed, pass `[]` instead.
+3. `overviews = await client.getTracesOverview(taskIds, start, end)`.
+ - `totals`: sum `trace_token_cost` (→ `totalTokenCost`), `trace_token_count` (→ `totalTokens`), `trace_count` (→ `traceCount`); `costPerRun = totalTokenCost / max(1, traceCount)`. Treat null `trace_token_cost` as 0.
+ - `byWorkflow`: one entry per overview → `{ taskId, name, runs, tokens, cost, costPerRun }`. `name` from the task listing (task name = ticket-run id).
+4. `byModel = await client.aggregateSpanTokensByModel(...)` → map to `{ model, cost, tokens }`.
+5. `daily`: fan out `getTracesTimeseries(taskId, start, end, bucketSize)` per task; **merge points by `timestamp`** summing cost/tokens; sort oldest→newest → `{ date, cost, tokens }[]`.
+
+Keep I/O behind the injected `client` so the aggregation is unit-testable with a fake client (mirror how `collect-runs.ts` takes a `RunsLister`).
+
+- [ ] **Step 2: Write the route**
+
+Mirror `workflows.get.ts`:
+```ts
+setResponseHeader(event, "Cache-Control", "private, max-age=15, stale-while-revalidate=60");
+const generatedAt = new Date().toISOString();
+if (!env.GENAI_ENGINE_API_KEY || !env.GENAI_ENGINE_TRACE_ENDPOINT) {
+ return { generatedAt, available: false, ...EMPTY };
+}
+try {
+ const client = ArthurClient.fromTraceEndpoint(env.GENAI_ENGINE_TRACE_ENDPOINT, env.GENAI_ENGINE_API_KEY);
+ const data = await collectCost(client, { now: new Date(), bucketSize: "day" });
+ return { generatedAt, available: true, ...data };
+} catch (err) {
+ logger.warn({ err: (err as Error).message }, "cost_collect_failed");
+ return { generatedAt, available: false, ...EMPTY };
+}
+```
+`EMPTY` = the empty totals/arrays/window matching `costFallback`.
+
+- [ ] **Step 3: Test the aggregator**
+
+Run: `cd apps/worker && pnpm vitest run src/lib/overview/collect-cost.test.ts`
+Expected: with a fake client returning fixtures (2 tasks, 2 models, multi-day timeseries), assert totals, `byWorkflow` rows + `costPerRun`, `byModel` grouping, and merged-by-timestamp `daily`. Empty/null inputs → zeros/empty arrays. PASS.
+
+- [ ] **Step 4: Worker typecheck**
+
+Run: `cd apps/worker && npx tsc --noEmit`
+Expected: PASS.
+
+---
+
+### Task 4: Add the dashboard fallback
+
+**Files:**
+- Modify: `apps/dashboard/lib/api/fallbacks.ts`
+
+- [ ] **Step 1: Add `costFallback`**
+
+```ts
+export function costFallback(now: string): CostResponse {
+ return {
+ generatedAt: now,
+ available: false,
+ window: { start: now, end: now },
+ totals: { totalTokenCost: 0, totalTokens: 0, traceCount: 0, costPerRun: 0 },
+ byModel: [],
+ byWorkflow: [],
+ daily: [],
+ };
+}
+```
+
+Add `CostResponse` to the existing `@shared/contracts` import.
+
+- [ ] **Step 2: Typecheck**
+
+Run: `cd apps/dashboard && npx tsc --noEmit`
+Expected: PASS (no consumers yet).
+
+---
+
+### Task 5: Add the skeleton + server data component, and convert `CostScreen`
+
+**Files:**
+- Create: `apps/dashboard/app/cost-skeleton.tsx`
+- Create: `apps/dashboard/app/cost-data.tsx`
+- Modify: `apps/dashboard/components/cockpit/screens/cost.tsx`
+
+- [ ] **Step 1: Create the skeleton**
+
+Mirror `overview-skeleton.tsx`, shaped to the cost layout (after embellishments are stripped: 3 KPI blocks, a chart+donut row, two table blocks):
+
+```tsx
+// apps/dashboard/app/cost-skeleton.tsx
+function Block({ className = "" }: { className?: string }) {
+ return ;
+}
+export function CostSkeleton() {
+ return (
+
+
+ {Array.from({ length: 3 }, (_, i) => )}
+
+
+
+
+
+
+
+
+
+
+
+
+ {Array.from({ length: 4 }, (_, i) => (
+
+ ))}
+
+
+
+
+
+
` markup from the old `PromptDiff` (drop the two-column diff). Default shows `prompt.body` (the production version). When the user selects a non-production version, fetch its body once via the proxy route and render it:
+ ```tsx
+ const [selectedVersion, setSelectedVersion] = useState
(null);
+ const [bodyCache, setBodyCache] = useState>({});
+ const [loading, setLoading] = useState(false);
+ // reset selection when the prompt changes
+ useEffect(() => { setSelectedVersion(null); }, [prompt?.name]);
+ async function showVersion(v: PromptVersion) {
+ setSelectedVersion(v.version);
+ if (v.body) { setBodyCache((c) => ({ ...c, [v.version]: v.body! })); return; }
+ if (bodyCache[v.version] !== undefined) return;
+ setLoading(true);
+ try {
+ const res = await fetch(`/api/prompts/${prompt!.name}/versions/${v.version}`);
+ const json = (await res.json()) as { body: string | null };
+ setBodyCache((c) => ({ ...c, [v.version]: json.body ?? "(version body unavailable)" }));
+ } finally { setLoading(false); }
+ }
+ const shownBody = selectedVersion != null ? (bodyCache[selectedVersion] ?? (loading ? "Loading…" : "")) : prompt!.body;
+ ```
+- Delete the now-unused `PromptDiff` and `PromptMetrics` functions.
+
+- [ ] **Step 5: Rewrite the top-level `PromptsScreen`**
+
+```tsx
+export function PromptsScreen({ data }: { data: PromptsResponse }) {
+ const [active, setActive] = useState(data.rows[0]?.name ?? "");
+ const selected = data.rows.find((p) => p.name === active);
+ const inProd = data.rows.filter((p) => p.versions.some((v) => v.tags.includes("production"))).length;
+ return (
+
+ {/* header — keep the title; leave the inert Import/New buttons */}
+
+
+
+ {/* A/B + avg-Δ tiles removed — no real source */}
+
+
+