kradle 0.4.1 → 0.4.3

package/README.md

@@ -138,14 +138,41 @@ Uses file watching with debouncing (300ms) and hash comparison to minimize unnec
 
 ### Run Challenge
 
-Run a challenge in production or studio environment:
+Run a challenge and wait for completion:
 
 ```bash
 kradle challenge run <challenge-name>
-kradle challenge run <challenge-name> --studio  # Run in local studio environment
+kradle challenge run <challenge-name> --studio     # Run in local studio environment
 kradle challenge run <team-name>:<challenge-name>  # Run a public challenge from another team
+kradle challenge run <challenge-name> --no-open    # Don't open browser
+kradle challenge run <challenge-name> --no-wait    # Fire and forget (don't wait for completion)
 ```
 
+By default, the command opens the run URL in your browser and polls until the run completes, then displays the outcome.
+
+### List Runs
+
+List your recent runs:
+
+```bash
+kradle challenge runs list              # List 10 most recent runs
+kradle challenge runs list --limit 20   # List 20 most recent runs
+```
+
+### Get Run Details
+
+Get details and logs for a specific run:
+
+```bash
+kradle challenge runs get <run-id>
+kradle challenge runs get <run-id> --no-logs   # Skip fetching logs
+```
+
+This displays:
+- Run metadata (status, duration, end state)
+- Participant results (agent, winner status, score)
+- Log entries with timestamps and levels (unless `--no-logs` is used)
+
 ## Experiment Commands
 
 Experiments allow you to run batches of challenge runs with different agents and configurations, then analyze the results. This is useful for benchmarking agents, testing challenge difficulty, or gathering statistics across many runs.
@@ -424,6 +451,7 @@ kradle-cli/
 │   │   ├── agent/            # Agent commands
 │   │   ├── ai-docs/          # AI documentation commands
 │   │   ├── challenge/        # Challenge management commands
+│   │   │   └── runs/         # Run listing and logs commands
 │   │   ├── experiment/       # Experiment commands
 │   │   └── world/            # World management commands
 │   └── lib/                  # Core libraries

package/dist/commands/challenge/run.d.ts

@@ -12,7 +12,11 @@ export default class Run extends Command {
         "studio-api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        open: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-open": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-wait": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-summary": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    private pollForCompletion;
+    private displayRunResult;
     run(): Promise<void>;
 }

package/dist/commands/challenge/run.js

@@ -3,13 +3,18 @@ import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
 import { getConfigFlags } from "../../lib/flags.js";
-import { loadTemplateRun, openInBrowser } from "../../lib/utils.js";
+import { formatDuration, getRunStatusDisplay, loadTemplateRun, openInBrowser } from "../../lib/utils.js";
+const POLL_INTERVAL_MS = 2000;
+const MAX_POLL_TIME_MS = 30 * 60 * 1000; // 30 minutes
+const TERMINAL_STATUSES = ["finished", "game_over", "error", "completed", "cancelled", "timeout", "failed"];
 export default class Run extends Command {
     static description = "Run a challenge";
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
         "<%= config.bin %> <%= command.id %> team-name:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --no-open",
+        "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
     ];
     static args = {
         challengeSlug: getChallengeSlugArgument({
@@ -19,9 +24,83 @@ export default class Run extends Command {
     };
     static flags = {
         studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
-        open: Flags.boolean({ char: "o", description: "Open the run URL in the browser", default: false }),
+        "no-open": Flags.boolean({
+            description: "Don't open the run URL in the browser",
+            default: false,
+        }),
+        "no-wait": Flags.boolean({
+            description: "Don't wait for the run to complete (fire and forget)",
+            default: false,
+        }),
+        "no-summary": Flags.boolean({
+            description: "Don't wait for the AI-generated summary",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url", "web-url", "studio-url", "studio-api-url"),
     };
+    async pollForCompletion(api, runId, waitForSummary) {
+        let lastStatus = "";
+        let reachedTerminal = false;
+        let waitingForSummary = false;
+        const startTime = Date.now();
+        while (true) {
+            // Check for timeout
+            const elapsed = Date.now() - startTime;
+            if (elapsed > MAX_POLL_TIME_MS) {
+                this.log(pc.yellow("\nTimed out waiting for run completion"));
+                return;
+            }
+            const result = await api.getRunResult(runId);
+            const currentStatus = result.status;
+            // Show status changes
+            if (currentStatus !== lastStatus) {
+                const elapsedSecs = (elapsed / 1000).toFixed(0);
+                this.log(pc.dim(`[${elapsedSecs}s] Status: ${getRunStatusDisplay(currentStatus)}`));
+                lastStatus = currentStatus;
+            }
+            // Check for terminal state
+            if (TERMINAL_STATUSES.includes(currentStatus)) {
+                if (!reachedTerminal) {
+                    reachedTerminal = true;
+                }
+                // If we need to wait for summary and it's not available yet, keep polling
+                if (waitForSummary && !result.summary) {
+                    if (!waitingForSummary) {
+                        waitingForSummary = true;
+                        this.log(pc.dim(`Waiting for summary...`));
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+                    continue;
+                }
+                this.log("");
+                this.displayRunResult(result);
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+    }
+    displayRunResult(result) {
+        this.log(pc.bold("=== Run Complete ===\n"));
+        this.log(`${pc.dim("Status:")}      ${getRunStatusDisplay(result.status)}`);
+        this.log(`${pc.dim("End State:")}   ${result.endState || "-"}`);
+        this.log(`${pc.dim("Duration:")}    ${formatDuration(result.totalTime)}`);
+        if (result.aggregatedResults) {
+            const agg = result.aggregatedResults;
+            this.log(`${pc.dim("Results:")}     ${pc.green(String(agg.successfulParticipantCount))} successful / ${agg.participantCount} participants`);
+        }
+        if (result.participantResults && Object.keys(result.participantResults).length > 0) {
+            this.log(pc.dim("\nParticipants:"));
+            for (const [participantId, pr] of Object.entries(result.participantResults)) {
+                const winnerIcon = pr.winner ? pc.green("\u2713") : pc.red("\u2717");
+                const score = pr.score !== undefined ? ` (score: ${pr.score})` : "";
+                this.log(`  ${winnerIcon} ${participantId}: ${pr.agent}${score}`);
+            }
+        }
+        if (result.summary) {
+            this.log(pc.bold("\n=== Summary ===\n"));
+            this.log(result.summary);
+        }
+    }
     async run() {
         const { args, flags } = await this.parse(Run);
         const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
@@ -29,23 +108,29 @@ export default class Run extends Command {
         const challengeSlug = args.challengeSlug;
         try {
             const { participants } = (await loadTemplateRun());
-            const template = {
+            this.log(pc.blue(`>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
+            const response = await studioApi.runChallenge({
                 challenge: challengeSlug,
                 participants,
-            };
-            this.log(pc.blue(`>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
-            const response = await studioApi.runChallenge(template);
+                jobType: "foreground",
+            });
             if (response.runIds && response.runIds.length > 0) {
+                const runId = response.runIds[0];
                 const baseUrl = flags.studio ? flags["studio-url"] : flags["web-url"];
-                const runUrl = `${baseUrl}/runs/${response.runIds[0]}`;
-                this.log(pc.green("\n✓ Challenge started!"));
+                const runUrl = `${baseUrl}/runs/${runId}`;
+                this.log(pc.green("\n\u2713 Challenge started!"));
+                this.log(pc.dim(`Run ID: ${runId}`));
                 this.log(pc.dim(`Run URL: ${runUrl}`));
-                if (flags.open) {
-                    await openInBrowser(runUrl);
+                if (!flags["no-open"]) {
+                    openInBrowser(runUrl);
+                }
+                if (!flags["no-wait"]) {
+                    this.log(pc.blue("\n>> Waiting for run to complete...\n"));
+                    await this.pollForCompletion(studioApi, runId, !flags["no-summary"]);
                 }
             }
             else {
-                this.log(pc.yellow("⚠ Challenge started but no run ID returned"));
+                this.log(pc.yellow("\u26a0 Challenge started but no run ID returned"));
             }
         }
         catch (error) {

package/dist/commands/challenge/runs/get.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "@oclif/core";
+export default class GetRun extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        runId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "no-logs": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/runs/get.js

@@ -0,0 +1,115 @@
+import { Args, Command, Flags } from "@oclif/core";
+import pc from "picocolors";
+import { ApiClient } from "../../../lib/api-client.js";
+import { getConfigFlags } from "../../../lib/flags.js";
+import { formatDuration, formatTime } from "../../../lib/utils.js";
+function getLogLevelColor(level) {
+    switch (level.toLowerCase()) {
+        case "error":
+            return pc.red;
+        case "warn":
+        case "warning":
+            return pc.yellow;
+        case "info":
+            return pc.blue;
+        case "debug":
+            return pc.dim;
+        default:
+            return (text) => text;
+    }
+}
+function formatLogMessage(log) {
+    if ("parsedMessage" in log) {
+        return JSON.stringify(log.parsedMessage, null, 2);
+    }
+    return log.message;
+}
+export default class GetRun extends Command {
+    static description = "Get details and logs for a specific run";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> abc123",
+        "<%= config.bin %> <%= command.id %> abc123 --no-logs",
+    ];
+    static args = {
+        runId: Args.string({
+            description: "Run ID to get details for",
+            required: true,
+        }),
+    };
+    static flags = {
+        "no-logs": Flags.boolean({
+            description: "Skip fetching and displaying logs",
+            default: false,
+        }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(GetRun);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const showLogs = !flags["no-logs"];
+        this.log(pc.blue(`>> Loading run ${args.runId}...`));
+        try {
+            const [runResult, logs] = await Promise.all([
+                api.getRunResult(args.runId),
+                showLogs ? api.getRunLogs(args.runId) : Promise.resolve([]),
+            ]);
+            // Run metadata
+            this.log(pc.bold("\n=== Run Result ===\n"));
+            this.log(`${pc.dim("ID:")}          ${runResult.id || args.runId}`);
+            this.log(`${pc.dim("Challenge:")}   ${runResult.challenge || "-"}`);
+            this.log(`${pc.dim("Status:")}      ${runResult.status}`);
+            this.log(`${pc.dim("End State:")}   ${runResult.endState || "-"}`);
+            this.log(`${pc.dim("Finished:")}    ${runResult.finishedStatus || "-"}`);
+            this.log(`${pc.dim("Duration:")}    ${formatDuration(runResult.totalTime)}`);
+            this.log(`${pc.dim("End Time:")}    ${formatTime(runResult.endTime)}`);
+            // Aggregated results
+            if (runResult.aggregatedResults) {
+                this.log(pc.bold("\n=== Aggregated Results ===\n"));
+                const agg = runResult.aggregatedResults;
+                this.log(`${pc.dim("Participants:")}     ${agg.participantCount}`);
+                this.log(`${pc.dim("Successful:")}       ${agg.successfulParticipantCount}`);
+                this.log(`${pc.dim("Unsuccessful:")}     ${agg.unsuccessfulParticipantCount}`);
+                this.log(`${pc.dim("Total Time:")}       ${formatDuration(agg.totalTime)}`);
+            }
+            // Participant results
+            if (runResult.participantResults && Object.keys(runResult.participantResults).length > 0) {
+                this.log(pc.bold("\n=== Participant Results ===\n"));
+                const headers = ["Participant", "Agent", "Winner", "Score", "Time to Success"];
+                const widths = [15, 35, 10, 10, 18];
+                this.log(headers.map((h, i) => h.padEnd(widths[i])).join(" "));
+                this.log("-".repeat(widths.reduce((a, b) => a + b + 1, 0)));
+                for (const [participantId, result] of Object.entries(runResult.participantResults)) {
+                    const agentPadded = result.agent.padEnd(widths[1]);
+                    const winnerText = result.winner ? "Yes" : "No";
+                    const winnerPadded = winnerText.padEnd(widths[2]);
+                    const winner = result.winner ? pc.green(winnerPadded) : pc.red(winnerPadded);
+                    const score = result.score !== undefined ? String(result.score) : "-";
+                    const timeToSuccess = result.timeToSuccess !== undefined ? formatDuration(result.timeToSuccess) : "-";
+                    this.log(`${participantId.padEnd(widths[0])} ${agentPadded} ${winner} ${score.padEnd(widths[3])} ${timeToSuccess}`);
+                }
+            }
+            // Logs
+            if (showLogs) {
+                if (logs.length > 0) {
+                    this.log(pc.bold("\n=== Logs ===\n"));
+                    for (const log of logs) {
+                        const time = formatTime(log.creationTime);
+                        const levelColor = getLogLevelColor(log.level);
+                        const levelText = `[${log.level.toUpperCase()}]`.padEnd(9);
+                        const level = levelColor(levelText);
+                        const participantText = `[${log.participantId}]`.padEnd(15);
+                        const participant = pc.cyan(participantText);
+                        const message = formatLogMessage(log);
+                        this.log(`${pc.dim(time)} ${level} ${participant} ${message}`);
+                    }
+                }
+                else {
+                    this.log(pc.dim("\nNo logs found."));
+                }
+            }
+        }
+        catch (error) {
+            this.error(pc.red(`Failed to get run: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

package/dist/commands/challenge/runs/list.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "@oclif/core";
+export default class ListRuns extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/runs/list.js

@@ -0,0 +1,42 @@
+import { Command, Flags } from "@oclif/core";
+import pc from "picocolors";
+import { ApiClient } from "../../../lib/api-client.js";
+import { getConfigFlags } from "../../../lib/flags.js";
+import { formatDuration, formatTime, getRunStatusDisplay } from "../../../lib/utils.js";
+export default class ListRuns extends Command {
+    static description = "List recent runs";
+    static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> --limit 20"];
+    static flags = {
+        limit: Flags.integer({
+            char: "n",
+            description: "Number of runs to display",
+            default: 10,
+        }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { flags } = await this.parse(ListRuns);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        this.log(pc.blue(">> Loading runs..."));
+        const { runs } = await api.listRuns(flags.limit);
+        if (runs.length === 0) {
+            this.log(pc.yellow("\nNo runs found."));
+            return;
+        }
+        this.log(pc.bold("\nRuns:\n"));
+        const headers = ["ID", "Challenge", "Status", "End State", "Duration", "Created"];
+        const widths = [38, 30, 15, 15, 12, 20];
+        this.log(headers.map((h, i) => h.padEnd(widths[i])).join(" "));
+        this.log("-".repeat(widths.reduce((a, b) => a + b + 1, 0)));
+        for (const run of runs) {
+            const challenge = run.challenge.length > 28 ? `${run.challenge.slice(0, 25)}...` : run.challenge;
+            const statusColored = getRunStatusDisplay(run.status);
+            const statusPadding = " ".repeat(Math.max(0, widths[2] - run.status.length));
+            const endState = run.endState || "-";
+            const duration = formatDuration(run.totalTime);
+            const created = formatTime(run.creationTime);
+            this.log(`${run.id.padEnd(widths[0])} ${challenge.padEnd(widths[1])} ${statusColored}${statusPadding} ${endState.padEnd(widths[3])} ${duration.padEnd(widths[4])} ${created}`);
+        }
+        this.log(pc.dim(`\nShowing ${runs.length} runs`));
+    }
+}

package/dist/lib/api-client.d.ts

@@ -1,5 +1,5 @@
 import type z from "zod";
-import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DashboardUrlResponse, type DownloadUrlResponse, HumanSchema, type ParsedLogEntry, type RecordingMetadata, type RunResultResponse, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
+import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DashboardUrlResponse, type DownloadUrlResponse, HumanSchema, type ParsedLogEntry, type RecordingMetadata, type Run, type RunResultResponse, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
 export declare class ApiClient {
     private apiUrl;
     private kradleApiKey;
@@ -75,7 +75,8 @@ export declare class ApiClient {
     runChallenge(runData: {
         challenge: string;
         participants: unknown[];
-    }, isBackground?: boolean): Promise<{
+        jobType: "background" | "foreground";
+    }): Promise<{
         runIds?: string[] | undefined;
         participants?: Record<string, {
             agent: string;
@@ -125,6 +126,15 @@ export declare class ApiClient {
      * @returns Run result with status, end_state, and participant results.
      */
     getRunResult(runId: string): Promise<RunResultResponse>;
+    /**
+     * List runs with pagination.
+     * @param limit - Maximum number of runs to return.
+     * @returns Object with runs array and optional nextPageToken.
+     */
+    listRuns(limit?: number): Promise<{
+        runs: Run[];
+        nextPageToken?: string;
+    }>;
     listWorlds(): Promise<WorldSchemaType[]>;
     listKradleWorlds(): Promise<WorldSchemaType[]>;
     getWorld(slug: string): Promise<WorldSchemaType>;

package/dist/lib/api-client.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DashboardUrlResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunLogsResponseSchema, RunResultResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DashboardUrlResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, ListRunsResponseSchema, RecordingsListResponseSchema, RunLogsResponseSchema, RunResultResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
 const DEFAULT_PAGE_SIZE = 30;
 const DEFAULT_CHALLENGE_SCHEMA = {
     slug: "",
@@ -221,11 +221,10 @@ export class ApiClient {
     async getChallengeDownloadUrl(slug) {
         return this.get(`challenges/${slug}/datapackDownloadUrl`, {}, DownloadUrlResponseSchema);
     }
-    async runChallenge(runData, isBackground = true) {
+    async runChallenge(runData) {
         const url = "jobs";
-        const payload = isBackground ? { ...runData, jobType: "background" } : runData;
         return this.post(url, {
-            body: JSON.stringify(payload),
+            body: JSON.stringify(runData),
         }, JobResponseSchema);
     }
     async deleteChallenge(challengeId) {
@@ -309,6 +308,32 @@ export class ApiClient {
         const url = `runs/${runId}`;
         return this.get(url, {}, RunResultResponseSchema);
     }
+    /**
+     * List runs with pagination.
+     * @param limit - Maximum number of runs to return.
+     * @returns Object with runs array and optional nextPageToken.
+     */
+    async listRuns(limit = 10) {
+        const runs = [];
+        let currentToken;
+        // Use consistent page size for all requests (page tokens are tied to page size)
+        const pageSize = DEFAULT_PAGE_SIZE;
+        while (runs.length < limit) {
+            const params = new URLSearchParams();
+            params.set("page_size", String(pageSize));
+            if (currentToken) {
+                params.set("page_token", currentToken);
+            }
+            const response = await this.get(`runs?${params}`, {}, ListRunsResponseSchema);
+            runs.push(...response.runs);
+            if (!response.nextPageToken || response.runs.length === 0) {
+                currentToken = undefined;
+                break;
+            }
+            currentToken = response.nextPageToken;
+        }
+        return { runs: runs.slice(0, limit), nextPageToken: currentToken };
+    }
     async listWorlds() {
         return this.listResource("worlds", "worlds", WorldsResponseSchema);
     }

package/dist/lib/experiment/runner.js

@@ -161,7 +161,8 @@ export class Runner {
             const response = await this.api.runChallenge({
                 challenge: state.config.challenge_slug,
                 participants: state.config.participants,
-            }, true);
+                jobType: "background",
+            });
             if (!response.runIds || response.runIds.length === 0) {
                 throw new Error("No run ID returned from API");
             }

package/dist/lib/experiment/types.d.ts

@@ -29,17 +29,17 @@ export type RunStatus = "queued" | "initializing" | "watcher_connected" | "parti
 export declare const ProgressEntrySchema: z.ZodObject<{
     index: z.ZodNumber;
     status: z.ZodEnum<{
+        finished: "finished";
+        game_over: "game_over";
+        completed: "completed";
+        started: "started";
+        initializing: "initializing";
         error: "error";
         queued: "queued";
-        initializing: "initializing";
         watcher_connected: "watcher_connected";
         participants_connected: "participants_connected";
-        started: "started";
         running: "running";
         recovering: "recovering";
-        completed: "completed";
-        game_over: "game_over";
-        finished: "finished";
     }>;
     runId: z.ZodOptional<z.ZodString>;
     participantIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -52,17 +52,17 @@ export declare const ProgressSchema: z.ZodObject<{
     entries: z.ZodArray<z.ZodObject<{
         index: z.ZodNumber;
         status: z.ZodEnum<{
+            finished: "finished";
+            game_over: "game_over";
+            completed: "completed";
+            started: "started";
+            initializing: "initializing";
             error: "error";
             queued: "queued";
-            initializing: "initializing";
             watcher_connected: "watcher_connected";
             participants_connected: "participants_connected";
-            started: "started";
             running: "running";
             recovering: "recovering";
-            completed: "completed";
-            game_over: "game_over";
-            finished: "finished";
         }>;
         runId: z.ZodOptional<z.ZodString>;
         participantIds: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/lib/schemas.d.ts

@@ -240,6 +240,7 @@ export declare const RunResultResponseSchema: z.ZodObject<{
         score: z.ZodOptional<z.ZodNumber>;
         timeToSuccess: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    summary: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const WorldSchema: z.ZodObject<{
     id: z.ZodString;
@@ -279,6 +280,73 @@ export declare const WorldsResponseSchema: z.ZodObject<{
 export declare const DashboardUrlResponseSchema: z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>;
+export declare const RunSchema: z.ZodObject<{
+    id: z.ZodString;
+    challenge: z.ZodString;
+    status: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        public: "public";
+    }>>;
+    creator: z.ZodOptional<z.ZodString>;
+    creationTime: z.ZodOptional<z.ZodString>;
+    updateTime: z.ZodOptional<z.ZodString>;
+    startTime: z.ZodOptional<z.ZodString>;
+    endTime: z.ZodOptional<z.ZodString>;
+    totalTime: z.ZodOptional<z.ZodNumber>;
+    endState: z.ZodOptional<z.ZodString>;
+    finishedStatus: z.ZodOptional<z.ZodString>;
+    aggregatedResults: z.ZodOptional<z.ZodObject<{
+        participantCount: z.ZodNumber;
+        successfulParticipantCount: z.ZodNumber;
+        successfulParticipantIds: z.ZodArray<z.ZodString>;
+        unsuccessfulParticipantCount: z.ZodNumber;
+        unsuccessfulParticipantIds: z.ZodArray<z.ZodString>;
+        totalTime: z.ZodNumber;
+    }, z.core.$strip>>;
+    participantResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        agent: z.ZodString;
+        winner: z.ZodBoolean;
+        score: z.ZodOptional<z.ZodNumber>;
+        timeToSuccess: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ListRunsResponseSchema: z.ZodObject<{
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        challenge: z.ZodString;
+        status: z.ZodString;
+        visibility: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            public: "public";
+        }>>;
+        creator: z.ZodOptional<z.ZodString>;
+        creationTime: z.ZodOptional<z.ZodString>;
+        updateTime: z.ZodOptional<z.ZodString>;
+        startTime: z.ZodOptional<z.ZodString>;
+        endTime: z.ZodOptional<z.ZodString>;
+        totalTime: z.ZodOptional<z.ZodNumber>;
+        endState: z.ZodOptional<z.ZodString>;
+        finishedStatus: z.ZodOptional<z.ZodString>;
+        aggregatedResults: z.ZodOptional<z.ZodObject<{
+            participantCount: z.ZodNumber;
+            successfulParticipantCount: z.ZodNumber;
+            successfulParticipantIds: z.ZodArray<z.ZodString>;
+            unsuccessfulParticipantCount: z.ZodNumber;
+            unsuccessfulParticipantIds: z.ZodArray<z.ZodString>;
+            totalTime: z.ZodNumber;
+        }, z.core.$strip>>;
+        participantResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            agent: z.ZodString;
+            winner: z.ZodBoolean;
+            score: z.ZodOptional<z.ZodNumber>;
+            timeToSuccess: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export type ChallengeSchemaType = z.infer<typeof ChallengeSchema>;
 export type ChallengeConfigSchemaType = z.infer<typeof ChallengeConfigSchema>;
 export type ChallengesResponseType = z.infer<typeof ChallengesResponseSchema>;
@@ -303,3 +371,5 @@ export type WorldSchemaType = z.infer<typeof WorldSchema>;
 export type WorldConfigSchemaType = z.infer<typeof WorldConfigSchema>;
 export type WorldsResponseType = z.infer<typeof WorldsResponseSchema>;
 export type DashboardUrlResponse = z.infer<typeof DashboardUrlResponseSchema>;
+export type Run = z.infer<typeof RunSchema>;
+export type ListRunsResponse = z.infer<typeof ListRunsResponseSchema>;

package/dist/lib/schemas.js

@@ -123,6 +123,7 @@ export const RunResultResponseSchema = z.object({
     endTime: z.string().optional(),
     aggregatedResults: RunAggregatedResultsSchema.optional(),
     participantResults: z.record(z.string(), RunParticipantResultSchema).optional(),
+    summary: z.string().optional(),
 });
 export const WorldSchema = z.object({
     id: z.string(),
@@ -147,3 +148,24 @@ export const WorldsResponseSchema = z.object({
 export const DashboardUrlResponseSchema = z.object({
     url: z.string(),
 });
+export const RunSchema = z.object({
+    id: z.string(),
+    challenge: z.string(),
+    status: z.string(),
+    visibility: z.enum(["private", "public"]).optional(),
+    creator: z.string().optional(),
+    creationTime: z.string().optional(),
+    updateTime: z.string().optional(),
+    startTime: z.string().optional(),
+    endTime: z.string().optional(),
+    totalTime: z.number().optional(),
+    endState: z.string().optional(),
+    finishedStatus: z.string().optional(),
+    aggregatedResults: RunAggregatedResultsSchema.optional(),
+    participantResults: z.record(z.string(), RunParticipantResultSchema).optional(),
+    tags: z.array(z.string()).optional(),
+});
+export const ListRunsResponseSchema = z.object({
+    runs: z.array(RunSchema),
+    nextPageToken: z.string().optional(),
+});

package/dist/lib/utils.d.ts

@@ -94,3 +94,21 @@ export declare function loadTypescriptExport(filePath: string, exportName: strin
  * @param url The URL to open.
  */
 export declare function openInBrowser(url: string): void;
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * @param ms Duration in milliseconds
+ * @returns Formatted string like "45.3s" or "2m 30s"
+ */
+export declare function formatDuration(ms: number | undefined): string;
+/**
+ * Format an ISO timestamp to a locale string.
+ * @param isoString ISO 8601 timestamp
+ * @returns Formatted locale string or "-" if undefined
+ */
+export declare function formatTime(isoString: string | undefined): string;
+/**
+ * Get a colored string for a run status.
+ * @param status The run status
+ * @returns Colored status string
+ */
+export declare function getRunStatusDisplay(status: string): string;

package/dist/lib/utils.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import pc from "picocolors";
 export async function loadTemplateRun() {
     const templatePath = path.resolve(process.cwd(), "template-run.json");
     const content = await fs.readFile(templatePath, "utf-8");
@@ -197,3 +198,54 @@ export function openInBrowser(url) {
     }
     exec(command);
 }
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * @param ms Duration in milliseconds
+ * @returns Formatted string like "45.3s" or "2m 30s"
+ */
+export function formatDuration(ms) {
+    if (ms === undefined)
+        return "-";
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m ${remainingSeconds.toFixed(0)}s`;
+}
+/**
+ * Format an ISO timestamp to a locale string.
+ * @param isoString ISO 8601 timestamp
+ * @returns Formatted locale string or "-" if undefined
+ */
+export function formatTime(isoString) {
+    if (!isoString)
+        return "-";
+    const date = new Date(isoString);
+    return date.toLocaleString();
+}
+/**
+ * Get a colored string for a run status.
+ * @param status The run status
+ * @returns Colored status string
+ */
+export function getRunStatusDisplay(status) {
+    switch (status) {
+        case "finished":
+        case "game_over":
+        case "completed":
+            return pc.green(status);
+        case "started":
+            return pc.blue(status);
+        case "initializing":
+        case "created":
+            return pc.yellow(status);
+        case "error":
+        case "failed":
+        case "cancelled":
+        case "timeout":
+            return pc.red(status);
+        default:
+            return status;
+    }
+}

package/oclif.manifest.json

@@ -42,6 +42,50 @@
         "init.js"
       ]
     },
+    "agent:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List all agents",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-url": {
+          "description": "Kradle Web API URL",
+          "env": "KRADLE_API_URL",
+          "name": "api-url",
+          "required": true,
+          "default": "https://api.kradle.ai/v0",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:list",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "agent",
+        "list.js"
+      ]
+    },
     "ai-docs:challenges-sdk": {
       "aliases": [],
       "args": {
@@ -451,7 +495,9 @@
       "examples": [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
-        "<%= config.bin %> <%= command.id %> team-name:my-challenge"
+        "<%= config.bin %> <%= command.id %> team-name:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --no-open",
+        "<%= config.bin %> <%= command.id %> my-challenge --no-wait"
       ],
       "flags": {
         "studio": {
@@ -461,10 +507,21 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "open": {
-          "char": "o",
-          "description": "Open the run URL in the browser",
-          "name": "open",
+        "no-open": {
+          "description": "Don't open the run URL in the browser",
+          "name": "no-open",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-wait": {
+          "description": "Don't wait for the run to complete (fire and forget)",
+          "name": "no-wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-summary": {
+          "description": "Don't wait for the AI-generated summary",
+          "name": "no-summary",
           "allowNo": false,
           "type": "boolean"
         },
@@ -1198,14 +1255,82 @@
         "push.js"
       ]
     },
-    "agent:list": {
+    "challenge:runs:get": {
+      "aliases": [],
+      "args": {
+        "runId": {
+          "description": "Run ID to get details for",
+          "name": "runId",
+          "required": true
+        }
+      },
+      "description": "Get details and logs for a specific run",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> abc123",
+        "<%= config.bin %> <%= command.id %> abc123 --no-logs"
+      ],
+      "flags": {
+        "no-logs": {
+          "description": "Skip fetching and displaying logs",
+          "name": "no-logs",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-url": {
+          "description": "Kradle Web API URL",
+          "env": "KRADLE_API_URL",
+          "name": "api-url",
+          "required": true,
+          "default": "https://api.kradle.ai/v0",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:runs:get",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "runs",
+        "get.js"
+      ]
+    },
+    "challenge:runs:list": {
       "aliases": [],
       "args": {},
-      "description": "List all agents",
+      "description": "List recent runs",
       "examples": [
-        "<%= config.bin %> <%= command.id %>"
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --limit 20"
       ],
       "flags": {
+        "limit": {
+          "char": "n",
+          "description": "Number of runs to display",
+          "name": "limit",
+          "default": 10,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "api-key": {
           "description": "Kradle API key",
           "env": "KRADLE_API_KEY",
@@ -1228,7 +1353,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:list",
+      "id": "challenge:runs:list",
       "pluginAlias": "kradle",
       "pluginName": "kradle",
       "pluginType": "core",
@@ -1238,10 +1363,11 @@
       "relativePath": [
         "dist",
         "commands",
-        "agent",
+        "challenge",
+        "runs",
         "list.js"
       ]
     }
   },
-  "version": "0.4.1"
+  "version": "0.4.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kradle",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -310,13 +310,15 @@ kradle challenge watch my-challenge
 
 ### `kradle challenge run <name>`
 
-Runs a challenge with configured participants.
+Runs a challenge with configured participants and waits for completion.
 
 **Usage:**
 ```bash
 kradle challenge run <challenge-name>
 kradle challenge run <challenge-name> --studio
 kradle challenge run <team-name>:<challenge-name>
+kradle challenge run <challenge-name> --no-open
+kradle challenge run <challenge-name> --no-wait
 ```
 
 **Arguments:**
@@ -325,10 +327,20 @@ kradle challenge run <team-name>:<challenge-name>
 | `challenge-name` | Challenge to run. Can be a short slug (e.g., `my-challenge`) or include a team/user namespace (e.g., `team-name:my-challenge`). The namespace is useful for running public challenges owned by other teams. If no namespace is provided, it defaults to the user's own namespace. | Yes |
 
 **Flags:**
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--studio` | Run in local studio environment instead of production | false |
-| `--open` | Open the run URL in the browser | false |
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--studio` | `-s` | Run in local studio environment instead of production |
+| `--no-open` | | Don't open the run URL in the browser |
+| `--no-wait` | | Don't wait for completion (fire and forget) |
+| `--no-summary` | | Don't wait for the AI-generated summary |
+
+**Behavior:**
+1. Creates a run with the challenge and participants from `template-run.json`
+2. Opens the run URL in the browser (unless `--no-open`)
+3. Polls every 2 seconds for status changes until completion (unless `--no-wait`)
+4. Displays the final outcome including status, duration, and participant results
+
+**Terminal states:** The polling stops when the run reaches: `finished`, `game_over`, `error`, or `completed`.
 
 **Prerequisites:**
 - `template-run.json` must exist in project root with participant configuration
@@ -352,7 +364,7 @@ kradle challenge run <team-name>:<challenge-name>
 
 **Examples:**
 ```bash
-# Run your own challenge in production
+# Run and wait for completion (default behavior)
 kradle challenge run my-challenge
 
 # Run a public challenge from another team
@@ -360,6 +372,115 @@ kradle challenge run team-kradle:battle-royale
 
 # Run in local studio
 kradle challenge run my-challenge --studio
+
+# Run without opening browser
+kradle challenge run my-challenge --no-open
+
+# Fire and forget (don't wait for completion)
+kradle challenge run my-challenge --no-wait
+
+# Fire and forget without browser
+kradle challenge run my-challenge --no-open --no-wait
+```
+
+---
+
+### `kradle challenge runs list`
+
+Lists recent runs for the authenticated user.
+
+**Usage:**
+```bash
+kradle challenge runs list
+kradle challenge runs list --limit 20
+```
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--limit` | `-n` | Number of runs to display | 10 |
+
+**Output format:**
+```
+Runs:
+
+ID              Challenge                       Status          End State       Duration     Created
+---------------------------------------------------------------------------------------------------------
+abc123def...    username:my-challenge           finished        game_over       45.3s        1/15/2025, 2:30 PM
+xyz789abc...    team-kradle:example             error           -               12.1s        1/15/2025, 2:15 PM
+```
+
+**Status colors:**
+- Green: `finished`, `game_over`, `completed`
+- Blue: `started`
+- Yellow: `initializing`, `created`
+- Red: `error`
+
+**Examples:**
+```bash
+# List 10 most recent runs (default)
+kradle challenge runs list
+
+# List 20 most recent runs
+kradle challenge runs list --limit 20
+
+# List 5 runs
+kradle challenge runs list -n 5
+```
+
+---
+
+### `kradle challenge runs get <run-id>`
+
+Gets details and optionally logs for a specific run.
+
+**Usage:**
+```bash
+kradle challenge runs get <run-id>
+kradle challenge runs get <run-id> --no-logs
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `run-id` | The ID of the run to get details for | Yes |
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--no-logs` | Skip fetching and displaying logs | false |
+
+**Output sections:**
+
+1. **Run Result** - Metadata about the run:
+   - ID, Challenge, Status, End State, Finished Status, Duration, End Time
+
+2. **Aggregated Results** - Summary statistics:
+   - Total participants, successful count, unsuccessful count, total time
+
+3. **Participant Results** - Per-participant breakdown (table format):
+   - Participant ID, Agent name, Winner status, Score, Time to Success
+
+4. **Logs** - Log entries from the run (unless `--no-logs` is used):
+   - Timestamp, Level (colored), Participant ID, Message
+   - JSON messages are automatically parsed and formatted
+
+**Log level colors:**
+- Red: `error`
+- Yellow: `warn`, `warning`
+- Blue: `info`
+- Dim: `debug`
+
+**Examples:**
+```bash
+# Get full details including logs
+kradle challenge runs get abc123def456
+
+# Get details without logs (faster)
+kradle challenge runs get abc123def456 --no-logs
+
+# Get details for a run (full ID)
+kradle challenge runs get 12345678-1234-1234-1234-123456789012
 ```
 
 ---
@@ -1024,7 +1145,9 @@ kradle challenge build --all --visibility public
 | `kradle challenge list` | List all challenges |
 | `kradle challenge pull [name]` | Pull challenge from cloud |
 | `kradle challenge watch <name>` | Watch and auto-rebuild |
-| `kradle challenge run <name>` | Run challenge |
+| `kradle challenge run <name>` | Run challenge and wait for completion |
+| `kradle challenge runs list` | List recent runs |
+| `kradle challenge runs get <run-id>` | Get details and logs for a run |
 | `kradle experiment create <name>` | Create new experiment |
 | `kradle experiment run <name>` | Run/resume experiment |
 | `kradle experiment recordings <name>` | Download recordings |