callva-harness-runner 0.3.0__tar.gz

callva_harness_runner-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.DS_Store

callva_harness_runner-0.3.0/DESIGN.md

@@ -0,0 +1,107 @@
+# Design
+
+`callva-harness-runner` runs one turn of an agent harness from a profile and hands back one result. It exists because the same fifty lines of launch-and-parse code had been written nine times across one owner's tools, each with a different bug, and a tenth was about to be written.
+
+## 1. Scope
+
+One turn: a prompt goes in, a harness runs to its end or its deadline, one `Result` comes out. The library runs the harness through its vendor's SDK against the CLI installed on the machine, configures it only from the profile's explicit knobs, keeps every process it starts under the deadline, reads the harness's report, and classifies a failure by what the harness said. That is the whole job.
+
+### Non-goals
+
+It does not schedule, queue, retry, or loop. It holds no ledger, no session store, no conversation memory. It renders no progress; it hands events to a callback and the caller renders. It does not know what a task, a message or a job is. It ships no presets and no fences: it never decides what a turn may do. Presets belong to consumers.
+
+## 2. Names
+
+The vocabulary: a harness is the vendor's agent runtime (Claude Code, the Codex CLI); a profile is one harness configuration; a run is one turn. The library holds no queue and no long-lived consumer of work; those belong to its callers.
+
+The distribution is `callva-harness-runner` and the import path is `callva.harness_runner`: the distribution name is the import path with dashes, the same rule `callva-livekit` follows, and `callva` is a namespace package with no `__init__.py` so the two coexist in one environment. It was `callva-agentworker` (`callva.agentworker`) up to 0.2.0; the README maps each old name to its new one, and every old name is refused with a message naming the new one. The three nouns a caller uses are `Profile` (how to run), `Session` (which conversation), and `Result` (what came back). `run()` is the one verb. `probe()` answers whether a harness is present.
+
+## 3. Harnesses
+
+`claude` is Claude Code through `claude-agent-sdk`; `codex` is Codex through `openai-codex`, which drives `codex app-server`. Both are dependencies pinned exactly, because an SDK release changes the protocol it speaks and the flags it passes.
+
+Both SDKs bundle a CLI, and the library never runs it: it always passes the installed CLI (`cli_path` on claude, the `app-server` launch on codex). The CLI is the profile's `cli_path`, or else the first `claude` or `codex` on the caller's `PATH`, then in the places a login shell would have added and a launchd job does not: `~/.local/bin`, fnm and nvm node directories, Homebrew. Codex is started at the file a symlinked install points to, because it finds its companion executables beside the path it was started from.
+
+Claude always runs on the `claude_code` system-prompt preset. The SDK's own default is a minimal prompt that is not Claude Code's; the preset keeps the prompt a `claude -p` turn has. Neither harness's system prompt is ever replaced; `append_system_prompt` adds to claude's and is codex's developer instructions.
+
+Codex's turn is read from the turn's notification stream, not from `thread.run()`, which raises on a failed turn and drops `codexErrorInfo`.
+
+## 4. Profile
+
+A `Profile` is a frozen, flat record of explicit knobs. There is no inheritance and no named fence. A knob at its default leaves the harness's own default in place. A knob one harness cannot honour is refused for that harness when the profile is built, with a `ProfileError` naming the knob; it is never ignored while the turn runs. Each knob's docstring on `Profile` is the home of what it does on each harness, and the README carries the same table for readers of the package page.
+
+The knobs: `harness`, `cli_path`, `model`, `effort`, `timeout_seconds`, `budget_usd`; `tools`, `allowed_tools`, `disallowed_tools`, `permission_mode`, `setting_sources`; `settings`, `mcp_config`, `strict_mcp`; `add_dirs`, `append_system_prompt`, `output_schema`, `name`; `env_set`, `env_remove`, `strip_session_markers`; `codex_config`, `approval_policy`, `service_tier`, `bypass_hook_trust`; `claude_extra_args`, `codex_extra_args`.
+
+`Profile.from_dict()` validates against `profile.schema.json`, which ships in the package so that every consumer's configuration file is checked by the same rule. Unknown keys are refused, and the 0.1.x keys (`fence`, `allow_tools`, `env`, `extra_args`) are refused with a message naming the knobs that replace them.
+
+Hook trust on codex is a knob that is refused on both harnesses. Over `app-server` there is no way to run a hook the machine has not trusted: `bypass_hook_trust` is not a config key (`--strict-config` rejects it) and the CLI's `--dangerously-bypass-hook-trust`, accepted before `app-server`, does not make an untrusted hook run, although the same hook runs under `codex exec` with it. Hooks the machine trusts run.
+
+### Environment
+
+Both SDKs merge the profile's variables over the environment the Python process has, and neither can remove one. The library therefore puts a launcher of its own where the SDK expects the CLI: a two-line shell script that runs `_launcher.py` with `python -I -S`, which removes the variables the turn removes and `exec`s the real CLI. What reaches the launcher is a spec of names and paths; a variable's value only ever travels through the SDK's own env option.
+
+The harness's environment is the caller's `environ` (this process's by default), with the profile's `env_remove` globs and, unless `strip_session_markers` is false, `SESSION_MARKERS` removed, and with `env_set` and the call's `extra_env` set on top. A variable in `env_set` is never removed, and a profile that both sets and removes one name is refused. On claude the variables the SDK itself sets for the CLI (its entrypoint, its version, its session-state flag, `PWD`) are the SDK's values and are not removed.
+
+## 5. Session
+
+`Session.fresh()` starts a new conversation. On claude the library generates the id before launch and pins it, so a turn that is killed is still addressable. On codex the id is the thread id the app-server gives, reported even when the turn is later killed. `Session.pinned(id)` lets the caller choose the id; it is claude-only and refused on codex. `Session.resume(id)` continues an existing conversation on either harness; on codex the thread is resumed with the profile's model, config, developer instructions, service tier and approval policy.
+
+## 6. Harness guard
+
+`TESTED_VERSIONS` declares, per harness, the inclusive range of CLI versions the release was tested with: the low end is the CLI installed where the release was tested, the high end is the CLI the pinned SDK bundles. Before every turn the installed CLI's `--version` is read (cached per binary file):
+
+- below the range, or unreadable: the turn is refused with `incompatible_harness`, naming both versions;
+- above the range: the turn runs and `Result.warnings` names both versions;
+- no CLI: `binary_missing`, as it was.
+
+## 7. Running
+
+The turn runs on a thread of its own; the calling thread holds the deadline and the cancel. The launcher records the harness's pid and command line and makes the harness a session leader. When the deadline passes or the caller's `threading.Event` is set, the library first writes a stop file that the launcher checks before any later start, then finds the harness's tree three ways: by parentage from the harness, by the process groups of what it found, and by the sessions of what it found, the harness's own included. The harnesses give each tool command a process group of its own, and a command that backgrounds a child and exits leaves that child with its group and session but a new parent, so parentage alone would miss it. The tree gets SIGTERM, three seconds, then SIGKILL; the caller's own group and session are never touched. Then the SDK is closed.
+
+A caller killed outright cannot do any of this, and the harness's tree outlives it.
+
+## 8. Reading
+
+Claude: the SDK's `ResultMessage` gives `result` as the answer (its `errors` when there is none), `structured_output`, `session_id`, `total_cost_usd`, `duration_ms`, `num_turns`, the four token counts from `usage`, the model that ran from `modelUsage`, `permission_denials`, and `subtype` with `is_error` as the verdict. The SDK raises after it hands over an error result; the result is the report and the raise is not. The last `api_retry` event is kept, because a turn that dies by the deadline while the harness retries a 401 or a 429 has already said why.
+
+Codex: the turn's `item/completed` notifications give the answer (the last agent message), `thread/tokenUsage/updated` gives this turn's tokens (the thread's running total less what it held before the turn), and `turn/completed` gives the status, the duration and the error with its `codexErrorInfo`. Cost is `None`: codex reports none under ChatGPT authentication.
+
+When `output_schema` is given and the harness returned no structured field, the answer text is parsed as JSON; if that fails, the turn is an `invalid_output` failure with the text kept.
+
+## 9. Result
+
+| Field | Meaning |
+|---|---|
+| `ok` | the harness confirmed a completed turn: claude `subtype == "success"` and `is_error` false; codex status `completed`, no error, and a non-empty answer. |
+| `harness` | which harness ran. |
+| `answer` | the final text, possibly empty on failure. |
+| `structured` | the parsed structured answer, or `None`. |
+| `session_id` | claude session id or codex thread id; set whenever it is known, including after a kill. |
+| `model` | the model that actually ran when claude reports it, else the requested one, else `None`. |
+| `cost_usd`, `duration_ms`, `num_turns`, `tokens` | as reported; `None` where the harness does not say. |
+| `permission_denials` | claude's list, empty on codex. |
+| `failure` | `None` when `ok`; otherwise a kind and the harness's own sentence. |
+| `exit_code` | the exit code the claude SDK reported for a failed process, else `None`. |
+| `stderr_tail` | the last lines of the harness's stderr, for a person. |
+| `command` | the CLI command line the launcher started. |
+| `raw` | claude's result message as a dict, or codex's `{"turn", "items", "errors"}`, for anything this table left out. |
+| `harness_version` | the CLI version the guard read. |
+| `warnings` | the guard's warning when the CLI is newer than tested. |
+
+## 10. Failure kinds
+
+`quota`: the subscription or rate limit is spent; the turn can be retried later without changing anything. `model_refused`: the harness will not run this model; retrying changes nothing. `not_authenticated`: no login or an invalid key. `timeout`: the deadline passed and the tree was killed. `cancelled`: the caller's event was set. `binary_missing`: no harness found. `max_turns`, `budget`: the harness ended the turn on its own limit. `invalid_output`: a schema was required and nothing parsed. `error`: the harness reported a failure this table does not name; the sentence is in `message`. `crash`: the harness ended without a report. `incompatible_harness`: the installed CLI is older than the tested range, or its version cannot be read.
+
+Classification reads the harness's own verdict first (claude's `error_max_turns` and budget subtypes; codex's `codexErrorInfo`: `usageLimitExceeded` and `rateLimitExceeded` are `quota`, `unauthorized` is `not_authenticated`, `sessionBudgetExceeded` is `budget`), then an HTTP status the harness reports (claude's `api_error_status` or its last `api_retry` status, codex's `httpStatusCode`: 429 is `quota`, 401 is `not_authenticated`), then the sentence, in a fixed order: quota before model refusal, because a spent subscription on one model says both, and only one of them is a pause. Codex wraps a provider's HTTP error as JSON; the sentence inside it is what is read and kept.
+
+## 11. Constraints worth knowing
+
+The cost claude reports is its own estimate and includes subagents; a turn that dies reports no cost at all, so an accumulated total is a floor. Codex under ChatGPT authentication reports tokens but no cost. A profile with no knobs runs the harness exactly as the machine configures it: user settings, hooks and MCP servers included. Hooks on codex run only when the machine trusts them.
+
+## 12. Versioning
+
+SemVer with the 0.x rule: the minor is the breaking position. A changed field meaning, a removed knob or a changed default is a minor; an added result field, an added knob whose default leaves the harness alone, or a widened tested range is a patch. `callva/harness_runner/version.py` is the one home of the number.
+
+## 13. Later
+
+Progress rendering helpers, if two consumers end up writing the same one. Cost lookup for codex by token price table, if anyone needs a number rather than `None`. A parent watch in the launcher, if a crashed caller's orphaned tree becomes a real problem.

callva_harness_runner-0.3.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

callva_harness_runner-0.3.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: callva-harness-runner
+Version: 0.3.0
+Summary: One headless turn of a coding agent (Claude Code or Codex) through the vendor SDKs: explicit knobs, a deadline that kills the tree, one result.
+Project-URL: Homepage, https://github.com/callva-io/harness-runner
+Project-URL: Source, https://github.com/callva-io/harness-runner
+Author: CallVA
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,claude,claude-agent-sdk,codex,harness,headless,openai-codex
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: claude-agent-sdk==0.2.161
+Requires-Dist: openai-codex==0.159.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# callva-harness-runner
+
+One run of an agent harness, as a Python library. A harness is the vendor's agent runtime: Claude Code, driven through Anthropic's `claude-agent-sdk`, or the Codex CLI, driven through OpenAI's `openai-codex`, always the CLI installed on the machine. A profile is one harness configuration, a flat set of explicit knobs. A run is one turn: a prompt goes in, the harness works to its end or its deadline, and one `Result` comes out, with the failure named. The deadline kills everything the harness started. The library ships no presets and no fences: what a run may do is whatever its profile says, and nothing else.
+
+`DESIGN.md` is the contract. The source is at https://github.com/callva-io/harness-runner.
+
+Formerly `callva-agentworker`, whose last release is 0.2.0. The 0.3.0 renames, with no aliases (each old name is refused with a message naming the new one):
+
+| 0.2.0 | 0.3.0 |
+|---|---|
+| distribution `callva-agentworker` | `callva-harness-runner` |
+| import `callva.agentworker` | `callva.harness_runner` |
+| profile knob `engine` | `harness` |
+| `Result.engine` | `Result.harness` |
+| `Result.engine_version` | `Result.harness_version` |
+| failure kind `incompatible_engine` (`FailureKind.INCOMPATIBLE_ENGINE`) | `incompatible_harness` (`FailureKind.INCOMPATIBLE_HARNESS`) |
+| `ENGINES` | `HARNESSES` |
+| `Probe.engine` | `Probe.harness` |
+
+## Install
+
+```
+pip install callva-harness-runner
+```
+
+It depends on `claude-agent-sdk==0.2.161` and `openai-codex==0.159.0`, pinned exactly; together they add about 0.5 GB, most of it the CLIs both SDKs bundle. The bundled CLIs are never run: the library always runs the CLI installed on the machine.
+
+In a PEP 723 script, pin the exact version so nothing outside the script's own release changes what it runs:
+
+```python
+# /// script
+# dependencies = ["callva-harness-runner==0.3.0"]
+# ///
+```
+
+## Use
+
+```python
+from callva.harness_runner import Profile, Session, run
+
+profile = Profile.from_dict(config["profile"])   # your configuration, your knobs
+result = run("Summarise README.md in one line.", profile, cwd="/path/to/project")
+if result.ok:
+    print(result.answer, result.cost_usd, result.session_id)
+else:
+    print(result.failure.kind, result.failure.message)
+```
+
+`run()` never raises for anything the harness did. Every ending is a `Result`; `result.failure.kind` says what kind, and `result.failure.message` carries the harness's own sentence. It raises `ValueError` only for a request it cannot express, such as a pinned session on codex.
+
+`run(prompt, profile, cwd, *, session=None, environ=None, extra_env=None, on_event=None, cancel=None, stderr_tail=40)`:
+
+- `session`: `Session.fresh()` (the default), `Session.pinned(id)` or `Session.resume(id)`, below.
+- `environ`: the environment the harness starts from; this process's by default. A variable absent from it is absent in the harness, even though both SDKs inherit this process's environment.
+- `extra_env`: variables set on top of `environ` and the profile's `env_set`.
+- `on_event`: called with one dict per harness event while the turn runs. On claude it is the SDK's message: a system message is the harness's own event (`subtype` `init` carries `apiKeySource`, `model` and `claude_code_version`), any other message is its fields plus `type`, the SDK class name. On codex it is `{"method", "params"}`, one app-server notification.
+- `cancel`: a `threading.Event`; setting it ends the turn and kills its processes.
+
+## Profile
+
+A profile is a flat set of explicit knobs. There is no inheritance, no preset and no fence. A knob left at its default leaves the harness's own default in place. A knob one harness cannot honour is refused for that harness with a `ProfileError` when the profile is built, never ignored while it runs. Each knob's docstring on `Profile` says what it does on each harness; `PROFILE_SCHEMA` (shipped as `profile.schema.json`) validates a profile kept in configuration, and `Profile.from_dict` refuses unknown keys.
+
+| Knob | claude | codex |
+|---|---|---|
+| `harness` | `claude` | `codex` |
+| `cli_path` | the CLI the SDK launches; `None` finds the installed `claude` | the binary whose `app-server` the SDK talks to; `None` finds the installed `codex` |
+| `model` | `--model` | the thread's model |
+| `effort` | `--effort` | the turn's reasoning effort |
+| `timeout_seconds` | the deadline; default 600 | the same |
+| `budget_usd` | `--max-budget-usd` | refused: codex reports no cost |
+| `tools` | `--tools`, the built-in tools that exist; `[]` removes them all | refused |
+| `allowed_tools` | `--allowedTools`, patterns that run without a prompt | refused |
+| `disallowed_tools` | `--disallowedTools` | refused |
+| `permission_mode` | `--permission-mode` | refused: use `approval_policy` and `codex_config` |
+| `setting_sources` | `--setting-sources`; `["project", "local"]` loads the target's CLAUDE.md, rules and hooks without the user's | refused |
+| `settings` | `--settings`, an object or path layered above the settings files: sandbox, permissions | refused: use `codex_config` |
+| `mcp_config` | `--mcp-config`, `{"mcpServers": {...}}` or a path | refused: `mcp_servers` in `codex_config` |
+| `strict_mcp` | `--strict-mcp-config` | refused |
+| `add_dirs` | `--add-dir` per entry | refused: give the directory access in `codex_config` permissions |
+| `append_system_prompt` | appended to the Claude Code system prompt | the thread's developer instructions |
+| `output_schema` | `--json-schema` | the turn's output schema |
+| `name` | `--name` | the thread's name |
+| `env_set` | set in the harness's environment | the same |
+| `env_remove` | names or globs removed from what the harness inherits | the same |
+| `strip_session_markers` | also remove `SESSION_MARKERS`; default true | the same |
+| `codex_config` | refused: use `settings` | the thread's config, keyed as in `config.toml`: permission profiles, `sandbox_mode`, network, `mcp_servers` |
+| `approval_policy` | refused: use `permission_mode` | `never` (escalations refused) or `auto_review` (codex's reviewer decides); `None` is the SDK default, `auto_review` |
+| `service_tier` | refused | the thread's service tier |
+| `bypass_hook_trust` | refused: claude has no hook trust | refused when true: the app-server has no hook-trust bypass, so hooks run only when the machine trusts them |
+| `claude_extra_args` | extra CLI flags, `{"flag": "value"}` or `{"flag": None}` | refused |
+| `codex_extra_args` | refused | arguments before `app-server`, such as `["-c", "key=value"]` |
+
+Claude always runs on the `claude_code` system-prompt preset, so a turn has the same prompt `claude -p` has; the library never replaces either harness's system prompt, and `append_system_prompt` only adds to it.
+
+### Environment
+
+Both SDKs only add to the environment they inherit. To remove a variable for real, the library puts a small launcher of its own in front of the CLI: the SDK starts the launcher, the launcher removes what the profile removes and becomes the CLI. The launcher learns names, never values. `SESSION_MARKERS` are the variables a running Claude Code session leaves in its children (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`, `CLAUDE_EFFORT`, `AI_AGENT` and the rest); a child harness that inherits them believes it runs inside that session, so they are removed unless `strip_session_markers` is false. On claude the values the SDK itself sets for the CLI, such as its entrypoint, stay.
+
+### Deadline and cancel
+
+The launcher makes the harness a session leader. When the deadline passes, or `cancel` is set, no further harness start is allowed, and the harness, every process it started, and everything those left behind in their process group or session are sent SIGTERM and then SIGKILL, grandchildren included. A caller that is itself killed cannot do this, and the harness's tree then outlives it.
+
+## Harness guard
+
+`TESTED_VERSIONS` holds, per harness, the range of CLI versions this release was tested with: claude 2.1.280 to 2.1.284, codex 0.159.0. Before a turn the library reads the installed CLI's `--version`:
+
+- older than the range: the turn is refused with failure kind `incompatible_harness`, and the message names the installed version and the tested one;
+- newer than the range: the turn runs, and `result.warnings` names both versions;
+- no CLI: `binary_missing`, as before.
+
+## Session
+
+`Session.fresh()` starts a conversation; on claude the id is chosen before launch so a killed turn is still addressable, on codex it is the thread id the app-server gives. `Session.resume(id)` continues one on either harness. `Session.pinned(id)` chooses the id and is claude-only.
+
+## Result
+
+| Field | Meaning |
+|---|---|
+| `ok` | the harness confirmed a completed turn with an answer |
+| `harness` | `claude` or `codex` |
+| `answer` | the final text |
+| `structured` | the parsed answer when `output_schema` was given |
+| `session_id` | claude session id or codex thread id, set whenever known, including after a kill |
+| `model` | the model that ran when claude reports it, else the requested one |
+| `cost_usd` | claude's own estimate; `None` on codex |
+| `duration_ms`, `num_turns` | as reported; `num_turns` is `None` on codex |
+| `tokens` | `input`, `output`, `cache_read`, `cache_creation` for this turn |
+| `permission_denials` | claude's list; empty on codex |
+| `failure` | `None` when `ok`; else `kind` and the harness's own `message` |
+| `exit_code` | the exit code the claude SDK reported for a failed process, else `None` |
+| `stderr_tail` | the harness's last stderr lines, for a person |
+| `command` | the CLI command line the launcher started |
+| `raw` | claude's result message, or codex's `{"turn", "items", "errors"}` |
+| `harness_version` | the installed CLI version the guard read |
+| `warnings` | the guard's warning when the CLI is newer than tested |
+
+### Failure kinds
+
+`quota`, `model_refused`, `not_authenticated`, `timeout`, `cancelled`, `binary_missing`, `max_turns`, `budget`, `invalid_output`, `error`, `crash`, `incompatible_harness`. The harness's own verdict is read first (claude's result subtype, codex's `codexErrorInfo`), then an HTTP status it reports, then its sentence: a spent quota before a refused model, because a subscription spent on one model says both and only one of them is a pause. A claude turn that times out while the harness is retrying a 401 or a 429 is `not_authenticated` or `quota`. `failure.retryable` is true for the kinds where running the same turn again later can succeed.
+
+## Changelog
+
+### 0.3.0
+
+The library is renamed and speaks of harnesses, profiles and runs; its behaviour is exactly 0.2.0's. What a 0.2.0 consumer must change: depend on `callva-harness-runner` and import `callva.harness_runner`; write `harness` where a profile said `engine`; read `Result.harness` and `Result.harness_version`; branch on `incompatible_harness`; import `HARNESSES`. The table at the top maps every old name.
+
+### 0.2.0
+
+The engines now run through the vendors' SDKs, and the profile is explicit knobs. What a 0.1.x consumer must change:
+
+- `fence` is gone, and so is its default. A 0.1.x profile that named no fence ran fenced to `read`; the same profile now runs with the engine's own defaults. State what the turn may do with `tools`, `allowed_tools`, `disallowed_tools`, `permission_mode`, `setting_sources`, `settings`, `mcp_config` and `strict_mcp` on claude, and `codex_config` and `approval_policy` on codex. `Profile.from_dict` refuses a `fence` key with a message naming these knobs, and `Profile.fence` no longer exists.
+- `allow_tools` becomes `tools` plus `allowed_tools`. `env` (`allow`, `deny`, `set`) becomes `env_set`, `env_remove` and `strip_session_markers`; there is no allow-list. `extra_args` becomes `claude_extra_args` (a mapping) or `codex_extra_args`. `EnvPolicy`, `DEFAULT_DENY` and `FENCES` are no longer exported.
+- `run()` loses `schema` (now the profile's `output_schema`), `name` (now the profile's `name`) and `prompt_via` (the prompt always travels over the SDK's own channel).
+- A knob the engine cannot honour is refused instead of ignored: `budget_usd` on codex, `service_tier` on claude.
+- `on_event` receives SDK messages (claude) and app-server notifications (codex) instead of CLI JSON lines. `raw` changes shape the same way, `command` is the command line the launcher started, and `exit_code` is `None` unless the claude SDK reported one.
+- A CLI older than the tested range is refused with the new kind `incompatible_engine`; `Result` gains `engine_version` and `warnings`.
+- Two dependencies arrive, about 0.5 GB.
+
+Unchanged: `Profile.from_dict`, `Session.fresh`, `Session.pinned`, `Session.resume`, `run(prompt, profile, cwd, session=, environ=, extra_env=, on_event=, cancel=)`, `FailureKind`, and every 0.1.x `Result` field.
+
+## Versioning
+
+SemVer with the 0.x rule: the minor is the breaking position. A changed field meaning, a removed knob or a changed default is a minor; an added result field, an added knob whose default leaves the harness alone, or a widened tested range is a patch.
+
+## License
+
+Apache-2.0.