oneharness-sdk 0.4.0__tar.gz

oneharness_sdk-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick DeRobertis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oneharness_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: oneharness-sdk
+Version: 0.4.0
+Summary: Typed async Python SDK for oneharness
+Keywords: cli,agent,claude,codex,harness
+Author: Nick DeRobertis
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: jsonschema>=4.18,<5
+Requires-Dist: oneharness-cli==0.4.0
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/nickderobertis/oneharness
+Project-URL: Repository, https://github.com/nickderobertis/oneharness
+Description-Content-Type: text/markdown
+
+# oneharness-sdk
+
+Async Python access to the `oneharness` engine, generated from and validated against the Rust-owned JSON Schema contracts. The distribution is `oneharness-sdk`, the import is `oneharness_sdk`, and every release depends on the exact same `oneharness-cli` version.
+
+```console
+pip install oneharness-sdk
+```
+
+```python
+import asyncio
+
+from oneharness_sdk import OneHarness
+
+
+async def main() -> None:
+    oneharness = OneHarness()
+    report = await oneharness.run(
+        {"prompt": "Summarize this repository", "harnesses": ["codex"]}
+    )
+    print(report["results"][0]["text"])
+
+
+asyncio.run(main())
+```
+
+The complete client surface is `run`, `run_stream`, `list`, `detect`, `history`, `history_list`, and `history_watch`. `run_stream` and `history_watch` are async iterators. Every envelope is validated before it is yielded; closing or cancelling an iterator terminates its subprocess.
+
+```python
+async for envelope in oneharness.run_stream(
+    {"prompt": "Inspect this repository", "harnesses": ["codex"]}
+):
+    if envelope["type"] == "event" and envelope["event"]["name"] == "shell":
+        break
+
+async for envelope in oneharness.history_watch(
+    {"labels": {"graph": "release"}, "after": last_history_id}
+):
+    print(envelope["record"]["history_id"])
+```
+
+Python input keys are snake case and strict: unknown fields and misspellings fail before the CLI starts. Output dictionaries preserve additive fields from newer compatible CLI versions. `history` and `history_watch` raise `HistoryNotFoundError` when a session, record, or cursor cannot be resolved.

oneharness_sdk-0.4.0/README.md

@@ -0,0 +1,41 @@
+# oneharness-sdk
+
+Async Python access to the `oneharness` engine, generated from and validated against the Rust-owned JSON Schema contracts. The distribution is `oneharness-sdk`, the import is `oneharness_sdk`, and every release depends on the exact same `oneharness-cli` version.
+
+```console
+pip install oneharness-sdk
+```
+
+```python
+import asyncio
+
+from oneharness_sdk import OneHarness
+
+
+async def main() -> None:
+    oneharness = OneHarness()
+    report = await oneharness.run(
+        {"prompt": "Summarize this repository", "harnesses": ["codex"]}
+    )
+    print(report["results"][0]["text"])
+
+
+asyncio.run(main())
+```
+
+The complete client surface is `run`, `run_stream`, `list`, `detect`, `history`, `history_list`, and `history_watch`. `run_stream` and `history_watch` are async iterators. Every envelope is validated before it is yielded; closing or cancelling an iterator terminates its subprocess.
+
+```python
+async for envelope in oneharness.run_stream(
+    {"prompt": "Inspect this repository", "harnesses": ["codex"]}
+):
+    if envelope["type"] == "event" and envelope["event"]["name"] == "shell":
+        break
+
+async for envelope in oneharness.history_watch(
+    {"labels": {"graph": "release"}, "after": last_history_id}
+):
+    print(envelope["record"]["history_id"])
+```
+
+Python input keys are snake case and strict: unknown fields and misspellings fail before the CLI starts. Output dictionaries preserve additive fields from newer compatible CLI versions. `history` and `history_watch` raise `HistoryNotFoundError` when a session, record, or cursor cannot be resolved.

oneharness_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "oneharness-sdk"
+version = "0.4.0"
+description = "Typed async Python SDK for oneharness"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Nick DeRobertis" }]
+keywords = ["cli", "agent", "claude", "codex", "harness"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "jsonschema>=4.18,<5",
+    "oneharness-cli==0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nickderobertis/oneharness"
+Repository = "https://github.com/nickderobertis/oneharness"
+
+[tool.uv.build-backend]
+module-name = "oneharness_sdk"
+module-root = "src"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B", "ASYNC", "S", "RUF"]
+ignore = [
+    "E501",  # JSON protocol fixtures are clearer as intact strings.
+    "UP045", # Optional keeps runtime annotations unambiguous on Python 3.9.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/**" = [
+    "S404", # The generator deliberately invokes Cargo across the schema boundary.
+    "S603", # Its fixed argument vector is not built from untrusted input.
+    "S607", # Cargo is a required developer tool resolved from the active toolchain.
+]
+"test/**" = [
+    "S101", # Assertions are the test contract.
+    "S404", # Subprocess boundaries are intentional integration coverage.
+    "S603", # Test commands use fixed arguments or controlled fixtures.
+    "S607", # Tests intentionally resolve required developer tools from PATH.
+]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_unreachable = true
+
+[tool.coverage.run]
+branch = true
+source = ["oneharness_sdk"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true

oneharness_sdk-0.4.0/src/oneharness_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""Async Python SDK for the oneharness CLI."""
+
+from ._client import OneHarness
+from ._errors import ContractError, HistoryNotFoundError, OneHarnessProcessError
+from ._generated_types import (
+    Detection,
+    HarnessInfo,
+    HistoryListOptions,
+    HistoryLookup,
+    HistoryRecord,
+    HistoryStreamEnvelope,
+    HistoryWatchOptions,
+    RunOptions,
+    RunReport,
+    RunStreamEnvelope,
+)
+from ._version import __version__
+
+__all__ = [
+    "ContractError",
+    "Detection",
+    "HarnessInfo",
+    "HistoryListOptions",
+    "HistoryLookup",
+    "HistoryNotFoundError",
+    "HistoryRecord",
+    "HistoryStreamEnvelope",
+    "HistoryWatchOptions",
+    "OneHarness",
+    "OneHarnessProcessError",
+    "RunOptions",
+    "RunReport",
+    "RunStreamEnvelope",
+    "__version__",
+]

oneharness_sdk-0.4.0/src/oneharness_sdk/_client.py

@@ -0,0 +1,332 @@
+"""Async subprocess client for the oneharness JSON and JSONL interfaces."""
+
+from __future__ import annotations
+
+import asyncio
+import builtins
+import json
+import os
+import shutil
+from collections.abc import AsyncIterator, Mapping, Sequence
+from functools import cache
+from pathlib import Path
+from typing import Any, Optional, cast
+
+from jsonschema import Draft202012Validator
+from jsonschema.protocols import Validator
+
+from ._errors import ContractError, HistoryNotFoundError, OneHarnessProcessError
+from ._generated_types import (
+    Detection,
+    HarnessInfo,
+    HistoryListOptions,
+    HistoryLookup,
+    HistoryRecord,
+    HistoryStreamEnvelope,
+    HistoryWatchOptions,
+    RunOptions,
+    RunReport,
+    RunStreamEnvelope,
+)
+
+_STREAM_LIMIT = 16 * 1024 * 1024
+_INPUT_ROOTS = {
+    "history_list_options",
+    "history_lookup",
+    "history_watch_options",
+    "run_options",
+}
+
+
+def _load_json(name: str) -> dict[str, Any]:
+    path = Path(__file__).with_name("_generated") / name
+    return cast("dict[str, Any]", json.loads(path.read_text(encoding="utf-8")))
+
+
+_SCHEMAS = _load_json("schemas.json")
+_INPUT_KEYS = cast("dict[str, dict[str, str]]", _load_json("input-keys.json"))
+
+
+@cache
+def _validator(root: str) -> Validator:
+    schema = _SCHEMAS[root]
+    Draft202012Validator.check_schema(schema)
+    return Draft202012Validator(schema)
+
+
+def _validate(root: str, value: Any, label: str) -> Any:
+    errors = sorted(_validator(root).iter_errors(value), key=lambda error: list(error.path))
+    if not errors:
+        return value
+    details = []
+    for error in errors:
+        path = ".".join(str(part) for part in error.absolute_path) or "<root>"
+        details.append(f"{path}: {error.message}")
+    raise ContractError(f"{label}: {'; '.join(details)}")
+
+
+def _input(root: str, value: Any, label: str) -> dict[str, Any]:
+    if root not in _INPUT_ROOTS:  # pragma: no cover - internal programming guard
+        raise AssertionError(f"{root} is not an input schema")
+    checked = cast("Mapping[str, Any]", _validate(root, value, label))
+    keys = _INPUT_KEYS[root]
+    return {keys.get(key, key): item for key, item in checked.items()}
+
+
+def _many(args: list[str], flag: str, values: Optional[Sequence[str]]) -> None:
+    for value in values or ():
+        args.extend((flag, value))
+
+
+def _run_arguments(options: Mapping[str, Any], *, stream: bool) -> list[str]:
+    args = ["run", "--prompt", cast("str", options["prompt"]), "--compact"]
+    _many(args, "--harness", cast("Optional[Sequence[str]]", options.get("harnesses")))
+    _many(args, "--model", cast("Optional[Sequence[str]]", options.get("models")))
+    scalar_flags = {
+        "system": "--system",
+        "reasoning": "--reasoning",
+        "resume": "--resume",
+        "session": "--session",
+        "mode": "--mode",
+        "historyName": "--history-name",
+        "historyDir": "--history-dir",
+    }
+    for key, flag in scalar_flags.items():
+        if key in options:
+            args.extend((flag, cast("str", options[key])))
+    if options.get("fork"):
+        args.append("--fork")
+    if "timeoutSeconds" in options:
+        args.extend(("--timeout", str(options["timeoutSeconds"])))
+    if options.get("events"):
+        args.append("--events")
+    if stream:
+        args.append("--stream")
+    if options.get("history"):
+        args.append("--history")
+    for key, value in cast("Mapping[str, str]", options.get("historyLabels", {})).items():
+        args.extend(("--history-label", f"{key}={value}"))
+    for key, value in cast("Mapping[str, str]", options.get("env", {})).items():
+        args.extend(("--env", f"{key}={value}"))
+    for key, value in cast("Mapping[str, str]", options.get("bins", {})).items():
+        args.extend(("--bin", f"{key}={value}"))
+    return args
+
+
+async def _terminate(process: asyncio.subprocess.Process) -> None:
+    if process.returncode is not None:
+        return
+    try:
+        process.terminate()
+    except ProcessLookupError:  # pragma: no cover - OS race after returncode check
+        return
+    try:
+        await asyncio.wait_for(process.wait(), timeout=2)
+    except asyncio.TimeoutError:  # pragma: no cover - defensive hard-kill fallback
+        process.kill()
+        await process.wait()
+
+
+def _process_error(returncode: int, stderr: str, *, history: bool) -> OneHarnessProcessError:
+    if history and (returncode == 1 or "was not found" in stderr):
+        return HistoryNotFoundError(returncode, stderr)
+    return OneHarnessProcessError(returncode, stderr)
+
+
+class OneHarness:
+    """Validated async access to an installed oneharness CLI."""
+
+    def __init__(
+        self,
+        *,
+        executable: Optional[str] = None,
+        executable_args: Sequence[str] = (),
+        env: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self._executable = executable
+        self._executable_args = tuple(executable_args)
+        self._env = dict(env or {})
+
+    def _command(self, args: Sequence[str]) -> tuple[str, ...]:
+        command = self._executable or os.environ.get("ONEHARNESS_BIN")
+        if command is None:
+            command = shutil.which("oneharness") or "oneharness"
+        return (command, *self._executable_args, *args)
+
+    async def _spawn(
+        self, args: Sequence[str], cwd: Optional[str] = None
+    ) -> asyncio.subprocess.Process:
+        return await asyncio.create_subprocess_exec(
+            *self._command(args),
+            cwd=cwd,
+            env={**os.environ, **self._env},
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            limit=_STREAM_LIMIT,
+        )
+
+    async def _invoke(
+        self,
+        args: Sequence[str],
+        *,
+        cwd: Optional[str] = None,
+        accept_json_on_nonzero: bool = False,
+        history: bool = False,
+    ) -> Any:
+        process = await self._spawn(args, cwd)
+        try:
+            stdout_bytes, stderr_bytes = await process.communicate()
+        except BaseException:
+            await _terminate(process)
+            raise
+        stderr = stderr_bytes.decode("utf-8", errors="replace")
+        if process.returncode != 0 and not accept_json_on_nonzero:
+            raise _process_error(process.returncode or 0, stderr, history=history)
+        try:
+            return json.loads(stdout_bytes)
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            if process.returncode != 0:
+                raise _process_error(process.returncode or 0, stderr, history=history) from error
+            raise ContractError(f"oneharness returned invalid JSON: {error}") from error
+
+    async def _stream(
+        self,
+        args: Sequence[str],
+        root: str,
+        label: str,
+        *,
+        cwd: Optional[str] = None,
+        history: bool = False,
+    ) -> AsyncIterator[dict[str, Any]]:
+        process = await self._spawn(args, cwd)
+        if process.stdout is None or process.stderr is None:  # pragma: no cover - PIPE invariant
+            await _terminate(process)
+            raise RuntimeError("oneharness stream pipes were not created")
+        stderr_task = asyncio.create_task(process.stderr.read())
+        try:
+            while line := await process.stdout.readline():
+                if not line.strip():
+                    continue
+                try:
+                    value = json.loads(line)
+                except (UnicodeDecodeError, json.JSONDecodeError) as error:
+                    raise ContractError(f"{label}: invalid JSON: {error}") from error
+                yield cast("dict[str, Any]", _validate(root, value, label))
+            returncode = await process.wait()
+            stderr = (await stderr_task).decode("utf-8", errors="replace")
+            if returncode != 0:
+                raise _process_error(returncode, stderr, history=history)
+        finally:
+            await _terminate(process)
+            if not stderr_task.done():
+                stderr_task.cancel()
+            await asyncio.gather(stderr_task, return_exceptions=True)
+
+    async def run(self, options: RunOptions) -> RunReport:
+        """Run one prompt and return a validated report."""
+        parsed = _input("run_options", options, "invalid oneharness run options")
+        value = await self._invoke(
+            _run_arguments(parsed, stream=False),
+            cwd=cast("Optional[str]", parsed.get("cwd")),
+            accept_json_on_nonzero=True,
+        )
+        return cast("RunReport", _validate("run_report", value, "invalid oneharness run contract"))
+
+    def run_stream(self, options: RunOptions) -> AsyncIterator[RunStreamEnvelope]:
+        """Yield validated action/result envelopes as the harness runs."""
+        parsed = _input("run_options", options, "invalid oneharness run options")
+        return self._stream(
+            _run_arguments(parsed, stream=True),
+            "run_stream_envelope",
+            "invalid oneharness run stream contract",
+            cwd=cast("Optional[str]", parsed.get("cwd")),
+        )
+
+    async def list(self) -> builtins.list[HarnessInfo]:
+        """Return the validated harness registry."""
+        value = _validate(
+            "list_report",
+            await self._invoke(("list", "--compact")),
+            "invalid oneharness list contract",
+        )
+        return cast("builtins.list[HarnessInfo]", value["harnesses"])
+
+    async def detect(self, harnesses: Sequence[str] = ()) -> builtins.list[Detection]:
+        """Probe selected harness binaries."""
+        if isinstance(harnesses, (str, bytes)) or not all(
+            isinstance(harness, str) for harness in harnesses
+        ):
+            raise ContractError("invalid oneharness detect options: harnesses must be strings")
+        args = ["detect", "--compact"]
+        _many(args, "--harness", harnesses)
+        value = _validate(
+            "detect_report",
+            await self._invoke(args),
+            "invalid oneharness detect contract",
+        )
+        return cast("builtins.list[Detection]", value["detected"])
+
+    async def history(self, lookup: HistoryLookup) -> builtins.list[HistoryRecord]:
+        """Resolve one history record or session."""
+        parsed = _input("history_lookup", lookup, "invalid oneharness history options")
+        args = ["history", "show", "--compact"]
+        if parsed.get("last") is True:
+            args.append("--last")
+        else:
+            args.append(cast("str", parsed["session"]))
+        if parsed.get("project"):
+            args.extend(("--project", cast("str", parsed["project"])))
+        if parsed.get("allProjects"):
+            args.append("--all-projects")
+        if parsed.get("historyDir"):
+            args.extend(("--history-dir", cast("str", parsed["historyDir"])))
+        value = await self._invoke(args, history=True)
+        return cast(
+            "builtins.list[HistoryRecord]",
+            _validate("history_records", value, "invalid oneharness history contract"),
+        )
+
+    async def history_list(
+        self, options: Optional[HistoryListOptions] = None
+    ) -> builtins.list[dict[str, Any]]:
+        """List standardized history sessions."""
+        parsed = _input(
+            "history_list_options", options or {}, "invalid oneharness history list options"
+        )
+        args = ["history", "list", "--compact"]
+        if parsed.get("project"):
+            args.extend(("--project", cast("str", parsed["project"])))
+        if parsed.get("allProjects"):
+            args.append("--all-projects")
+        if parsed.get("historyDir"):
+            args.extend(("--history-dir", cast("str", parsed["historyDir"])))
+        value = await self._invoke(args)
+        return cast(
+            "builtins.list[dict[str, Any]]",
+            _validate("history_list", value, "invalid oneharness history list contract"),
+        )
+
+    def history_watch(
+        self, options: Optional[HistoryWatchOptions] = None
+    ) -> AsyncIterator[HistoryStreamEnvelope]:
+        """Follow validated standardized history records."""
+        parsed = _input(
+            "history_watch_options", options or {}, "invalid oneharness history watch options"
+        )
+        args = ["history", "watch", "--format", "jsonl"]
+        if parsed.get("after"):
+            args.extend(("--after", cast("str", parsed["after"])))
+        for key, value in cast("Mapping[str, str]", parsed.get("labels", {})).items():
+            args.extend(("--label", f"{key}={value}"))
+        if parsed.get("project"):
+            args.extend(("--project", cast("str", parsed["project"])))
+        if parsed.get("allProjects"):
+            args.append("--all-projects")
+        if parsed.get("historyDir"):
+            args.extend(("--history-dir", cast("str", parsed["historyDir"])))
+        return self._stream(
+            args,
+            "history_stream_envelope",
+            "invalid oneharness history watch contract",
+            history=True,
+        )

oneharness_sdk-0.4.0/src/oneharness_sdk/_errors.py

@@ -0,0 +1,18 @@
+"""Typed public errors raised by the Python SDK."""
+
+
+class ContractError(ValueError):
+    """A value did not match its Rust-owned SDK contract."""
+
+
+class OneHarnessProcessError(RuntimeError):
+    """The oneharness subprocess exited unsuccessfully."""
+
+    def __init__(self, returncode: int, stderr: str) -> None:
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"oneharness exited {returncode}: {stderr.strip()}")
+
+
+class HistoryNotFoundError(OneHarnessProcessError):
+    """A history session, record, or watch cursor could not be resolved."""

oneharness_sdk-0.4.0/src/oneharness_sdk/_generated/__init__.py

@@ -0,0 +1 @@
+"""Rust-generated Python SDK assets."""

oneharness_sdk-0.4.0/src/oneharness_sdk/_generated/input-keys.json

@@ -0,0 +1,41 @@
+{
+  "history_list_options": {
+    "all_projects": "allProjects",
+    "history_dir": "historyDir",
+    "project": "project"
+  },
+  "history_lookup": {
+    "all_projects": "allProjects",
+    "history_dir": "historyDir",
+    "last": "last",
+    "project": "project",
+    "session": "session"
+  },
+  "history_watch_options": {
+    "after": "after",
+    "all_projects": "allProjects",
+    "history_dir": "historyDir",
+    "labels": "labels",
+    "project": "project"
+  },
+  "run_options": {
+    "bins": "bins",
+    "cwd": "cwd",
+    "env": "env",
+    "events": "events",
+    "fork": "fork",
+    "harnesses": "harnesses",
+    "history": "history",
+    "history_dir": "historyDir",
+    "history_labels": "historyLabels",
+    "history_name": "historyName",
+    "mode": "mode",
+    "models": "models",
+    "prompt": "prompt",
+    "reasoning": "reasoning",
+    "resume": "resume",
+    "session": "session",
+    "system": "system",
+    "timeout_seconds": "timeoutSeconds"
+  }
+}