@oneharness/sdk 0.6.5 → 0.6.7

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

@@ -4,7 +4,25 @@
  * `history_id` remains the resumable cursor.
  */
 export type HistoryStreamEnvelope = {
-    record: HistoryRecord;
+    /**
+     * One harness run, normalized and frozen for the history log. Serialized as one
+     * JSONL line per harness run, appended as the run finalizes. Carries only the
+     * normalized cross-harness signals — no raw stdout/stderr.
+     */
+    record: ({
+        error?: null | undefined;
+        [k: string]: unknown;
+    } | ({
+        error: string;
+        schema_version?: "1.3" | undefined;
+        [k: string]: unknown;
+    } & ({
+        status?: "nonzero" | "timeout" | "spawn-error" | "skipped" | undefined;
+        [k: string]: unknown;
+    } | {
+        failure_kind: "tool_deferred";
+        [k: string]: unknown;
+    }))) & HistoryRecord;
     type: "record";
     [k: string]: unknown;
 } | {
@@ -12,13 +30,22 @@ export type HistoryStreamEnvelope = {
     type: "event";
     [k: string]: unknown;
 };
-/**
- * One harness run, normalized and frozen for the history log. Serialized as one
- * JSONL line per harness run, appended as the run finalizes. Carries only the
- * normalized cross-harness signals — no raw stdout/stderr.
- */
 export type HistoryRecord = {
     duration_ms: number;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
@@ -98,7 +125,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2";
+    schema_version: "1.2" | "1.3";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -128,6 +155,20 @@ export type HistoryRecord = {
     [k: string]: unknown;
 } | {
     duration_ms: number;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
@@ -210,7 +251,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.1";
+    schema_version: "1.0" | "1.1";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -239,58 +280,50 @@ export type HistoryRecord = {
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
-    duration_ms: number;
+    duration_ms: number | null;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
      */
-    events: (((ActionEvent & {
-        duration_ms: number;
-        finished_at: string;
-        kind: "tool_call";
-        started_at: string;
-        status: "completed";
-        tool_call_id: string;
-        [k: string]: unknown;
-    }) | (ActionEvent & {
-        duration_ms: number;
-        finished_at: string;
-        kind: "tool_call";
-        started_at: string;
-        status: "failed";
-        tool_call_id: string;
-        [k: string]: unknown;
-    }) | (ActionEvent & {
-        kind: "tool_call";
-        started_at: string;
-        status: "timeout";
-        tool_call_id: string;
-        [k: string]: unknown;
-    }) | (ActionEvent & {
-        kind: "tool_call";
-        started_at: string;
-        status: "interrupted";
-        tool_call_id: string;
-        [k: string]: unknown;
-    }) | (ActionEvent & {
-        kind?: "tool_result" | undefined;
-        [k: string]: unknown;
-    })) & {
-        timing_source?: never | undefined;
+    events: {
+        duration_ms?: null | undefined;
+        finished_at?: null | undefined;
+        index: number;
+        input: unknown;
+        kind: string;
+        name: string | null;
+        output: string | null;
+        started_at?: null | undefined;
+        status?: null | undefined;
+        tool_call_id?: string | null | undefined;
         [k: string]: unknown;
-    })[] | null;
+    }[] | null;
     exit_code: number | null;
     /**
      * Best-effort classified failure reason (see [`FailureKind`]); `null` when
      * unclassified.
      */
     failure_kind: FailureKind | null;
-    finished_at: string | null;
+    finished_at: null;
     /**
      * Canonical harness id (e.g. `claude-code`).
      */
     harness: string;
-    harness_id?: string | undefined;
+    harness_id: string;
     /**
      * Globally unique, time-ordered record id. This is also the cursor accepted
      * by `history watch --after` and the exact id accepted by history lookup.
@@ -301,7 +334,7 @@ export type HistoryRecord = {
      * The effective top-level model for the run, if any.
      */
     model: string | null;
-    model_ms: number;
+    model_ms?: never | undefined;
     /**
      * The human-meaningful session name (see [`session_name`]); repeated on
      * every record so a reader can resolve a session by name from any line.
@@ -322,7 +355,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.0";
+    schema_version: "1.2" | "1.3";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -331,8 +364,8 @@ export type HistoryRecord = {
      * The harness's own continuation id, when it exposed one; `null` otherwise.
      */
     session_id: string | null;
-    started_at: string;
-    status: Status;
+    started_at?: never | undefined;
+    status: "ok" | "planned";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -341,34 +374,36 @@ export type HistoryRecord = {
      * How `text` was extracted; `null` when absent.
      */
     text_source: string | null;
-    time_to_first_token_ms?: number | null | undefined;
+    time_to_first_token_ms?: never | undefined;
     /**
      * RFC3339 UTC instant the record was written (append time).
      */
     timestamp: string;
-    tool_ms: number;
+    tool_ms?: never | undefined;
     usage: Usage2;
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
-    duration_ms: number | null;
+    duration_ms: number;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
      */
-    events: {
-        duration_ms?: null | undefined;
-        finished_at?: null | undefined;
-        index: number;
-        input: unknown;
-        kind: string;
-        name: string | null;
-        output: string | null;
-        started_at?: null | undefined;
-        status?: null | undefined;
-        tool_call_id?: string | null | undefined;
-        [k: string]: unknown;
-    }[] | null;
+    events: ActionEvent[] | null;
     exit_code: number | null;
     /**
      * Best-effort classified failure reason (see [`FailureKind`]); `null` when
@@ -397,7 +432,7 @@ export type HistoryRecord = {
      * every record so a reader can resolve a session by name from any line.
      */
     name: string;
-    observed_tool_ms?: never | undefined;
+    observed_tool_ms: number;
     /**
      * The normalized approval mode requested for the run.
      */
@@ -412,7 +447,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2";
+    schema_version: "1.2" | "1.3";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -441,7 +476,21 @@ export type HistoryRecord = {
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
-    duration_ms: number;
+    duration_ms: number | null;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
@@ -475,7 +524,7 @@ export type HistoryRecord = {
      * every record so a reader can resolve a session by name from any line.
      */
     name: string;
-    observed_tool_ms: number;
+    observed_tool_ms?: never | undefined;
     /**
      * The normalized approval mode requested for the run.
      */
@@ -490,7 +539,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.2";
+    schema_version: "1.2" | "1.3";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -500,7 +549,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: Status;
+    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -518,25 +567,119 @@ export type HistoryRecord = {
     usage: Usage4;
     variant?: string | null | undefined;
     [k: string]: unknown;
+} | {
+    duration_ms: number;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
+    /**
+     * Best-effort normalized tool-call events; `null` when the harness exposes
+     * no machine-readable trace.
+     */
+    events: ActionEvent[] | null;
+    exit_code: number | null;
+    /**
+     * Best-effort classified failure reason (see [`FailureKind`]); `null` when
+     * unclassified.
+     */
+    failure_kind: FailureKind | null;
+    finished_at: null;
+    /**
+     * Canonical harness id (e.g. `claude-code`).
+     */
+    harness: string;
+    harness_id: string;
+    /**
+     * Globally unique, time-ordered record id. This is also the cursor accepted
+     * by `history watch --after` and the exact id accepted by history lookup.
+     */
+    history_id: string;
+    labels?: HistoryLabels5 | undefined;
+    /**
+     * The effective top-level model for the run, if any.
+     */
+    model: string | null;
+    model_ms?: never | undefined;
+    /**
+     * The human-meaningful session name (see [`session_name`]); repeated on
+     * every record so a reader can resolve a session by name from any line.
+     */
+    name: string;
+    observed_tool_ms?: never | undefined;
+    /**
+     * The normalized approval mode requested for the run.
+     */
+    permission_mode: "read-only" | "plan" | "default" | "edit" | "auto" | "bypass";
+    /**
+     * The project directory the run operated in (the real path, not the
+     * on-disk slug), so the list view can show where a session ran.
+     */
+    project: string;
+    /**
+     * The prompt this harness run received (its own, on a batch run; else the
+     * run's single prompt).
+     */
+    prompt: string;
+    schema_version: "1.3";
+    /**
+     * The oneharness session id this run belongs to (the history file's stem).
+     */
+    session: string;
+    /**
+     * The harness's own continuation id, when it exposed one; `null` otherwise.
+     */
+    session_id: string | null;
+    started_at: string;
+    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
+    /**
+     * Best-effort final assistant text; `null` when extraction was impossible.
+     */
+    text: string | null;
+    /**
+     * How `text` was extracted; `null` when absent.
+     */
+    text_source: string | null;
+    time_to_first_token_ms?: number | null | undefined;
+    /**
+     * RFC3339 UTC instant the record was written (append time).
+     */
+    timestamp: string;
+    tool_ms?: never | undefined;
+    usage: Usage5;
+    variant?: string | null | undefined;
+    [k: string]: unknown;
 } | {
     duration_ms: number | null;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
      */
-    events: ({
-        duration_ms?: null | undefined;
-        finished_at?: null | undefined;
-        index: number;
-        input: unknown;
-        kind: string;
-        name: string | null;
-        output: string | null;
-        started_at?: null | undefined;
-        status?: null | undefined;
-        tool_call_id?: string | null | undefined;
-        [k: string]: unknown;
-    } & {
+    events: (ActionEvent & {
         timing_source?: never | undefined;
         [k: string]: unknown;
     })[] | null;
@@ -557,7 +700,7 @@ export type HistoryRecord = {
      * by `history watch --after` and the exact id accepted by history lookup.
      */
     history_id: string;
-    labels?: HistoryLabels5 | undefined;
+    labels?: HistoryLabels6 | undefined;
     /**
      * The effective top-level model for the run, if any.
      */
@@ -583,7 +726,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.1";
+    schema_version: "1.0" | "1.1";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -593,7 +736,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: Status;
+    status: "nonzero" | "timeout" | "spawn-error" | "skipped";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -608,11 +751,25 @@ export type HistoryRecord = {
      */
     timestamp: string;
     tool_ms?: never | undefined;
-    usage: Usage5;
+    usage: Usage6;
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
     duration_ms: number | null;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     /**
      * Best-effort normalized tool-call events; `null` when the harness exposes
      * no machine-readable trace.
@@ -650,7 +807,7 @@ export type HistoryRecord = {
      * by `history watch --after` and the exact id accepted by history lookup.
      */
     history_id: string;
-    labels?: HistoryLabels6 | undefined;
+    labels?: HistoryLabels7 | undefined;
     /**
      * The effective top-level model for the run, if any.
      */
@@ -676,7 +833,7 @@ export type HistoryRecord = {
      * run's single prompt).
      */
     prompt: string;
-    schema_version: "1.0";
+    schema_version: "1.0" | "1.1";
     /**
      * The oneharness session id this run belongs to (the history file's stem).
      */
@@ -686,7 +843,7 @@ export type HistoryRecord = {
      */
     session_id: string | null;
     started_at?: never | undefined;
-    status: Status;
+    status: "ok" | "planned";
     /**
      * Best-effort final assistant text; `null` when extraction was impossible.
      */
@@ -701,11 +858,25 @@ export type HistoryRecord = {
      */
     timestamp: string;
     tool_ms?: never | undefined;
-    usage: Usage6;
+    usage: Usage7;
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
     duration_ms: number | null;
+    /**
+     * Best-effort normalized failure text for a run that did not succeed: the
+     * harness's own diagnostic as oneharness captured it on stderr, or
+     * oneharness's own message when it generated one (a spawn failure, a
+     * timeout, a binary that is not installed). This is the *only* place a
+     * record quotes the process's own bytes, and it is deliberately narrow —
+     * trimmed, bounded to [`ERROR_MAX`] characters, and written only for a run
+     * that failed. `failure_kind` says what class of failure it was; this says
+     * what the harness actually reported, which is what an operator reads when
+     * the class is unclassified. Never derived from stdout, so it can never
+     * stand in for provider output the run did not produce. Omitted on the wire
+     * when absent, and gated to [`FIRST_ERROR_SCHEMA_VERSION`].
+     */
+    error?: string | null | undefined;
     events: {
         index: number;
         input: unknown;
@@ -731,7 +902,7 @@ export type HistoryRecord = {
      * by `history watch --after` and the exact id accepted by history lookup.
      */
     history_id: string;
-    labels?: HistoryLabels7 | undefined;
+    labels?: HistoryLabels8 | undefined;
     /**
      * The effective top-level model for the run, if any.
      */
@@ -792,7 +963,7 @@ export type HistoryRecord = {
      */
     timestamp: string;
     tool_ms?: number | null | undefined;
-    usage: Usage7;
+    usage: Usage8;
     variant?: string | null | undefined;
     [k: string]: unknown;
 };
@@ -821,7 +992,7 @@ export type HistoryEventLine = {
     harness: string;
     harness_id?: string | null | undefined;
     run_id: string;
-    schema_version: "1.2";
+    schema_version: "1.2" | "1.3";
     variant?: string | null | undefined;
     [k: string]: unknown;
 } | {
@@ -1189,3 +1360,40 @@ export interface Usage7 {
     output_tokens: number | null;
     [k: string]: unknown;
 }
+/**
+ * Caller-supplied metadata used to select related task-graph records.
+ * Omitted on the wire when empty for additive compatibility.
+ */
+export interface HistoryLabels8 {
+    [k: string]: string;
+}
+/**
+ * Best-effort token/cost accounting (every field `null` when unreported).
+ */
+export interface Usage8 {
+    /**
+     * Prompt tokens served from the provider's prompt cache (a cheap read of a
+     * previously-written prefix), when the harness reports them. `None` when the
+     * harness does not surface cache counts — never `0` as a guess.
+     */
+    cache_read_tokens: number | null;
+    /**
+     * Prompt tokens written to the provider's prompt cache (a.k.a. cache
+     * creation), when the harness reports them. `None` when not surfaced.
+     */
+    cache_write_tokens: number | null;
+    /**
+     * Total cost in USD, when the harness reports it (often absent on
+     * subscription auth, where there is no per-call dollar figure).
+     */
+    cost_usd: number | null;
+    /**
+     * Prompt/input tokens billed, when the harness reports them.
+     */
+    input_tokens: number | null;
+    /**
+     * Completion/output tokens billed, when the harness reports them.
+     */
+    output_tokens: number | null;
+    [k: string]: unknown;
+}