@desplega.ai/agent-swarm 2.5.4 → 2.7.0

package/src/tests/ui-logs-parser.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { normalizeSessionLogs as normalizeEvalLogs } from "../../apps/evals/ui/src/logs-parser";
 import {
+  cacheHitRatio,
   extractSubagentRuns,
   normalizeSessionLogs,
   parseSessionLogs,
   type SessionLogRecord,
+  sumItemCallUsage,
   unwrapResult,
 } from "../../apps/ui/src/logs-parser";
 
@@ -1696,3 +1698,181 @@ describe.each([
     expect(item?.meta).toMatchObject({ type: "codex_error", isError: true });
   });
 });
+
+describe("per-call usage", () => {
+  const claudeUsage = {
+    input_tokens: 6,
+    cache_read_input_tokens: 90_000,
+    cache_creation_input_tokens: 684,
+    output_tokens: 120,
+  };
+  function claudeLine(
+    id: string,
+    line: number,
+    messageId: string,
+    block: unknown,
+    extra: Record<string, unknown> = {},
+  ) {
+    return log(id, "claude", line, {
+      type: "assistant",
+      message: { id: messageId, role: "assistant", content: [block], usage: claudeUsage },
+      ...extra,
+    });
+  }
+  const usages = (logs: SessionLogRecord[]) =>
+    normalizeSessionLogs(logs)
+      .items.filter((item) => item.kind === "call_usage")
+      .map((item) => item.usage);
+
+  test("claude: one call_usage per message.id, not per content-block line", () => {
+    const result = usages([
+      claudeLine("a1", 1, "msg_1", { type: "thinking", thinking: "" }),
+      claudeLine("a2", 2, "msg_1", { type: "text", text: "Looking." }),
+      claudeLine("a3", 3, "msg_1", { type: "tool_use", id: "t1", name: "Read", input: {} }),
+      claudeLine(
+        "s1",
+        4,
+        "msg_2",
+        { type: "text", text: "sub" },
+        {
+          parent_tool_use_id: "toolu_agent",
+        },
+      ),
+    ]);
+    expect(result).toHaveLength(2);
+    expect(result[0]).toMatchObject({
+      callId: "msg_1",
+      promptTokens: 90_690,
+      cacheReadTokens: 90_000,
+      cacheWriteTokens: 684,
+      uncachedInputTokens: 6,
+      outputTokens: 120,
+      sidechain: false,
+      harness: "claude",
+      reportedAt: "start",
+    });
+    expect(result[1]).toMatchObject({ callId: "msg_2", sidechain: true });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(90_000 / 90_690);
+  });
+
+  test("claude: an assistant line without usage emits no call_usage", () => {
+    const result = usages([
+      log("a1", "claude", 1, {
+        type: "assistant",
+        message: { id: "msg_1", role: "assistant", content: [{ type: "text", text: "hi" }] },
+      }),
+    ]);
+    expect(result).toEqual([]);
+  });
+
+  test("the call_usage block shares the call's message, ahead of its content", () => {
+    const messages = parseSessionLogs([
+      claudeLine("a1", 1, "msg_1", { type: "text", text: "Looking." }),
+    ]);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]?.role).toBe("assistant");
+    expect(messages[0]?.content.map((b) => b.type)).toEqual(["provider_meta", "text"]);
+    expect(messages[0]?.content[0]).toMatchObject({
+      kind: "helper",
+      data: { helperType: "call_usage" },
+    });
+  });
+
+  test("codex: context.updated input_tokens already includes cached tokens", () => {
+    const result = usages([
+      log("c1", "codex", 1, {
+        type: "context.updated",
+        usage: {
+          input_tokens: 49_300,
+          cached_input_tokens: 12_000,
+          cache_write_input_tokens: 0,
+          output_tokens: 300,
+          reasoning_output_tokens: 40,
+        },
+        contextWindow: 272_000,
+      }),
+    ]);
+    expect(result).toEqual([
+      {
+        callId: "c1",
+        promptTokens: 49_300,
+        cacheReadTokens: 12_000,
+        cacheWriteTokens: 0,
+        uncachedInputTokens: 37_300,
+        outputTokens: 300,
+        reasoningTokens: 40,
+        sidechain: false,
+        harness: "codex",
+        reportedAt: "end",
+      },
+    ]);
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(12_000 / 49_300);
+  });
+
+  test("opencode: session.step.ended input excludes cache", () => {
+    const result = usages([
+      log("o1", "opencode", 1, {
+        type: "session.step.ended",
+        data: {
+          sessionID: "ses_1",
+          tokens: { input: 200, output: 50, reasoning: 5, cache: { read: 9_000, write: 800 } },
+        },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      promptTokens: 10_000,
+      cacheReadTokens: 9_000,
+      cacheWriteTokens: 800,
+      uncachedInputTokens: 200,
+      harness: "opencode",
+      reportedAt: "end",
+    });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(0.9);
+  });
+
+  test("pi: the adapter's call_usage line", () => {
+    const result = usages([
+      log("p1", "pi", 1, {
+        type: "call_usage",
+        harness: "pi",
+        usage: { input: 100, cacheRead: 300, cacheWrite: 100, output: 20, reasoning: 0 },
+      }),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      promptTokens: 500,
+      cacheReadTokens: 300,
+      harness: "pi",
+      reportedAt: "start",
+    });
+    expect(cacheHitRatio(result[0]!)).toBeCloseTo(0.6);
+  });
+
+  test("session totals: Σ read / Σ prompt, and no-cache sessions say so", () => {
+    const totals = sumItemCallUsage(
+      normalizeSessionLogs([
+        claudeLine("a1", 1, "msg_1", { type: "text", text: "one" }),
+        claudeLine("a2", 2, "msg_2", { type: "text", text: "two" }),
+      ]).items,
+    );
+    expect(totals).toMatchObject({
+      calls: 2,
+      promptTokens: 181_380,
+      cacheReadTokens: 180_000,
+      cacheReported: true,
+    });
+    expect(totals?.ratio).toBeCloseTo(180_000 / 181_380);
+
+    const uncached = sumItemCallUsage(
+      normalizeSessionLogs([
+        log("o1", "opencode", 1, {
+          type: "session.step.ended",
+          data: { tokens: { input: 500, output: 5, reasoning: 0, cache: { read: 0, write: 0 } } },
+        }),
+      ]).items,
+    );
+    expect(uncached).toMatchObject({ calls: 1, cacheReported: false, ratio: 0 });
+    expect(sumItemCallUsage([])).toBeNull();
+  });
+});

package/src/tests/used-by-route.test.ts

@@ -183,6 +183,17 @@ describe("POST /api/used-by", () => {
     expect(proxied[1]?.body).not.toHaveProperty("quote");
   });
 
+  test("a job function the catalog does not list yet is stored but not sent", async () => {
+    const grant = await post(
+      { granted: true, contactEmail: "admin@acme.com", contactFunction: "marketing" },
+      OPERATOR,
+    );
+    expect(grant.statusCode).toBe(200);
+    expect(proxied[0]?.body).toMatchObject({ granted: true, contact_email: "admin@acme.com" });
+    expect(proxied[0]?.body).not.toHaveProperty("contact_function");
+    expect(await configValue("SWARM_USED_BY_CONTACT_FUNCTION")).toBe("marketing");
+  });
+
   test("a grant requires valid contact details and a quote of at most 280 characters", async () => {
     for (const details of [
       {},

package/src/tests/workflow-cascade-cancel.test.ts

@@ -26,6 +26,7 @@ import {
   WorkflowStepNotExecutableError,
 } from "../be/db/workflow-runs";
 import { handleApprovalRequests } from "../http/approval-requests";
+import { handleWorkflows } from "../http/workflows";
 import * as slackApp from "../slack/app";
 import type { AgentTask, Workflow, WorkflowDefinition, WorkflowRun } from "../types";
 import * as approvalNotifications from "../workflows/approval-notifications";
@@ -1167,3 +1168,174 @@ describe("run lineage guard", () => {
     ).toBe("failed");
   });
 });
+
+describe("run tree read (GET /api/workflow-runs/{id}/tree)", () => {
+  let server: ReturnType<typeof createServer>;
+  let baseUrl = "";
+
+  beforeAll(async () => {
+    server = createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const handled = await handleWorkflows(
+        req,
+        res,
+        url.pathname.split("/").filter(Boolean),
+        url.searchParams,
+        undefined,
+      );
+      if (!handled) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+      }
+    });
+    baseUrl = `http://127.0.0.1:${await listenOnFreePort(server)}`;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  type TreeBody = {
+    rootRunId: string;
+    runs: Array<WorkflowRun & Record<string, unknown>>;
+    hasOpenWork: boolean;
+    error?: string;
+  };
+
+  async function getTree(runId: string): Promise<{ status: number; body: TreeBody | null }> {
+    const response = await fetch(`${baseUrl}/api/workflow-runs/${runId}/tree`);
+    const text = await response.text();
+    return { status: response.status, body: text ? (JSON.parse(text) as TreeBody) : null };
+  }
+
+  test("lists every run of every attempt, root first, and settles after a cascade cancel", async () => {
+    const grandchild = await makeWorkflow(taskDef);
+    const child = await makeWorkflow(parentOf(grandchild.id));
+    const root = await makeWorkflow(parentOf(child.id));
+    const rootId = await startWorkflowExecution(root, {}, registry);
+    const childRun = await runOf(child.id, "waiting");
+    const grandchildRun = await runOf(grandchild.id, "waiting");
+    const [task] = await waitFor(
+      () => tasksOfRun(grandchildRun.id),
+      (tasks) => tasks.length === 1,
+    );
+
+    // A retry of the root step: the live child is attempt 1, and attempt 0's
+    // child failed after starting a grandchild of its own.
+    const [rootStep] = await getWorkflowRunStepsByRunId(rootId);
+    await getDbClient().run("UPDATE workflow_run_steps SET retryCount = 1 WHERE id = ?", [
+      rootStep!.id,
+    ]);
+    await getDbClient().run("UPDATE workflow_runs SET parentStepAttempt = 1 WHERE id = ?", [
+      childRun.id,
+    ]);
+    const oldChild = await linkedRun({
+      workflowId: child.id,
+      status: "failed",
+      parentStepId: rootStep!.id,
+      parentStepAttempt: 0,
+    });
+    const oldChildStep = await linkedStep(oldChild, {
+      nodeId: "child0",
+      nodeType: "sub-workflow",
+      status: "failed",
+    });
+    const oldGrandchild = await linkedRun({
+      workflowId: grandchild.id,
+      status: "failed",
+      parentStepId: oldChildStep,
+    });
+
+    const before = await getTree(rootId);
+    expect(before.status).toBe(200);
+    expect(before.body!.rootRunId).toBe(rootId);
+    expect(before.body!.hasOpenWork).toBe(true);
+    const ids = before.body!.runs.map((run) => run.id);
+    expect(ids[0]).toBe(rootId);
+    expect(new Set(ids.slice(1, 3))).toEqual(new Set([childRun.id, oldChild]));
+    expect(new Set(ids.slice(3))).toEqual(new Set([grandchildRun.id, oldGrandchild]));
+    const byId = new Map(before.body!.runs.map((run) => [run.id, run]));
+    expect(byId.get(childRun.id)).toMatchObject({
+      workflowId: child.id,
+      status: "waiting",
+      parentStepId: rootStep!.id,
+      parentStepAttempt: 1,
+    });
+    expect(byId.get(oldChild)).toMatchObject({ status: "failed", parentStepAttempt: 0 });
+    expect(byId.get(oldGrandchild)?.parentStepId).toBe(oldChildStep);
+    for (const run of before.body!.runs) expect("context" in run).toBe(false);
+
+    await cancelWorkflowRun(rootId, "stop the tree");
+    expect((await getTaskById(task!.id))?.status).toBe("cancelled");
+
+    const after = await getTree(rootId);
+    expect(after.status).toBe(200);
+    expect(after.body!.hasOpenWork).toBe(false);
+    expect(after.body!.runs.map((run) => run.id)).toEqual(ids);
+    const statuses = new Map(after.body!.runs.map((run) => [run.id, run.status]));
+    expect(statuses.get(rootId)).toBe("cancelled");
+    expect(statuses.get(childRun.id)).toBe("cancelled");
+    expect(statuses.get(grandchildRun.id)).toBe("cancelled");
+    // Terminal history keeps its status.
+    expect(statuses.get(oldChild)).toBe("failed");
+    expect(statuses.get(oldGrandchild)).toBe("failed");
+
+    // A subtree reads on its own, without its ancestors.
+    const subtree = await getTree(childRun.id);
+    expect(subtree.body!.runs.map((run) => run.id)).toEqual([childRun.id, grandchildRun.id]);
+  });
+
+  test("a tree wider than one summary query returns every run once, in walk order", async () => {
+    const wf = await makeWorkflow({ nodes: [] });
+    const rootId = await linkedRun({ workflowId: wf.id, status: "completed" });
+    const step = await linkedStep(rootId, {
+      nodeId: "fan",
+      nodeType: "sub-workflow",
+      status: "completed",
+    });
+    // One child per attempt, over two 500-id summary chunks, so a dropped or
+    // repeated chunk shows.
+    const childCount = 1_100;
+    await getDbClient().transaction(async () => {
+      for (let i = 0; i < childCount; i++) {
+        await createWorkflowRun({
+          id: crypto.randomUUID(),
+          workflowId: wf.id,
+          parentStepId: step,
+          parentStepAttempt: i,
+        });
+      }
+    });
+
+    const walk = await getWorkflowRunTreeIds(rootId);
+    expect(walk).toHaveLength(childCount + 1);
+    const tree = await getTree(rootId);
+    expect(tree.status).toBe(200);
+    expect(tree.body!.runs.map((run) => run.id)).toEqual(walk);
+    expect(tree.body!.hasOpenWork).toBe(true);
+  });
+
+  test("a run without children is its own tree", async () => {
+    const wf = await makeWorkflow({ nodes: [] });
+    const runId = await linkedRun({ workflowId: wf.id, status: "completed" });
+    const tree = await getTree(runId);
+    expect(tree.status).toBe(200);
+    expect(tree.body!.runs.map((run) => run.id)).toEqual([runId]);
+    expect(tree.body!.hasOpenWork).toBe(false);
+  });
+
+  test("an unknown run is 404 and a cycle in the stored links is 409", async () => {
+    expect((await getTree(crypto.randomUUID())).status).toBe(404);
+
+    const wf = await makeWorkflow({ nodes: [] });
+    const a = await linkedRun({ workflowId: wf.id, status: "waiting" });
+    const aStep = await linkedStep(a, { nodeId: "s", nodeType: "sub-workflow", status: "waiting" });
+    const b = await linkedRun({ workflowId: wf.id, status: "waiting", parentStepId: aStep });
+    const bStep = await linkedStep(b, { nodeId: "s", nodeType: "sub-workflow", status: "waiting" });
+    await getDbClient().run("UPDATE workflow_runs SET parentStepId = ? WHERE id = ?", [bStep, a]);
+
+    const cycle = await getTree(a);
+    expect(cycle.status).toBe(409);
+    expect(cycle.body!.error).toContain("cycle");
+  });
+});

package/src/tests/workflow-engine-v2.test.ts

@@ -21,7 +21,7 @@ import {
   getWorkflowRunStepsByRunId,
   initDb,
 } from "../be/db";
-import type { Workflow, WorkflowDefinition } from "../types";
+import type { ExecutorMeta, Workflow, WorkflowDefinition } from "../types";
 import { shouldSkipCooldown } from "../workflows/cooldown";
 import {
   findReadyNodes,
@@ -143,6 +143,45 @@ class SlowExecutor extends BaseExecutor<typeof SlowExecutor.schema, typeof SlowE
   }
 }
 
+/** What the last `signal-probe` step saw: its abort signal and whether it got to its side effect. */
+const signalProbe: { signal?: AbortSignal; sideEffect: boolean } = { sideEffect: false };
+
+class SignalProbeExecutor extends BaseExecutor<
+  typeof SignalProbeExecutor.schema,
+  typeof SignalProbeExecutor.outSchema
+> {
+  static readonly schema = z.object({ delayMs: z.number() });
+  static readonly outSchema = z.object({ finished: z.boolean() });
+
+  readonly type = "signal-probe";
+  readonly mode = "instant" as const;
+  readonly configSchema = SignalProbeExecutor.schema;
+  readonly outputSchema = SignalProbeExecutor.outSchema;
+
+  protected async execute(
+    config: z.infer<typeof SignalProbeExecutor.schema>,
+    _context: Readonly<Record<string, unknown>>,
+    meta: ExecutorMeta,
+  ): Promise<ExecutorResult<z.infer<typeof SignalProbeExecutor.outSchema>>> {
+    const signal = meta.signal;
+    signalProbe.signal = signal;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, config.delayMs);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+    // A one-shot action, like the review trigger a claim script fires.
+    if (!signal?.aborted) signalProbe.sideEffect = true;
+    return { status: "success", output: { finished: true } };
+  }
+}
+
 class FailingExecutor extends BaseExecutor<
   typeof FailingExecutor.schema,
   typeof FailingExecutor.outSchema
@@ -216,6 +255,7 @@ function createTestRegistry(): ExecutorRegistry {
   registry.register(new SlowExecutor(mockDeps));
   registry.register(new FailingExecutor(mockDeps));
   registry.register(new ValidatePassExecutor(mockDeps));
+  registry.register(new SignalProbeExecutor(mockDeps));
   return registry;
 }
 
@@ -561,6 +601,41 @@ describe("Workflow Engine v2 (Phase 3)", () => {
       expect(run!.error).toContain("timed out");
     }, 5_000); // Allow test up to 5s
 
+    test("a timed-out step aborts its executor, so the side effect never happens", async () => {
+      signalProbe.signal = undefined;
+      signalProbe.sideEffect = false;
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "probe", type: "signal-probe", config: { delayMs: 600, timeoutMs: 100 } }],
+      });
+
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      const run = await getWorkflowRun(runId);
+      expect(run!.status).toBe("failed");
+      expect(run!.error).toContain("Step timed out after 100ms");
+      expect(signalProbe.signal?.aborted).toBe(true);
+      // Past the executor's own delay: without the abort it would have fired.
+      await Bun.sleep(700);
+      expect(signalProbe.sideEffect).toBe(false);
+    }, 5_000);
+
+    test("a step that finishes in budget is never aborted afterwards", async () => {
+      signalProbe.signal = undefined;
+      signalProbe.sideEffect = false;
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "probe", type: "signal-probe", config: { delayMs: 10, timeoutMs: 150 } }],
+      });
+
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+      expect(signalProbe.sideEffect).toBe(true);
+      await Bun.sleep(250);
+      expect(signalProbe.signal?.aborted).toBe(false);
+    }, 5_000);
+
     // The inline runtime's ulimit preamble fails on macOS (no usable
     // RLIMIT_AS), so the script dies before the watchdog behavior under test.
     // Linux CI is the enforcing environment; the skip only unblocks local
@@ -598,6 +673,46 @@ describe("Workflow Engine v2 (Phase 3)", () => {
 
   // ─── Validation ───────────────────────────────────────────
 
+  describe("Detached start", () => {
+    test("detach returns once the run is committed and walks its instant steps in the background", async () => {
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [
+          { id: "slow", type: "slow", config: { delayMs: 400 }, next: "after" },
+          { id: "after", type: "echo", config: { message: "done" } },
+        ],
+      });
+
+      const started = performance.now();
+      const runId = await startWorkflowExecution(workflow, {}, registry, { detach: true });
+      const returnedAfterMs = performance.now() - started;
+
+      expect(returnedAfterMs).toBeLessThan(300);
+      expect((await getWorkflowRun(runId))!.status).toBe("running");
+
+      const deadline = Date.now() + 3_000;
+      while ((await getWorkflowRun(runId))!.status === "running" && Date.now() < deadline) {
+        await Bun.sleep(25);
+      }
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+      const steps = await getWorkflowRunStepsByRunId(runId);
+      expect(steps.map((step) => step.nodeId).sort()).toEqual(["after", "slow"]);
+    }, 5_000);
+
+    test("without detach the start resolves only after the instant steps ran", async () => {
+      const registry = createTestRegistry();
+      const workflow = await makeWorkflow({
+        nodes: [{ id: "slow", type: "slow", config: { delayMs: 300 } }],
+      });
+
+      const started = performance.now();
+      const runId = await startWorkflowExecution(workflow, {}, registry);
+
+      expect(performance.now() - started).toBeGreaterThanOrEqual(290);
+      expect((await getWorkflowRun(runId))!.status).toBe("completed");
+    }, 5_000);
+  });
+
   describe("Validation", () => {
     test("validation pass allows step to complete", async () => {
       const registry = createTestRegistry();

package/src/tests/workflow-http-v2.test.ts

@@ -20,6 +20,7 @@ import {
   initDb,
   listWorkflowRuns,
   updateWorkflowRun,
+  updateWorkflowRunStep,
 } from "../be/db";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { handleWorkflows } from "../http/workflows";
@@ -1007,6 +1008,136 @@ describe("Workflow HTTP API v2", () => {
       });
       expect(res.status).toBe(404);
     });
+
+    type RunDetail = {
+      run: WorkflowRun;
+      steps: WorkflowRunStep[];
+      parent?: { runId: string; workflowId: string; stepId: string; nodeId: string };
+    };
+
+    async function getRunDetail(runId: string, fields?: "full" | "slim"): Promise<RunDetail> {
+      const query = fields ? `?fields=${fields}` : "";
+      const res = await fetch(`${baseUrl}/api/workflow-runs/${runId}${query}`, { headers });
+      expect(res.status).toBe(200);
+      return (await res.json()) as RunDetail;
+    }
+
+    /** A finished run whose `poll` node ran `iterations` times, each step snapshotting the context. */
+    async function createLoopRun(iterations: number) {
+      const workflow = await createTestWorkflow();
+      const runId = crypto.randomUUID();
+      await createWorkflowRun({ id: runId, workflowId: workflow.id });
+      const context = {
+        trigger: { repo: "a/b" },
+        poll: { attempts: iterations },
+        blob: "x".repeat(4_000),
+      };
+      for (let i = 0; i < iterations; i++) {
+        const step = await createWorkflowRunStep({
+          id: crypto.randomUUID(),
+          runId,
+          nodeId: "poll",
+          nodeType: "script",
+          input: { ...context, iteration: i },
+          idempotencyKey: `${runId}:poll:${i}`,
+        });
+        await updateWorkflowRunStep(step.id, {
+          status: i === iterations - 1 ? "completed" : "failed",
+          output: { iteration: i, ready: i === iterations - 1 },
+          error: i === iterations - 1 ? null : `not ready (${i})`,
+          diagnostics: `iteration ${i}`,
+          retryCount: i,
+          nextRetryAt: new Date(Date.now() + 60_000).toISOString(),
+          finishedAt: new Date().toISOString(),
+        });
+      }
+      await updateWorkflowRun(runId, {
+        status: "completed",
+        context,
+        finishedAt: new Date().toISOString(),
+      });
+      return { workflow, runId, context };
+    }
+
+    test("fields=slim omits run.context and steps[].input, keeps every other field", async () => {
+      const { runId, context } = await createLoopRun(3);
+
+      const byDefault = await getRunDetail(runId);
+      const full = await getRunDetail(runId, "full");
+      const slim = await getRunDetail(runId, "slim");
+
+      expect(byDefault).toEqual(full);
+      expect(full.run.context).toEqual(context);
+      expect(full.steps).toHaveLength(3);
+      for (const step of full.steps) expect(step.input).toBeDefined();
+
+      expect(slim.run).not.toHaveProperty("context");
+      expect(slim.steps).toHaveLength(3);
+      for (const step of slim.steps) expect(step).not.toHaveProperty("input");
+
+      const { context: _context, ...fullRunRest } = full.run;
+      expect(slim.run).toEqual(fullRunRest);
+      const fullStepsRest = full.steps.map(({ input: _input, ...rest }) => rest);
+      // Same steps in the same order: both reads break `startedAt` ties by rowid.
+      expect(slim.steps).toEqual(fullStepsRest);
+      // The retry and result fields the slim view exists to serve.
+      const last = slim.steps.at(-1)!;
+      expect(last.output).toEqual({ iteration: 2, ready: true });
+      expect(last.retryCount).toBe(2);
+      expect(last.diagnostics).toBe("iteration 2");
+      expect(last.nextRetryAt).toBeDefined();
+      expect(slim.steps[0]!.error).toBe("not ready (0)");
+
+      expect(JSON.stringify(slim).length).toBeLessThan(JSON.stringify(full).length / 4);
+    });
+
+    test("fields=slim returns 404 for missing run", async () => {
+      const res = await fetch(`${baseUrl}/api/workflow-runs/${crypto.randomUUID()}?fields=slim`, {
+        headers,
+      });
+      expect(res.status).toBe(404);
+    });
+
+    test("rejects an unknown fields value", async () => {
+      const { runId } = await createLoopRun(1);
+      const res = await fetch(`${baseUrl}/api/workflow-runs/${runId}?fields=tiny`, { headers });
+      expect(res.status).toBe(400);
+    });
+
+    test("child run carries parent in both views", async () => {
+      const { workflow: parentWorkflow, runId: parentRunId } = await createLoopRun(1);
+      const parentStep = await createWorkflowRunStep({
+        id: crypto.randomUUID(),
+        runId: parentRunId,
+        nodeId: "child",
+        nodeType: "sub-workflow",
+        input: { large: "y".repeat(1_000) },
+      });
+      const childWorkflow = await createTestWorkflow();
+      const childRunId = crypto.randomUUID();
+      await createWorkflowRun({
+        id: childRunId,
+        workflowId: childWorkflow.id,
+        parentStepId: parentStep.id,
+        parentStepAttempt: 0,
+      });
+
+      const expectedParent = {
+        runId: parentRunId,
+        workflowId: parentWorkflow.id,
+        stepId: parentStep.id,
+        nodeId: "child",
+      };
+      const full = await getRunDetail(childRunId, "full");
+      const slim = await getRunDetail(childRunId, "slim");
+      expect(full.parent).toEqual(expectedParent);
+      expect(slim.parent).toEqual(expectedParent);
+      expect(slim.run.parentStepId).toBe(parentStep.id);
+      expect(slim.run.parentStepAttempt).toBe(0);
+
+      // A top-level run has no parent in either view.
+      expect(await getRunDetail(parentRunId, "slim")).not.toHaveProperty("parent");
+    });
   });
 
   // ─── WEBHOOK ──────────────────────────────────────────────