@oneharness/sdk 0.6.7 → 0.6.9

package/dist/generated/contracts.d.ts

@@ -25,7 +25,39 @@ export type OutputFormat = "text" | "json" | "stream-json";
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
+/**
+ * Measured execution telemetry for one harness run: when the invocation ran,
+ * and — when the harness's transcript supports it — how its wall clock split
+ * between provider latency and tool work.
+ *
+ * Carried from the runner/parser to the history writer *and*, since report
+ * schema `0.5`, serialized on [`RunResult::telemetry`]. Exposing it there is
+ * what lets a consumer read the numbers off the run it just made instead of
+ * re-opening the history file the same run wrote.
+ *
+ * Internally tagged by `source`, so the variant is a value a consumer switches
+ * on rather than a shape it has to sniff. Every variant states only what was
+ * actually measured — there is no variant meaning "no telemetry"; that is a
+ * `null` field.
+ */
+export type ExecutionTelemetry = {
+    finished_at: string | null;
+    model_ms: number | null;
+    source: "provider_measured";
+    started_at: string;
+    time_to_first_token_ms: number | null;
+    tool_ms: number | null;
+    [k: string]: unknown;
+} | {
+    source: "partial_invocation";
+    started_at: string;
+    [k: string]: unknown;
+} | {
+    source: "stdout_observed";
+    tool_ms: number;
+    [k: string]: unknown;
+};
 /**
  * The top-level `run` report written to stdout.
  */
@@ -251,7 +283,8 @@ export interface RunResult {
      */
     failure_kind: FailureKind | null;
     /**
-     * Where `failure_kind` was read (`stderr`/`stdout`); `null` when absent.
+     * Where `failure_kind` was read (`stderr`/`stdout`, or `config:env_from`
+     * for a candidate refused before spawning); `null` when absent.
      */
     failure_kind_source: string | null;
     /**
@@ -320,6 +353,14 @@ export interface RunResult {
      * see what the harness produced.
      */
     structured: unknown;
+    /**
+     * Measured execution telemetry for this run: the invocation bounds and, when
+     * the harness's transcript carried a trace to read them from, the
+     * model/tool split. `null` when nothing was measured — never estimated.
+     * Added in report schema `0.5`; before that a consumer had to re-read the
+     * history file for numbers the run itself already had.
+     */
+    telemetry: ExecutionTelemetry | null;
     /**
      * Best-effort final assistant text; `null` when extraction is impossible.
      */

package/dist/generated/history-line.d.ts

@@ -6,7 +6,7 @@ export type HistoryLine = ({
     harness: string;
     harness_id?: string | null | undefined;
     run_id: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     type: "event";
     variant?: string | null | undefined;
     [k: string]: unknown;
@@ -27,15 +27,21 @@ export type HistoryLine = ({
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | undefined;
+    schema_version?: "1.3" | "1.4" | undefined;
     [k: string]: unknown;
 } & ({
-    status?: "nonzero" | "timeout" | "spawn-error" | "skipped" | undefined;
+    status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
     [k: string]: unknown;
 } | {
     failure_kind: "tool_deferred";
     [k: string]: unknown;
 }))) & ({
+    status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.4" | undefined;
+    [k: string]: unknown;
+}) & ({
     duration_ms: number;
     /**
      * Normalized failure text for a run that did not succeed (see
@@ -56,7 +62,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at: string;
@@ -91,11 +97,11 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at: string;
-    status: "timeout" | "spawn-error" | "skipped" | "planned";
+    status: "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
     text: string | null;
     text_source: string | null;
     time_to_first_token_ms?: number | null | undefined;
@@ -126,7 +132,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
@@ -161,11 +167,11 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     text: string | null;
     text_source: string | null;
     time_to_first_token_ms?: never | undefined;
@@ -196,11 +202,11 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.3";
+    schema_version: "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at: string;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     text: string | null;
     text_source: string | null;
     time_to_first_token_ms?: number | null | undefined;
@@ -231,7 +237,7 @@ export type HistoryLine = ({
     permission_mode: PermissionMode;
     project: string;
     prompt: string;
-    schema_version: "1.0" | "1.1" | "1.2" | "1.3";
+    schema_version: "1.0" | "1.1" | "1.2" | "1.3" | "1.4";
     session: string;
     session_id: string | null;
     started_at?: never | undefined;
@@ -272,7 +278,7 @@ export type PermissionMode = "read-only" | "plan" | "default" | "edit" | "auto"
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
 /**
  * One normalized action a harness took, harness-agnostic so a single consumer
  * assertion works across harnesses. Every field is always serialized (null when

package/dist/generated/history-records.d.ts

@@ -93,7 +93,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -323,7 +323,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -415,7 +415,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -507,7 +507,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -517,7 +517,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -599,7 +599,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3";
+    schema_version: "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -609,7 +609,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at: string;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -704,7 +704,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -954,21 +954,27 @@ export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" |
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
 export type HistoryRecords = (({
     error?: null | undefined;
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | undefined;
+    schema_version?: "1.3" | "1.4" | undefined;
     [k: string]: unknown;
 } & ({
-    status?: "nonzero" | "timeout" | "spawn-error" | "skipped" | undefined;
+    status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
     [k: string]: unknown;
 } | {
     failure_kind: "tool_deferred";
     [k: string]: unknown;
-}))) & HistoryRecord)[];
+}))) & ({
+    status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.4" | undefined;
+    [k: string]: unknown;
+}) & HistoryRecord)[];
 /**
  * One normalized action a harness took, harness-agnostic so a single consumer
  * assertion works across harnesses. Every field is always serialized (null when

package/dist/generated/history-stream-envelope.d.ts

@@ -14,15 +14,21 @@ export type HistoryStreamEnvelope = {
         [k: string]: unknown;
     } | ({
         error: string;
-        schema_version?: "1.3" | undefined;
+        schema_version?: "1.3" | "1.4" | undefined;
         [k: string]: unknown;
     } & ({
-        status?: "nonzero" | "timeout" | "spawn-error" | "skipped" | undefined;
+        status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
         [k: string]: unknown;
     } | {
         failure_kind: "tool_deferred";
         [k: string]: unknown;
-    }))) & HistoryRecord;
+    }))) & ({
+        status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
+        [k: string]: unknown;
+    } | {
+        schema_version?: "1.4" | undefined;
+        [k: string]: unknown;
+    }) & HistoryRecord;
     type: "record";
     [k: string]: unknown;
 } | {
@@ -125,7 +131,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -355,7 +361,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -447,7 +453,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -539,7 +545,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -549,7 +555,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -631,7 +637,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3";
+    schema_version: "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -641,7 +647,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at: string;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -736,7 +742,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -986,13 +992,13 @@ export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" |
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
 export type HistoryEventLine = {
     event: ActionEvent;
     harness: string;
     harness_id?: string | null | undefined;
     run_id: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {

package/dist/generated/history.d.ts

@@ -8,15 +8,21 @@ export type HistoryRecord = ({
     [k: string]: unknown;
 } | ({
     error: string;
-    schema_version?: "1.3" | undefined;
+    schema_version?: "1.3" | "1.4" | undefined;
     [k: string]: unknown;
 } & ({
-    status?: "nonzero" | "timeout" | "spawn-error" | "skipped" | undefined;
+    status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
     [k: string]: unknown;
 } | {
     failure_kind: "tool_deferred";
     [k: string]: unknown;
 }))) & ({
+    status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.4" | undefined;
+    [k: string]: unknown;
+}) & ({
     duration_ms: number;
     /**
      * Best-effort normalized failure text for a run that did not succeed: the
@@ -111,7 +117,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -341,7 +347,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -433,7 +439,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -525,7 +531,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2" | "1.3";
+    schema_version: "1.2" | "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -535,7 +541,7 @@ export type HistoryRecord = ({
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -617,7 +623,7 @@ export type HistoryRecord = ({
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.3";
+    schema_version: "1.3" | "1.4";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -627,7 +633,7 @@ export type HistoryRecord = ({
      */
     session_id: string | null;
     started_at: string;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -722,7 +728,7 @@ export type HistoryRecord = ({
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    status: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -972,7 +978,7 @@ export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" |
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
 /**
  * One normalized action a harness took, harness-agnostic so a single consumer
  * assertion works across harnesses. Every field is always serialized (null when

package/dist/generated/run-stream-envelope.d.ts

@@ -42,7 +42,39 @@ export type OutputFormat = "text" | "json" | "stream-json";
 /**
  * The outcome of attempting to run one harness.
  */
-export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | "planned";
+/**
+ * Measured execution telemetry for one harness run: when the invocation ran,
+ * and — when the harness's transcript supports it — how its wall clock split
+ * between provider latency and tool work.
+ *
+ * Carried from the runner/parser to the history writer *and*, since report
+ * schema `0.5`, serialized on [`RunResult::telemetry`]. Exposing it there is
+ * what lets a consumer read the numbers off the run it just made instead of
+ * re-opening the history file the same run wrote.
+ *
+ * Internally tagged by `source`, so the variant is a value a consumer switches
+ * on rather than a shape it has to sniff. Every variant states only what was
+ * actually measured — there is no variant meaning "no telemetry"; that is a
+ * `null` field.
+ */
+export type ExecutionTelemetry = {
+    finished_at: string | null;
+    model_ms: number | null;
+    source: "provider_measured";
+    started_at: string;
+    time_to_first_token_ms: number | null;
+    tool_ms: number | null;
+    [k: string]: unknown;
+} | {
+    source: "partial_invocation";
+    started_at: string;
+    [k: string]: unknown;
+} | {
+    source: "stdout_observed";
+    tool_ms: number;
+    [k: string]: unknown;
+};
 /**
  * One normalized action a harness took, harness-agnostic so a single consumer
  * assertion works across harnesses. Every field is always serialized (null when
@@ -325,7 +357,8 @@ export interface RunResult {
      */
     failure_kind: FailureKind | null;
     /**
-     * Where `failure_kind` was read (`stderr`/`stdout`); `null` when absent.
+     * Where `failure_kind` was read (`stderr`/`stdout`, or `config:env_from`
+     * for a candidate refused before spawning); `null` when absent.
      */
     failure_kind_source: string | null;
     /**
@@ -394,6 +427,14 @@ export interface RunResult {
      * see what the harness produced.
      */
     structured: unknown;
+    /**
+     * Measured execution telemetry for this run: the invocation bounds and, when
+     * the harness's transcript carried a trace to read them from, the
+     * model/tool split. `null` when nothing was measured — never estimated.
+     * Added in report schema `0.5`; before that a consumer had to re-read the
+     * history file for numbers the run itself already had.
+     */
+    telemetry: ExecutionTelemetry | null;
     /**
      * Best-effort final assistant text; `null` when extraction is impossible.
      */