kradle 0.6.14 → 0.7.0

package/README.md

@@ -233,6 +233,8 @@ This displays:
 - Participant results (agent, winner status, score)
 - Log entries with timestamps and levels (unless `--no-logs` is used)
 
+If the run is still finalising (status `game_over`), the command waits automatically for scores and end state to be written before displaying results.
+
 ## 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.
@@ -462,6 +464,8 @@ The CLI uses GitHub Actions for automated releases. To publish a new version:
 4. **Review and merge** the automatically created PR
 5. **Done!** The package is automatically published to npm when the PR is merged
 
+For full deployment instrucitons, see this [notion doc](https://www.notion.so/CLI-SDK-How-to-test-release-2f13a5a82da68040818fe4a545afa0af)
+
 
 ## Development
 

package/bin/run.js

@@ -5,6 +5,9 @@ import path from "node:path";
 import fs from "node:fs";
 import dotenv from "dotenv";
 
+process.stdout.setDefaultEncoding("utf8");
+process.stderr.setDefaultEncoding("utf8");
+
 // Load .env file from cwd if it exists
 const envPath = path.join(process.cwd(), ".env");
 if (fs.existsSync(envPath)) {

package/dist/commands/challenge/run.js

@@ -5,10 +5,9 @@ import { ApiClient } from "../../lib/api-client.js";
 import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
-import { clearScreen, formatDuration, fuzzyHighlight, getRunStatusDisplay, openInBrowser } from "../../lib/utils.js";
+import { clearScreen, formatDuration, fuzzyHighlight, getRunStatusDisplay, openInBrowser, TERMINAL_STATUSES, } 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";
     // Allow variadic arguments for inline agent specification

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

@@ -2,7 +2,9 @@ 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";
+import { formatDuration, formatTime, sleep, TERMINAL_STATUSES } from "../../../lib/utils.js";
+const FINALISE_POLL_MS = 2000;
+const FINALISE_TIMEOUT_MS = 120_000;
 function getLogLevelColor(level) {
     switch (level.toLowerCase()) {
         case "error":
@@ -54,6 +56,24 @@ export default class GetRun extends Command {
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         const showLogs = !flags["no-logs"];
         this.log(pc.blue(`>> Loading run ${args.runId}...`));
+        // Scores and endState aren't written until the run transitions from
+        // game_over → finished. Poll briefly to avoid returning incomplete data.
+        const initial = await api.getRunStatus(args.runId);
+        if (initial.status === "game_over") {
+            this.log(pc.dim("  Run is finalising, waiting..."));
+            const deadline = Date.now() + FINALISE_TIMEOUT_MS;
+            let timedOut = true;
+            while (Date.now() < deadline) {
+                const status = await api.getRunStatus(args.runId);
+                if (TERMINAL_STATUSES.includes(status.status)) {
+                    timedOut = false;
+                    break;
+                }
+                await sleep(FINALISE_POLL_MS);
+            }
+            if (timedOut)
+                this.log(pc.yellow("  Timed out waiting for finalisation — results may be incomplete."));
+        }
         try {
             const [runResult, logs] = await Promise.all([
                 api.getRunResult(args.runId),

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

@@ -13,6 +13,7 @@ export default class Run extends Command {
         "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>;
+        "hide-participant-names": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/experiment/run.js

@@ -38,6 +38,10 @@ export default class Run extends Command {
             description: "Automatically download logs after each run finishes",
             default: false,
         }),
+        "hide-participant-names": Flags.boolean({
+            description: "Replace participant names with Player1, Player2, etc. to prevent models inferring opponents from their names",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url", "web-url"),
     };
     async run() {
@@ -63,6 +67,7 @@ export default class Run extends Command {
                 openMetabase: true,
                 downloadRecordings: flags["download-recordings"],
                 downloadLogs: flags["download-logs"],
+                hideParticipantNames: flags["hide-participant-names"],
             });
             this.log(pc.green("\n✓ Experiment complete!"));
         }

package/dist/config/releases/arena-minecraft.d.ts

@@ -1 +1 @@
-export declare const MINECRAFT_ARENA_MANAGER_TAG = "14f7331";
+export declare const MINECRAFT_ARENA_MANAGER_TAG = "69ce836";

package/dist/config/releases/arena-minecraft.js

@@ -1,2 +1,2 @@
 // Managed by https://github.com/Kradle-ai/arena-minecraft/actions/workflows/release.yaml
-export const MINECRAFT_ARENA_MANAGER_TAG = "14f7331";
+export const MINECRAFT_ARENA_MANAGER_TAG = "69ce836";

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

@@ -77,6 +77,7 @@ export declare class ApiClient {
         participants: unknown[];
         jobType: "background" | "foreground" | "foreground_with_recording";
         env?: "cloud" | "studio";
+        hideParticipantNames?: boolean;
     }): Promise<{
         runIds?: string[] | undefined;
         participants?: Record<string, {

package/dist/lib/experiment/experimenter.js

@@ -260,14 +260,16 @@ export class Experimenter {
         // Fetch the user's slug to prefix tags for uniqueness
         const human = await this.api.getHuman();
         const prefix = human.username;
-        // We have 2 mandatory tags: "<user>(<exp-name>)" and "<user>(<exp-name>-v<version>)"
-        const experimentTag = `${prefix}(exp-${this.name})`;
-        const versionTag = `${prefix}(exp-${this.name}-v${version})`;
+        // We have 2 mandatory tags: "<user>-exp-<name>" and "<user>-exp-<name>-v<version>"
+        // Use hyphens as delimiters — the API requires tags to start and end with alphanumerics.
+        const experimentTag = `${prefix}-exp-${this.name}`;
+        const versionTag = `${prefix}-exp-${this.name}-v${version}`;
         const tags = [experimentTag, versionTag, ...(manifest.tags ?? [])];
         // Create runner
         this.runner = new Runner(manifest.runs, this.api, this.webUrl, {
             maxConcurrent: options.maxConcurrent,
             tags: tags,
+            hideParticipantNames: options.hideParticipantNames,
             onStateChange: () => this.onRunStateChange(),
             onRunComplete: options.downloadRecordings || options.downloadLogs
                 ? async (index, runId) => {

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

@@ -11,11 +11,13 @@ export declare class Runner {
     private stopped;
     private maxConcurrent;
     private tags;
+    private hideParticipantNames;
     private onStateChange?;
     private onRunComplete?;
     constructor(runs: RunConfig[], api: ApiClient, baseUrl: string, options?: {
         maxConcurrent?: number;
         tags?: string[];
+        hideParticipantNames?: boolean;
         onStateChange?: (index: number, state: RunState) => void;
         onRunComplete?: (index: number, runId: string) => Promise<void>;
     });
@@ -67,10 +69,6 @@ export declare class Runner {
      * Main execution loop
      */
     execute(): Promise<void>;
-    /**
-     * Helper for delays
-     */
-    private delay;
     /**
      * Get progress entries for saving
      */

package/dist/lib/experiment/runner.js

@@ -1,3 +1,4 @@
+import { sleep } from "../utils.js";
 const DEFAULT_MAX_CONCURRENT = 5;
 const STATUS_POLL_INTERVAL_MS = 2000;
 const MAX_START_RUN_TRIES = 10;
@@ -20,6 +21,7 @@ export class Runner {
     stopped = false;
     maxConcurrent;
     tags;
+    hideParticipantNames;
     onStateChange;
     onRunComplete;
     constructor(runs, api, baseUrl, options = {}) {
@@ -28,10 +30,11 @@ export class Runner {
         this.baseUrl = baseUrl;
         this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
         this.tags = options.tags ?? [];
-        // Validate tags respect regex
+        this.hideParticipantNames = options.hideParticipantNames ?? false;
+        // Validate tags match API rules: start and end with alphanumeric, 3-36 chars total.
         for (const tag of this.tags) {
-            if (!/^[a-zA-Z0-9()][a-zA-Z0-9()-]{1,34}[a-zA-Z0-9()]$/.test(tag)) {
-                throw new Error(`Invalid tag: ${tag}. Tags must start and end with a letter or number, and can only contain letters, numbers, hyphens, underscores, and parentheses.`);
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9()-]{1,34}[a-zA-Z0-9]$/.test(tag)) {
+                throw new Error(`Invalid tag: ${tag}. Tags must start and end with a letter or number, and can only contain letters, numbers, hyphens, and parentheses.`);
             }
         }
         this.onStateChange = options.onStateChange;
@@ -54,7 +57,9 @@ export class Runner {
                 state.runId = entry.runId;
                 state.participantIds = entry.participantIds;
                 state.startTime = entry.startTime;
-                if (entry.status === "completed" || entry.status === "finished" || entry.status === "game_over") {
+                // game_over is not terminal — data isn't written until finished.
+                // Leave game_over runs out of completedRuns so resumeInFlightRuns re-polls them.
+                if (entry.status === "completed" || entry.status === "finished") {
                     this.completedRuns.add(entry.index);
                 }
                 else if (entry.status === "error") {
@@ -108,7 +113,7 @@ export class Runner {
         let queued = 0;
         let errors = 0;
         for (const state of this.states) {
-            if (state.status === "completed" || state.status === "finished" || state.status === "game_over") {
+            if (state.status === "completed" || state.status === "finished") {
                 completed++;
             }
             else if (state.status === "error") {
@@ -162,6 +167,7 @@ export class Runner {
                 challenge: state.config.challenge_slug,
                 participants: state.config.participants,
                 jobType: "background",
+                hideParticipantNames: this.hideParticipantNames || undefined,
             });
             if (!response.runIds || response.runIds.length === 0) {
                 throw new Error("No run ID returned from API");
@@ -191,7 +197,7 @@ export class Runner {
                 // Re-queue for later
                 this.updateState(index, { status: "queued", error: undefined });
                 this.activeRuns.delete(index);
-                await this.delay(getBackoffTime(tries));
+                await sleep(getBackoffTime(tries));
                 await this.startRun(index, tries + 1);
                 return;
             }
@@ -209,10 +215,11 @@ export class Runner {
                 const status = await this.api.getRunStatus(runId);
                 const normalizedStatus = this.normalizeStatus(status.status);
                 this.updateState(index, { status: normalizedStatus });
-                if (normalizedStatus === "completed" || normalizedStatus === "finished" || normalizedStatus === "game_over") {
+                // game_over means gameplay ended but the PUT /end hasn't fired yet —
+                // keep polling so onRunComplete receives complete data.
+                if (normalizedStatus === "completed" || normalizedStatus === "finished") {
                     this.completedRuns.add(index);
                     this.activeRuns.delete(index);
-                    // Trigger recording download if callback provided
                     if (this.onRunComplete) {
                         // Don't await - run in background to avoid blocking
                         this.onRunComplete(index, runId).catch(() => {
@@ -226,11 +233,11 @@ export class Runner {
                     this.activeRuns.delete(index);
                     return;
                 }
-                await this.delay(STATUS_POLL_INTERVAL_MS);
+                await sleep(STATUS_POLL_INTERVAL_MS);
             }
             catch (error) {
                 // Network error, continue polling
-                await this.delay(STATUS_POLL_INTERVAL_MS * 2);
+                await sleep(STATUS_POLL_INTERVAL_MS * 2);
             }
         }
         this.activeRuns.delete(index);
@@ -275,22 +282,16 @@ export class Runner {
                 // Don't await - run concurrently
                 this.startRun(index);
                 // Wait a bit to avoid overwhelming the API
-                await this.delay(350);
+                await sleep(350);
             }
             // Wait a bit before checking again
-            await this.delay(500);
+            await sleep(500);
         }
         // Wait for active runs to complete
         while (this.activeRuns.size > 0 && !this.stopped) {
-            await this.delay(500);
+            await sleep(500);
         }
     }
-    /**
-     * Helper for delays
-     */
-    delay(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
     /**
      * Get progress entries for saving
      */

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

@@ -30,11 +30,11 @@ export declare const ProgressEntrySchema: z.ZodObject<{
     index: z.ZodNumber;
     status: z.ZodEnum<{
         finished: "finished";
-        game_over: "game_over";
+        error: "error";
         completed: "completed";
+        game_over: "game_over";
         started: "started";
         initializing: "initializing";
-        error: "error";
         queued: "queued";
         watcher_connected: "watcher_connected";
         participants_connected: "participants_connected";
@@ -53,11 +53,11 @@ export declare const ProgressSchema: z.ZodObject<{
         index: z.ZodNumber;
         status: z.ZodEnum<{
             finished: "finished";
-            game_over: "game_over";
+            error: "error";
             completed: "completed";
+            game_over: "game_over";
             started: "started";
             initializing: "initializing";
-            error: "error";
             queued: "queued";
             watcher_connected: "watcher_connected";
             participants_connected: "participants_connected";
@@ -106,6 +106,7 @@ export interface ExperimentOptions {
     openMetabase?: boolean;
     downloadRecordings?: boolean;
     downloadLogs?: boolean;
+    hideParticipantNames?: boolean;
 }
 export declare const STATUS_ICONS: Record<RunStatus, {
     icon: string;

package/dist/lib/experiment/types.js

@@ -64,7 +64,7 @@ export const STATUS_ICONS = {
     running: { icon: "▶", color: "magenta" },
     recovering: { icon: "⟳", color: "cyan" },
     completed: { icon: "✓", color: "green" },
-    game_over: { icon: "✓", color: "green" },
+    game_over: { icon: "⟳", color: "cyan" },
     finished: { icon: "✓", color: "green" },
     error: { icon: "✗", color: "red" },
 };

package/dist/lib/schemas.d.ts

@@ -67,6 +67,7 @@ export declare const ChallengeSchema: z.ZodObject<{
         tickRate: z.ZodOptional<z.ZodNumber>;
         startLives: z.ZodOptional<z.ZodNumber>;
         watcherCommands: z.ZodOptional<z.ZodString>;
+        hideRoleAssignments: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     description: z.ZodOptional<z.ZodString>;
     task: z.ZodOptional<z.ZodString>;
@@ -114,6 +115,7 @@ export declare const ChallengeConfigSchema: z.ZodObject<{
         tickRate: z.ZodOptional<z.ZodNumber>;
         startLives: z.ZodOptional<z.ZodNumber>;
         watcherCommands: z.ZodOptional<z.ZodString>;
+        hideRoleAssignments: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     task: z.ZodOptional<z.ZodString>;
     scoreLabel: z.ZodOptional<z.ZodString>;
@@ -164,6 +166,7 @@ export declare const ChallengesResponseSchema: z.ZodObject<{
             tickRate: z.ZodOptional<z.ZodNumber>;
             startLives: z.ZodOptional<z.ZodNumber>;
             watcherCommands: z.ZodOptional<z.ZodString>;
+            hideRoleAssignments: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>;
         description: z.ZodOptional<z.ZodString>;
         task: z.ZodOptional<z.ZodString>;

package/dist/lib/schemas.js

@@ -34,6 +34,7 @@ export const ChallengeSchema = z.object({
         tickRate: z.number().min(5).max(25).optional(),
         startLives: z.number().optional(),
         watcherCommands: z.string().optional(),
+        hideRoleAssignments: z.boolean().optional(),
     }),
     description: z.string().optional(),
     task: z.string().optional(),

package/dist/lib/utils.d.ts

@@ -93,6 +93,10 @@ export declare function loadTypescriptExport(filePath: string, exportName: strin
  * @param url The URL to open.
  */
 export declare function openInBrowser(url: string): void;
+/** Run statuses that indicate a run is fully complete and data is written. */
+export declare const TERMINAL_STATUSES: string[];
+/** Sleep for the given number of milliseconds. */
+export declare function sleep(ms: number): Promise<void>;
 /**
  * Format a duration in milliseconds to a human-readable string.
  * @param ms Duration in milliseconds

package/dist/lib/utils.js

@@ -209,6 +209,12 @@ export function openInBrowser(url) {
     }
     exec(command);
 }
+/** Run statuses that indicate a run is fully complete and data is written. */
+export const TERMINAL_STATUSES = ["finished", "error", "completed", "cancelled", "timeout", "failed"];
+/** Sleep for the given number of milliseconds. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Format a duration in milliseconds to a human-readable string.
  * @param ms Duration in milliseconds
@@ -243,9 +249,10 @@ export function formatTime(isoString) {
 export function getRunStatusDisplay(status) {
     switch (status) {
         case "finished":
-        case "game_over":
         case "completed":
             return pc.green(status);
+        case "game_over":
+            return pc.cyan(status);
         case "started":
             return pc.blue(status);
         case "initializing":

package/oclif.manifest.json

@@ -1046,6 +1046,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "hide-participant-names": {
+          "description": "Replace participant names with Player1, Player2, etc. to prevent models inferring opponents from their names",
+          "name": "hide-participant-names",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "api-key": {
           "description": "Kradle API key",
           "env": "KRADLE_API_KEY",
@@ -1543,5 +1549,5 @@
       ]
     }
   },
-  "version": "0.6.14"
+  "version": "0.7.0"
 }

package/package.json

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