kradle 0.3.1 → 0.4.0

package/README.md

@@ -18,18 +18,19 @@ Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
 
 ## Installation
 
+Make sure you have [NodeJS 22.18 or higher](https://nodejs.org/en/download/current) installed.
+
 1. Install Kradle's CLI globally
 ```
 npm i -g kradle
 ```
-2. Initialize a new directory to store challenges and experiments
+2. Initialize a new directory to store challenges, and other Kradle resources:
 ```
 kradle init
 ```
-3. Congrats 🎉 You can now create a new challenge or a new experiment:
+3. Congrats 🎉 You can now create a new challenge:
 ```
 kradle challenge create <challenge-name>
-kradle experiment create <experiment-name>
 ```
 
 In addition, you can enable [autocomplete](#Autocomplete).
@@ -184,6 +185,7 @@ kradle experiment run <name>                       # Resume current version or c
 kradle experiment run <name> --new-version         # Start a new version
 kradle experiment run <name> --max-concurrent 10   # Control parallelism (default: 5)
 kradle experiment run <name> --download-recordings # Auto-download recordings as runs complete
+kradle experiment run <name> --download-logs       # Auto-download logs as runs complete
 ```
 
 The run command:
@@ -207,6 +209,21 @@ kradle experiment recordings <name> <run-id> --all   # Download all participants
 
 Recordings are saved to `experiments/<name>/versions/<version>/recordings/<run-id>/`.
 
+### Download Logs
+
+Download logs and run results from completed experiment runs:
+
+```bash
+kradle experiment logs <name>                  # Interactive selection of run
+kradle experiment logs <name> <run-id>         # Download specific run
+kradle experiment logs <name> --all            # Download all runs
+kradle experiment logs <name> --version 2      # Download from specific version
+```
+
+Files are saved to `experiments/<name>/versions/<version>/logs/<run-id>/`:
+- `run.json` - Run result with status, end_state, and participant results
+- `logs.json` - Log entries from the run
+
 ### List Experiments
 
 List all local experiments:

package/dist/commands/challenge/list.js

@@ -13,13 +13,14 @@ export default class List extends Command {
         const { flags } = await this.parse(List);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         this.log(pc.blue(">> Loading challenges..."));
-        const [cloudChallenges, localChallenges, human] = await Promise.all([
+        const [cloudChallenges, kradleChallenges, localChallenges, human] = await Promise.all([
             api.listChallenges(),
+            api.listKradleChallenges(),
             Challenge.getLocalChallenges(),
             api.getHuman(),
         ]);
-        // Create a map for easy lookup
-        const cloudMap = new Map(cloudChallenges.map((c) => [c.slug, c]));
+        // Create a map for easy lookup (user's challenges + team-kradle challenges)
+        const cloudMap = new Map([...cloudChallenges, ...kradleChallenges].map((c) => [c.slug, c]));
         const allSlugs = new Set([...cloudMap.keys(), ...localChallenges.map((id) => `${human.username}:${id}`)]);
         this.log(pc.bold("\nChallenges:\n"));
         this.log(`${"Status".padEnd(15)} ${"Slug".padEnd(40)} ${"Name".padEnd(30)}`);

package/dist/commands/challenge/pull.js

@@ -1,14 +1,12 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import path from "node:path";
 import { Command, Flags } from "@oclif/core";
 import enquirer from "enquirer";
 import { Listr } from "listr2";
 import pc from "picocolors";
-import * as tar from "tar";
 import { ApiClient } from "../../lib/api-client.js";
 import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
-import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
+import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Pull extends Command {
     static description = "Pull a challenge from the cloud and extract source files locally";
@@ -97,67 +95,16 @@ export default class Pull extends Command {
                 return;
             }
         }
-        const tempTarballPath = path.join(flags["challenges-path"], `${challenge.shortSlug}-pull-temp.tar.gz`);
         const tasks = new Listr([
             {
-                title: "Downloading challenge",
-                task: async (_, task) => {
-                    const { downloadUrl } = await api.getChallengeDownloadUrl(challengeSlug);
-                    const response = await fetch(downloadUrl);
-                    if (!response.ok) {
-                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
-                    }
-                    const buffer = await response.arrayBuffer();
-                    await fs.mkdir(path.dirname(tempTarballPath), { recursive: true });
-                    await fs.writeFile(tempTarballPath, Buffer.from(buffer));
-                    task.title = "Downloaded challenge";
-                },
-            },
-            {
-                title: "Creating challenge directory",
+                title: "Downloading and extracting source files",
                 task: async (_, task) => {
                     await fs.mkdir(challenge.challengeDir, { recursive: true });
-                    task.title = `Created directory: ${challenge.challengeDir}`;
-                },
-            },
-            {
-                title: "Extracting source files",
-                task: async (_, task) => {
-                    const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
-                    const tempExtractDir = path.join(flags["challenges-path"], `${challenge.shortSlug}-extract-temp`);
-                    await fs.mkdir(tempExtractDir, { recursive: true });
-                    try {
-                        await tar.extract({
-                            file: tempTarballPath,
-                            cwd: tempExtractDir,
-                            filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
-                        });
-                        const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
-                        const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
-                        let extractedCount = 0;
-                        if (existsSync(srcChallengeTs)) {
-                            await fs.copyFile(srcChallengeTs, challenge.challengePath);
-                            extractedCount++;
-                        }
-                        if (existsSync(srcConfigTs)) {
-                            await fs.copyFile(srcConfigTs, challenge.configPath);
-                            extractedCount++;
-                        }
-                        if (extractedCount === 0) {
-                            throw new Error(`No source files found in tarball. The challenge may not have been built with source files.`);
-                        }
-                        task.title = `Extracted ${extractedCount} source file(s)`;
+                    const extractedCount = await Challenge.downloadSourceFiles(api, challengeSlug, challenge.challengeDir);
+                    if (extractedCount === 0) {
+                        throw new Error("No source files found in tarball. The challenge may not have been built with source files.");
                     }
-                    finally {
-                        await fs.rm(tempExtractDir, { recursive: true, force: true });
-                    }
-                },
-            },
-            {
-                title: "Cleaning up",
-                task: async (_, task) => {
-                    await fs.rm(tempTarballPath, { force: true });
-                    task.title = "Cleaned up temporary files";
+                    task.title = `Extracted ${extractedCount} source file(s)`;
                 },
             },
             {
@@ -175,7 +122,6 @@ export default class Pull extends Command {
             this.log(pc.dim(`  → config.ts: ${challenge.configPath}`));
         }
         catch (error) {
-            await fs.rm(tempTarballPath, { force: true }).catch(() => { });
             this.error(pc.red(`Pull failed: ${error instanceof Error ? error.message : String(error)}`));
         }
     }

package/dist/commands/challenge/watch.js

@@ -33,6 +33,9 @@ export default class Watch extends Command {
             // Clear screen before subsequent rebuilds for clean output
             clearScreen();
             this.log(pc.cyan(`\n  Rebuild started...\n`));
+            // Track if config changed so we can force tarball re-upload
+            // (tarball includes source files which contain config.ts)
+            let configChanged = false;
             const tasks = new Listr([
                 {
                     title: "Checking configuration",
@@ -42,6 +45,7 @@ export default class Watch extends Command {
                             task.title = "Uploading configuration";
                             await api.updateChallenge(challenge.shortSlug, newConfig, "private");
                             lastConfig = newConfig;
+                            configChanged = true;
                             task.title = "Configuration uploaded";
                         }
                         else {
@@ -61,7 +65,8 @@ export default class Watch extends Command {
                     title: "Checking datapack changes",
                     task: async (_ctx, task) => {
                         const newHash = await challenge.getDatapackHash();
-                        if (newHash !== lastHash) {
+                        // Upload if datapack changed OR if config changed (since tarball includes source files)
+                        if (newHash !== lastHash || configChanged) {
                             task.title = "Uploading datapack";
                             await api.uploadChallengeDatapack(challenge.shortSlug, challenge.tarballPath);
                             lastHash = newHash;

package/dist/commands/experiment/logs.d.ts

@@ -0,0 +1,18 @@
+import { Command } from "@oclif/core";
+export default class Logs extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        experimentName: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        runId: import("@oclif/core/interfaces").Arg<string | undefined, 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>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private downloadForExperiment;
+    private downloadLogs;
+}

package/dist/commands/experiment/logs.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Args, Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { Experimenter } from "../../lib/experiment/experimenter.js";
+import { getConfigFlags } from "../../lib/flags.js";
+// Get all versions for an experiment
+async function getAllVersions(experimentDir) {
+    const versionsDir = path.join(experimentDir, "versions");
+    try {
+        const entries = await fs.readdir(versionsDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory())
+            .map((e) => parseInt(e.name, 10))
+            .filter((n) => !Number.isNaN(n))
+            .sort((a, b) => a - b);
+    }
+    catch {
+        return [];
+    }
+}
+export default class Logs extends Command {
+    static description = "Download logs from an experiment run";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-experiment",
+        "<%= config.bin %> <%= command.id %> my-experiment <run-id>",
+        "<%= config.bin %> <%= command.id %> my-experiment --all",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 2",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 1 --all",
+    ];
+    static args = {
+        experimentName: Args.string({
+            description: "Experiment name",
+            required: true,
+        }),
+        runId: Args.string({
+            description: "Specific run ID to download logs from (optional)",
+            required: false,
+        }),
+    };
+    static flags = {
+        all: Flags.boolean({
+            description: "Download logs for all runs",
+            default: false,
+        }),
+        version: Flags.integer({
+            description: "Specific experiment version to download logs from (e.g., 0, 1, 2)",
+            required: false,
+        }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Logs);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const { experimentName, runId } = args;
+        await this.downloadForExperiment(experimentName, runId, api, flags.all, flags.version);
+    }
+    async downloadForExperiment(experimentName, runId, api, all, version) {
+        const experimenter = new Experimenter(experimentName, "", api);
+        // Check if experiment exists
+        if (!(await experimenter.exists())) {
+            this.error(pc.red(`Experiment '${experimentName}' does not exist. Run 'kradle experiment list' to see available experiments.`));
+        }
+        const experimentDir = experimenter.experimentDir;
+        // Get all versions
+        const allVersions = await getAllVersions(experimentDir);
+        if (allVersions.length === 0) {
+            this.error(pc.red("No experiment versions found. Run the experiment first."));
+        }
+        // Default to latest version if not specified
+        let targetVersion;
+        if (version !== undefined) {
+            if (!allVersions.includes(version)) {
+                this.error(pc.red(`Version ${version} not found in experiment '${experimentName}'. ` +
+                    `Available versions: ${allVersions.join(", ")}`));
+            }
+            targetVersion = version;
+            this.log(pc.blue(`>> Filtering to version ${version}`));
+        }
+        else {
+            // Default to latest version
+            targetVersion = Math.max(...allVersions);
+        }
+        const allRunInfos = [];
+        const completedStatuses = new Set(["completed", "finished", "game_over"]);
+        const progressPath = path.join(experimentDir, "versions", targetVersion.toString().padStart(3, "0"), "progress.json");
+        try {
+            const progressData = await fs.readFile(progressPath, "utf-8");
+            const progress = JSON.parse(progressData);
+            for (const entry of progress.entries) {
+                // Only include runs that are completed (exclude in-progress, queued, or error runs)
+                if (entry.runId && completedStatuses.has(entry.status)) {
+                    allRunInfos.push({
+                        version: targetVersion,
+                        runId: entry.runId,
+                        index: entry.index,
+                        status: entry.status,
+                        participantIds: entry.participantIds,
+                    });
+                }
+            }
+        }
+        catch { }
+        if (allRunInfos.length === 0) {
+            this.error(pc.yellow("No completed runs found. Wait for runs to finish or run the experiment first."));
+        }
+        let selectedRuns;
+        if (all && !runId) {
+            // Download all runs (--all without specific run)
+            selectedRuns = allRunInfos;
+            this.log(pc.blue(`>> Downloading logs for all ${selectedRuns.length} runs`));
+        }
+        else if (runId) {
+            // Find specific run by ID
+            const matchingRun = allRunInfos.find((r) => r.runId === runId);
+            if (!matchingRun) {
+                this.error(pc.red(`Run ID '${runId}' not found in experiment '${experimentName}'. ` +
+                    `Run 'kradle experiment logs ${experimentName}' to see available runs.`));
+            }
+            selectedRuns = [matchingRun];
+            this.log(pc.blue(`>> Downloading logs for run: ${runId}`));
+        }
+        else {
+            // Interactive run selection
+            const choices = [
+                // Only show "All runs" option if there are multiple runs
+                ...(allRunInfos.length > 1
+                    ? [
+                        {
+                            name: "all",
+                            message: `All runs (${allRunInfos.length} total)`,
+                            hint: "Download all",
+                        },
+                    ]
+                    : []),
+                ...allRunInfos.map((run) => {
+                    const participants = run.participantIds?.join(", ") || "No participants";
+                    return {
+                        name: run.runId,
+                        message: `${participants} - ${run.runId}`,
+                        hint: run.status,
+                    };
+                }),
+            ];
+            const { selectedRunId } = await enquirer.prompt({
+                type: "select",
+                name: "selectedRunId",
+                message: "Select a run to download logs from",
+                choices,
+            });
+            if (selectedRunId === "all") {
+                selectedRuns = allRunInfos;
+                this.log(pc.blue(`>> Downloading logs for all ${selectedRuns.length} runs`));
+            }
+            else {
+                const selectedRun = allRunInfos.find((r) => r.runId === selectedRunId);
+                if (!selectedRun) {
+                    this.error(pc.red("Selected run not found."));
+                }
+                selectedRuns = [selectedRun];
+            }
+        }
+        // Build download targets
+        const downloadTargets = selectedRuns.map((run) => ({
+            version: run.version,
+            runId: run.runId,
+            experimentDir,
+        }));
+        this.log(pc.blue(`>> Fetching and downloading logs for ${downloadTargets.length} run(s)...`));
+        await this.downloadLogs(api, downloadTargets);
+        const logsDir = path.join(experimentDir, "versions", targetVersion.toString().padStart(3, "0"), "logs");
+        this.log(pc.green(`\n Downloaded logs for ${downloadTargets.length} run(s) to ${logsDir}`));
+    }
+    async downloadLogs(api, targets) {
+        const allTasks = [];
+        for (const target of targets) {
+            const { version, runId, experimentDir } = target;
+            allTasks.push({
+                title: `${runId}`,
+                task: async (_, task) => {
+                    const runDir = path.join(experimentDir, "versions", version.toString().padStart(3, "0"), "logs", runId);
+                    const runPath = path.join(runDir, "run.json");
+                    const logsPath = path.join(runDir, "logs.json");
+                    // Fetch run result
+                    let runResult;
+                    try {
+                        runResult = await api.getRunResult(runId);
+                    }
+                    catch (error) {
+                        throw new Error(`Failed to fetch run result: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    // Fetch logs
+                    let logs = [];
+                    try {
+                        logs = await api.getRunLogs(runId);
+                    }
+                    catch (error) {
+                        throw new Error(`Failed to fetch logs: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    // Save run result and logs
+                    await fs.mkdir(runDir, { recursive: true });
+                    await fs.writeFile(runPath, JSON.stringify(runResult, null, 2));
+                    await fs.writeFile(logsPath, JSON.stringify(logs, null, 2));
+                    task.title = `${runId} (${logs.length} log entries)`;
+                },
+            });
+        }
+        if (allTasks.length === 0) {
+            return;
+        }
+        const tasks = new Listr(allTasks, {
+            concurrent: 3,
+            exitOnError: false,
+        });
+        await tasks.run();
+    }
+}

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

@@ -12,6 +12,7 @@ export default class Run extends Command {
         "new-version": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "max-concurrent": import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         "download-recordings": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "download-logs": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/experiment/run.js

@@ -33,6 +33,11 @@ export default class Run extends Command {
             description: "Automatically download recordings after each run finishes",
             default: false,
         }),
+        "download-logs": Flags.boolean({
+            char: "l",
+            description: "Automatically download logs after each run finishes",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url", "web-url"),
     };
     async run() {
@@ -57,6 +62,7 @@ export default class Run extends Command {
                 maxConcurrent: flags["max-concurrent"],
                 openMetabase: true,
                 downloadRecordings: flags["download-recordings"],
+                downloadLogs: flags["download-logs"],
             });
             this.log(pc.green("\n✓ Experiment complete!"));
         }

package/dist/commands/init.js

@@ -72,8 +72,7 @@ export default class Init extends Command {
             // 	this.log(pc.green("Using Kradle's production environment."));
             // }
             this.log();
-            this.log(pc.yellow("Cloud Analytics are only available in the development environment for now. Development environment will be used."));
-            const useDev = true;
+            const useDev = false;
             const domain = useDev ? "dev.kradle.ai" : "kradle.ai";
             let apiKey;
             if (flags["api-key"]) {

package/dist/commands/world/list.js

@@ -13,12 +13,13 @@ export default class List extends Command {
         const { flags } = await this.parse(List);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         this.log(pc.blue(">> Loading worlds..."));
-        const [cloudWorlds, localWorlds, human] = await Promise.all([
+        const [cloudWorlds, kradleWorlds, localWorlds, human] = await Promise.all([
             api.listWorlds(),
+            api.listKradleWorlds(),
             World.getLocalWorlds(),
             api.getHuman(),
         ]);
-        const cloudMap = new Map(cloudWorlds.map((w) => [w.slug, w]));
+        const cloudMap = new Map([...cloudWorlds, ...kradleWorlds].map((w) => [w.slug, w]));
         const allSlugs = new Set([...cloudMap.keys(), ...localWorlds.map((slug) => `${human.username}:${slug}`)]);
         this.log(pc.bold("\nWorlds:\n"));
         this.log(`${"Status".padEnd(15)} ${"Slug".padEnd(40)} ${"Name".padEnd(30)}`);

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

@@ -1,5 +1,5 @@
 import type z from "zod";
-import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DownloadUrlResponse, HumanSchema, type RecordingMetadata, 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 RunResultResponse, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
 export declare class ApiClient {
     private apiUrl;
     private kradleApiKey;
@@ -114,6 +114,18 @@ export declare class ApiClient {
      * @returns Download URL and expiration time.
      */
     getRecordingDownloadUrl(runId: string, participantId: string, timestamp: string): Promise<DownloadUrlResponse>;
+    /**
+     * Get logs for a run, and parse the message if it is a JSON object.
+     * @param runId - The ID of the run.
+     * @returns Array of log entries.
+     */
+    getRunLogs(runId: string): Promise<ParsedLogEntry[]>;
+    /**
+     * Get the result of a run.
+     * @param runId - The ID of the run.
+     * @returns Run result with status, end_state, and participant results.
+     */
+    getRunResult(runId: string): Promise<RunResultResponse>;
     listWorlds(): Promise<WorldSchemaType[]>;
     listKradleWorlds(): Promise<WorldSchemaType[]>;
     getWorld(slug: string): Promise<WorldSchemaType>;
@@ -130,4 +142,9 @@ export declare class ApiClient {
     getWorldUploadUrl(slug: string): Promise<string>;
     getWorldDownloadUrl(slug: string): Promise<DownloadUrlResponse>;
     uploadWorldFile(slug: string, tarballPath: string): Promise<void>;
+    /**
+     * Get the dashboard URL for the current environment.
+     * @returns The dashboard URL.
+     */
+    getDashboardUrl(): Promise<DashboardUrlResponse>;
 }

package/dist/lib/api-client.js

@@ -1,13 +1,13 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DashboardUrlResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunLogsResponseSchema, RunResultResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
 const DEFAULT_PAGE_SIZE = 30;
 const DEFAULT_CHALLENGE_SCHEMA = {
     slug: "",
     name: "",
     visibility: "private",
     domain: "minecraft",
-    world: "team-kradle:colosseum",
+    world: "team-kradle:flat-world",
     challengeConfig: { cheat: false, datapack: true, gameMode: "survival" },
     task: ".",
     roles: { "default-role": { description: "default-role", specificTask: "do your best!" } },
@@ -277,6 +277,40 @@ export class ApiClient {
         const url = `runs/${runId}/recordings/${participantId}/downloadUrl?timestamp=${encodeURIComponent(timestamp)}`;
         return this.get(url, {}, DownloadUrlResponseSchema);
     }
+    /**
+     * Get logs for a run, and parse the message if it is a JSON object.
+     * @param runId - The ID of the run.
+     * @returns Array of log entries.
+     */
+    async getRunLogs(runId) {
+        const url = `runs/${runId}/logs`;
+        const response = await this.get(url, {}, RunLogsResponseSchema);
+        return response.logs.map((log) => {
+            const { message, ...rest } = log;
+            try {
+                const parsedMessage = JSON.parse(message);
+                return {
+                    ...rest,
+                    parsedMessage: parsedMessage,
+                };
+            }
+            catch {
+                return {
+                    ...rest,
+                    message: message,
+                };
+            }
+        });
+    }
+    /**
+     * Get the result of a run.
+     * @param runId - The ID of the run.
+     * @returns Run result with status, end_state, and participant results.
+     */
+    async getRunResult(runId) {
+        const url = `runs/${runId}`;
+        return this.get(url, {}, RunResultResponseSchema);
+    }
     async listWorlds() {
         return this.listResource("worlds", "worlds", WorldsResponseSchema);
     }
@@ -343,4 +377,11 @@ export class ApiClient {
             throw new Error(`Failed to upload world: ${response.statusText}`);
         }
     }
+    /**
+     * Get the dashboard URL for the current environment.
+     * @returns The dashboard URL.
+     */
+    async getDashboardUrl() {
+        return this.get("dashboard", {}, DashboardUrlResponseSchema);
+    }
 }

package/dist/lib/challenge.d.ts

@@ -57,4 +57,12 @@ export declare class Challenge {
      * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
      */
     static createLocal(slug: string, kradleChallengesPath: string): Promise<void>;
+    /**
+     * Download challenge source files (challenge.ts and config.ts) from the cloud
+     * @param api - The API client to use
+     * @param slug - The challenge slug to download
+     * @param targetDir - The directory to save the source files to
+     * @returns The number of files extracted
+     */
+    static downloadSourceFiles(api: ApiClient, slug: string, targetDir: string): Promise<number>;
 }

package/dist/lib/challenge.js

@@ -194,4 +194,50 @@ export class Challenge {
         // Copy challenge.ts template
         await fs.copyFile(challengeTemplatePath, challenge.challengePath);
     }
+    /**
+     * Download challenge source files (challenge.ts and config.ts) from the cloud
+     * @param api - The API client to use
+     * @param slug - The challenge slug to download
+     * @param targetDir - The directory to save the source files to
+     * @returns The number of files extracted
+     */
+    static async downloadSourceFiles(api, slug, targetDir) {
+        const { downloadUrl } = await api.getChallengeDownloadUrl(slug);
+        const response = await fetch(downloadUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to download challenge "${slug}": ${response.status} ${response.statusText}`);
+        }
+        // Save tarball to temp location
+        const tempTarballPath = path.join(targetDir, `${slug}-temp.tar.gz`);
+        const buffer = await response.arrayBuffer();
+        await fs.mkdir(targetDir, { recursive: true });
+        await fs.writeFile(tempTarballPath, Buffer.from(buffer));
+        const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
+        const tempExtractDir = path.join(targetDir, `${slug}-extract-temp`);
+        try {
+            await fs.mkdir(tempExtractDir, { recursive: true });
+            await tar.extract({
+                file: tempTarballPath,
+                cwd: tempExtractDir,
+                filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
+            });
+            const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
+            const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
+            let extractedCount = 0;
+            if (existsSync(srcChallengeTs)) {
+                await fs.copyFile(srcChallengeTs, path.join(targetDir, "challenge.ts"));
+                extractedCount++;
+            }
+            if (existsSync(srcConfigTs)) {
+                await fs.copyFile(srcConfigTs, path.join(targetDir, "config.ts"));
+                extractedCount++;
+            }
+            return extractedCount;
+        }
+        finally {
+            // Clean up temp files
+            await fs.rm(tempExtractDir, { recursive: true, force: true });
+            await fs.rm(tempTarballPath, { force: true });
+        }
+    }
 }