@benchsdk/runner 0.3.0 → 0.5.2

package/dist/index.d.cts

@@ -1,5 +1,8 @@
 import { TaskResultRecord, JsonObject, DefineStepOptions, BenchmarkLogOptions, TaskStepRecord } from '@benchsdk/api';
+export { BenchmarkAnalyticsReadiness, BenchmarkApiError, BenchmarkArtifact, BenchmarkArtifactDownload, BenchmarkAssignment, BenchmarkClient, BenchmarkClientConfig, BenchmarkConcurrencyPoint, BenchmarkEventRateBucket, BenchmarkFailurePoint, BenchmarkLogLevel, BenchmarkLogOptions, BenchmarkParticipant, BenchmarkResource, BenchmarkResultLatencySummary, BenchmarkResultSummary, BenchmarkResultsOverview, BenchmarkResultsOverviewAnalytics, BenchmarkResultsOverviewInput, BenchmarkResultsOverviewRun, BenchmarkRun, BenchmarkRunAnalyticsSummary, BenchmarkRunImportItem, BenchmarkRunImports, BenchmarkRunImportsSummary, BenchmarkRunResults, BenchmarkRunStatus, BenchmarkRunSummaryInput, BenchmarkRunSummaryMetric, BenchmarkRunSummaryResult, BenchmarkRunSummaryRunMetadata, BenchmarkRunSummaryScalar, BenchmarkRunTaskResults, BenchmarkRunTaskResultsInput, BenchmarkRunTimeline, BenchmarkRunTimelineInput, BenchmarkRunWorker, BenchmarkStepOutcome, BenchmarkStepResultSummary, BenchmarkTaskBucket, BenchmarkWorkerAttempt, BenchmarkWorkerStatus, ClaimWorkerInput, CreateRunInput, CreateWorkerArtifactInput, CreateWorkerArtifactResponse, DefineStepOptions, JsonObject, JsonValue, PlanWorkersInput, RunProgress, RunProgressConcurrency, RunProgressParticipant, RunProgressParticipantCounts, RunProgressStatus, RunProgressSummary, RunProgressTaskCounts, RunProgressWorkerCounts, RunWorkerContext, RunWorkerOptions, RunWorkerResult, SendTaskResultsInput, TaskFunction, TaskResultRecord, TaskResultsResponse, TaskStepRecord, UpdateBenchmarkInput, UpdateParticipantInput, UpdateRunInput, UpdateWorkerInput, UploadWorkerArtifactInput, UpsertBenchmarkInput, UpsertParticipantInput, WorkerConcurrencySample, WorkerFinishContext, WorkerHeartbeatInput, createBenchmarkClient } from '@benchsdk/api';
 import { BaseParticipant } from '@benchsdk/worker';
+export { BaseParticipant, BenchmarkReporter, BenchmarkReporterArtifactInput, BenchmarkReporterBarrierInput, BenchmarkReporterBarrierResult, BenchmarkReporterConfig, BenchmarkReporterHeartbeatInput, BenchmarkReporterProgress, BenchmarkSystemMetricsCollector, BenchmarkSystemMetricsSample, claimBenchmarkReporter, createSystemMetricsCollector, filterParticipantsByEnv, runWorker, selectParticipants } from '@benchsdk/worker';
+export { AuthError, CliAuth, createApiClient, resolveAuth } from '@benchsdk/cli';
 
 type MetricValue = string | ((record: TaskResultRecord) => number | number[] | undefined);
 interface MetricScoring {
@@ -192,8 +195,19 @@ interface TaskStepOptions extends Omit<DefineStepOptions, 'concurrency' | 'stepC
     /** Per-iteration timeout in milliseconds. If an invocation exceeds this, it is aborted and a `step_timeout` TaskError is thrown. */
     timeoutMs?: number;
     /** Number of times to invoke `fn` in parallel. Defaults to 1. When greater than 1, the step returns an array of results. */
+    parallelInvocations?: number;
+    /** @deprecated use `parallelInvocations` instead. */
     concurrency?: number;
 }
+interface TaskErrorOptions {
+    code?: string;
+    data?: JsonObject;
+    steps?: TaskStepRecord[];
+    /** The step name this error was thrown from, when known. */
+    step?: string;
+    /** The timeout that was exceeded, when this is a timeout error. */
+    timeoutMs?: number;
+}
 /**
  * Throw this from a task to record a failure while preserving domain data and
  * any pre-measured steps (a plain thrown Error loses them).
@@ -202,11 +216,10 @@ declare class TaskError extends Error {
     readonly code?: string;
     readonly data?: JsonObject;
     readonly steps?: TaskStepRecord[];
-    constructor(message: string, opts?: {
-        code?: string;
-        data?: JsonObject;
-        steps?: TaskStepRecord[];
-    });
+    readonly step?: string;
+    readonly timeoutMs?: number;
+    constructor(message: string, opts?: TaskErrorOptions);
+    toString(): string;
 }
 /** Context handed to a benchmark `task` for a single iteration. */
 interface TaskContext<T extends BaseParticipant = BaseParticipant> {
@@ -218,11 +231,12 @@ interface TaskContext<T extends BaseParticipant = BaseParticipant> {
     phase?: string;
     /**
      * Runs `fn` as a named platform step. Mirrors `@benchsdk/worker`'s
-     * `RunWorkerContext.step`; supports closures and try/finally. A `concurrency`
+     * `RunWorkerContext.step`; supports closures and try/finally. `parallelInvocations`
      * greater than 1 invokes `fn` that many times in parallel and returns an array.
      * `timeoutMs` aborts any invocation that exceeds it with a `step_timeout` TaskError.
      */
     step<R, C extends number = 1>(name: string, fn: () => Promise<R> | R, options?: TaskStepOptions & {
+        parallelInvocations?: C;
         concurrency?: C;
     }): Promise<C extends 1 ? R : R[]>;
     /**
@@ -268,49 +282,6 @@ interface ResolvedRunConfig {
     groupBy: GroupBy;
     providers?: string[];
 }
-/** Display metadata for a single custom metric a benchmark reports via `ctx.measure`. */
-interface BenchmarkMetricDisplay {
-    /** Stable metric key, matching the key in `ctx.measure` or `data`. */
-    key: string;
-    /** Human-readable label shown in the platform UI. */
-    label: string;
-    /** Optional unit shown after the value (e.g. `Mbps`, `/s`, `ms`). */
-    unit?: string;
-    /** Number of decimal places when formatting numeric values. Defaults to the display format. */
-    decimals?: number;
-    /** Whether higher or lower values rank better. */
-    direction?: 'higher-better' | 'lower-better';
-    /** Optional ordering hint for metric lists. */
-    order?: number;
-}
-/** Display metadata for a single task lifecycle step. */
-interface BenchmarkStepDisplay {
-    /** Stable step name, matching the string passed to `ctx.step`. */
-    key: string;
-    /** Human-readable label shown in the platform UI. */
-    label: string;
-    /** Optional ordering hint for step lists. */
-    order?: number;
-}
-/** Display defaults for the benchmark overview page. */
-interface BenchmarkOverviewDisplay {
-    /** Metric key to rank participants by by default (falls back to overall task latency). */
-    defaultMetric?: string;
-    /** Default overview layout. */
-    defaultLayout?: 'ranking' | 'cards' | 'chart' | 'leaderboard';
-}
-/**
- * Optional platform display manifest. A `*.bench.ts` file owns not only how the
- * benchmark runs, but how it should be rendered, without a platform code change.
- */
-interface BenchmarkDisplayConfig {
-    /** Metric catalog — labels, units, and ranking direction for `ctx.measure` keys. */
-    metrics?: BenchmarkMetricDisplay[];
-    /** Step catalog — human labels for lifecycle steps reported via `ctx.step`. */
-    steps?: BenchmarkStepDisplay[];
-    /** Overview defaults. */
-    overview?: BenchmarkOverviewDisplay;
-}
 /**
  * Result of a benchmark run, passed to `config.onComplete`. Exposes the raw
  * per-participant records so completion hooks can write legacy local results.
@@ -409,6 +380,58 @@ interface BenchmarkConfig<T extends BaseParticipant = BaseParticipant> {
      */
     display?: BenchmarkDisplayConfig;
 }
+/** Display metadata for a single custom metric a benchmark reports via `ctx.measure`. */
+interface BenchmarkMetricDisplay {
+    /** Stable metric key, matching the key in `ctx.measure` or `data`. */
+    key: string;
+    /** Human-readable label shown in the platform UI. */
+    label: string;
+    /** Optional unit shown after the value (e.g. `Mbps`, `/s`, `ms`). */
+    unit?: string;
+    /** Number of decimal places when formatting numeric values. Defaults to the display format. */
+    decimals?: number;
+    /** Whether higher or lower values rank better. */
+    direction?: 'higher-better' | 'lower-better';
+    /** Optional ordering hint for metric lists. */
+    order?: number;
+}
+/** Display metadata for a single task lifecycle step. */
+interface BenchmarkStepDisplay {
+    /** Stable step name, matching the string passed to `ctx.step`. */
+    key: string;
+    /** Human-readable label shown in the platform UI. */
+    label: string;
+    /** Optional ordering hint for step lists. */
+    order?: number;
+}
+/** Display defaults for the benchmark overview page. */
+interface BenchmarkOverviewDisplay {
+    /** Metric key to rank participants by by default (falls back to overall task latency). */
+    defaultMetric?: string;
+    /** Default overview layout. */
+    defaultLayout?: 'ranking' | 'cards' | 'chart' | 'leaderboard';
+}
+/**
+ * Optional platform display manifest. A `*.bench.ts` file owns not only how the
+ * benchmark runs, but how it should be rendered, without a platform code change.
+ */
+interface BenchmarkDisplayConfig {
+    /** Metric catalog — labels, units, and ranking direction for `ctx.measure` keys. */
+    metrics?: BenchmarkMetricDisplay[];
+    /** Step catalog — human labels for lifecycle steps reported via `ctx.step`. */
+    steps?: BenchmarkStepDisplay[];
+    /** Overview defaults. */
+    overview?: BenchmarkOverviewDisplay;
+}
+interface BenchmarkConfigErrorItem {
+    field: string;
+    message: string;
+}
+declare class BenchmarkConfigError extends Error {
+    readonly issues: BenchmarkConfigErrorItem[];
+    constructor(issues: BenchmarkConfigErrorItem[]);
+    private static formatIssues;
+}
 /** Validates `config` at file-evaluation time so mistakes surface immediately. */
 declare function defineBenchmarkConfig<T extends BaseParticipant = BaseParticipant>(config: BenchmarkConfig<T>): BenchmarkConfig<T>;
 /**
@@ -423,6 +446,16 @@ declare function defineBenchmarkConfig<T extends BaseParticipant = BaseParticipa
  *   });
  */
 declare function defineTask<T extends BaseParticipant = BaseParticipant>(task: BenchmarkTask<T>): BenchmarkTask<T>;
+/**
+ * Validates a `BenchmarkConfig` without throwing, returning a list of
+ * `{ field, message }` issues. Returns an empty array when the config is valid.
+ */
+declare function validateBenchmarkConfig<T extends BaseParticipant = BaseParticipant>(config: BenchmarkConfig<T>): BenchmarkConfigErrorItem[];
+/**
+ * Typed helper for `config.onComplete` callbacks. The body receives the full
+ * `BenchmarkRunOutcome` and can be sync or async.
+ */
+declare function defineOnComplete(onComplete: (outcome: BenchmarkRunOutcome) => void | Promise<void>): (outcome: BenchmarkRunOutcome) => void | Promise<void>;
 
 /**
  * Thrown when every selected participant was env-gated out, i.e. none of their
@@ -473,6 +506,11 @@ interface CliArgs {
 declare function parseCliArgs(argv: string[], allowedCustomFlags?: readonly string[]): CliArgs;
 /** Merges CLI overrides over config defaults, filling in knob fallbacks. */
 declare function mergeConfig<T extends BaseParticipant>(config: BenchmarkConfig<T>, args: CliArgs): ResolvedRunConfig;
+interface PlatformConfig {
+    baseUrl?: string;
+    apiKey?: string;
+}
+type RunBenchmarkOptions = PlatformConfig;
 /**
  * Runs `config`'s `task` against its participants. Selects participants by
  * `--provider` (if given), env-gates them, then drives them per the resolved
@@ -482,7 +520,26 @@ declare function mergeConfig<T extends BaseParticipant>(config: BenchmarkConfig<
  * CI job per provider) get-or-create one shared run and each registers only its
  * own participants.
  */
-declare function runBenchmark<T extends BaseParticipant>(fileConfig: BenchmarkConfig<T>, task: BenchmarkTask<T>, argv?: string[]): Promise<BenchmarkRunOutcome>;
+declare function runBenchmark<T extends BaseParticipant>(fileConfig: BenchmarkConfig<T>, task: BenchmarkTask<T>, argv?: string[], options?: RunBenchmarkOptions): Promise<BenchmarkRunOutcome>;
+interface RunBenchmarkWorkerOptions<T extends BaseParticipant = BaseParticipant> {
+    benchmarkSlug: string;
+    benchmarkName?: string;
+    runKey?: string;
+    participant: T;
+    task: BenchmarkTask<T>;
+    iterations?: number;
+    concurrency?: number;
+    staggerDelayMs?: number;
+    groupBy?: GroupBy;
+    noIngest?: boolean;
+}
+/**
+ * One-shot helper: run a single participant's worker for a benchmark without
+ * creating a `*.bench.ts` file. This is a convenience wrapper around
+ * `runBenchmark` that builds a minimal `BenchmarkConfig` from the supplied
+ * options.
+ */
+declare function runBenchmarkWorker<T extends BaseParticipant>(options: RunBenchmarkWorkerOptions<T>): Promise<BenchmarkRunOutcome>;
 
 /**
  * Dispatches one CLI invocation. Throws on bad usage / invalid exports and lets
@@ -495,4 +552,4 @@ declare function run(argv: string[]): Promise<void>;
 
 declare const BENCHSDK_RUNNER_VERSION: string;
 
-export { BENCHSDK_RUNNER_VERSION, type BenchmarkConfig, type BenchmarkDisplayConfig, type BenchmarkMetricDisplay, type BenchmarkOverviewDisplay, type BenchmarkRunOutcome, type BenchmarkScoreResult, type BenchmarkScoringConfig, type BenchmarkScoringMetric, type BenchmarkScoringSuccess, type BenchmarkScoringWeights, type BenchmarkStepDisplay, type BenchmarkTask, type CliArgs, type GroupBy, type MetricScoring, NoAvailableParticipantsError, type ParticipantRecords, type Phase, type ResolvedRunConfig, type ScoringSpec, ScoringSpecError, type TaskContext, TaskError, type TaskResult, type TaskStepOptions, defineBenchmarkConfig, defineTask, higherIsBetter, lowerIsBetter, mergeConfig, parseCliArgs, run, runBenchmark, runBenchmarkFile, score, scoringConfigToSpec, validateScoringSpec };
+export { BENCHSDK_RUNNER_VERSION, type BenchmarkConfig, BenchmarkConfigError, type BenchmarkConfigErrorItem, type BenchmarkDisplayConfig, type BenchmarkMetricDisplay, type BenchmarkOverviewDisplay, type BenchmarkRunOutcome, type BenchmarkScoreResult, type BenchmarkScoringConfig, type BenchmarkScoringMetric, type BenchmarkScoringSuccess, type BenchmarkScoringWeights, type BenchmarkStepDisplay, type BenchmarkTask, type CliArgs, type GroupBy, type MetricScoring, NoAvailableParticipantsError, type ParticipantRecords, type Phase, type PlatformConfig, type ResolvedRunConfig, type RunBenchmarkOptions, type RunBenchmarkWorkerOptions, type ScoringSpec, ScoringSpecError, type TaskContext, TaskError, type TaskResult, type TaskStepOptions, defineBenchmarkConfig, defineOnComplete, defineTask, higherIsBetter, lowerIsBetter, mergeConfig, parseCliArgs, run, runBenchmark, runBenchmarkFile, runBenchmarkWorker, score, scoringConfigToSpec, validateBenchmarkConfig, validateScoringSpec };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { TaskResultRecord, JsonObject, DefineStepOptions, BenchmarkLogOptions, TaskStepRecord } from '@benchsdk/api';
+export { BenchmarkAnalyticsReadiness, BenchmarkApiError, BenchmarkArtifact, BenchmarkArtifactDownload, BenchmarkAssignment, BenchmarkClient, BenchmarkClientConfig, BenchmarkConcurrencyPoint, BenchmarkEventRateBucket, BenchmarkFailurePoint, BenchmarkLogLevel, BenchmarkLogOptions, BenchmarkParticipant, BenchmarkResource, BenchmarkResultLatencySummary, BenchmarkResultSummary, BenchmarkResultsOverview, BenchmarkResultsOverviewAnalytics, BenchmarkResultsOverviewInput, BenchmarkResultsOverviewRun, BenchmarkRun, BenchmarkRunAnalyticsSummary, BenchmarkRunImportItem, BenchmarkRunImports, BenchmarkRunImportsSummary, BenchmarkRunResults, BenchmarkRunStatus, BenchmarkRunSummaryInput, BenchmarkRunSummaryMetric, BenchmarkRunSummaryResult, BenchmarkRunSummaryRunMetadata, BenchmarkRunSummaryScalar, BenchmarkRunTaskResults, BenchmarkRunTaskResultsInput, BenchmarkRunTimeline, BenchmarkRunTimelineInput, BenchmarkRunWorker, BenchmarkStepOutcome, BenchmarkStepResultSummary, BenchmarkTaskBucket, BenchmarkWorkerAttempt, BenchmarkWorkerStatus, ClaimWorkerInput, CreateRunInput, CreateWorkerArtifactInput, CreateWorkerArtifactResponse, DefineStepOptions, JsonObject, JsonValue, PlanWorkersInput, RunProgress, RunProgressConcurrency, RunProgressParticipant, RunProgressParticipantCounts, RunProgressStatus, RunProgressSummary, RunProgressTaskCounts, RunProgressWorkerCounts, RunWorkerContext, RunWorkerOptions, RunWorkerResult, SendTaskResultsInput, TaskFunction, TaskResultRecord, TaskResultsResponse, TaskStepRecord, UpdateBenchmarkInput, UpdateParticipantInput, UpdateRunInput, UpdateWorkerInput, UploadWorkerArtifactInput, UpsertBenchmarkInput, UpsertParticipantInput, WorkerConcurrencySample, WorkerFinishContext, WorkerHeartbeatInput, createBenchmarkClient } from '@benchsdk/api';
 import { BaseParticipant } from '@benchsdk/worker';
+export { BaseParticipant, BenchmarkReporter, BenchmarkReporterArtifactInput, BenchmarkReporterBarrierInput, BenchmarkReporterBarrierResult, BenchmarkReporterConfig, BenchmarkReporterHeartbeatInput, BenchmarkReporterProgress, BenchmarkSystemMetricsCollector, BenchmarkSystemMetricsSample, claimBenchmarkReporter, createSystemMetricsCollector, filterParticipantsByEnv, runWorker, selectParticipants } from '@benchsdk/worker';
+export { AuthError, CliAuth, createApiClient, resolveAuth } from '@benchsdk/cli';
 
 type MetricValue = string | ((record: TaskResultRecord) => number | number[] | undefined);
 interface MetricScoring {
@@ -192,8 +195,19 @@ interface TaskStepOptions extends Omit<DefineStepOptions, 'concurrency' | 'stepC
     /** Per-iteration timeout in milliseconds. If an invocation exceeds this, it is aborted and a `step_timeout` TaskError is thrown. */
     timeoutMs?: number;
     /** Number of times to invoke `fn` in parallel. Defaults to 1. When greater than 1, the step returns an array of results. */
+    parallelInvocations?: number;
+    /** @deprecated use `parallelInvocations` instead. */
     concurrency?: number;
 }
+interface TaskErrorOptions {
+    code?: string;
+    data?: JsonObject;
+    steps?: TaskStepRecord[];
+    /** The step name this error was thrown from, when known. */
+    step?: string;
+    /** The timeout that was exceeded, when this is a timeout error. */
+    timeoutMs?: number;
+}
 /**
  * Throw this from a task to record a failure while preserving domain data and
  * any pre-measured steps (a plain thrown Error loses them).
@@ -202,11 +216,10 @@ declare class TaskError extends Error {
     readonly code?: string;
     readonly data?: JsonObject;
     readonly steps?: TaskStepRecord[];
-    constructor(message: string, opts?: {
-        code?: string;
-        data?: JsonObject;
-        steps?: TaskStepRecord[];
-    });
+    readonly step?: string;
+    readonly timeoutMs?: number;
+    constructor(message: string, opts?: TaskErrorOptions);
+    toString(): string;
 }
 /** Context handed to a benchmark `task` for a single iteration. */
 interface TaskContext<T extends BaseParticipant = BaseParticipant> {
@@ -218,11 +231,12 @@ interface TaskContext<T extends BaseParticipant = BaseParticipant> {
     phase?: string;
     /**
      * Runs `fn` as a named platform step. Mirrors `@benchsdk/worker`'s
-     * `RunWorkerContext.step`; supports closures and try/finally. A `concurrency`
+     * `RunWorkerContext.step`; supports closures and try/finally. `parallelInvocations`
      * greater than 1 invokes `fn` that many times in parallel and returns an array.
      * `timeoutMs` aborts any invocation that exceeds it with a `step_timeout` TaskError.
      */
     step<R, C extends number = 1>(name: string, fn: () => Promise<R> | R, options?: TaskStepOptions & {
+        parallelInvocations?: C;
         concurrency?: C;
     }): Promise<C extends 1 ? R : R[]>;
     /**
@@ -268,49 +282,6 @@ interface ResolvedRunConfig {
     groupBy: GroupBy;
     providers?: string[];
 }
-/** Display metadata for a single custom metric a benchmark reports via `ctx.measure`. */
-interface BenchmarkMetricDisplay {
-    /** Stable metric key, matching the key in `ctx.measure` or `data`. */
-    key: string;
-    /** Human-readable label shown in the platform UI. */
-    label: string;
-    /** Optional unit shown after the value (e.g. `Mbps`, `/s`, `ms`). */
-    unit?: string;
-    /** Number of decimal places when formatting numeric values. Defaults to the display format. */
-    decimals?: number;
-    /** Whether higher or lower values rank better. */
-    direction?: 'higher-better' | 'lower-better';
-    /** Optional ordering hint for metric lists. */
-    order?: number;
-}
-/** Display metadata for a single task lifecycle step. */
-interface BenchmarkStepDisplay {
-    /** Stable step name, matching the string passed to `ctx.step`. */
-    key: string;
-    /** Human-readable label shown in the platform UI. */
-    label: string;
-    /** Optional ordering hint for step lists. */
-    order?: number;
-}
-/** Display defaults for the benchmark overview page. */
-interface BenchmarkOverviewDisplay {
-    /** Metric key to rank participants by by default (falls back to overall task latency). */
-    defaultMetric?: string;
-    /** Default overview layout. */
-    defaultLayout?: 'ranking' | 'cards' | 'chart' | 'leaderboard';
-}
-/**
- * Optional platform display manifest. A `*.bench.ts` file owns not only how the
- * benchmark runs, but how it should be rendered, without a platform code change.
- */
-interface BenchmarkDisplayConfig {
-    /** Metric catalog — labels, units, and ranking direction for `ctx.measure` keys. */
-    metrics?: BenchmarkMetricDisplay[];
-    /** Step catalog — human labels for lifecycle steps reported via `ctx.step`. */
-    steps?: BenchmarkStepDisplay[];
-    /** Overview defaults. */
-    overview?: BenchmarkOverviewDisplay;
-}
 /**
  * Result of a benchmark run, passed to `config.onComplete`. Exposes the raw
  * per-participant records so completion hooks can write legacy local results.
@@ -409,6 +380,58 @@ interface BenchmarkConfig<T extends BaseParticipant = BaseParticipant> {
      */
     display?: BenchmarkDisplayConfig;
 }
+/** Display metadata for a single custom metric a benchmark reports via `ctx.measure`. */
+interface BenchmarkMetricDisplay {
+    /** Stable metric key, matching the key in `ctx.measure` or `data`. */
+    key: string;
+    /** Human-readable label shown in the platform UI. */
+    label: string;
+    /** Optional unit shown after the value (e.g. `Mbps`, `/s`, `ms`). */
+    unit?: string;
+    /** Number of decimal places when formatting numeric values. Defaults to the display format. */
+    decimals?: number;
+    /** Whether higher or lower values rank better. */
+    direction?: 'higher-better' | 'lower-better';
+    /** Optional ordering hint for metric lists. */
+    order?: number;
+}
+/** Display metadata for a single task lifecycle step. */
+interface BenchmarkStepDisplay {
+    /** Stable step name, matching the string passed to `ctx.step`. */
+    key: string;
+    /** Human-readable label shown in the platform UI. */
+    label: string;
+    /** Optional ordering hint for step lists. */
+    order?: number;
+}
+/** Display defaults for the benchmark overview page. */
+interface BenchmarkOverviewDisplay {
+    /** Metric key to rank participants by by default (falls back to overall task latency). */
+    defaultMetric?: string;
+    /** Default overview layout. */
+    defaultLayout?: 'ranking' | 'cards' | 'chart' | 'leaderboard';
+}
+/**
+ * Optional platform display manifest. A `*.bench.ts` file owns not only how the
+ * benchmark runs, but how it should be rendered, without a platform code change.
+ */
+interface BenchmarkDisplayConfig {
+    /** Metric catalog — labels, units, and ranking direction for `ctx.measure` keys. */
+    metrics?: BenchmarkMetricDisplay[];
+    /** Step catalog — human labels for lifecycle steps reported via `ctx.step`. */
+    steps?: BenchmarkStepDisplay[];
+    /** Overview defaults. */
+    overview?: BenchmarkOverviewDisplay;
+}
+interface BenchmarkConfigErrorItem {
+    field: string;
+    message: string;
+}
+declare class BenchmarkConfigError extends Error {
+    readonly issues: BenchmarkConfigErrorItem[];
+    constructor(issues: BenchmarkConfigErrorItem[]);
+    private static formatIssues;
+}
 /** Validates `config` at file-evaluation time so mistakes surface immediately. */
 declare function defineBenchmarkConfig<T extends BaseParticipant = BaseParticipant>(config: BenchmarkConfig<T>): BenchmarkConfig<T>;
 /**
@@ -423,6 +446,16 @@ declare function defineBenchmarkConfig<T extends BaseParticipant = BaseParticipa
  *   });
  */
 declare function defineTask<T extends BaseParticipant = BaseParticipant>(task: BenchmarkTask<T>): BenchmarkTask<T>;
+/**
+ * Validates a `BenchmarkConfig` without throwing, returning a list of
+ * `{ field, message }` issues. Returns an empty array when the config is valid.
+ */
+declare function validateBenchmarkConfig<T extends BaseParticipant = BaseParticipant>(config: BenchmarkConfig<T>): BenchmarkConfigErrorItem[];
+/**
+ * Typed helper for `config.onComplete` callbacks. The body receives the full
+ * `BenchmarkRunOutcome` and can be sync or async.
+ */
+declare function defineOnComplete(onComplete: (outcome: BenchmarkRunOutcome) => void | Promise<void>): (outcome: BenchmarkRunOutcome) => void | Promise<void>;
 
 /**
  * Thrown when every selected participant was env-gated out, i.e. none of their
@@ -473,6 +506,11 @@ interface CliArgs {
 declare function parseCliArgs(argv: string[], allowedCustomFlags?: readonly string[]): CliArgs;
 /** Merges CLI overrides over config defaults, filling in knob fallbacks. */
 declare function mergeConfig<T extends BaseParticipant>(config: BenchmarkConfig<T>, args: CliArgs): ResolvedRunConfig;
+interface PlatformConfig {
+    baseUrl?: string;
+    apiKey?: string;
+}
+type RunBenchmarkOptions = PlatformConfig;
 /**
  * Runs `config`'s `task` against its participants. Selects participants by
  * `--provider` (if given), env-gates them, then drives them per the resolved
@@ -482,7 +520,26 @@ declare function mergeConfig<T extends BaseParticipant>(config: BenchmarkConfig<
  * CI job per provider) get-or-create one shared run and each registers only its
  * own participants.
  */
-declare function runBenchmark<T extends BaseParticipant>(fileConfig: BenchmarkConfig<T>, task: BenchmarkTask<T>, argv?: string[]): Promise<BenchmarkRunOutcome>;
+declare function runBenchmark<T extends BaseParticipant>(fileConfig: BenchmarkConfig<T>, task: BenchmarkTask<T>, argv?: string[], options?: RunBenchmarkOptions): Promise<BenchmarkRunOutcome>;
+interface RunBenchmarkWorkerOptions<T extends BaseParticipant = BaseParticipant> {
+    benchmarkSlug: string;
+    benchmarkName?: string;
+    runKey?: string;
+    participant: T;
+    task: BenchmarkTask<T>;
+    iterations?: number;
+    concurrency?: number;
+    staggerDelayMs?: number;
+    groupBy?: GroupBy;
+    noIngest?: boolean;
+}
+/**
+ * One-shot helper: run a single participant's worker for a benchmark without
+ * creating a `*.bench.ts` file. This is a convenience wrapper around
+ * `runBenchmark` that builds a minimal `BenchmarkConfig` from the supplied
+ * options.
+ */
+declare function runBenchmarkWorker<T extends BaseParticipant>(options: RunBenchmarkWorkerOptions<T>): Promise<BenchmarkRunOutcome>;
 
 /**
  * Dispatches one CLI invocation. Throws on bad usage / invalid exports and lets
@@ -495,4 +552,4 @@ declare function run(argv: string[]): Promise<void>;
 
 declare const BENCHSDK_RUNNER_VERSION: string;
 
-export { BENCHSDK_RUNNER_VERSION, type BenchmarkConfig, type BenchmarkDisplayConfig, type BenchmarkMetricDisplay, type BenchmarkOverviewDisplay, type BenchmarkRunOutcome, type BenchmarkScoreResult, type BenchmarkScoringConfig, type BenchmarkScoringMetric, type BenchmarkScoringSuccess, type BenchmarkScoringWeights, type BenchmarkStepDisplay, type BenchmarkTask, type CliArgs, type GroupBy, type MetricScoring, NoAvailableParticipantsError, type ParticipantRecords, type Phase, type ResolvedRunConfig, type ScoringSpec, ScoringSpecError, type TaskContext, TaskError, type TaskResult, type TaskStepOptions, defineBenchmarkConfig, defineTask, higherIsBetter, lowerIsBetter, mergeConfig, parseCliArgs, run, runBenchmark, runBenchmarkFile, score, scoringConfigToSpec, validateScoringSpec };
+export { BENCHSDK_RUNNER_VERSION, type BenchmarkConfig, BenchmarkConfigError, type BenchmarkConfigErrorItem, type BenchmarkDisplayConfig, type BenchmarkMetricDisplay, type BenchmarkOverviewDisplay, type BenchmarkRunOutcome, type BenchmarkScoreResult, type BenchmarkScoringConfig, type BenchmarkScoringMetric, type BenchmarkScoringSuccess, type BenchmarkScoringWeights, type BenchmarkStepDisplay, type BenchmarkTask, type CliArgs, type GroupBy, type MetricScoring, NoAvailableParticipantsError, type ParticipantRecords, type Phase, type PlatformConfig, type ResolvedRunConfig, type RunBenchmarkOptions, type RunBenchmarkWorkerOptions, type ScoringSpec, ScoringSpecError, type TaskContext, TaskError, type TaskResult, type TaskStepOptions, defineBenchmarkConfig, defineOnComplete, defineTask, higherIsBetter, lowerIsBetter, mergeConfig, parseCliArgs, run, runBenchmark, runBenchmarkFile, runBenchmarkWorker, score, scoringConfigToSpec, validateBenchmarkConfig, validateScoringSpec };