@oneharness/sdk 0.6.8 → 0.6.10

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

@@ -20,6 +20,49 @@ export type ToolCallStatus = "completed" | "failed" | "timeout" | "interrupted";
  * How a normalized tool interval was obtained.
  */
 export type TimingSource = "provider_measured" | "stdout_observed";
+/**
+ * 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";
 /**
  * The normalized, closed set of failure reasons oneharness can classify from a
  * harness's output. It is the single source for the `failure_kind` contract
@@ -42,7 +85,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
@@ -121,6 +196,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
@@ -231,6 +314,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
@@ -395,6 +497,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.
      */