@oneharness/sdk 0.20.0 → 0.21.1

package/README.md

@@ -11,7 +11,7 @@ const checked: RunReport = RunReportSchema.parse(report);
 console.log(checked.results[0]?.text, checked.results[0]?.usage.input_tokens);
 ```
 
-The client covers every verb the CLI exposes, so nothing needs a hand-built command line: `run`, `runMock`, `runStream`, `list`, `detect`, `config`, `sync`, `init`, `usage`, `gate`, `mock`, `interrupt`, `history`, `historyList`, `historyWatch`, `historyClear`, `historyMigrate`, and `historyPointers`. That coverage is gated, not asserted here. `runMock` uses the deterministic responder shipped in the CLI; see [Testing patterns](../../docs/testing-patterns.md). Both streaming methods return async iterators:
+The client covers every verb the CLI exposes, so nothing needs a hand-built command line: `run`, `runMock`, `runStream`, `list`, `detect`, `config`, `sync`, `init`, `usage`, `gate`, `mock`, `interrupt`, `history`, `historyList`, `historyWatch`, `historyClear`, `historyMigrate`, `historyReindex`, and `historyPointers`. That coverage is gated, not asserted here. `runMock` uses the deterministic responder shipped in the CLI; see [Testing patterns](../../docs/testing-patterns.md). Both streaming methods return async iterators:
 
 ```ts
 for await (const envelope of oneharness.runStream({
@@ -35,7 +35,7 @@ Breaking or returning from either iterator terminates its oneharness subprocess.
 
 `null` usage fields mean the harness did not report the value; zero remains a real measured zero. String-valued harness/model/event identifiers should be treated as open sets for forward compatibility. `history` and `historyWatch` raise the exported `HistoryNotFoundError` when a session, record, or watch cursor cannot be resolved.
 
-Named exports include `RunOptionsSchema`, `HistoryLookupSchema`, `HistoryListOptionsSchema`, `HistoryWatchOptionsSchema`, `RunReportSchema`, `RunStreamEnvelopeSchema`, `RunResultSchema`, `ActionEventSchema`, `UsageSchema`, `HistoryRecordSchema`, `HistoryStreamEnvelopeSchema`, `HistoryRecordsSchema`, `HistoryListSchema`, `HistorySessionSummarySchema`, `ListReportSchema`, `HarnessInfoSchema`, and the registry/detection enum and object schemas. `RunStreamEnvelope` and `HistoryStreamEnvelope` are also exported TypeScript types for consumers building JSONL clients. Each schema's `z.infer` type is compile-time checked against its generated TypeScript type.
+Every contract the CLI reads or prints is exported as a Zod schema named after its generated TypeScript type plus `Schema` (`RunReport` → `RunReportSchema`), generated from the same Rust wire types. Each schema's `z.infer` type is compile-time checked against its generated TypeScript type.
 
 Output objects accept and preserve unknown fields. That deliberate loose-object behavior lets an older SDK validate a newer additive CLI response without erasing fields before an application can inspect them. Known fields are still validated recursively. The input schemas `RunOptionsSchema`, `HistoryLookupSchema`, `HistoryListOptionsSchema`, and `HistoryWatchOptionsSchema` are deliberately strict instead: unknown input keys are rejected because this SDK version cannot forward an option it does not understand, which also catches misspellings. Every method validates its input before spawning the CLI.
 

package/dist/generated/capabilities.d.ts

@@ -1,4 +1,10 @@
-export type FlagKind = "positional" | "value" | "repeated" | "switch" | "key-value" | "trailing";
+export type FlagKind = "positional" | "value" | "repeated" | "switch" | "key-value" | "trailing" | "window";
+/** The three spellings a `window` binding renders exactly one of. */
+export type WindowFlags = {
+    readonly days: string;
+    readonly since: string;
+    readonly allTime: string;
+};
 /**
  * What both members of a suppressed pair rendering an argument means.
  *
@@ -17,6 +23,8 @@ export type OptionBinding = {
     readonly unless: string | null;
     /** Only present beside an `unless`, which it says how to resolve. */
     readonly unless_resolution?: UnlessResolution;
+    /** Only present on a `window` binding: the flag each window renders. */
+    readonly window?: WindowFlags;
 };
 /** How a verb's stdout reaches a caller. */
 export type StdoutShape = "json" | "jsonl" | "text";
@@ -836,10 +844,10 @@ export declare const CAPABILITIES: {
         readonly method: "history";
         readonly argv: readonly ["history", "show"];
         readonly options: "history_lookup";
-        readonly output: "history_records";
+        readonly output: "history_show_entries";
         readonly stdout: "json";
         readonly stdin: false;
-        readonly rust: "oneharness_core::io::history::read_session";
+        readonly rust: "oneharness_core::io::history::read_session_display";
         readonly always: readonly ["--compact", "--format", "json"];
         readonly bindings: readonly [{
             readonly option: "session";
@@ -868,6 +876,16 @@ export declare const CAPABILITIES: {
             readonly flag: "--all-projects";
             readonly kind: "switch";
             readonly unless: null;
+        }, {
+            readonly option: "window";
+            readonly flag: "";
+            readonly kind: "window";
+            readonly unless: null;
+            readonly window: {
+                readonly days: "--days";
+                readonly since: "--since";
+                readonly allTime: "--all-time";
+            };
         }, {
             readonly option: "historyDir";
             readonly flag: "--history-dir";
@@ -912,6 +930,16 @@ export declare const CAPABILITIES: {
             readonly flag: "--all-projects";
             readonly kind: "switch";
             readonly unless: null;
+        }, {
+            readonly option: "window";
+            readonly flag: "";
+            readonly kind: "window";
+            readonly unless: null;
+            readonly window: {
+                readonly days: "--days";
+                readonly since: "--since";
+                readonly allTime: "--all-time";
+            };
         }, {
             readonly option: "historyDir";
             readonly flag: "--history-dir";
@@ -944,7 +972,8 @@ export declare const CAPABILITIES: {
             readonly option: "after";
             readonly flag: "--after";
             readonly kind: "value";
-            readonly unless: null;
+            readonly unless: "window";
+            readonly unless_resolution: "refuse";
         }, {
             readonly option: "labels";
             readonly flag: "--label";
@@ -981,6 +1010,16 @@ export declare const CAPABILITIES: {
             readonly flag: "--events";
             readonly kind: "switch";
             readonly unless: null;
+        }, {
+            readonly option: "window";
+            readonly flag: "";
+            readonly kind: "window";
+            readonly unless: null;
+            readonly window: {
+                readonly days: "--days";
+                readonly since: "--since";
+                readonly allTime: "--all-time";
+            };
         }, {
             readonly option: "config";
             readonly flag: "--config";
@@ -1067,6 +1106,34 @@ export declare const CAPABILITIES: {
         }];
         readonly uncovered: readonly [];
     };
+    readonly historyReindex: {
+        readonly method: "historyReindex";
+        readonly argv: readonly ["history", "reindex"];
+        readonly options: "history_reindex_options";
+        readonly output: "history_reindex_report";
+        readonly stdout: "json";
+        readonly stdin: false;
+        readonly rust: "oneharness_core::io::history::reindex";
+        readonly always: readonly ["--compact", "--format", "json"];
+        readonly bindings: readonly [{
+            readonly option: "historyDir";
+            readonly flag: "--history-dir";
+            readonly kind: "value";
+            readonly unless: null;
+        }, {
+            readonly option: "config";
+            readonly flag: "--config";
+            readonly kind: "repeated";
+            readonly unless: "noConfig";
+            readonly unless_resolution: "refuse";
+        }, {
+            readonly option: "noConfig";
+            readonly flag: "--no-config";
+            readonly kind: "switch";
+            readonly unless: null;
+        }];
+        readonly uncovered: readonly [];
+    };
     readonly historyPointers: {
         readonly method: "historyPointers";
         readonly argv: readonly ["history", "pointers"];

package/dist/generated/capabilities.js

@@ -941,10 +941,10 @@ export const CAPABILITIES = {
         method: "history",
         argv: ["history", "show"],
         options: "history_lookup",
-        output: "history_records",
+        output: "history_show_entries",
         stdout: "json",
         stdin: false,
-        rust: "oneharness_core::io::history::read_session",
+        rust: "oneharness_core::io::history::read_session_display",
         always: ["--compact", "--format", "json"],
         bindings: [
             {
@@ -979,6 +979,17 @@ export const CAPABILITIES = {
                 kind: "switch",
                 unless: null,
             },
+            {
+                option: "window",
+                flag: "",
+                kind: "window",
+                unless: null,
+                window: {
+                    days: "--days",
+                    since: "--since",
+                    allTime: "--all-time",
+                },
+            },
             {
                 option: "historyDir",
                 flag: "--history-dir",
@@ -1030,6 +1041,17 @@ export const CAPABILITIES = {
                 kind: "switch",
                 unless: null,
             },
+            {
+                option: "window",
+                flag: "",
+                kind: "window",
+                unless: null,
+                window: {
+                    days: "--days",
+                    since: "--since",
+                    allTime: "--all-time",
+                },
+            },
             {
                 option: "historyDir",
                 flag: "--history-dir",
@@ -1066,7 +1088,8 @@ export const CAPABILITIES = {
                 option: "after",
                 flag: "--after",
                 kind: "value",
-                unless: null,
+                unless: "window",
+                unless_resolution: "refuse",
             },
             {
                 option: "labels",
@@ -1111,6 +1134,17 @@ export const CAPABILITIES = {
                 kind: "switch",
                 unless: null,
             },
+            {
+                option: "window",
+                flag: "",
+                kind: "window",
+                unless: null,
+                window: {
+                    days: "--days",
+                    since: "--since",
+                    allTime: "--all-time",
+                },
+            },
             {
                 option: "config",
                 flag: "--config",
@@ -1210,6 +1244,38 @@ export const CAPABILITIES = {
         ],
         uncovered: [],
     },
+    historyReindex: {
+        method: "historyReindex",
+        argv: ["history", "reindex"],
+        options: "history_reindex_options",
+        output: "history_reindex_report",
+        stdout: "json",
+        stdin: false,
+        rust: "oneharness_core::io::history::reindex",
+        always: ["--compact", "--format", "json"],
+        bindings: [
+            {
+                option: "historyDir",
+                flag: "--history-dir",
+                kind: "value",
+                unless: null,
+            },
+            {
+                option: "config",
+                flag: "--config",
+                kind: "repeated",
+                unless: "noConfig",
+                unless_resolution: "refuse",
+            },
+            {
+                option: "noConfig",
+                flag: "--no-config",
+                kind: "switch",
+                unless: null,
+            },
+        ],
+        uncovered: [],
+    },
     historyPointers: {
         method: "historyPointers",
         argv: ["history", "pointers"],

package/dist/generated/history-list-options.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Which dates of the index a listing reads.
+ *
+ * It is also the one value an SDK history lookup, listing or watch takes as
+ * its `window`, so "from this date" and "from the beginning" cannot both be
+ * stated. On the wire it is externally tagged in camelCase —
+ * `{"recent": {"days": 3}}`, `{"since": "2026-01-05"}`, or `"allTime"` — and
+ * renders to the CLI's `--days`, `--since` or `--all-time`.
+ */
+export type HistoryWindow = {
+    recent: {
+        /**
+         * How many UTC days, today included; at least one.
+         */
+        days: number;
+    };
+} | {
+    since: string;
+} | "allTime";
 /**
  * Options accepted by `OneHarness.historyList()` in the published Node SDK.
  */
@@ -19,4 +38,10 @@ export interface HistoryListOptions {
      * Narrow to one configured harness identity (`claude-code:work`).
      */
     variant?: string | undefined;
+    /**
+     * Which dates of the index to read: the last `days` UTC days, from a
+     * UTC date on, or all time (every dated segment plus the legacy index an
+     * older oneharness kept). Omitted, the last 7 UTC days.
+     */
+    window?: HistoryWindow | null | undefined;
 }

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

@@ -24,6 +24,25 @@
  * non-empty.
  */
 export type HistoryLookup = HistoryLookupByLast | HistoryLookupBySession;
+/**
+ * Which dates of the index a listing reads.
+ *
+ * It is also the one value an SDK history lookup, listing or watch takes as
+ * its `window`, so "from this date" and "from the beginning" cannot both be
+ * stated. On the wire it is externally tagged in camelCase —
+ * `{"recent": {"days": 3}}`, `{"since": "2026-01-05"}`, or `"allTime"` — and
+ * renders to the CLI's `--days`, `--since` or `--all-time`.
+ */
+export type HistoryWindow = {
+    recent: {
+        /**
+         * How many UTC days, today included; at least one.
+         */
+        days: number;
+    };
+} | {
+    since: string;
+} | "allTime";
 /**
  * Select the most recent session.
  */
@@ -57,6 +76,12 @@ export interface HistoryLookupByLast {
      * than invalid, so `{"session": "", "last": true}` stays accepted.
      */
     session?: string | undefined;
+    /**
+     * Which dates of the index to read: the last `days` UTC days, from a
+     * UTC date on, or all time (every dated segment plus the legacy index an
+     * older oneharness kept). Omitted, the last 7 UTC days.
+     */
+    window?: HistoryWindow | null | undefined;
 }
 /**
  * Select the session named by `session`.
@@ -91,4 +116,10 @@ export interface HistoryLookupBySession {
      * the name that selects, so it must be non-empty.
      */
     session: string;
+    /**
+     * Which dates of the index to read: the last `days` UTC days, from a
+     * UTC date on, or all time (every dated segment plus the legacy index an
+     * older oneharness kept). Omitted, the last 7 UTC days.
+     */
+    window?: HistoryWindow | null | undefined;
 }

package/dist/generated/history-reindex-options.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options accepted by the language SDKs' `historyReindex()`.
+ */
+export interface HistoryReindexOptions {
+    /**
+     * Load configuration from exactly these files, in order, skipping
+     * user/project discovery; each later file overrides the earlier ones.
+     */
+    config?: string[] | undefined;
+    historyDir?: string | undefined;
+    /**
+     * Ignore every configuration file and `ONEHARNESS_*` override. `true`
+     * beside a non-empty `config` is refused before anything runs.
+     */
+    noConfig?: boolean | undefined;
+}

package/dist/generated/history-reindex-report.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `oneharness history reindex` output contract.
+ */
+export interface HistoryReindexReport {
+    /**
+     * The sum of `segments[].added`.
+     */
+    entries_added: number;
+    /**
+     * How many session files were read.
+     */
+    files_read: number;
+    /**
+     * One row per segment this run appended to, in file-name order; a
+     * segment that already held every entry is not listed.
+     */
+    segments: SegmentReindexSummary[];
+    /**
+     * Every session file (or project directory) that could not be read,
+     * with why. The rest are indexed regardless.
+     */
+    unreadable: UnreadableSessionFile[];
+    [k: string]: unknown;
+}
+/**
+ * What [`reindex`] appended to one segment.
+ */
+export interface SegmentReindexSummary {
+    /**
+     * How many entries this run appended to it.
+     */
+    added: number;
+    /**
+     * The segment's path, as a display string.
+     */
+    path: string;
+    /**
+     * The segment's file name (`runs-YYYY-MM-DD.ndjson` or
+     * `events-YYYY-MM-DD.ndjson`).
+     */
+    segment: string;
+    [k: string]: unknown;
+}
+/**
+ * A session file [`reindex`] could not read.
+ */
+export interface UnreadableSessionFile {
+    /**
+     * Why it could not be read, as the operating system said it.
+     */
+    error: string;
+    path: string;
+    [k: string]: unknown;
+}

package/dist/generated/history-reindex-report.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

package/dist/generated/{history-records.d.ts → history-show-entries.d.ts}

@@ -1,4 +1,66 @@
-export type HistoryRecord = {
+/**
+ * One entry of `history show`'s answer: a finished run's record, or a run still
+ * in flight.
+ */
+export type HistoryShowEntry = (({
+    error?: null | undefined;
+    [k: string]: unknown;
+} | ({
+    error: string;
+    schema_version?: "1.3" | "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+} & ({
+    status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
+    [k: string]: unknown;
+} | {
+    failure_kind: "tool_deferred";
+    [k: string]: unknown;
+}))) & ({
+    work?: null | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.7" | "1.8" | "1.9" | undefined;
+    status?: "nonzero" | "timeout" | "cancelled" | undefined;
+    work: "done" | "none";
+    [k: string]: unknown;
+}) & ({
+    observed_model?: null | undefined;
+    [k: string]: unknown;
+} | {
+    observed_model: string;
+    schema_version?: "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+}) & ({
+    status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+}) & (({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "model_mismatch" | "server_overloaded" | null;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "model_mismatch" | "server_overloaded" | null;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.6" | "1.7" | "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "server_overloaded" | null;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.8" | "1.9" | undefined;
+    [k: string]: unknown;
+}) & ({
+    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "model_mismatch" | null;
+    [k: string]: unknown;
+} | {
+    schema_version?: "1.9" | undefined;
+    [k: string]: unknown;
+})) & ({
     duration_ms: number;
     /**
      * Best-effort normalized failure text for a run that did not succeed: the
@@ -1255,7 +1317,7 @@ export type HistoryRecord = {
      */
     work?: RunWork | null | undefined;
     [k: string]: unknown;
-};
+})) | IncompleteHistoryRun;
 export type ToolCallStatus = "completed" | "failed" | "timeout" | "interrupted";
 /**
  * How a normalized tool interval was obtained.
@@ -1298,65 +1360,7 @@ export type Status = "ok" | "nonzero" | "timeout" | "cancelled" | "spawn-error"
  * [billed]: crate::domain::signals::Usage::reports_billed_work
  */
 export type RunWork = "done" | "none";
-export type HistoryRecords = (({
-    error?: null | undefined;
-    [k: string]: unknown;
-} | ({
-    error: string;
-    schema_version?: "1.3" | "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-} & ({
-    status?: "nonzero" | "timeout" | "cancelled" | "spawn-error" | "skipped" | undefined;
-    [k: string]: unknown;
-} | {
-    failure_kind: "tool_deferred";
-    [k: string]: unknown;
-}))) & ({
-    work?: null | undefined;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.7" | "1.8" | "1.9" | undefined;
-    status?: "nonzero" | "timeout" | "cancelled" | undefined;
-    work: "done" | "none";
-    [k: string]: unknown;
-}) & ({
-    observed_model?: null | undefined;
-    [k: string]: unknown;
-} | {
-    observed_model: string;
-    schema_version?: "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-}) & ({
-    status?: "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned" | undefined;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-}) & (({
-    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "model_mismatch" | "server_overloaded" | null;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-}) & ({
-    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "model_mismatch" | "server_overloaded" | null;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.6" | "1.7" | "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-}) & ({
-    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "server_overloaded" | null;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.8" | "1.9" | undefined;
-    [k: string]: unknown;
-}) & ({
-    failure_kind?: "auth" | "rate_limit" | "model_not_found" | "quota" | "session_not_found" | "tool_deferred" | "untrusted_directory" | "input_too_large" | "model_mismatch" | null;
-    [k: string]: unknown;
-} | {
-    schema_version?: "1.9" | undefined;
-    [k: string]: unknown;
-})) & HistoryRecord)[];
+export type HistoryShowEntries = HistoryShowEntry[];
 /**
  * One normalized action a harness took, harness-agnostic so a single consumer
  * assertion works across harnesses. Every field is always serialized (null when
@@ -1753,3 +1757,27 @@ export interface Usage8 {
     output_tokens: number | null;
     [k: string]: unknown;
 }
+/**
+ * A run that has published events but no closing record yet.
+ */
+export interface IncompleteHistoryRun {
+    /**
+     * The events published so far, in `index` order; never empty.
+     *
+     * @minItems 1
+     */
+    events: ActionEvent[];
+    /**
+     * The harness the event lines name.
+     */
+    harness: string;
+    /**
+     * The id the run's closing record will carry as its `history_id`.
+     */
+    run_id: string;
+    /**
+     * Always `incomplete`: what tells this entry apart from a record.
+     */
+    type: "incomplete";
+    [k: string]: unknown;
+}

package/dist/generated/history-show-entries.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

package/dist/generated/history-watch-options.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Which dates of the index a listing reads.
+ *
+ * It is also the one value an SDK history lookup, listing or watch takes as
+ * its `window`, so "from this date" and "from the beginning" cannot both be
+ * stated. On the wire it is externally tagged in camelCase —
+ * `{"recent": {"days": 3}}`, `{"since": "2026-01-05"}`, or `"allTime"` — and
+ * renders to the CLI's `--days`, `--since` or `--all-time`.
+ */
+export type HistoryWindow = {
+    recent: {
+        /**
+         * How many UTC days, today included; at least one.
+         */
+        days: number;
+    };
+} | {
+    since: string;
+} | "allTime";
 /**
  * Options accepted by the language SDKs' continuous history iterators.
  *
@@ -32,6 +51,13 @@ export interface HistoryWatchOptions {
      * Narrow to one configured harness identity (`claude-code:work`).
      */
     variant?: string | undefined;
+    /**
+     * Where the watch starts when no `after` cursor is given: the beginning
+     * of the last `days` UTC days, of a UTC date, or of all time (the legacy
+     * index an older oneharness kept included). Omitted, the current UTC
+     * day. Refused beside `after`, the other answer to where a watch begins.
+     */
+    window?: HistoryWindow | null | undefined;
 }
 export interface HistoryLabels {
     [k: string]: string;