@oneharness/sdk 0.3.22

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

@@ -0,0 +1,150 @@
+/**
+ * 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";
+export type HistoryRecords = 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.
+ */
+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;
+    /**
+     * 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;
+}
+/**
+ * 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-records.js

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

package/dist/generated/history.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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;
+    /**
+     * 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;
+}
+/**
+ * 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.js

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

package/dist/generated/options.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The unified approval mode, from least to most autonomy. A harness may not
+ * support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the
+ * command layer refuses an unsupported one before spawning, never silently
+ * downgrading it.
+ */
+export type PermissionMode = "read-only" | "plan" | "default" | "edit" | "auto" | "bypass";
+/**
+ * Options accepted by `OneHarness.run()` in the published Node SDK.
+ *
+ * Unknown fields are rejected because the SDK cannot forward an option it does
+ * not understand. This differs deliberately from output contracts, whose Zod
+ * schemas preserve unknown fields for forward compatibility.
+ */
+export interface RunOptions {
+    bins?: {
+        [k: string]: string;
+    } | undefined;
+    cwd?: string | undefined;
+    env?: {
+        [k: string]: string;
+    } | undefined;
+    events?: boolean | undefined;
+    fork?: boolean | undefined;
+    harnesses?: readonly string[] | undefined;
+    history?: boolean | undefined;
+    historyDir?: string | undefined;
+    historyName?: string | undefined;
+    mode?: PermissionMode | undefined;
+    models?: readonly string[] | undefined;
+    /**
+     * The user message sent to the selected harnesses.
+     */
+    prompt: string;
+    reasoning?: string | undefined;
+    resume?: string | undefined;
+    session?: string | undefined;
+    system?: string | undefined;
+    timeoutSeconds?: number | undefined;
+}

package/dist/generated/options.js

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

package/dist/generated/registry.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The unified approval mode, from least to most autonomy. A harness may not
+ * support every value (see [`crate::domain::harness::HarnessSpec::mode`]); the
+ * command layer refuses an unsupported one before spawning, never silently
+ * downgrading it.
+ */
+export type PermissionMode = "read-only" | "plan" | "default" | "edit" | "auto" | "bypass";
+/**
+ * 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";
+export interface ListReport {
+    harnesses: HarnessInfo[];
+    schema_version: string;
+    [k: string]: unknown;
+}
+export interface HarnessInfo {
+    default_bin: string;
+    display: string;
+    /**
+     * The argv oneharness would build, with placeholders, so the adapter's
+     * shape is visible without running anything.
+     */
+    example_command: string[];
+    /**
+     * Whether a forked run reuses the parent session's prompt-cache prefix, so a
+     * fork-based `--batch-strategy min-tokens` run actually reduces tokens. `true`
+     * only for Claude Code today; `false` (incl. OpenCode, whose fork re-sends the
+     * prefix cold) means `min-tokens` only orders the calls (no saving).
+     */
+    fork_reuses_cache: boolean;
+    id: string;
+    install_hint: string;
+    /**
+     * The input-rewrite verdict shape `oneharness mock <id>` speaks for this
+     * harness (`claude-nested`, `crush-flat`, `opencode-shim`); `null` when
+     * the harness has no verified rewrite — a rewrite rule for it is then a
+     * loud usage error (see the README mock support matrix).
+     */
+    mock_rewrite: string | null;
+    /**
+     * The approval modes (`--mode`) this harness can express, each with its
+     * headless behavior. Modes not listed are unsupported for the harness.
+     */
+    modes: ModeInfo[];
+    output_format: OutputFormat;
+    /**
+     * Whether `run --session <name>` is supported — a uniform, caller-owned
+     * handle oneharness maps to the harness's native session id. `true` only for
+     * harnesses that expose a session id headlessly; `false` means `--session` is
+     * a loud usage error (there is no id to bind a name to).
+     */
+    session_capable: boolean;
+    /**
+     * Whether the unified allow/deny rule lists and hooks table can be synced
+     * into that file (see the README support matrix).
+     */
+    supports_allowed_tools: boolean;
+    supports_denied_tools: boolean;
+    /**
+     * Whether `run --resume <session> --fork` is supported — branching a new
+     * session from the resumed one. `false` means it resumes linearly only.
+     */
+    supports_fork: boolean;
+    supports_hooks: boolean;
+    /**
+     * Whether `oneharness mock <id>` can express a pre-tool *deny* for this
+     * harness (the same protocol `oneharness gate` speaks).
+     */
+    supports_mock_deny: boolean;
+    /**
+     * Whether `run --schema` is delivered through a native structured-output
+     * flag for this harness (Claude Code's `--json-schema`). `false` means the
+     * portable prompt-based path is used — structured output works either way;
+     * oneharness always validates and retries.
+     */
+    supports_native_schema: boolean;
+    /**
+     * Whether a large user prompt can be delivered off the argv (piped to the
+     * harness's stdin) so it never trips the OS argument ceiling (`E2BIG`).
+     */
+    supports_prompt_stdin: boolean;
+    /**
+     * Whether `run --reasoning <effort>` can be delivered on the argv for this
+     * harness (Claude Code's `--effort`, Codex's `model_reasoning_effort`).
+     * `false` means it has no headless reasoning flag — a reasoning request is
+     * then a loud usage error (effort is provider/model config there).
+     */
+    supports_reasoning: boolean;
+    /**
+     * Whether `run --resume <session>` is supported for this harness.
+     */
+    supports_resume: boolean;
+    /**
+     * Whether a large system prompt can be delivered off the argv via a file
+     * flag (Claude Code's `--append-system-prompt-file`). `false` does not mean a
+     * large system is unhandled — for a harness whose system rides the prompt it
+     * travels on stdin with the prompt; see the README large-prompt matrix.
+     */
+    supports_system_file: boolean;
+    /**
+     * The project-scoped config file `oneharness sync` writes for this
+     * harness; `null` when it has none (sync settings are then rejected).
+     */
+    sync_file: string | null;
+    [k: string]: unknown;
+}
+/**
+ * One supported approval mode for a harness, with its headless behavior, in
+ * `oneharness list`. A [`PermissionMode`] absent from a harness's array is
+ * unsupported for it (a `--mode` request would be refused).
+ */
+export interface ModeInfo {
+    /**
+     * `"clean"` (never blocks headless) or `"hangs"` (would block on an
+     * approval prompt; refused without --permit-prompts).
+     */
+    headless: "clean" | "hangs";
+    mode: PermissionMode;
+    [k: string]: unknown;
+}

package/dist/generated/registry.js

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