@oneharness/sdk 0.3.22

package/README.md

@@ -0,0 +1,46 @@
+# @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.
+
+```ts
+import { OneHarness, RunReportSchema, type RunReport } from "@oneharness/sdk";
+
+const oneharness = new OneHarness();
+const report = await oneharness.run({ prompt: "Summarize this repository", harnesses: ["codex"], events: true });
+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.
+
+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.
+
+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.
+
+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.
+
+Continuation passes the prior result's native session id with a new user message:
+
+```ts
+const first = await oneharness.run({ prompt: "Inspect the bug", harnesses: ["codex"] });
+const next = await oneharness.run({
+  prompt: "Now propose the smallest fix",
+  harnesses: ["codex"],
+  resume: first.results[0]?.session_id ?? undefined,
+});
+```
+
+Standardized history records and session summaries use their generated schemas too:
+
+```ts
+import { HistoryListSchema, HistoryRecordSchema } from "@oneharness/sdk";
+
+const records = await oneharness.history({ last: true });
+const sessions = await oneharness.historyList({ allProjects: true });
+HistoryRecordSchema.parse(records[0]);
+HistoryListSchema.parse(sessions);
+```
+
+`HistoryLookupSchema` states the selector rule itself: a lookup is a union of the only two ways to select a session, so it accepts `last: true` or a non-empty `session` and rejects a lookup that selects neither. `history({})`, `history({ last: false })`, and `history({ session: "" })` fail validation rather than reaching the CLI, and `HistoryLookup` rejects them at compile time too.
+
+`last: true` has priority over a name, so `history({ session: "old", last: true })` returns the most recent session and `history({ session: "old", last: false })` returns `old`. The two cases overlap deliberately — the union resolves `last: true` to its last-session variant first — which keeps `last` an ordinary `boolean` beside a named session, so a caller can pass one straight through.

package/dist/generated/contracts.d.ts

@@ -0,0 +1,421 @@
+/**
+ * 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";
+/**
+ * How a harness emits its result, which decides how `text` is extracted.
+ *
+ * Also accepted as a CLI value (`--output-format`, parsed in the `oneharness`
+ * binary) and a config-file value (`output_format`, via `Deserialize`). The
+ * CLI parsing lives in the binary so this core crate stays free of `clap`.
+ */
+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";
+/**
+ * The top-level `run` report written to stdout.
+ */
+export interface RunReport {
+    /**
+     * Same-prefix batch metadata when this run fanned **one** harness over more
+     * than one prompt; `null` on an ordinary run. Its presence is the signal a
+     * consumer keys on to read each result's own `prompt`.
+     */
+    batch: BatchReport | null;
+    /**
+     * Back-compat convenience: `true` exactly when `permission_mode` is
+     * `bypass`. Retained so existing consumers keep working; new consumers
+     * should read `permission_mode`.
+     */
+    bypass_permissions: boolean;
+    /**
+     * Config files that shaped this run, in layering order (user first,
+     * project last); empty under `--no-config` or when none exist.
+     */
+    config_files: string[];
+    dry_run: boolean;
+    /**
+     * Fallback-mode metadata when this run drove the selected harnesses in
+     * priority order, stopping at the first that ran (`--run-mode fallback`);
+     * `null` on a parallel run (and under `--print-command`, where nothing
+     * executes). Its presence tells a consumer that `results` holds only the
+     * harnesses actually *attempted* — the fallen-through ones in order, then
+     * the one that ran — not every selected harness.
+     */
+    fallback: FallbackReport | null;
+    /**
+     * Whether the resumed session was forked (`--fork`) rather than appended to.
+     * `false` unless `--resume` was given with `--fork`.
+     */
+    fork: boolean;
+    /**
+     * The history session file this run streamed normalized records to
+     * (absolute); `null` when history was not enabled (or under `--print-command`,
+     * where nothing runs). The programmatic handle a consumer captures to read the
+     * session back later with `oneharness history show`.
+     */
+    history_file: string | null;
+    /**
+     * The parsed `--mock-rules` ruleset this run was intercepted with; `null`
+     * when no mocking was requested. Present so a consumer can tell a mocked
+     * run's report from a clean one without out-of-band state.
+     */
+    mock_rules: unknown;
+    /**
+     * The effective top-level model: the first of the fan-out `models` list when
+     * one was given, else the single configured/CLI model, else `null`. Each
+     * result's own `model` is authoritative on a fan-out run.
+     */
+    model: string | null;
+    /**
+     * The model fan-out list this run multiplied over (repeated `--model` /
+     * config `models`), or `null` on an ordinary single-model run. Its presence
+     * is the signal a consumer keys on to read each result's own `model`: in
+     * `parallel` mode `results` holds one entry per (harness, model) pair; in
+     * `fallback` mode the pairs were tried in priority order (harness-major,
+     * model-minor).
+     */
+    models: string[] | null;
+    oneharness_version: string;
+    /**
+     * The normalized approval mode requested for this run (see the README
+     * support matrix). Each harness maps it to its own mechanism.
+     */
+    permission_mode: "read-only" | "plan" | "default" | "edit" | "auto" | "bypass";
+    /**
+     * The prompt sent. On an ordinary run this is *the* prompt every result
+     * shares; on a **batch** run (see `batch`) it repeats the first prompt for
+     * back-compat, and each result's own `prompt` field is authoritative.
+     */
+    prompt: string;
+    results: RunResult[];
+    /**
+     * The session id being continued, when `--resume` was passed; else `null`.
+     */
+    resume: string | null;
+    /**
+     * The JSON Schema applied to this run (structured output), or `null` when
+     * none was requested. Echoed so a consumer sees the exact constraint each
+     * result was validated against.
+     */
+    schema: unknown;
+    /**
+     * Maximum retries allowed per harness under the validate/retry loop; `null`
+     * when no schema was requested.
+     */
+    schema_max_retries: number | null;
+    schema_version: string;
+    /**
+     * The uniform session handle in play (`--session <name>`), or `null` when
+     * none was requested. Lets a consumer thread one stable name across turns
+     * instead of extracting each harness's native session id. Distinct from the
+     * low-level `resume` field above, which echoes an explicit `--resume` id.
+     */
+    session: SessionReport | null;
+    /**
+     * The spy-log path the mock hook appended tool-call records to (absolute);
+     * `null` when none was requested.
+     */
+    spy_file: string | null;
+    [k: string]: unknown;
+}
+/**
+ * Metadata for a same-prefix batch run (one harness, N prompts sharing a
+ * cacheable prefix). Present on [`RunReport::batch`] only in that mode.
+ */
+export interface BatchReport {
+    /**
+     * Whether the fan-out actually **forked** the warm-up's session to reuse its
+     * cached prefix (`min-tokens` on a fork-capable harness whose warm-up exposed
+     * a session id). `false` for `speed`, for `min-tokens` on a harness that
+     * cannot fork, or when the warm-up exposed no session to fork. When `true`,
+     * the fan-out results' `command` carries the resume/fork flags and their
+     * `usage.cache_read_tokens` reflect the reused prefix.
+     */
+    forked: boolean;
+    /**
+     * How many prompts were run (equals `results.len()`).
+     */
+    prompt_count: number;
+    /**
+     * How the prompts were scheduled across the parallel runner.
+     */
+    strategy: "speed" | "min-tokens";
+    [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
+ * detail lives in `results`; this block summarizes the outcome so a consumer
+ * need not re-derive it from statuses.
+ */
+export interface FallbackReport {
+    /**
+     * The candidates fallen through because they could not run the task at all,
+     * in priority order, each with why (`not-installed`, `spawn-error`, `auth`,
+     * `quota`, and — on a model fan-out — `model-not-found` / `rate-limit`; see
+     * [`crate::domain::fallback::startup_failure_reason`]).
+     */
+    fell_through: FallThrough[];
+    /**
+     * The harness that actually ran the task (the run stopped there), or `null`
+     * when no candidate could run at all — every one was a startup failure.
+     */
+    ran: string | null;
+    [k: string]: unknown;
+}
+/**
+ * One candidate a fallback run fell through, with the reason it could not run.
+ */
+export interface FallThrough {
+    /**
+     * Canonical harness id.
+     */
+    harness: string;
+    /**
+     * Short reason token (`not-installed` / `spawn-error` / `auth` / `quota` /
+     * `model-not-found` / `rate-limit`).
+     */
+    reason: string;
+    [k: string]: unknown;
+}
+/**
+ * One harness's entry in the report.
+ */
+export interface RunResult {
+    /**
+     * Whether that binary was found.
+     */
+    available: boolean;
+    /**
+     * The binary name or path oneharness resolved and would invoke.
+     */
+    bin: string;
+    /**
+     * The exact argv oneharness built (argv[0] is the binary).
+     */
+    command: string[];
+    /**
+     * Wall-clock duration of the run; `null` when not executed.
+     */
+    duration_ms: number | null;
+    /**
+     * Human-readable problem + suggested action; `null` on success.
+     */
+    error: string | null;
+    /**
+     * Best-effort normalized tool-call / action events the harness took (shell
+     * commands, file edits, tool uses), in order — so consumers can assert on
+     * *behavior*, not just the final `text`. `null` when the harness's output
+     * exposes no machine-readable trace (a plain-text harness, or Claude Code's
+     * single-document `json` result), distinct from `[]` — an empty array is not
+     * currently emitted; absence is signalled by `null` + a null `events_source`.
+     * Never fabricated. See [`crate::domain::events`].
+     */
+    events: ActionEvent[] | null;
+    /**
+     * How `events` was recovered (e.g. `json:opencode-parts`,
+     * `stream-json:content-blocks`), parallel to `text_source`; `null` when no
+     * events were found. Lets a consumer tell "harness doesn't support it" from
+     * "no tools were used."
+     */
+    events_source: string | null;
+    /**
+     * Process exit code; `null` when not run, timed out, or signalled.
+     */
+    exit_code: number | null;
+    /**
+     * Best-effort failure reason; `null` when unclassified. Distinct from
+     * `status`, which records oneharness's relationship to the process. Two
+     * families: coarse reasons for a non-zero run (`auth`, `rate_limit`,
+     * `model_not_found`, `quota`), and `tool_deferred` — a run that exited
+     * *cleanly* but only deferred a builtin tool call instead of executing it
+     * (Claude Code bridge/managed deployments), so it did no useful work. The
+     * deferred case is the only `failure_kind` that can appear on a `status: ok`
+     * run, and it also marks the run as failed for exit-code purposes.
+     * Serialized as its snake_case token (see [`FailureKind`]).
+     */
+    failure_kind: FailureKind | null;
+    /**
+     * Where `failure_kind` was read (`stderr`/`stdout`); `null` when absent.
+     */
+    failure_kind_source: string | null;
+    /**
+     * Canonical harness id (e.g. `claude-code`).
+     */
+    harness: string;
+    /**
+     * The model this result ran with (the value oneharness put on the harness's
+     * model flag), or `null` when no model was requested and the harness used its
+     * own default. On a **model fan-out** run (`RunReport::models`), this is what
+     * distinguishes results that share a harness — each entry is one (harness,
+     * model) pair. The model is also visible in `command`; this field surfaces it
+     * without parsing the argv.
+     */
+    model: string | null;
+    output_format: OutputFormat;
+    /**
+     * The prompt this result ran, set only on a **batch** run (one harness
+     * fanned over N prompts), where each result has its own prompt. `null` on an
+     * ordinary run, where the single top-level `prompt` applies to every result.
+     */
+    prompt: string | null;
+    /**
+     * Structured-output run only: how many times this harness was invoked under
+     * the validate/retry loop (1 + retries). `null` when no schema was
+     * requested or the harness did not run.
+     */
+    schema_attempts: number | null;
+    /**
+     * Structured-output run only: the validation errors from the final attempt,
+     * joined for display; `null` when valid or no schema was requested.
+     */
+    schema_error: string | null;
+    /**
+     * Structured-output run only: whether `structured` conformed to the schema
+     * on the final attempt. `null` when no schema was requested (or the harness
+     * did not run); `false` when a schema was requested but the result never
+     * conformed (including "no JSON found").
+     */
+    schema_valid: boolean | null;
+    /**
+     * Best-effort harness session id for continuation; `null` when none is
+     * exposed. Surfaced for a consumer to thread into `--resume`, and consumed
+     * by oneharness itself when `--session` is in play (it is captured into the
+     * session store to back the uniform handle — see [`RunReport::session`]).
+     */
+    session_id: string | null;
+    status: Status;
+    /**
+     * Raw captured stderr (empty for skipped/planned).
+     */
+    stderr: string;
+    /**
+     * Raw captured stdout (empty for skipped/planned).
+     */
+    stdout: string;
+    /**
+     * Structured-output run only: the JSON value extracted from the final
+     * answer and validated against the requested schema. `null` when no schema
+     * was requested, or when no JSON value could be extracted. Carries the
+     * last-attempted value even when it failed validation, so a consumer can
+     * see what the harness produced.
+     */
+    structured: unknown;
+    /**
+     * Best-effort final assistant text; `null` when extraction is impossible.
+     */
+    text: string | null;
+    /**
+     * How `text` was extracted (e.g. `json:result`, `raw`); `null` when absent.
+     */
+    text_source: string | null;
+    usage: Usage;
+    /**
+     * How `usage` was read (e.g. `json`); `null` when nothing was found.
+     */
+    usage_source: string | null;
+    [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;
+}
+/**
+ * Best-effort token/cost accounting; every field is `null` when the harness
+ * does not report it. Always present so consumers can read a stable shape.
+ */
+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;
+}
+/**
+ * The uniform session handle for a run (`--session`). Present on
+ * [`RunReport::session`] only when `--session <name>` was requested.
+ */
+export interface SessionReport {
+    /**
+     * The caller's stable handle (`--session <name>`, sanitized for the store).
+     */
+    name: string;
+    /**
+     * Whether this run created the named session (no prior token) or continued
+     * an existing one.
+     */
+    phase: "create" | "continue";
+    /**
+     * The session store file backing the handle (absolute); the programmatic
+     * handle to the persisted state.
+     */
+    store_file: string | null;
+    /**
+     * The harness native token now bound to the name: the id resumed on a
+     * continue, or the id captured on a create. `null` only when a create run
+     * exposed no session id (the handle then cannot be continued — a warning is
+     * emitted), or under `--print-command` on a create (nothing ran).
+     */
+    token: string | null;
+    [k: string]: unknown;
+}

package/dist/generated/contracts.js

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

package/dist/generated/detection.d.ts

@@ -0,0 +1,13 @@
+export interface DetectReport {
+    detected: DetectInfo[];
+    schema_version: string;
+    [k: string]: unknown;
+}
+export interface DetectInfo {
+    available: boolean;
+    bin: string;
+    id: string;
+    path: string | null;
+    version: string | null;
+    [k: string]: unknown;
+}

package/dist/generated/detection.js

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

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

@@ -0,0 +1,8 @@
+/**
+ * Options accepted by `OneHarness.historyList()` in the published Node SDK.
+ */
+export interface HistoryListOptions {
+    allProjects?: boolean | undefined;
+    historyDir?: string | undefined;
+    project?: string | undefined;
+}

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

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

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

@@ -0,0 +1,37 @@
+export type HistoryList = HistorySessionSummary[];
+/**
+ * A one-line summary of a session, for `oneharness history list`. Read from the
+ * session's records: `name`/`project`/`started` come from the first record,
+ * `harnesses` is the distinct set across all records.
+ */
+export interface HistorySessionSummary {
+    /**
+     * The distinct harness ids the session touched, in first-seen order.
+     */
+    harnesses: string[];
+    /**
+     * The session id (the file stem), unique and sortable by start time.
+     */
+    id: string;
+    /**
+     * The human-meaningful session name (non-unique).
+     */
+    name: string;
+    /**
+     * The absolute path of the session file.
+     */
+    path: string;
+    /**
+     * The project directory the run operated in.
+     */
+    project: string;
+    /**
+     * How many harness-run records the session holds.
+     */
+    record_count: number;
+    /**
+     * The RFC3339 UTC start time (first record's timestamp); empty if unknown.
+     */
+    started: string;
+    [k: string]: unknown;
+}

package/dist/generated/history-list.js

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

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

@@ -0,0 +1,66 @@
+/**
+ * The session selector accepted by `OneHarness.history()` in the published Node
+ * SDK.
+ *
+ * A lookup must select a session, so the contract is a union of the only two
+ * ways to do that: ask for the most recent one ([`HistoryLookupByLast`]), or
+ * name one ([`HistoryLookupBySession`]). A lookup that selects nothing — `{}`,
+ * `{"session": ""}`, or `{"last": false}` — matches neither variant and fails
+ * at the boundary, so `history()` never has to re-check for one.
+ *
+ * The variants overlap on purpose, and the order is load-bearing: an untagged
+ * enum takes the first match, so `Last` coming first is what gives `last: true`
+ * priority over a name. `{"session": "x", "last": true}` satisfies *both*
+ * variants and resolves to `Last`, selecting the most recent session rather
+ * than `x`; `{"session": "x", "last": false}` fails `Last` and resolves to
+ * `Session`. That is exactly the reading of the `if (last) … else if (session)`
+ * rule this replaces, now decided by the union rather than re-derived after
+ * parsing. Zod resolves its generated union in the same order, so the Node SDK
+ * agrees with Rust by construction.
+ *
+ * Because `Last` ignores the name it carries, that name is a plain `String`:
+ * `{"session": "", "last": true}` stays valid and still selects the most recent
+ * session, as it always has. Only a name that actually selects has to be
+ * non-empty.
+ */
+export type HistoryLookup = HistoryLookupByLast | HistoryLookupBySession;
+/**
+ * Select the most recent session.
+ */
+export interface HistoryLookupByLast {
+    allProjects?: boolean | undefined;
+    historyDir?: string | undefined;
+    /**
+     * Select the most recent session. Only `true` selects, so this variant
+     * accepts no other value.
+     */
+    last: true;
+    project?: string | undefined;
+    /**
+     * A name may accompany `last: true` — it is what the caller would have
+     * looked up otherwise — but `last` takes priority, so it never selects.
+     * It is therefore unconstrained: an empty name is meaningless here rather
+     * than invalid, so `{"session": "", "last": true}` stays accepted.
+     */
+    session?: string | undefined;
+}
+/**
+ * Select the session named by `session`.
+ */
+export interface HistoryLookupBySession {
+    allProjects?: boolean | undefined;
+    historyDir?: string | undefined;
+    /**
+     * Whether the most recent session was asked for instead. An ordinary
+     * `bool`, so a caller holding a `boolean` can pass it straight through.
+     * `true` here also satisfies [`HistoryLookup::Last`], which the union tries
+     * first — so a lookup that reaches this variant always meant the name.
+     */
+    last?: boolean | undefined;
+    project?: string | undefined;
+    /**
+     * The oneharness-derived session name recorded by `run --history`. This is
+     * the name that selects, so it must be non-empty.
+     */
+    session: string;
+}

package/dist/generated/history-lookup.js

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