@oneharness/sdk 0.14.0 → 0.15.1

package/README.md

@@ -29,6 +29,8 @@ for await (const envelope of oneharness.historyWatch({
 }
 ```
 
+Every JSON-returning method passes `--format json --compact` itself, so the CLI's own default (a human-readable text view) never reaches the SDK. A `run` over several harnesses is a **fallback chain** by default — the first candidate that can run does, and the report's `fallback` block says which; pass `runMode: "parallel"` to run them all at once.
+
 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.

package/dist/generated/config-report.d.ts

@@ -244,8 +244,9 @@ export interface Field31 {
     [k: string]: unknown;
 }
 /**
- * The configured run mode, if any. Unset falls back to `parallel` (the
- * built-in default) at run time.
+ * The effective run mode: a configured value, else `fallback` (the
+ * built-in default, attributed to [`DEFAULT_SOURCE`]) — the report says what
+ * a run would do, so an unset mode is never shown as `null`.
  */
 export interface Field9 {
     source: string | null;

package/dist/generated/contracts.d.ts

@@ -384,7 +384,7 @@ export interface RunResult {
      */
     bin: string;
     /**
-     * The exact argv oneharness built (argv[0] is the binary).
+     * The exact argv oneharness built; its first element is the binary.
      */
     command: string[];
     /**

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

@@ -458,7 +458,7 @@ export interface RunResult {
      */
     bin: string;
     /**
-     * The exact argv oneharness built (argv[0] is the binary).
+     * The exact argv oneharness built; its first element is the binary.
      */
     command: string[];
     /**

package/dist/generated/schemas.json

@@ -1842,7 +1842,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -2057,7 +2057,7 @@
                         "type": "string"
                     },
                     "command": {
-                        "description": "The exact argv oneharness built (argv[0] is the binary).",
+                        "description": "The exact argv oneharness built; its first element is the binary.",
                         "type": "array",
                         "items": {
                             "type": "string"
@@ -2923,7 +2923,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -3302,7 +3302,7 @@
                         "type": "string"
                     },
                     "command": {
-                        "description": "The exact argv oneharness built (argv[0] is the binary).",
+                        "description": "The exact argv oneharness built; its first element is the binary.",
                         "type": "array",
                         "items": {
                             "type": "string"
@@ -4016,12 +4016,12 @@
                 "description": "How the selected harnesses are run. Accepted as a CLI value (`--run-mode`,\nparsed in the `oneharness` binary) and a config-file value (`run_mode`, via\n`Deserialize`); the CLI parsing lives in the binary so this core crate stays\nfree of `clap`.",
                 "oneOf": [
                     {
-                        "description": "Run every selected harness at once, each an independent subprocess, and\nreport them all. The default — the historical behavior.",
+                        "description": "Run every selected harness at once, each an independent subprocess, and\nreport them all. The opt-in (`--run-mode parallel`, `run_mode =\n\"parallel\"`, `ONEHARNESS_RUN_MODE=parallel`); it was the default before\nthe fallback chain became one.",
                         "type": "string",
                         "const": "parallel"
                     },
                     {
-                        "description": "Run the selected harnesses in priority order (the `--harness` / config\norder, else registry order under `--all`), stopping at the first that\nactually runs the task; fall through only the candidates that cannot run\nat all (see [`startup_failure_reason`]).",
+                        "description": "Run the selected harnesses in priority order (the `--harness` / config\norder, else registry order under `--all`), stopping at the first that\nactually runs the task; fall through only the candidates that cannot run\nat all (see [`startup_failure_reason`]). The default wherever a run mode\nis left unset — in the request, every config layer and the environment.",
                         "type": "string",
                         "const": "fallback"
                     }
@@ -5974,7 +5974,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -8976,7 +8976,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -9360,7 +9360,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -12482,7 +12482,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -15986,7 +15986,7 @@
                 "$ref": "#/$defs/Field"
             },
             "run_mode": {
-                "description": "The configured run mode, if any. Unset falls back to `parallel` (the\nbuilt-in default) at run time.",
+                "description": "The effective run mode: a configured value, else `fallback` (the\nbuilt-in default, attributed to [`DEFAULT_SOURCE`]) — the report says what\na run would do, so an unset mode is never shown as `null`.",
                 "$ref": "#/$defs/Field9"
             },
             "schema_file": {
@@ -16453,12 +16453,12 @@
                 "description": "How the selected harnesses are run. Accepted as a CLI value (`--run-mode`,\nparsed in the `oneharness` binary) and a config-file value (`run_mode`, via\n`Deserialize`); the CLI parsing lives in the binary so this core crate stays\nfree of `clap`.",
                 "oneOf": [
                     {
-                        "description": "Run every selected harness at once, each an independent subprocess, and\nreport them all. The default — the historical behavior.",
+                        "description": "Run every selected harness at once, each an independent subprocess, and\nreport them all. The opt-in (`--run-mode parallel`, `run_mode =\n\"parallel\"`, `ONEHARNESS_RUN_MODE=parallel`); it was the default before\nthe fallback chain became one.",
                         "type": "string",
                         "const": "parallel"
                     },
                     {
-                        "description": "Run the selected harnesses in priority order (the `--harness` / config\norder, else registry order under `--all`), stopping at the first that\nactually runs the task; fall through only the candidates that cannot run\nat all (see [`startup_failure_reason`]).",
+                        "description": "Run the selected harnesses in priority order (the `--harness` / config\norder, else registry order under `--all`), stopping at the first that\nactually runs the task; fall through only the candidates that cannot run\nat all (see [`startup_failure_reason`]). The default wherever a run mode\nis left unset — in the request, every config layer and the environment.",
                         "type": "string",
                         "const": "fallback"
                     }
@@ -16760,7 +16760,7 @@
     "usage_report": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "title": "UsageReport",
-        "description": "One usage report: every probed identity, stamped with a single observation\ntime supplied by the caller (this module reads no clock).\n\nDeserializing is a consumer boundary — `oneharness-core` is published for\nsibling tools — so the envelope is validated on the way in rather than\ntrusted: see [`UsageReportWire`].",
+        "description": "One usage report: every probed identity, stamped with a single observation\ntime supplied by the caller (this module reads no clock).\n\nDeserializing is a consumer boundary — `oneharness-core` is published for\nsibling tools — so the envelope is validated on the way in rather than\ntrusted: see the private `UsageReportWire` shape.",
         "type": "object",
         "properties": {
             "identities": {
@@ -17057,7 +17057,7 @@
                 ]
             },
             "UsageIdentity": {
-                "description": "One harness identity's headroom.\n\nDeserializing is a consumer boundary like the envelope's, so every string an\nidentity carries is flattened through [`without_control_chars`] on the way in\n— see [`UsageIdentityWire`].",
+                "description": "One harness identity's headroom.\n\nDeserializing is a consumer boundary like the envelope's, so every string an\nidentity carries is flattened through the private `without_control_chars`\nfilter on the way in — see the private `UsageIdentityWire` shape.",
                 "type": "object",
                 "properties": {
                     "auth_mode": {

package/dist/generated/usage-report.d.ts

@@ -145,7 +145,7 @@ export type UnknownReason = {
  *
  * Deserializing is a consumer boundary — `oneharness-core` is published for
  * sibling tools — so the envelope is validated on the way in rather than
- * trusted: see [`UsageReportWire`].
+ * trusted: see the private `UsageReportWire` shape.
  */
 export interface UsageReport {
     identities: UsageIdentity[];
@@ -163,8 +163,8 @@ export interface UsageReport {
  * One harness identity's headroom.
  *
  * Deserializing is a consumer boundary like the envelope's, so every string an
- * identity carries is flattened through [`without_control_chars`] on the way in
- * — see [`UsageIdentityWire`].
+ * identity carries is flattened through the private `without_control_chars`
+ * filter on the way in — see the private `UsageIdentityWire` shape.
  */
 export interface UsageIdentity {
     auth_mode: AuthMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneharness/sdk",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Typed Node.js SDK for oneharness",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "oneharness-cli": "0.14.0",
+    "oneharness-cli": "0.15.1",
     "zod": "^4.4.3"
   }
 }