@benchsdk/runner 0.3.0 → 0.5.2

package/dist/index.cjs

@@ -30,21 +30,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AuthError: () => import_cli4.AuthError,
   BENCHSDK_RUNNER_VERSION: () => BENCHSDK_RUNNER_VERSION,
+  BenchmarkApiError: () => import_api3.BenchmarkApiError,
+  BenchmarkConfigError: () => BenchmarkConfigError,
+  BenchmarkReporter: () => import_worker3.BenchmarkReporter,
   NoAvailableParticipantsError: () => NoAvailableParticipantsError,
   ScoringSpecError: () => ScoringSpecError,
   TaskError: () => TaskError,
+  claimBenchmarkReporter: () => import_worker3.claimBenchmarkReporter,
+  createApiClient: () => import_cli4.createApiClient,
+  createBenchmarkClient: () => import_api3.createBenchmarkClient,
+  createSystemMetricsCollector: () => import_worker3.createSystemMetricsCollector,
   defineBenchmarkConfig: () => defineBenchmarkConfig,
+  defineOnComplete: () => defineOnComplete,
   defineTask: () => defineTask,
+  filterParticipantsByEnv: () => import_worker3.filterParticipantsByEnv,
   higherIsBetter: () => higherIsBetter,
   lowerIsBetter: () => lowerIsBetter,
   mergeConfig: () => mergeConfig,
   parseCliArgs: () => parseCliArgs,
+  resolveAuth: () => import_cli4.resolveAuth,
   run: () => run,
   runBenchmark: () => runBenchmark,
   runBenchmarkFile: () => runBenchmarkFile,
+  runBenchmarkWorker: () => runBenchmarkWorker,
+  runWorker: () => import_worker3.runWorker,
   score: () => score,
   scoringConfigToSpec: () => scoringConfigToSpec,
+  selectParticipants: () => import_worker3.selectParticipants,
+  validateBenchmarkConfig: () => validateBenchmarkConfig,
   validateScoringSpec: () => validateScoringSpec
 });
 module.exports = __toCommonJS(src_exports);
@@ -54,14 +69,55 @@ var TaskError = class extends Error {
   code;
   data;
   steps;
+  step;
+  timeoutMs;
   constructor(message, opts) {
     super(message);
     this.name = "TaskError";
     this.code = opts?.code;
     this.data = opts?.data;
     this.steps = opts?.steps;
+    this.step = opts?.step;
+    this.timeoutMs = opts?.timeoutMs;
+  }
+  toString() {
+    let s = `[${this.name}${this.code ? ` (${this.code})` : ""}] ${this.message}`;
+    if (this.step) {
+      s += `
+  step: ${this.step}`;
+    }
+    if (this.timeoutMs !== void 0) {
+      s += `
+  timeoutMs: ${this.timeoutMs}`;
+    }
+    if (this.data && Object.keys(this.data).length > 0) {
+      s += `
+  data: ${JSON.stringify(this.data, null, 2)}`;
+    }
+    return s;
+  }
+};
+var BenchmarkConfigError = class _BenchmarkConfigError extends Error {
+  issues;
+  constructor(issues) {
+    super(_BenchmarkConfigError.formatIssues(issues));
+    this.name = "BenchmarkConfigError";
+    this.issues = issues;
+  }
+  static formatIssues(issues) {
+    const lines = issues.map((i) => `  - ${i.field}: ${i.message}`);
+    return `Invalid benchmark config:
+${lines.join("\n")}
+
+Fix the fields above and try again.`;
   }
 };
+function assertFiniteNumber(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${field} must be a finite number (got ${value})`);
+  }
+  return value;
+}
 function assertNonEmptyString(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new Error(`${field} must be a non-empty string`);
@@ -75,18 +131,6 @@ function assertOnlyAllowedKeys(value, allowed, field) {
     }
   }
 }
-function assertPositiveInt(value, field) {
-  if (value === void 0) return;
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`${field} must be an integer >= 1 (got ${value})`);
-  }
-}
-function assertFiniteNumber(value, field) {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    throw new Error(`${field} must be a finite number (got ${value})`);
-  }
-  return value;
-}
 function validateBenchmarkScoringConfig(scoring, display) {
   if (!Array.isArray(scoring.metrics) || scoring.metrics.length === 0) {
     throw new Error("scoring.metrics must be a non-empty array");
@@ -157,154 +201,236 @@ function validateBenchmarkScoringConfig(scoring, display) {
     throw new Error(`scoring metric weights must sum to 1.0 (got ${totalWeight.toFixed(3)})`);
   }
 }
+function validateBenchmarkDisplayConfig(display) {
+  if (typeof display !== "object" || display === null || Array.isArray(display)) {
+    throw new Error("display must be an object");
+  }
+  assertOnlyAllowedKeys(display, ["metrics", "steps", "overview"], "display");
+  const displayMetricKeys = /* @__PURE__ */ new Set();
+  if (display.metrics !== void 0) {
+    if (!Array.isArray(display.metrics)) {
+      throw new Error("display.metrics must be an array");
+    }
+    for (let i = 0; i < display.metrics.length; i++) {
+      const metric = display.metrics[i];
+      if (metric === null || typeof metric !== "object" || Array.isArray(metric)) {
+        throw new Error(`display.metrics[${i}] must be an object`);
+      }
+      assertOnlyAllowedKeys(metric, ["key", "label", "unit", "direction", "decimals", "order"], `display.metrics[${i}]`);
+      const key = assertNonEmptyString(metric.key, `display.metrics[${i}].key`);
+      if (displayMetricKeys.has(key)) {
+        throw new Error(`duplicate display metric key: ${key}`);
+      }
+      displayMetricKeys.add(key);
+      assertNonEmptyString(metric.label, `display.metrics[${i}].label`);
+      if (metric.unit !== void 0 && typeof metric.unit !== "string") {
+        throw new Error(`display.metrics[${i}].unit must be a string`);
+      }
+      if (metric.direction !== void 0 && metric.direction !== "higher-better" && metric.direction !== "lower-better") {
+        throw new Error(`display.metrics[${i}].direction must be 'higher-better' or 'lower-better'`);
+      }
+      if (metric.decimals !== void 0 && (!Number.isInteger(metric.decimals) || metric.decimals < 0)) {
+        throw new Error(`display.metrics[${i}].decimals must be a non-negative integer`);
+      }
+      if (metric.order !== void 0 && (!Number.isInteger(metric.order) || metric.order < 0)) {
+        throw new Error(`display.metrics[${i}].order must be a non-negative integer`);
+      }
+    }
+  }
+  if (display.steps !== void 0) {
+    if (!Array.isArray(display.steps)) {
+      throw new Error("display.steps must be an array");
+    }
+    const seenStepKeys = /* @__PURE__ */ new Set();
+    for (let i = 0; i < display.steps.length; i++) {
+      const step = display.steps[i];
+      if (step === null || typeof step !== "object" || Array.isArray(step)) {
+        throw new Error(`display.steps[${i}] must be an object`);
+      }
+      assertOnlyAllowedKeys(step, ["key", "label", "order"], `display.steps[${i}]`);
+      const key = assertNonEmptyString(step.key, `display.steps[${i}].key`);
+      if (seenStepKeys.has(key)) {
+        throw new Error(`duplicate display step key: ${key}`);
+      }
+      seenStepKeys.add(key);
+      assertNonEmptyString(step.label, `display.steps[${i}].label`);
+      if (step.order !== void 0 && (!Number.isInteger(step.order) || step.order < 0)) {
+        throw new Error(`display.steps[${i}].order must be a non-negative integer`);
+      }
+    }
+  }
+  if (display.overview !== void 0) {
+    if (typeof display.overview !== "object" || display.overview === null || Array.isArray(display.overview)) {
+      throw new Error("display.overview must be an object");
+    }
+    assertOnlyAllowedKeys(display.overview, ["defaultMetric", "defaultLayout"], "display.overview");
+    const { defaultMetric, defaultLayout } = display.overview;
+    if (defaultMetric !== void 0) {
+      const metric = assertNonEmptyString(defaultMetric, "display.overview.defaultMetric");
+      const validDefaultMetrics = new Set(displayMetricKeys);
+      validDefaultMetrics.add("compositeScore");
+      validDefaultMetrics.add("task");
+      if (display.metrics !== void 0 && !validDefaultMetrics.has(metric)) {
+        throw new Error(`display.overview.defaultMetric '${metric}' is not declared in display.metrics and is not a known default (compositeScore, task)`);
+      }
+    }
+    if (defaultLayout !== void 0 && !["ranking", "cards", "chart", "leaderboard"].includes(defaultLayout)) {
+      throw new Error("display.overview.defaultLayout must be 'ranking', 'cards', 'chart', or 'leaderboard'");
+    }
+  }
+}
 function defineBenchmarkConfig(config) {
+  const issues = validateBenchmarkConfig(config);
+  if (config.scoring !== void 0) {
+    try {
+      validateBenchmarkScoringConfig(config.scoring, config.display);
+    } catch (error) {
+      issues.push({
+        field: "scoring",
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  if (issues.length > 0) {
+    throw new BenchmarkConfigError(issues);
+  }
+  return config;
+}
+function defineTask(task) {
+  if (typeof task !== "function") {
+    throw new Error("defineTask requires a task function.");
+  }
+  return task;
+}
+function validateBenchmarkConfig(config) {
+  const issues = [];
   if (!config.benchmarkSlug || typeof config.benchmarkSlug !== "string") {
-    throw new Error("benchmarkSlug is required");
+    issues.push({ field: "benchmarkSlug", message: "is required" });
   }
   if (!config.benchmarkName || typeof config.benchmarkName !== "string") {
-    throw new Error("benchmarkName is required");
+    issues.push({ field: "benchmarkName", message: "is required" });
+  }
+  if (!Array.isArray(config.participants) || config.participants.length === 0) {
+    issues.push({ field: "participants", message: "must be a non-empty array" });
+  } else {
+    const seenParticipants = /* @__PURE__ */ new Set();
+    for (let i = 0; i < config.participants.length; i++) {
+      const p = config.participants[i];
+      if (p === null || typeof p !== "object" || Array.isArray(p)) {
+        issues.push({ field: `participants[${i}]`, message: "must be an object" });
+        continue;
+      }
+      const participant = p;
+      if (typeof participant.name !== "string" || participant.name.trim() === "") {
+        issues.push({ field: `participants[${i}].name`, message: "must be a non-empty string" });
+      } else if (seenParticipants.has(participant.name)) {
+        issues.push({ field: `participants[${i}].name`, message: `duplicate participant name: ${participant.name}` });
+      } else {
+        seenParticipants.add(participant.name);
+      }
+      if (participant.requiredEnvVars !== void 0 && (!Array.isArray(participant.requiredEnvVars) || !participant.requiredEnvVars.every((v) => typeof v === "string"))) {
+        issues.push({ field: `participants[${i}].requiredEnvVars`, message: "must be an array of strings" });
+      }
+    }
   }
   if (config.phases !== void 0) {
     if (config.iterations !== void 0) {
-      throw new Error("phases and iterations are mutually exclusive");
+      issues.push({ field: "iterations", message: "phases and iterations are mutually exclusive" });
     }
     if (!Array.isArray(config.phases) || config.phases.length === 0) {
-      throw new Error("phases must be a non-empty array");
-    }
-    const seen = /* @__PURE__ */ new Set();
-    for (const phase of config.phases) {
-      if (!phase.name || typeof phase.name !== "string") {
-        throw new Error("each phase requires a non-empty name");
-      }
-      if (seen.has(phase.name)) {
-        throw new Error(`duplicate phase name: ${phase.name}`);
+      issues.push({ field: "phases", message: "must be a non-empty array" });
+    } else {
+      const seen = /* @__PURE__ */ new Set();
+      for (let i = 0; i < config.phases.length; i++) {
+        const phase = config.phases[i];
+        if (phase === null || typeof phase !== "object" || Array.isArray(phase)) {
+          issues.push({ field: `phases[${i}]`, message: "must be an object" });
+          continue;
+        }
+        const phaseObj = phase;
+        if (typeof phaseObj.name !== "string" || phaseObj.name.trim() === "") {
+          issues.push({ field: `phases[${i}]`, message: "must have a non-empty string name" });
+        } else {
+          const name = phaseObj.name;
+          if (seen.has(name)) {
+            issues.push({ field: `phases['${name}']`, message: `duplicate phase name: ${name}` });
+          }
+          seen.add(name);
+          const iterations = phaseObj.iterations;
+          if (typeof iterations !== "number" || !Number.isInteger(iterations) || iterations < 1) {
+            issues.push({ field: `phases['${name}'].iterations`, message: `must be an integer >= 1 (got ${iterations})` });
+          }
+        }
       }
-      seen.add(phase.name);
-      assertPositiveInt(phase.iterations, `phase '${phase.name}' iterations`);
     }
   }
-  assertPositiveInt(config.iterations, "iterations");
-  assertPositiveInt(config.concurrency, "concurrency");
+  if (config.iterations !== void 0 && (!Number.isInteger(config.iterations) || config.iterations < 1)) {
+    issues.push({ field: "iterations", message: `must be an integer >= 1 (got ${config.iterations})` });
+  }
+  if (config.concurrency !== void 0 && (!Number.isInteger(config.concurrency) || config.concurrency < 1)) {
+    issues.push({ field: "concurrency", message: `must be an integer >= 1 (got ${config.concurrency})` });
+  }
   if (config.staggerDelayMs !== void 0 && (!Number.isFinite(config.staggerDelayMs) || config.staggerDelayMs < 0)) {
-    throw new Error(`staggerDelayMs must be a number >= 0 (got ${config.staggerDelayMs})`);
+    issues.push({ field: "staggerDelayMs", message: `must be a number >= 0 (got ${config.staggerDelayMs})` });
   }
   if (config.groupBy !== void 0 && config.groupBy !== "participant" && config.groupBy !== "round") {
-    throw new Error(`groupBy must be 'participant' or 'round' (got ${config.groupBy})`);
+    issues.push({ field: "groupBy", message: `must be 'participant' or 'round' (got ${config.groupBy})` });
   }
   if (config.shapes !== void 0) {
-    for (const [shapeName, shape] of Object.entries(config.shapes)) {
-      if (!shape.slug || !/^[a-z0-9][a-z0-9-]*$/.test(shape.slug)) {
-        throw new Error(`shape '${shapeName}' needs a lowercase slug (got ${JSON.stringify(shape.slug)})`);
-      }
-      if (shape.name !== void 0 && (typeof shape.name !== "string" || shape.name.trim() === "")) {
-        throw new Error(`shape '${shapeName}' name must be a non-empty string`);
-      }
-      if (shape.staggerDelayMs !== void 0 && (!Number.isFinite(shape.staggerDelayMs) || shape.staggerDelayMs < 0)) {
-        throw new Error(`shape '${shapeName}' staggerDelayMs must be a number >= 0 (got ${shape.staggerDelayMs})`);
+    if (typeof config.shapes !== "object" || config.shapes === null || Array.isArray(config.shapes)) {
+      issues.push({ field: "shapes", message: "must be a plain object" });
+    } else {
+      for (const [shapeName, shape] of Object.entries(config.shapes)) {
+        if (shape === null || typeof shape !== "object" || Array.isArray(shape)) {
+          issues.push({ field: `shapes['${shapeName}']`, message: "must be an object" });
+          continue;
+        }
+        const shapeObj = shape;
+        const slug = shapeObj.slug;
+        if (typeof slug !== "string" || slug === "" || !/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+          issues.push({ field: `shapes['${shapeName}'].slug`, message: `needs a lowercase slug (got ${JSON.stringify(slug)})` });
+        }
+        const name = shapeObj.name;
+        if (name !== void 0 && (typeof name !== "string" || name.trim() === "")) {
+          issues.push({ field: `shapes['${shapeName}'].name`, message: "must be a non-empty string" });
+        }
+        const staggerDelayMs = shapeObj.staggerDelayMs;
+        if (staggerDelayMs !== void 0 && (typeof staggerDelayMs !== "number" || !Number.isFinite(staggerDelayMs) || staggerDelayMs < 0)) {
+          issues.push({ field: `shapes['${shapeName}'].staggerDelayMs`, message: `must be a number >= 0 (got ${staggerDelayMs})` });
+        }
       }
     }
   }
   if (config.dimensions !== void 0) {
     if (config.dimensions === null || typeof config.dimensions !== "object" || Array.isArray(config.dimensions)) {
-      throw new Error("dimensions must be a plain object");
+      issues.push({ field: "dimensions", message: "must be a plain object" });
     }
   }
-  if (config.scoring !== void 0) {
-    validateBenchmarkScoringConfig(config.scoring, config.display);
-  }
   if (config.customCliFlags !== void 0) {
     if (!Array.isArray(config.customCliFlags) || !config.customCliFlags.every((f) => typeof f === "string" && f.startsWith("--"))) {
-      throw new Error('customCliFlags must be an array of strings starting with "--"');
+      issues.push({ field: "customCliFlags", message: 'must be an array of strings starting with "--"' });
     }
   }
   if (config.display !== void 0) {
-    if (typeof config.display !== "object" || config.display === null || Array.isArray(config.display)) {
-      throw new Error("display must be an object");
-    }
-    assertOnlyAllowedKeys(config.display, ["metrics", "steps", "overview"], "display");
-    const displayMetricKeys = /* @__PURE__ */ new Set();
-    if (config.display.metrics !== void 0) {
-      if (!Array.isArray(config.display.metrics)) {
-        throw new Error("display.metrics must be an array");
-      }
-      for (let i = 0; i < config.display.metrics.length; i++) {
-        const metric = config.display.metrics[i];
-        if (metric === null || typeof metric !== "object" || Array.isArray(metric)) {
-          throw new Error(`display.metrics[${i}] must be an object`);
-        }
-        assertOnlyAllowedKeys(metric, ["key", "label", "unit", "direction", "decimals", "order"], `display.metrics[${i}]`);
-        const key = assertNonEmptyString(metric.key, `display.metrics[${i}].key`);
-        if (displayMetricKeys.has(key)) {
-          throw new Error(`duplicate display metric key: ${key}`);
-        }
-        displayMetricKeys.add(key);
-        assertNonEmptyString(metric.label, `display.metrics[${i}].label`);
-        if (metric.unit !== void 0 && typeof metric.unit !== "string") {
-          throw new Error(`display.metrics[${i}].unit must be a string`);
-        }
-        if (metric.direction !== void 0 && metric.direction !== "higher-better" && metric.direction !== "lower-better") {
-          throw new Error(`display.metrics[${i}].direction must be 'higher-better' or 'lower-better'`);
-        }
-        if (metric.decimals !== void 0 && (!Number.isInteger(metric.decimals) || metric.decimals < 0)) {
-          throw new Error(`display.metrics[${i}].decimals must be a non-negative integer`);
-        }
-        if (metric.order !== void 0 && (!Number.isInteger(metric.order) || metric.order < 0)) {
-          throw new Error(`display.metrics[${i}].order must be a non-negative integer`);
-        }
-      }
-    }
-    if (config.display.steps !== void 0) {
-      if (!Array.isArray(config.display.steps)) {
-        throw new Error("display.steps must be an array");
-      }
-      const seenStepKeys = /* @__PURE__ */ new Set();
-      for (let i = 0; i < config.display.steps.length; i++) {
-        const step = config.display.steps[i];
-        if (step === null || typeof step !== "object" || Array.isArray(step)) {
-          throw new Error(`display.steps[${i}] must be an object`);
-        }
-        assertOnlyAllowedKeys(step, ["key", "label", "order"], `display.steps[${i}]`);
-        const key = assertNonEmptyString(step.key, `display.steps[${i}].key`);
-        if (seenStepKeys.has(key)) {
-          throw new Error(`duplicate display step key: ${key}`);
-        }
-        seenStepKeys.add(key);
-        assertNonEmptyString(step.label, `display.steps[${i}].label`);
-        if (step.order !== void 0 && (!Number.isInteger(step.order) || step.order < 0)) {
-          throw new Error(`display.steps[${i}].order must be a non-negative integer`);
-        }
-      }
-    }
-    if (config.display.overview !== void 0) {
-      if (typeof config.display.overview !== "object" || config.display.overview === null || Array.isArray(config.display.overview)) {
-        throw new Error("display.overview must be an object");
-      }
-      assertOnlyAllowedKeys(config.display.overview, ["defaultMetric", "defaultLayout"], "display.overview");
-      const { defaultMetric, defaultLayout } = config.display.overview;
-      if (defaultMetric !== void 0) {
-        const metric = assertNonEmptyString(defaultMetric, "display.overview.defaultMetric");
-        const validDefaultMetrics = new Set(displayMetricKeys);
-        validDefaultMetrics.add("compositeScore");
-        validDefaultMetrics.add("task");
-        if (config.display.metrics !== void 0 && !validDefaultMetrics.has(metric)) {
-          throw new Error(`display.overview.defaultMetric '${metric}' is not declared in display.metrics and is not a known default (compositeScore, task)`);
-        }
-      }
-      if (defaultLayout !== void 0 && !["ranking", "cards", "chart", "leaderboard"].includes(defaultLayout)) {
-        throw new Error("display.overview.defaultLayout must be 'ranking', 'cards', 'chart', or 'leaderboard'");
-      }
+    try {
+      validateBenchmarkDisplayConfig(config.display);
+    } catch (error) {
+      issues.push({
+        field: "display",
+        message: error instanceof Error ? error.message : String(error)
+      });
     }
   }
   if (config.display?.overview?.defaultMetric === "compositeScore" && config.scoring === void 0 && config.onScore === void 0) {
-    throw new Error("display.overview.defaultMetric cannot be 'compositeScore' without config.scoring or config.onScore");
+    issues.push({
+      field: "display.overview.defaultMetric",
+      message: "cannot be 'compositeScore' without config.scoring or config.onScore"
+    });
   }
-  return config;
+  return issues;
 }
-function defineTask(task) {
-  if (typeof task !== "function") {
-    throw new Error("defineTask requires a task function.");
-  }
-  return task;
+function defineOnComplete(onComplete) {
+  return onComplete;
 }
 
 // src/no-available-participants.ts
@@ -590,12 +716,18 @@ function isStepOutcome(value) {
   if (!keys.every((k) => STEP_OUTCOME_KEYS.has(k))) return false;
   return typeof o.stdout === "string" || typeof o.stderr === "string" || typeof o.error === "string";
 }
-function withTimeout(promise, ms, name) {
+function withTimeout(promise, { stepName, timeoutMs, participantSlug }) {
   return new Promise((resolve2, reject) => {
-    const timer = setTimeout(
-      () => reject(new TaskError(`Step "${name}" timed out after ${ms}ms`, { code: "step_timeout" })),
-      ms
-    );
+    const timer = setTimeout(() => {
+      const participant = participantSlug ? ` for participant "${participantSlug}"` : "";
+      reject(
+        new TaskError(`Step "${stepName}" timed out after ${timeoutMs}ms${participant}`, {
+          code: "step_timeout",
+          step: stepName,
+          timeoutMs
+        })
+      );
+    }, timeoutMs);
     promise.then(
       (value) => {
         clearTimeout(timer);
@@ -608,20 +740,23 @@ function withTimeout(promise, ms, name) {
     );
   });
 }
-async function runStepInvocations(name, fn, options) {
-  const requestedConcurrency = options?.concurrency;
-  if (requestedConcurrency !== void 0 && (!Number.isInteger(requestedConcurrency) || requestedConcurrency < 1)) {
-    throw new Error(`step "${name}" concurrency must be an integer >= 1 (got ${requestedConcurrency})`);
+async function runStepInvocations(name, fn, options, participantSlug) {
+  if (options?.concurrency !== void 0) {
+    console.warn(`[benchsdk] step "${name}" option "concurrency" is deprecated; use "parallelInvocations"`);
+  }
+  const requestedParallelism = options?.parallelInvocations ?? options?.concurrency;
+  if (requestedParallelism !== void 0 && (!Number.isInteger(requestedParallelism) || requestedParallelism < 1)) {
+    throw new Error(`step "${name}" parallelInvocations must be an integer >= 1 (got ${requestedParallelism})`);
   }
   const timeoutMs = options?.timeoutMs;
   if (timeoutMs !== void 0 && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
     throw new Error(`step "${name}" timeoutMs must be a number >= 0 (got ${timeoutMs})`);
   }
-  const count = requestedConcurrency ?? 1;
+  const count = requestedParallelism ?? 1;
   const invocations = Array.from({ length: count }, () => {
     const promise = Promise.resolve().then(() => fn());
     if (timeoutMs === void 0) return promise;
-    return withTimeout(promise, timeoutMs, name);
+    return withTimeout(promise, { stepName: name, timeoutMs, participantSlug });
   });
   if (count === 1) {
     return invocations[0];
@@ -639,14 +774,14 @@ async function runStepInvocations(name, fn, options) {
   if (firstError !== void 0) throw firstError;
   return results;
 }
-async function runStepWithClient(clientStep, name, fn, options) {
-  const { concurrency: runnerConcurrency, timeoutMs, ...clientOptions } = options ?? {};
+async function runStepWithClient(clientStep, name, fn, options, participantSlug) {
+  const { parallelInvocations: runnerParallelism, concurrency: deprecatedConcurrency, timeoutMs, ...clientOptions } = options ?? {};
   const clientStepOptions = {
     ...clientOptions,
     timeoutMs,
-    stepConcurrency: runnerConcurrency
+    stepConcurrency: runnerParallelism ?? deprecatedConcurrency
   };
-  const result = await clientStep(name, () => runStepInvocations(name, fn, options), clientStepOptions);
+  const result = await clientStep(name, () => runStepInvocations(name, fn, options, participantSlug), clientStepOptions);
   return result;
 }
 function parseCliArgs(argv, allowedCustomFlags) {
@@ -814,7 +949,9 @@ function defaultOnResult(record, meta) {
     const data = record.data && Object.keys(record.data).length > 0 ? ` ${JSON.stringify(record.data)}` : "";
     console.log(`  [${meta.participant}] Task ${n}/${meta.iterations}: success${data}`);
   } else {
-    console.log(`  [${meta.participant}] Task ${n}/${meta.iterations}: FAILED \u2014 ${record.errorCode ?? "unknown error"}`);
+    const detail = record.data?.errorMessage ?? record.data?.error;
+    const suffix = typeof detail === "string" && detail.length > 0 ? `: ${detail}` : "";
+    console.log(`  [${meta.participant}] Task ${n}/${meta.iterations}: FAILED \u2014 ${record.errorCode ?? "unknown error"}${suffix}`);
   }
 }
 function resolveShape(config, shapeName) {
@@ -855,7 +992,23 @@ function resolveParticipants(config, resolved) {
   if (available.length === 0) throw new NoAvailableParticipantsError(skipped);
   return available;
 }
-function runConfigToJson(config, resolved, participants) {
+function resolveTriggerSource(env = process.env) {
+  const source = env.BENCH_TRIGGER_SOURCE?.trim();
+  if (source) return source;
+  return env.GITHUB_EVENT_NAME?.trim() || "manual";
+}
+function triggerToJson(env = process.env) {
+  const requestedBy = env.BENCH_TRIGGER_REQUESTED_BY?.trim();
+  const requestId = env.BENCH_TRIGGER_REQUEST_ID?.trim();
+  const event = env.GITHUB_EVENT_NAME?.trim();
+  return {
+    source: resolveTriggerSource(env),
+    ...event ? { event } : {},
+    ...requestedBy ? { requestedBy } : {},
+    ...requestId ? { requestId } : {}
+  };
+}
+function runConfigToJson(config, resolved, participants, env = process.env) {
   const phases = config.phases?.map((phase) => ({
     name: phase.name,
     iterations: resolved.phaseIterations ?? phase.iterations
@@ -871,24 +1024,38 @@ function runConfigToJson(config, resolved, participants) {
     groupBy: resolved.groupBy,
     ...config.dimensions ? { dimensions: config.dimensions } : {},
     ...config.scoring ? { scoring: config.scoring } : {},
-    participants
+    participants,
+    trigger: triggerToJson(env)
   };
   return JSON.parse(JSON.stringify(runConfig));
 }
-async function runBenchmark(fileConfig, task, argv = []) {
+async function runBenchmark(fileConfig, task, argv = [], options = {}) {
   const args = parseCliArgs(argv, fileConfig.customCliFlags);
   const noIngest = args.noIngest ?? isEnvNoIngest();
   const shaped = applyShape(fileConfig, resolveShape(fileConfig, args.shape));
   const config = applyIdentityOverrides(shaped, args);
   const resolved = mergeConfig(config, args);
-  const auth = await (0, import_cli.resolveAuth)();
-  const client = (0, import_api.createBenchmarkClient)({
-    baseUrl: auth.apiBaseUrl,
-    apiKey: auth.apiKey,
-    token: auth.token,
-    orgSlug: auth.orgSlug,
-    orgId: auth.orgId
-  });
+  let baseUrl = "";
+  let apiKey = "";
+  let token;
+  let orgSlug;
+  let orgId;
+  let client = null;
+  const auth = noIngest ? await (0, import_cli.resolveAuth)({ baseUrl: options.baseUrl, apiKey: options.apiKey }).catch(() => null) : await (0, import_cli.resolveAuth)({ baseUrl: options.baseUrl, apiKey: options.apiKey });
+  if (auth) {
+    baseUrl = auth.apiBaseUrl;
+    apiKey = auth.apiKey ?? "";
+    token = auth.token;
+    orgSlug = auth.orgSlug;
+    orgId = auth.orgId;
+    client = (0, import_api.createBenchmarkClient)({
+      baseUrl: auth.apiBaseUrl,
+      apiKey: auth.apiKey,
+      token: auth.token,
+      orgSlug: auth.orgSlug,
+      orgId: auth.orgId
+    });
+  }
   const available = resolveParticipants(config, resolved);
   const schedule = buildSchedule(config, resolved, task);
   const totalTasks = schedule.length;
@@ -909,15 +1076,26 @@ async function runBenchmark(fileConfig, task, argv = []) {
     runId = "no-ingest";
     dashboardUrl = "";
   } else {
-    if (identityIsOurs) {
+    {
       const benchmarkConfig = {
         ...config.scoring ? { scoring: config.scoring } : {},
         ...config.display ? { display: config.display } : {}
       };
-      await client.upsertBenchmark(config.benchmarkSlug, {
-        name: config.benchmarkName,
-        ...Object.keys(benchmarkConfig).length > 0 ? { config: benchmarkConfig } : {}
-      });
+      let initializeTarget = identityIsOurs;
+      if (!initializeTarget) {
+        try {
+          await client.getBenchmark(config.benchmarkSlug);
+        } catch (error) {
+          if (!(error instanceof import_api.BenchmarkApiError && error.status === 404)) throw error;
+          initializeTarget = true;
+        }
+      }
+      const upsertInput = {};
+      if (initializeTarget) {
+        upsertInput.name = config.benchmarkName;
+        if (Object.keys(benchmarkConfig).length > 0) upsertInput.config = benchmarkConfig;
+      }
+      await client.upsertBenchmark(config.benchmarkSlug, upsertInput);
     }
     const runConfig = client ? runConfigToJson(config, resolved, available.map((p) => p.name)) : {};
     if (args.runKey) {
@@ -926,7 +1104,7 @@ async function runBenchmark(fileConfig, task, argv = []) {
         config: runConfig
       });
       runId = run2.id;
-      dashboardUrl = dashboardUrlFor(auth.apiBaseUrl, organizationSlug, config.benchmarkSlug, run2.id);
+      dashboardUrl = dashboardUrlFor(baseUrl, organizationSlug, config.benchmarkSlug, run2.id);
       for (const participant of available) {
         await client.upsertParticipant(config.benchmarkSlug, runId, participant.name, { totalTasks });
       }
@@ -941,7 +1119,7 @@ async function runBenchmark(fileConfig, task, argv = []) {
         config: runConfig
       });
       runId = run2.id;
-      dashboardUrl = dashboardUrlFor(auth.apiBaseUrl, organizationSlug, config.benchmarkSlug, run2.id);
+      dashboardUrl = dashboardUrlFor(baseUrl, organizationSlug, config.benchmarkSlug, run2.id);
       console.log(`Run created: ${run2.name} (${runId})`);
       console.log(`View at: ${dashboardUrl}
 `);
@@ -950,7 +1128,7 @@ async function runBenchmark(fileConfig, task, argv = []) {
   const onResult = defaultOnResult;
   let participantRecords;
   if (resolved.groupBy === "round") {
-    participantRecords = await runGroupedByRound(config, schedule, available, resolved, client, runId, auth.apiBaseUrl, auth.apiKey, auth.token, auth.orgSlug, auth.orgId, onResult, noIngest);
+    participantRecords = await runGroupedByRound(config, schedule, available, resolved, client, runId, baseUrl, apiKey, token, orgSlug, orgId, onResult, noIngest);
   } else {
     participantRecords = await runGroupedByParticipant(config, schedule, available, resolved, client, runId, onResult, noIngest);
   }
@@ -961,14 +1139,14 @@ async function runBenchmark(fileConfig, task, argv = []) {
     participants: participantRecords,
     config: resolved
   };
-  if (!noIngest && (config.onScore || config.scoring)) {
+  if (!noIngest && client && (config.onScore || config.scoring)) {
     try {
       const spec = config.onScore ? await config.onScore(lowerIsBetter, higherIsBetter) : scoringConfigToSpec(config.scoring, config.dimensions, config.display);
       const scored = score(outcome, spec, config.display?.metrics);
       const run2 = {
         gitSha: process.env.GITHUB_SHA ?? getGitSha(),
         gitRef: process.env.GITHUB_REF_NAME ?? process.env.GITHUB_REF ?? getGitRef(),
-        triggeredBy: process.env.GITHUB_EVENT_NAME ?? "manual",
+        triggeredBy: resolveTriggerSource(),
         nodeVersion: process.version,
         platform: import_node_os.default.platform(),
         arch: import_node_os.default.arch()
@@ -987,6 +1165,22 @@ async function runBenchmark(fileConfig, task, argv = []) {
   if (config.onComplete) await config.onComplete(outcome);
   return outcome;
 }
+async function runBenchmarkWorker(options) {
+  const config = defineBenchmarkConfig({
+    benchmarkSlug: options.benchmarkSlug,
+    benchmarkName: options.benchmarkName ?? options.benchmarkSlug,
+    participants: [options.participant],
+    iterations: options.iterations ?? 1,
+    concurrency: options.concurrency ?? 1,
+    staggerDelayMs: options.staggerDelayMs ?? 0,
+    groupBy: options.groupBy ?? "participant",
+    defaultProviders: [options.participant.name]
+  });
+  const argv = [];
+  if (options.runKey) argv.push("--run-key", options.runKey);
+  if (options.noIngest) argv.push("--dry-run");
+  return runBenchmark(config, options.task, argv);
+}
 function getGitSha() {
   if (process.env.GITHUB_SHA) return process.env.GITHUB_SHA;
   try {
@@ -1061,7 +1255,7 @@ async function runGroupedByParticipant(config, schedule, available, resolved, cl
             participant,
             taskIndex: scheduleIndex,
             phase: slot.phase,
-            step: (name, fn, options) => runStepWithClient(ctx.step, name, fn, options),
+            step: (name, fn, options) => runStepWithClient(ctx.step, name, fn, options, participant.name),
             measure: ctx.measure,
             log: ctx.log
           });
@@ -1218,12 +1412,13 @@ async function runTaskRecord(task, participant, scheduleIndex, taskIndex, phase,
         completedAt: new Date(stepStartedAtMs).toISOString(),
         latencyMs: 0
       };
-      if (options?.concurrency !== void 0) stepRecord.concurrency = options.concurrency;
+      const requestedParallelism = options?.parallelInvocations ?? options?.concurrency;
+      if (requestedParallelism !== void 0) stepRecord.concurrency = requestedParallelism;
       if (options?.timeoutMs !== void 0) stepRecord.timeoutMs = options.timeoutMs;
       const previousStep = activeStep;
       activeStep = stepRecord;
       try {
-        const result2 = await runStepInvocations(name, fn, options);
+        const result2 = await runStepInvocations(name, fn, options, participant.name);
         const outcome = options?.captureOutput !== false && !Array.isArray(result2) && isStepOutcome(result2) ? result2 : {};
         logBuffer.step(taskIndex, name, outcome);
         return result2;
@@ -1293,16 +1488,144 @@ async function runTaskRecord(task, participant, scheduleIndex, taskIndex, phase,
 var import_node_path = require("path");
 var import_node_url = require("url");
 var import_cli2 = require("@benchsdk/cli");
-var USAGE = 'Usage:\n  bench run <file.bench.ts> [--shape name] [--provider a,b] [--run-key key]\n      [--benchmark slug] [--name "My benchmark"]\n      [--iterations N] [--concurrency N] [--stagger-delay-ms N] [--group-by participant|round]\n      [--no-ingest | --dry-run]';
+var import_api2 = require("@benchsdk/api");
+var import_worker2 = require("@benchsdk/worker");
+var USAGE = 'Usage:\n  bench run <file.bench.ts> [--shape name] [--provider a,b] [--run-key key]\n      [--benchmark slug] [--name "My benchmark"]\n      [--iterations N] [--concurrency N] [--stagger-delay-ms N] [--group-by participant|round]\n      [--no-ingest | --dry-run] [--check]\n  bench check <file.bench.ts> [--base-url <url>] [--api-key <key>]';
 function isBenchmarkConfig(value) {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value;
   return typeof candidate.benchmarkSlug === "string" && Array.isArray(candidate.participants);
 }
+function shiftFlag(argv, name) {
+  const prefix = `--${name}`;
+  const prefixEq = `${prefix}=`;
+  const result = [];
+  let value;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === prefix) {
+      const next = argv[++i];
+      if (!next || next.startsWith("--")) throw new Error(USAGE);
+      value = next;
+      continue;
+    }
+    if (arg.startsWith(prefixEq)) {
+      const eqValue = arg.slice(prefixEq.length);
+      if (!eqValue) throw new Error(USAGE);
+      value = eqValue;
+      continue;
+    }
+    result.push(arg);
+  }
+  return { value, argv: result };
+}
+function shiftPlatformFlags(flags) {
+  const { value: baseUrl, argv: withoutBaseUrl } = shiftFlag(flags, "base-url");
+  const { value: apiKey, argv: rest } = shiftFlag(withoutBaseUrl, "api-key");
+  return { baseUrl, apiKey, flags: rest };
+}
+async function runCheck(argv) {
+  const [command, ...rest] = argv;
+  const [file, ...flags] = rest;
+  if (command !== "check" || !file || file.startsWith("-")) throw new Error(USAGE);
+  const mod = await import((0, import_node_url.pathToFileURL)((0, import_node_path.resolve)(process.cwd(), file)).href);
+  const config = mod.config;
+  const task = mod.task ?? mod.default;
+  if (!isBenchmarkConfig(config)) {
+    throw new Error(`${file} must export a \`config\` created with defineBenchmarkConfig (with participants).`);
+  }
+  if (typeof task !== "function") {
+    throw new Error(`${file} must export a \`task\` created with defineTask.`);
+  }
+  const cfg = config;
+  const configIssues = validateBenchmarkConfig(cfg);
+  if (configIssues.length > 0) {
+    throw new BenchmarkConfigError(configIssues);
+  }
+  const { baseUrl, apiKey, flags: runnerFlags } = shiftPlatformFlags(flags);
+  const parsed = parseCliArgs(runnerFlags, cfg.customCliFlags ?? []);
+  resolveShape(cfg, parsed.shape);
+  const dryRun = parsed.noIngest ?? false;
+  let client;
+  let apiOk = dryRun;
+  let auth = null;
+  if (!dryRun) {
+    try {
+      auth = await (0, import_cli2.resolveAuth)({ baseUrl, apiKey });
+      client = (0, import_api2.createBenchmarkClient)({
+        baseUrl: auth.apiBaseUrl,
+        apiKey: auth.apiKey,
+        token: auth.token,
+        orgSlug: auth.orgSlug,
+        orgId: auth.orgId
+      });
+      await client.listBenchmarks({ limit: 1 });
+      apiOk = true;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[benchsdk] API connectivity check failed: ${message}`);
+    }
+  }
+  const effectiveProviderNames = parsed.providers ?? cfg.defaultProviders;
+  let selected;
+  try {
+    selected = (0, import_worker2.selectParticipants)(cfg.participants, effectiveProviderNames);
+  } catch (err) {
+    throw new Error(`Participant selection failed: ${err instanceof Error ? err.message : err}`);
+  }
+  const { available, skipped } = (0, import_worker2.filterParticipantsByEnv)(selected);
+  let scoringOk = true;
+  if (cfg.onScore) {
+    try {
+      const spec = await cfg.onScore(lowerIsBetter, higherIsBetter);
+      validateScoringSpec(spec);
+    } catch (err) {
+      scoringOk = false;
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[benchsdk] Scoring validation failed: ${message}`);
+    }
+  } else if (cfg.scoring) {
+    try {
+      const spec = scoringConfigToSpec(cfg.scoring, cfg.dimensions);
+      validateScoringSpec(spec);
+    } catch (err) {
+      scoringOk = false;
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[benchsdk] Scoring validation failed: ${message}`);
+    }
+  }
+  const missingPlatformAuth = dryRun ? [] : auth ? [] : [["BENCHMARKS_PLATFORM_API_KEY or BENCHMARKS_PLATFORM_TOKEN", void 0]];
+  for (const [name] of missingPlatformAuth) {
+    console.warn(`[benchsdk] ${name} is not set`);
+  }
+  const report = {
+    file,
+    benchmarkSlug: cfg.benchmarkSlug,
+    apiOk,
+    envOk: dryRun || missingPlatformAuth.length === 0,
+    participants: {
+      requested: selected.map((p) => p.name),
+      available: available.map((p) => p.name),
+      skipped: skipped.map((s) => ({ name: s.name, missing: s.missing }))
+    },
+    scoringOk: cfg.scoring || cfg.onScore ? scoringOk : void 0
+  };
+  console.log(JSON.stringify(report, null, 2));
+  const authFailure = !dryRun && missingPlatformAuth.length > 0;
+  if (!apiOk || available.length === 0 || scoringOk === false || authFailure) {
+    throw new Error("Benchmark check failed. See warnings above for details.");
+  }
+}
 async function runBenchmarkFile(argv) {
   const [command, ...rest] = argv;
   const [file, ...flags] = rest;
   if (command !== "run" || !file || file.startsWith("-")) throw new Error(USAGE);
+  const check = flags.includes("--check") || flags.includes("--validate");
+  if (check) {
+    const checkFlags = flags.filter((f) => f !== "--check" && f !== "--validate");
+    return runCheck(["check", file, ...checkFlags]);
+  }
+  const { baseUrl, apiKey, flags: runnerFlags } = shiftPlatformFlags(flags);
   const mod = await import((0, import_node_url.pathToFileURL)((0, import_node_path.resolve)(process.cwd(), file)).href);
   const config = mod.config;
   const task = mod.task ?? mod.default;
@@ -1312,44 +1635,78 @@ async function runBenchmarkFile(argv) {
   if (typeof task !== "function") {
     throw new Error(`${file} must export a \`task\` created with defineTask.`);
   }
-  await runBenchmark(config, task, flags);
+  const envFlags = [];
+  if (process.env.BENCHMARK_SLUG) {
+    envFlags.push("--benchmark", process.env.BENCHMARK_SLUG);
+  }
+  if (process.env.BENCHMARK_NAME) {
+    envFlags.push("--name", process.env.BENCHMARK_NAME);
+  }
+  await runBenchmark(
+    config,
+    task,
+    [...envFlags, ...runnerFlags],
+    { baseUrl, apiKey }
+  );
 }
 async function run(argv) {
-  if (argv[0] !== "run") {
-    return (0, import_cli2.run)(argv);
-  }
+  const [command, ...rest] = argv;
   try {
-    await runBenchmarkFile(argv);
+    if (command === "run") {
+      await runBenchmarkFile(argv);
+    } else if (command === "check") {
+      await runCheck(argv);
+    } else {
+      return (0, import_cli2.run)(argv);
+    }
     process.exit(0);
   } catch (err) {
     if (err instanceof NoAvailableParticipantsError) {
       console.log(err.message);
       process.exit(0);
     }
-    console.error("Benchmark failed:", err instanceof Error ? err.message : err);
+    console.error("Benchmark failed:", String(err));
     process.exit(1);
   }
 }
 
 // src/index.ts
-var BENCHSDK_RUNNER_VERSION = "0.3.0";
+var import_cli4 = require("@benchsdk/cli");
+var import_worker3 = require("@benchsdk/worker");
+var import_api3 = require("@benchsdk/api");
+var BENCHSDK_RUNNER_VERSION = "0.5.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthError,
   BENCHSDK_RUNNER_VERSION,
+  BenchmarkApiError,
+  BenchmarkConfigError,
+  BenchmarkReporter,
   NoAvailableParticipantsError,
   ScoringSpecError,
   TaskError,
+  claimBenchmarkReporter,
+  createApiClient,
+  createBenchmarkClient,
+  createSystemMetricsCollector,
   defineBenchmarkConfig,
+  defineOnComplete,
   defineTask,
+  filterParticipantsByEnv,
   higherIsBetter,
   lowerIsBetter,
   mergeConfig,
   parseCliArgs,
+  resolveAuth,
   run,
   runBenchmark,
   runBenchmarkFile,
+  runBenchmarkWorker,
+  runWorker,
   score,
   scoringConfigToSpec,
+  selectParticipants,
+  validateBenchmarkConfig,
   validateScoringSpec
 });
 //# sourceMappingURL=index.cjs.map