@oneharness/sdk 0.3.24 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @oneharness/sdk
 
-Typed Node.js access to the `oneharness` engine. The SDK launches the packaged CLI and validates every response with named Zod schemas generated from the Rust wire types. The corresponding TypeScript declarations come from the same Rust JSON Schema bundle.
+Typed Node.js access to the `oneharness` engine. The SDK launches its exact-version packaged CLI dependency and validates every response and stream envelope with named Zod schemas generated from the Rust wire types. The corresponding TypeScript declarations come from the same Rust JSON Schema bundle.
 
 ```ts
 import { OneHarness, RunReportSchema, type RunReport } from "@oneharness/sdk";
@@ -11,11 +11,31 @@ const checked: RunReport = RunReportSchema.parse(report);
 console.log(checked.results[0]?.text, checked.results[0]?.usage.input_tokens);
 ```
 
-`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.
+The complete client surface is `run`, `runStream`, `list`, `detect`, `history`, `historyList`, and `historyWatch`. Both streaming methods return async iterators:
 
-Named exports include `RunOptionsSchema`, `HistoryLookupSchema`, `HistoryListOptionsSchema`, `RunReportSchema`, `RunResultSchema`, `ActionEventSchema`, `UsageSchema`, `HistoryRecordSchema`, `HistoryRecordsSchema`, `HistoryListSchema`, `HistorySessionSummarySchema`, `ListReportSchema`, `HarnessInfoSchema`, and the registry/detection enum and object schemas. Each schema's `z.infer` type is compile-time checked against its generated TypeScript type.
+```ts
+for await (const envelope of oneharness.runStream({
+  prompt: "Inspect this repository",
+  harnesses: ["codex"],
+})) {
+  if (envelope.type === "event" && envelope.event.name === "shell") break;
+}
+
+for await (const envelope of oneharness.historyWatch({
+  labels: { graph: "release" },
+  after: lastHistoryId,
+})) {
+  console.log(envelope.record.history_id, envelope.record.status);
+}
+```
+
+Breaking or returning from either iterator terminates its oneharness subprocess. Every line is validated before it is yielded; malformed or unknown envelope variants fail the iterator. Additive fields within known output envelopes are accepted and preserved.
+
+`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.
 
-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`, and `HistoryListOptionsSchema` 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. `run`, `history`, and `historyList` validate against them before reading any option, so an unusable input raises `invalid oneharness run options` / `invalid oneharness history options` / `invalid oneharness history list options` rather than reaching the CLI.
+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.
 
 Nullable CLI fields remain required object keys: the generated response schemas model Rust's serialization contract, so an unavailable value is `null`, while an omitted guaranteed field is malformed. Optional `RunOptions`, `HistoryLookup`, and `HistoryListOptions` fields may be absent or explicitly `undefined`; every `HistoryListOptions` field is optional, so `historyList()` and `historyList({})` both list the default store.
 

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

@@ -13,6 +13,7 @@ export interface HistorySessionSummary {
      * The session id (the file stem), unique and sortable by start time.
      */
     id: string;
+    labels?: HistoryLabels | undefined;
     /**
      * The human-meaningful session name (non-unique).
      */
@@ -35,3 +36,9 @@ export interface HistorySessionSummary {
     started: string;
     [k: string]: unknown;
 }
+/**
+ * Labels shared by every record in the session. Omitted when empty.
+ */
+export interface HistoryLabels {
+    [k: string]: string;
+}

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

@@ -36,6 +36,12 @@ export interface HistoryRecord {
      * Canonical harness id (e.g. `claude-code`).
      */
     harness: 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?: HistoryLabels | undefined;
     /**
      * The effective top-level model for the run, if any.
      */
@@ -118,6 +124,13 @@ export interface ActionEvent {
     output: string | 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 HistoryLabels {
+    [k: string]: string;
+}
 /**
  * Best-effort token/cost accounting (every field `null` when unreported).
  */

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

@@ -0,0 +1,172 @@
+/**
+ * One line emitted by `history watch --format jsonl`. The tagged envelope lets
+ * SDKs distinguish the stream from other NDJSON surfaces while the record's
+ * `history_id` remains the resumable cursor.
+ */
+export type HistoryStreamEnvelope = {
+    record: HistoryRecord;
+    type: "record";
+    [k: string]: unknown;
+};
+/**
+ * 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
+ * value: serialized as the snake_case token a consumer reads in the report
+ * (`auth`, `rate_limit`, `model_not_found`, `quota`, `tool_deferred`), so the
+ * wire shape is unchanged — modeling it as an enum keeps a misspelled or
+ * invalid kind unrepresentable and gives every producer/consumer (classifier,
+ * `is_failure`, the fallback fall-through rule, the report, history) one
+ * definition to share instead of scattered string literals.
+ */
+export type FailureKind = "auth" | "rate_limit" | "model_not_found" | "quota" | "tool_deferred";
+/**
+ * The outcome of attempting to run one harness.
+ */
+export type Status = "ok" | "nonzero" | "timeout" | "spawn-error" | "skipped" | "planned";
+/**
+ * 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 interface HistoryRecord {
+    duration_ms: number | null;
+    /**
+     * 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;
+    /**
+     * Canonical harness id (e.g. `claude-code`).
+     */
+    harness: 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?: HistoryLabels | undefined;
+    /**
+     * The effective top-level model for the run, if any.
+     */
+    model: string | null;
+    /**
+     * 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;
+    /**
+     * 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: string;
+    /**
+     * 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;
+    status: Status;
+    /**
+     * Best-effort final assistant text; `null` when extraction was impossible.
+     */
+    text: string | null;
+    /**
+     * How `text` was extracted; `null` when absent.
+     */
+    text_source: string | null;
+    /**
+     * RFC3339 UTC instant the record was written (append time).
+     */
+    timestamp: string;
+    usage: Usage;
+    [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
+ * absent) so the shape is stable, mirroring the `usage` contract.
+ */
+export interface ActionEvent {
+    /**
+     * Position of this event within the run, so "≤ N tool calls" and "did X
+     * before Y" are expressible from a stable ordering (also array order).
+     */
+    index: number;
+    /**
+     * Structured, tool-shaped arguments (the command string, the file path),
+     * so a consumer asserts on specific args without re-parsing; `null` when the
+     * event carries none (e.g. a `tool_result`).
+     */
+    input: unknown;
+    /**
+     * The kind of event: `tool_call` (the model invoked a tool) or
+     * `tool_result` (the observation returned to the model). Left open for
+     * future kinds rather than an enum, so a new shape never breaks the field.
+     */
+    kind: string;
+    /**
+     * Normalized tool name where knowable (e.g. `bash`, `Edit`); `null` for a
+     * `tool_result`, or when the harness did not name the tool.
+     */
+    name: string | null;
+    /**
+     * The result/observation text, when the trace exposes it; `null` otherwise.
+     */
+    output: string | 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 HistoryLabels {
+    [k: string]: string;
+}
+/**
+ * Best-effort token/cost accounting (every field `null` when unreported).
+ */
+export interface Usage {
+    /**
+     * 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;
+}

package/dist/generated/history-stream-envelope.js

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

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

@@ -0,0 +1,17 @@
+/**
+ * Options accepted by the language SDKs' continuous history iterators.
+ *
+ * The CLI spells `labels` as repeated `--label key=value` arguments, while an
+ * SDK can expose the validated map directly. Unknown fields remain a boundary
+ * error, as they are for every other SDK input contract.
+ */
+export interface HistoryWatchOptions {
+    after?: string | undefined;
+    allProjects?: boolean | undefined;
+    historyDir?: string | undefined;
+    labels?: HistoryLabels | undefined;
+    project?: string | undefined;
+}
+export interface HistoryLabels {
+    [k: string]: string;
+}

package/dist/generated/history-watch-options.js

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

package/dist/generated/history.d.ts

@@ -35,6 +35,12 @@ export interface HistoryRecord {
      * Canonical harness id (e.g. `claude-code`).
      */
     harness: 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?: HistoryLabels | undefined;
     /**
      * The effective top-level model for the run, if any.
      */
@@ -117,6 +123,13 @@ export interface ActionEvent {
     output: string | 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 HistoryLabels {
+    [k: string]: string;
+}
 /**
  * Best-effort token/cost accounting (every field `null` when unreported).
  */

package/dist/generated/options.d.ts

@@ -25,6 +25,7 @@ export interface RunOptions {
     harnesses?: readonly string[] | undefined;
     history?: boolean | undefined;
     historyDir?: string | undefined;
+    historyLabels?: HistoryLabels | undefined;
     historyName?: string | undefined;
     mode?: PermissionMode | undefined;
     models?: readonly string[] | undefined;
@@ -38,3 +39,6 @@ export interface RunOptions {
     system?: string | undefined;
     timeoutSeconds?: number | undefined;
 }
+export interface HistoryLabels {
+    [k: string]: string;
+}