environment-harness 0.2.3rc1__tar.gz

environment_harness-0.2.3rc1/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.json
+coverage.xml
+*.egg-info/
+dist/
+node_modules/
+.local/
+*.sqlite*
+.environment-harness/
+
+.env
+.env.*
+researcher-token

environment_harness-0.2.3rc1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## Unreleased
+
+Production PyPI publishing now uses short-lived Trusted Publishing credentials and publishes only the reviewed Python wheel and source distribution. Releases support PEP 440 alpha, beta, and release-candidate versions while mapping those versions to npm-compatible SemVer prereleases. Package metadata now includes the rendered README, classifiers, project links, and the `py.typed` marker.
+
+## 0.2.2 - 2026-09-18
+
+Release publishing now extracts immutable-ID artifacts directly into the verified distribution directory before checking attestations and explicitly disables dependency caching during the tag build. Routine Dependabot version updates are grouped into one monthly pull request per ecosystem, while security updates remain immediate.
+
+## 0.2.1 - 2026-09-17
+
+The public SDK now includes coordinated vulnerability reporting, governance and support files, dependency cooldowns, immutable workflow and container pins, credential-free security scans, cross-platform CI, positive distribution manifests, installed-wheel smoke tests, SBOM and tag-triggered artifact-attestation release automation, and protected-release setup guidance. Release maintainers create the reviewed protected tag manually; Actions stores no long-lived release credential. Python and TypeScript coverage gates require at least 90% statements/lines and 80% branches; security-critical Python modules meet those floors independently.
+
+Session recovery now rejects stale worker completion and protects reconciled responses. Cancellation works while a writer is active, terminates managed command process groups and reports unresolved effects. The runner validates registered agent implementations, and conformance supports coordinator closure and explicit event inputs.
+
+Comparisons keep incompatible metric definitions and units in separate groups. Legacy reports remain readable as raw values. Large inherited records use bounded chunks and can be branched repeatedly without adding encoding layers. Existing stores require no migration. See [compatibility and protocol details](docs/COMPATIBILITY.md).
+
+The command line gains `list`, `show` and `timeline`. `timeline` groups recorded events by the state revision an action was taken from and prints one line per participant with the observation, the attempted action and the executed outcome; `--participant`, `--kind` and `--verbose` narrow or expand it. `compare` now prints a readable summary by default, and `--json` on these commands prints the underlying records, so scripts that parsed `compare` output should pass `--json`. Comparison records include `participants` and `revision`.
+
+The browser viewer is read-only. It groups the timeline by revision, names environments by their participants and role, collapses inherited history into one line, renders scores as cards, and uses a sandstone palette that follows the system light or dark preference. Checkpoint, pause, cancel and branch controls moved out of the viewer; they remain command-line and SDK operations.
+
+The README's local startup now uses `serve --open` to open and connect the viewer automatically. A single-use loopback connection ticket avoids copying credentials, and tab-scoped storage keeps the local viewer connected across refreshes. Supplier API authentication remains required.
+
+## 0.1.0
+
+EnvironmentHarness provides persistent shared environments, participant-specific observations, checkpoints, isolated branches and recorded evidence. The local viewer supports inspection, comparison and JSONL export.
+
+The release includes Python and TypeScript clients, an authenticated HTTP service, and runnable synthetic examples. The examples require no account or model API key. Their results demonstrate the SDK workflow and do not measure model intelligence or safety.

environment_harness-0.2.3rc1/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+EnvironmentHarness follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Be respectful, constructive, and welcoming. Harassment, intimidation, discrimination, and publication of another person's private information are not acceptable in project spaces.
+
+Report conduct concerns privately to founders@kimpton.ai. Maintainers will review reports confidentially, avoid conflicts of interest, and may remove content or participation privileges when necessary.

environment_harness-0.2.3rc1/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Use Python 3.12 or later, uv 0.12.0, Node.js 22, and npm 11.17 or later. Run `uv sync --extra server` and `npm ci --ignore-scripts --prefix packages/typescript`. Resolution observes the seven-day dependency cooldown in [docs/DEPENDENCY-SECURITY.md](docs/DEPENDENCY-SECURITY.md).
+
+The PostgreSQL integration test uses PostgreSQL 17.6 Alpine at an immutable container digest in the weekly workflow. Update both the version and digest deliberately when testing a newer database release.
+
+Python and TypeScript ship as one coordinated three-component SemVer release. Keep user-facing changes under `Unreleased`; do not edit package versions individually. Patch releases contain backward-compatible fixes. Minor releases contain new capabilities and, while the SDK is below 1.0, any intentionally incompatible public change with documented migration guidance. After 1.0, incompatible public API or contract changes require a major release.
+
+To release, create a release branch after adding notes under `Unreleased`, then run `python scripts/release_version.py prepare --bump patch` (or `minor`/`major`). It moves the accumulated notes to a dated version and synchronizes `pyproject.toml`, `environment_harness.__version__`, `uv.lock`, the TypeScript package and lockfile, the root and TypeScript README examples, and the release status. Validate the proposed tag with `python scripts/release_version.py validate --release-tag vX.Y.Z`, run the release checks, and merge the release PR normally.
+
+After the release PR merges, copy its merge commit SHA from GitHub; do not use the newest `main` commit if later changes have landed. A release maintainer fetches `main` and tags, detaches at the recorded merge commit, and runs `python scripts/release_version.py detect`. Create the reported protected tag with `git tag vX.Y.Z <release-merge-sha>` and push only `refs/tags/vX.Y.Z`. The tag dispatches the attested publisher, which waits for independent `github-release` environment approval. Release preparation and tag creation intentionally use no stored GitHub App private key or other long-lived Actions credential. Never rebuild different artifacts under an existing version.
+
+Before submitting a change, run `make check`, `make viewer`, `npm run typecheck --prefix packages/typescript`, and `make build`. Include a small reproducible example of the behavior you changed. Schema changes must update the generated JSON and TypeScript contracts. `src/environment_harness/presentation.py` and `packages/typescript/src/timeline.ts` must keep the same turn-grouping rules and field names so the command line and the viewer describe evidence identically. Do not change protocol semantics without describing compatibility and migration.
+
+CI requires at least 90% statement and 80% branch coverage overall and for security-critical modules. Changed executable lines require 100% diff coverage. A changed regression test must also fail when applied to `origin/main`.
+
+Keep domain implementations, credentials and recorded private data out of this repository. Examples and test fixtures must be synthetic or explicitly redistributable. Optional integration support should state its actual checkpoint and recovery limits.
+
+Open a GitHub issue for a bug or integration question. Include the release version, operating system, exact command and a sanitized reproduction. Never attach credentials or a private environment store. Report security concerns privately as described in [SECURITY.md](SECURITY.md).

environment_harness-0.2.3rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kimpton AI, Inc.
+
+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.

environment_harness-0.2.3rc1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: environment-harness
+Version: 0.2.3rc1
+Summary: Durable sessions and evidence for independently implemented AI environments
+Project-URL: Homepage, https://github.com/kimpton-ai/environment-harness
+Project-URL: Repository, https://github.com/kimpton-ai/environment-harness
+Project-URL: Documentation, https://github.com/kimpton-ai/environment-harness#readme
+Project-URL: Changelog, https://github.com/kimpton-ai/environment-harness/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kimpton-ai/environment-harness/issues
+Project-URL: Security, https://github.com/kimpton-ai/environment-harness/security/policy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,environments,evaluation,experiments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jsonschema<5,>=4.26
+Requires-Dist: pydantic<3,>=2.12.5
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30.0; extra == 'mcp'
+Provides-Extra: modal
+Requires-Dist: modal<2,>=1.5.4; extra == 'modal'
+Provides-Extra: pettingzoo
+Requires-Dist: pettingzoo<2,>=1.25; extra == 'pettingzoo'
+Requires-Dist: pygame<3,>=2.6.1; extra == 'pettingzoo'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]<4,>=3.3.3; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.135.1; extra == 'server'
+Requires-Dist: uvicorn<1,>=0.41; extra == 'server'
+Provides-Extra: signatures
+Requires-Dist: cryptography<51,>=50.0.1; extra == 'signatures'
+Provides-Extra: verifiers
+Requires-Dist: datasets<6,>=5.0.1; extra == 'verifiers'
+Requires-Dist: verifiers<0.4,>=0.3.1; extra == 'verifiers'
+Description-Content-Type: text/markdown
+
+# EnvironmentHarness
+
+[![CI](https://github.com/kimpton-ai/environment-harness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kimpton-ai/environment-harness/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/kimpton-ai/environment-harness/graph/badge.svg?branch=main)](https://app.codecov.io/gh/kimpton-ai/environment-harness)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](https://github.com/kimpton-ai/environment-harness/blob/main/LICENSE)
+
+Run agents in persistent shared environments, then inspect exactly what they observed, attempted, and changed.
+
+EnvironmentHarness is an MIT-licensed SDK for evaluations that unfold over time. It records participant-specific observations, actions, outcomes, checkpoints, score reports, and branch lineage as durable evidence.
+
+[Install](#install) · [Try it locally](#try-it-locally) · [Connect an agent](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) · [Implement an environment](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AUTHORING.md) · [Protocol](https://github.com/kimpton-ai/environment-harness/blob/main/docs/PROTOCOL.md) · [Release scope](https://github.com/kimpton-ai/environment-harness/blob/main/docs/STATUS.md)
+
+## What you can do
+
+- Run one or more agents against stateful environment rules.
+- Give each participant a different private observation of the same shared state.
+- Record observations, attempted actions, executed outcomes, scores, costs, and artifacts.
+- Checkpoint an environment session, branch it with a declared intervention, and continue both sessions.
+- Inspect a timeline, compare related environment sessions, or export the evidence as JSONL.
+
+You provide the environment rules, agent programs, and grading method. EnvironmentHarness coordinates the environment session and preserves the evidence.
+
+```text
+Your environment + agents + scorer
+                 │
+                 ▼
+        EnvironmentSession
+     records every state revision
+                 │
+                 ▼
+       Python / CLI / local viewer
+              / JSONL
+```
+
+## Install
+
+Install the stable Python SDK from PyPI:
+
+```sh
+python -m pip install environment-harness
+```
+
+Add the local HTTP service and viewer when you need them:
+
+```sh
+python -m pip install "environment-harness[server]"
+```
+
+Release candidates use PEP 440 versions such as `0.2.3rc1`. Pip excludes prereleases from ordinary installs; test one by requesting its exact version or by opting in:
+
+```sh
+python -m pip install "environment-harness==0.2.3rc1"
+python -m pip install --pre --upgrade environment-harness
+```
+
+## Try it locally
+
+You need macOS or Linux, Python 3.12 or later, and [uv 0.12.0 or later](https://docs.astral.sh/uv/getting-started/installation/). The demo uses synthetic agents, so it needs no account, model API key, or paid service.
+
+```sh
+git clone --branch v0.2.3rc1 --depth 1 https://github.com/kimpton-ai/environment-harness.git
+cd environment-harness
+uv sync --extra server
+uv run python examples/branch_comparison.py --store .local/branch-demo
+uv run environment-harness --store .local/branch-demo serve --open
+```
+
+The last command serves something, but only on your computer:
+
+- a local authenticated API at `http://127.0.0.1:8765`
+- a read-only browser viewer for the evidence in `.local/branch-demo`
+
+It does not deploy or publish the environment session. `--open` creates a short-lived local login link and opens the viewer. Press `Ctrl+C` in the terminal to stop the service.
+
+### What the demo means
+
+The example creates one original environment session with a shared counter. Alice and Bob each add `1` per turn:
+
+1. After three turns, the original session's shared total is `6`.
+2. The example saves a checkpoint and creates a separate branched session from it.
+3. A declared intervention changes only the branched session's starting total from `6` to `20`.
+4. Both sessions run for two more turns. The original finishes at `10`; the branch finishes at `24`.
+
+The totals are values in the synthetic environment's shared state. They are not the number of agents, scores of agent quality, or independent statistical results. The example exists to demonstrate state, lineage, intervention, and recorded evidence.
+
+### What the viewer shows
+
+The viewer is an evidence inspector, not a control panel:
+
+![EnvironmentHarness local evidence viewer showing original and branched environment sessions with a participant timeline](https://raw.githubusercontent.com/kimpton-ai/environment-harness/main/docs/assets/environment-session-viewer.png)
+
+1. The **Environment sessions** list lets you open the original or branched session. Check two boxes to compare them.
+2. **Timeline** groups evidence by state revision. Each participant row shows the observation delivered to that participant, the action it attempted, and the outcome the environment executed.
+3. **Scores and findings** shows reports submitted by your scorer. In this demo, `synthetic total` is just the final counter value.
+4. **Environment comparison** shows what the sessions share, the intervention applied to the branch, and their recorded results.
+
+The viewer never changes an environment session. Use the Python SDK or CLI for checkpoint, branch, resume, cancel, and execution operations.
+
+## Use your own agent
+
+Run the included external JSON program through the command-agent boundary:
+
+```sh
+uv run python examples/custom_agent.py --store .local/custom-agent
+uv run environment-harness --store .local/custom-agent serve --open
+```
+
+A Python agent implements `act(observation) -> dict`. An external program can instead read one JSON observation from stdin and write one JSON action to stdout. Your integration keeps ownership of prompts, model providers, tools, credentials, and spending limits.
+
+See [Connect an agent](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) for the complete contract and [custom_agent.py](https://github.com/kimpton-ai/environment-harness/blob/main/examples/custom_agent.py) for a working example.
+
+## Use the Python API
+
+```python
+from environment_harness import AgentSpec, EnvironmentSession, EvidenceStore, ExperimentSpec, Principal
+from environment_harness.fixtures import SyntheticAgent, SyntheticEnvironment
+from environment_harness.runner import run
+
+environment = SyntheticEnvironment()
+session = EnvironmentSession(EvidenceStore(".local/experiment"), environment)
+researcher = Principal(tenant="local", subject="researcher", role="researcher")
+experiment = ExperimentSpec(
+    environment=environment.spec,
+    participants=(
+        AgentSpec(id="alice", implementation="synthetic-agent@1", policy_version="1"),
+    ),
+)
+
+environment_session = session.create(experiment, researcher)
+run(
+    session,
+    environment_session["id"],
+    researcher,
+    {"alice": SyntheticAgent()},
+    turns=5,
+)
+```
+
+The local Python API is a trusted embedding interface. A local command subprocess is also not an operating-system security sandbox. Run hostile programs in an isolated backend with explicitly scoped network access.
+
+## Find the right guide
+
+| Goal | Guide |
+| --- | --- |
+| Connect a Python agent, model integration, or JSON program | [Agent integration](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) |
+| Implement and package environment rules | [Environment authoring](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AUTHORING.md) |
+| Understand checkpoints, branches, and coordinated sessions | [Coordinated sessions](https://github.com/kimpton-ai/environment-harness/blob/main/docs/coordinated-sessions.md) |
+| Use the authenticated HTTP API | [Protocol](https://github.com/kimpton-ai/environment-harness/blob/main/docs/PROTOCOL.md) |
+| Use the TypeScript client | [TypeScript package](https://github.com/kimpton-ai/environment-harness/blob/main/packages/typescript/README.md) |
+| Check adapter and isolation boundaries | [Adapters](https://github.com/kimpton-ai/environment-harness/blob/main/docs/ADAPTERS.md) |
+| Check compatibility and release limits | [Compatibility](https://github.com/kimpton-ai/environment-harness/blob/main/docs/COMPATIBILITY.md) · [Release scope](https://github.com/kimpton-ai/environment-harness/blob/main/docs/STATUS.md) |
+
+## Project
+
+[Contributing](https://github.com/kimpton-ai/environment-harness/blob/main/CONTRIBUTING.md) · [Support](https://github.com/kimpton-ai/environment-harness/blob/main/SUPPORT.md) · [Security](https://github.com/kimpton-ai/environment-harness/blob/main/SECURITY.md) · [Changelog](https://github.com/kimpton-ai/environment-harness/blob/main/CHANGELOG.md) · [MIT license](https://github.com/kimpton-ai/environment-harness/blob/main/LICENSE)
+
+Report vulnerabilities privately through [SECURITY.md](https://github.com/kimpton-ai/environment-harness/blob/main/SECURITY.md). Do not put credentials or private environment sessions in a public issue.

environment_harness-0.2.3rc1/README.md

@@ -0,0 +1,158 @@
+# EnvironmentHarness
+
+[![CI](https://github.com/kimpton-ai/environment-harness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kimpton-ai/environment-harness/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/kimpton-ai/environment-harness/graph/badge.svg?branch=main)](https://app.codecov.io/gh/kimpton-ai/environment-harness)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](https://github.com/kimpton-ai/environment-harness/blob/main/LICENSE)
+
+Run agents in persistent shared environments, then inspect exactly what they observed, attempted, and changed.
+
+EnvironmentHarness is an MIT-licensed SDK for evaluations that unfold over time. It records participant-specific observations, actions, outcomes, checkpoints, score reports, and branch lineage as durable evidence.
+
+[Install](#install) · [Try it locally](#try-it-locally) · [Connect an agent](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) · [Implement an environment](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AUTHORING.md) · [Protocol](https://github.com/kimpton-ai/environment-harness/blob/main/docs/PROTOCOL.md) · [Release scope](https://github.com/kimpton-ai/environment-harness/blob/main/docs/STATUS.md)
+
+## What you can do
+
+- Run one or more agents against stateful environment rules.
+- Give each participant a different private observation of the same shared state.
+- Record observations, attempted actions, executed outcomes, scores, costs, and artifacts.
+- Checkpoint an environment session, branch it with a declared intervention, and continue both sessions.
+- Inspect a timeline, compare related environment sessions, or export the evidence as JSONL.
+
+You provide the environment rules, agent programs, and grading method. EnvironmentHarness coordinates the environment session and preserves the evidence.
+
+```text
+Your environment + agents + scorer
+                 │
+                 ▼
+        EnvironmentSession
+     records every state revision
+                 │
+                 ▼
+       Python / CLI / local viewer
+              / JSONL
+```
+
+## Install
+
+Install the stable Python SDK from PyPI:
+
+```sh
+python -m pip install environment-harness
+```
+
+Add the local HTTP service and viewer when you need them:
+
+```sh
+python -m pip install "environment-harness[server]"
+```
+
+Release candidates use PEP 440 versions such as `0.2.3rc1`. Pip excludes prereleases from ordinary installs; test one by requesting its exact version or by opting in:
+
+```sh
+python -m pip install "environment-harness==0.2.3rc1"
+python -m pip install --pre --upgrade environment-harness
+```
+
+## Try it locally
+
+You need macOS or Linux, Python 3.12 or later, and [uv 0.12.0 or later](https://docs.astral.sh/uv/getting-started/installation/). The demo uses synthetic agents, so it needs no account, model API key, or paid service.
+
+```sh
+git clone --branch v0.2.3rc1 --depth 1 https://github.com/kimpton-ai/environment-harness.git
+cd environment-harness
+uv sync --extra server
+uv run python examples/branch_comparison.py --store .local/branch-demo
+uv run environment-harness --store .local/branch-demo serve --open
+```
+
+The last command serves something, but only on your computer:
+
+- a local authenticated API at `http://127.0.0.1:8765`
+- a read-only browser viewer for the evidence in `.local/branch-demo`
+
+It does not deploy or publish the environment session. `--open` creates a short-lived local login link and opens the viewer. Press `Ctrl+C` in the terminal to stop the service.
+
+### What the demo means
+
+The example creates one original environment session with a shared counter. Alice and Bob each add `1` per turn:
+
+1. After three turns, the original session's shared total is `6`.
+2. The example saves a checkpoint and creates a separate branched session from it.
+3. A declared intervention changes only the branched session's starting total from `6` to `20`.
+4. Both sessions run for two more turns. The original finishes at `10`; the branch finishes at `24`.
+
+The totals are values in the synthetic environment's shared state. They are not the number of agents, scores of agent quality, or independent statistical results. The example exists to demonstrate state, lineage, intervention, and recorded evidence.
+
+### What the viewer shows
+
+The viewer is an evidence inspector, not a control panel:
+
+![EnvironmentHarness local evidence viewer showing original and branched environment sessions with a participant timeline](https://raw.githubusercontent.com/kimpton-ai/environment-harness/main/docs/assets/environment-session-viewer.png)
+
+1. The **Environment sessions** list lets you open the original or branched session. Check two boxes to compare them.
+2. **Timeline** groups evidence by state revision. Each participant row shows the observation delivered to that participant, the action it attempted, and the outcome the environment executed.
+3. **Scores and findings** shows reports submitted by your scorer. In this demo, `synthetic total` is just the final counter value.
+4. **Environment comparison** shows what the sessions share, the intervention applied to the branch, and their recorded results.
+
+The viewer never changes an environment session. Use the Python SDK or CLI for checkpoint, branch, resume, cancel, and execution operations.
+
+## Use your own agent
+
+Run the included external JSON program through the command-agent boundary:
+
+```sh
+uv run python examples/custom_agent.py --store .local/custom-agent
+uv run environment-harness --store .local/custom-agent serve --open
+```
+
+A Python agent implements `act(observation) -> dict`. An external program can instead read one JSON observation from stdin and write one JSON action to stdout. Your integration keeps ownership of prompts, model providers, tools, credentials, and spending limits.
+
+See [Connect an agent](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) for the complete contract and [custom_agent.py](https://github.com/kimpton-ai/environment-harness/blob/main/examples/custom_agent.py) for a working example.
+
+## Use the Python API
+
+```python
+from environment_harness import AgentSpec, EnvironmentSession, EvidenceStore, ExperimentSpec, Principal
+from environment_harness.fixtures import SyntheticAgent, SyntheticEnvironment
+from environment_harness.runner import run
+
+environment = SyntheticEnvironment()
+session = EnvironmentSession(EvidenceStore(".local/experiment"), environment)
+researcher = Principal(tenant="local", subject="researcher", role="researcher")
+experiment = ExperimentSpec(
+    environment=environment.spec,
+    participants=(
+        AgentSpec(id="alice", implementation="synthetic-agent@1", policy_version="1"),
+    ),
+)
+
+environment_session = session.create(experiment, researcher)
+run(
+    session,
+    environment_session["id"],
+    researcher,
+    {"alice": SyntheticAgent()},
+    turns=5,
+)
+```
+
+The local Python API is a trusted embedding interface. A local command subprocess is also not an operating-system security sandbox. Run hostile programs in an isolated backend with explicitly scoped network access.
+
+## Find the right guide
+
+| Goal | Guide |
+| --- | --- |
+| Connect a Python agent, model integration, or JSON program | [Agent integration](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AGENT-INTEGRATION.md) |
+| Implement and package environment rules | [Environment authoring](https://github.com/kimpton-ai/environment-harness/blob/main/docs/AUTHORING.md) |
+| Understand checkpoints, branches, and coordinated sessions | [Coordinated sessions](https://github.com/kimpton-ai/environment-harness/blob/main/docs/coordinated-sessions.md) |
+| Use the authenticated HTTP API | [Protocol](https://github.com/kimpton-ai/environment-harness/blob/main/docs/PROTOCOL.md) |
+| Use the TypeScript client | [TypeScript package](https://github.com/kimpton-ai/environment-harness/blob/main/packages/typescript/README.md) |
+| Check adapter and isolation boundaries | [Adapters](https://github.com/kimpton-ai/environment-harness/blob/main/docs/ADAPTERS.md) |
+| Check compatibility and release limits | [Compatibility](https://github.com/kimpton-ai/environment-harness/blob/main/docs/COMPATIBILITY.md) · [Release scope](https://github.com/kimpton-ai/environment-harness/blob/main/docs/STATUS.md) |
+
+## Project
+
+[Contributing](https://github.com/kimpton-ai/environment-harness/blob/main/CONTRIBUTING.md) · [Support](https://github.com/kimpton-ai/environment-harness/blob/main/SUPPORT.md) · [Security](https://github.com/kimpton-ai/environment-harness/blob/main/SECURITY.md) · [Changelog](https://github.com/kimpton-ai/environment-harness/blob/main/CHANGELOG.md) · [MIT license](https://github.com/kimpton-ai/environment-harness/blob/main/LICENSE)
+
+Report vulnerabilities privately through [SECURITY.md](https://github.com/kimpton-ai/environment-harness/blob/main/SECURITY.md). Do not put credentials or private environment sessions in a public issue.

environment_harness-0.2.3rc1/SECURITY.md

@@ -0,0 +1,47 @@
+# Security policy
+
+## Supported versions
+
+Only the latest immutable GitHub release is supported. The `main` branch is unreleased development. Older releases require upgrading unless a maintainer explicitly announces extended support.
+
+## Report a vulnerability privately
+
+Use [GitHub Private Vulnerability Reporting](https://github.com/kimpton-ai/environment-harness/security/advisories/new) as the primary reporting path. If that is unavailable, email support@kimpton.ai with the subject `EnvironmentHarness security`.
+
+Include:
+
+- the affected release or commit and the expected impact;
+- a minimal synthetic reproduction and relevant sanitized configuration;
+- the suspected attack path and affected security boundary; and
+- whether the issue or exploit has been disclosed elsewhere.
+
+Do not send live credentials, private trajectories, production environment stores, supplier code, deployment state, or an unnecessary working exploit.
+
+Maintainers aim to acknowledge a report within five business days. This is a target, not a contractual SLA or bug bounty. The security team will validate scope, identify affected versions, assign a primary owner, coordinate remediation and disclosure, publish an advisory, and credit the reporter if desired.
+
+Please wait for an agreed disclosure date. Fixes and exploit details remain private until patched artifacts and the advisory are ready. The advisory will identify affected and fixed versions, mitigations, CVE/GHSA identifiers when applicable, and any required credential rotation.
+
+## Security boundaries
+
+EnvironmentHarness enforces authenticated HTTP principals, tenant/environment/participant scope, generation checks, and evidence filtering. The researcher viewer is not an authorization boundary.
+
+The following remain trusted:
+
+- Python callers with local access to an `EnvironmentSession` or its store;
+- installed plugins and database owners; and
+- command subprocesses launched without a separate operating-system isolation boundary.
+
+Use an isolated backend for hostile programs. The deployer or private deployment repository owns production TLS, reverse proxies, cloud IAM, secrets, backups, logging, network policy, and request-rate controls. Keep private suppliers, marketplace logic, credentials, deployment state, production environment sessions, and recorded launches outside this public SDK.
+
+## Dependency and CI incidents
+
+Dependency releases are held for 168 hours before adoption, including security updates, unless an exact tracked exception is approved by a security CODEOWNER. Vulnerability and malware scanning and routine dependency alerts are immediate; they are distinct from private vulnerability reports. See [the dependency and supply-chain policy](docs/DEPENDENCY-SECURITY.md).
+
+If untrusted workflow code could access a credential or writable identity:
+
+1. Revoke the affected credentials first.
+2. Inspect at least 30 days of workflow runs and the complete commit ranges.
+3. Delete potentially poisoned caches and artifacts.
+4. Rotate every credential reachable by those jobs.
+
+Prefer job-scoped OIDC credentials lasting minutes. Exceptional static release credentials must expire within 24 hours.

environment_harness-0.2.3rc1/SUPPORT.md

@@ -0,0 +1,7 @@
+# Support
+
+Use [GitHub Discussions](https://github.com/kimpton-ai/environment-harness/discussions) for usage questions and [GitHub Issues](https://github.com/kimpton-ai/environment-harness/issues) for reproducible defects.
+
+Include the EnvironmentHarness version, operating system, Python/Node version, exact command, and a minimal synthetic reproduction. Do not attach credentials, private environment sessions, supplier code, deployment state, or recorded launches.
+
+Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

environment_harness-0.2.3rc1/contracts/Action.schema.json

@@ -0,0 +1,39 @@
+{
+  "$id": "urn:environment-harness:v1:Action",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "observation_id": {
+      "title": "Observation Id",
+      "type": "string"
+    },
+    "operation_id": {
+      "pattern": "^[a-zA-Z0-9_-]{1,128}$",
+      "title": "Operation Id",
+      "type": "string"
+    },
+    "participant": {
+      "title": "Participant",
+      "type": "string"
+    },
+    "payload": {
+      "additionalProperties": true,
+      "title": "Payload",
+      "type": "object"
+    },
+    "revision": {
+      "minimum": 0,
+      "title": "Revision",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "operation_id",
+    "participant",
+    "observation_id",
+    "revision",
+    "payload"
+  ],
+  "title": "Action",
+  "type": "object"
+}

environment_harness-0.2.3rc1/contracts/AgentSpec.schema.json

@@ -0,0 +1,39 @@
+{
+  "$id": "urn:environment-harness:v1:AgentSpec",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "checkpoint": {
+      "default": false,
+      "title": "Checkpoint",
+      "type": "boolean"
+    },
+    "config": {
+      "additionalProperties": true,
+      "title": "Config",
+      "type": "object"
+    },
+    "id": {
+      "pattern": "^[a-zA-Z0-9_-]{1,80}$",
+      "title": "Id",
+      "type": "string"
+    },
+    "implementation": {
+      "minLength": 1,
+      "title": "Implementation",
+      "type": "string"
+    },
+    "policy_version": {
+      "minLength": 1,
+      "title": "Policy Version",
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "implementation",
+    "policy_version"
+  ],
+  "title": "AgentSpec",
+  "type": "object"
+}