@oneharness/sdk 0.6.8 → 0.6.10

package/dist/generated/contracts.d.ts

@@ -1,3 +1,46 @@
+/**
+ * One control request the run handled, recorded in the report so a consumer
+ * can tell an interrupted turn from one that simply ended.
+ *
+ * A sum type discriminated by `outcome`, so a record can never say "served,
+ * and here is the refusal reason": the reason exists exactly when there was a
+ * refusal. Serialized flat — `{"outcome":"served","verb":…,"at":…}` /
+ * `{"outcome":"refused","verb":…,"at":…,"reason":…}`.
+ */
+export type ControlEvent = {
+    /**
+     * When the request was handled.
+     */
+    at: string;
+    outcome: "served";
+    /**
+     * The verb requested.
+     */
+    verb: "interrupt";
+    [k: string]: unknown;
+} | {
+    at: UtcInstant;
+    outcome: "refused";
+    reason: ControlReason;
+    verb: ControlVerb;
+    [k: string]: unknown;
+};
+/**
+ * An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.
+ */
+export type UtcInstant = string;
+/**
+ * Why a control request could not be served. Distinct reasons because a
+ * supervisor reacts differently to each: `unsupported` is permanent for the
+ * harness, `not_running` means the dispatch is gone, `no_active_turn` means
+ * the run is alive but between turns.
+ */
+export type ControlReason = "unsupported" | "no_active_turn" | "not_running";
+/**
+ * The control verb a supervisor sends. Only `interrupt` exists today; the
+ * frame's `v` is what leaves room for `steer` later.
+ */
+export type ControlVerb = "interrupt";
 export type ToolCallStatus = "completed" | "failed" | "timeout" | "interrupted";
 /**
  * How a normalized tool interval was obtained.
@@ -25,7 +68,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.
  */
@@ -47,6 +122,14 @@ export interface RunReport {
      * project last); empty under `--no-config` or when none exist.
      */
     config_files: string[];
+    /**
+     * Out-of-band turn control for this run (`--control`), or `null` when none
+     * was requested — which is every ordinary run. It records the socket a
+     * separate `oneharness interrupt` process could address, the harness
+     * mechanism behind it, and each request served, so a consumer can tell an
+     * interrupted turn from one that simply ended.
+     */
+    control: ControlReport | null;
     dry_run: boolean;
     /**
      * Fallback-mode metadata when this run drove the selected harnesses in
@@ -157,6 +240,25 @@ export interface BatchReport {
     strategy: "speed" | "min-tokens";
     [k: string]: unknown;
 }
+/**
+ * The run report's `control` block: where the socket lived, which mechanism
+ * backed it, and every request served over the run's lifetime.
+ */
+export interface ControlReport {
+    /**
+     * Every control request served, in order.
+     */
+    interrupts: ControlEvent[];
+    /**
+     * The harness mechanism backing it.
+     */
+    mechanism: "claude-control-request" | "codex-app-server" | "opencode-http" | "acp-cancel" | "crush-http";
+    /**
+     * Absolute path of the socket this run listened on.
+     */
+    socket: string;
+    [k: string]: unknown;
+}
 /**
  * Metadata for a fallback run (harnesses tried in priority order until one
  * runs). Present on [`RunReport::fallback`] only in that mode. The per-harness
@@ -321,6 +423,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/registry.d.ts

@@ -1,3 +1,13 @@
+/**
+ * How a harness accepts an out-of-band interrupt for an in-flight turn.
+ *
+ * Registry data on [`crate::domain::harness::HarnessSpec::control`], sourced
+ * from a live interrupt against the real CLI — never guessed. `None` there
+ * means `oneharness interrupt` is a loud usage error for the harness, never a
+ * silent no-op: a supervisor that is told "ok" while the turn keeps running is
+ * worse off than one told the lever does not exist.
+ */
+export type ControlShape = "claude-control-request" | "codex-app-server" | "opencode-http" | "acp-cancel" | "crush-http";
 /**
  * The unified approval mode, from least to most autonomy. A harness may not
  * support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the
@@ -19,6 +29,13 @@ export interface ListReport {
     [k: string]: unknown;
 }
 export interface HarnessInfo {
+    /**
+     * How `run --control` + `oneharness interrupt` abort an in-flight turn on
+     * this harness (the mechanism id), or `null` when it has no out-of-band
+     * turn control at all — in which case `--control` is a loud usage error for
+     * it, never a socket that reports success while the turn keeps running.
+     */
+    control: ControlShape | null;
     default_bin: string;
     display: string;
     /**