chassis-harness 0.1.0__tar.gz

chassis_harness-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,61 @@
+name: Bug report
+description: Something behaves differently from what the documentation claims
+title: "[bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening this: `harness.diagnostics.status()`, `diagnostics.plugins()`, and
+        `diagnostics.explain("entry-id")` answer most "why is this not active" questions,
+        and [troubleshooting](https://github.com/andreolli-davide/chassis/blob/main/docs/troubleshooting.md)
+        lists the errors and their causes.
+
+        Security issue? Report it privately instead:
+        https://github.com/andreolli-davide/chassis/security/advisories/new
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I ran the same code against the latest release (`python -c "import chassis; print(chassis.__version__)"`)
+          required: true
+        - label: I searched the existing issues
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: Chassis version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and platform
+      placeholder: "3.12.10 on macOS 15.3 (arm64)"
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected
+      description: Include the exact error type and its structured `context` if there was one.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: A runnable script or the smallest test that shows it. `TestHarness` and the fakes in `chassis.testing` usually keep this short.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics output, if relevant
+      description: "`harness.diagnostics.status()`, `diagnostics.explain(...)`, or `diagnostics.generations()`."
+      render: text
+    validations:
+      required: false

chassis_harness-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question, or "how do I do X?"
+    url: https://github.com/andreolli-davide/chassis/discussions
+    about: Ask in Discussions. Bug reports and feature requests have their own forms.
+  - name: Documentation
+    url: https://github.com/andreolli-davide/chassis/blob/main/docs/README.md
+    about: Getting started, recipes, troubleshooting, and the design guarantees.
+  - name: Security issue
+    url: https://github.com/andreolli-davide/chassis/security/advisories/new
+    about: Report privately, never in a public issue.

chassis_harness-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: Feature request
+description: Suggest a capability, an integration, or a documentation gap
+title: "[feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Chassis deliberately does *not* do several things — graph execution, LangSmith
+        experiment management, sandboxing in-process plugins, deterministic replay of
+        external systems, Python hot reload. Please check
+        [design.md](https://github.com/andreolli-davide/chassis/blob/main/docs/design.md)
+        first: "deliberate absences" is a decision list, not a backlog.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem you have
+      description: Describe the situation in your application, not the API you want.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you tried, and what you would expect instead
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - lifecycle / scopes / generations
+        - capabilities / plugin authoring
+        - tools / policy / approval
+        - hooks / tasks
+        - budgets
+        - secrets
+        - LangGraph integration
+        - telemetry / observability
+        - configuration / reconciliation
+        - replay / evaluation
+        - documentation / examples
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you are doing today instead
+      description: A workaround tells us how expensive the gap really is.
+    validations:
+      required: false

chassis_harness-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What this changes
+
+<!-- One paragraph. What behaviour, invariant, or documentation is different after this? -->
+
+## Why
+
+<!-- The problem it solves. If it fixes a bug, what was the failure mode? -->
+
+## Checklist
+
+- [ ] `uv run ruff check .`, `uv run ruff format --check .`, `uv run pyright`, `uv run pytest` all pass
+- [ ] the change and its tests are in the same commit, and a plausible bug would fail them
+- [ ] every caller was migrated and what the change obsoletes is deleted (no shims, aliases, or dead options)
+- [ ] `docs/` and `CHANGELOG.md` updated if a public API, invariant, or limitation changed
+- [ ] no placeholder implementations, TODOs-as-functionality, or pinned-to-current-text tests
+
+## Notes for the reviewer
+
+<!-- Trade-offs you decided, alternatives you rejected, and anything you are unsure about. -->

chassis_harness-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: lint, type-check, test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync environment from the lockfile
+        run: uv sync --locked --all-extras --dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Pytest
+        run: uv run pytest
+
+  package:
+    name: build and install the wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Build
+        run: uv build
+
+      # The wheel must work on its own, in an environment that has never seen the
+      # source tree: `import chassis`, the version resolving from the distribution
+      # name, and a real LangGraph run.
+      - name: Install the wheel into a clean environment
+        run: |
+          uv venv .smoke
+          uv pip install --python .smoke/bin/python dist/*.whl
+
+      - name: Import the installed package
+        run: |
+          .smoke/bin/python - <<'PY'
+          import chassis
+          import chassis.langgraph
+          import chassis.testing
+
+          assert chassis.__version__ != "0.0.0", "version did not resolve from the distribution"
+          print("chassis", chassis.__version__)
+          PY
+
+      - name: Run the quickstart against the installed package
+        run: .smoke/bin/python examples/quickstart.py

chassis_harness-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+    paths: ["docs/**", "mkdocs.yml", "README.md", ".github/workflows/docs.yml"]
+  pull_request:
+    paths: ["docs/**", "mkdocs.yml", "README.md", ".github/workflows/docs.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build the site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      # Strict mode fails on a broken link or an unknown target, so the site cannot
+      # be published with dead ends in it. tests/test_docs_links.py covers the same
+      # ground against the source tree, where links out of docs/ are real files.
+      - name: Build (strict)
+        run: |
+          uv sync --locked --no-dev --group docs
+          uv run mkdocs build --strict
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload the site
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

chassis_harness-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and verify only, do not publish"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build and verify the distribution
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Sync environment from the lockfile
+        run: uv sync --locked --all-extras --dev
+
+      - name: Lint, type-check, and test
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pyright
+          uv run pytest
+
+      - name: Read the project version
+        id: version
+        run: |
+          version=$(uv run python -c "import pathlib, tomllib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "project version: $version"
+
+      # Publishing is irreversible, so the tag, the project version, and the
+      # changelog must agree before anything is built.
+      - name: The tag must match the project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$tag" != "${{ steps.version.outputs.version }}" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match pyproject version ${{ steps.version.outputs.version }}" >&2
+            exit 1
+          fi
+          echo "tag and project version agree: $tag"
+
+      - name: The changelog must document this version
+        run: |
+          key="## [${{ steps.version.outputs.version }}]"
+          if ! grep -qF "$key" CHANGELOG.md; then
+            echo "CHANGELOG.md has no '$key' section" >&2
+            exit 1
+          fi
+          echo "changelog documents ${{ steps.version.outputs.version }}"
+
+      - name: Build
+        run: uv build
+
+      # The artifact, not the source tree: install the wheel into an environment
+      # that has never seen this checkout and run a real agent with it.
+      - name: Verify the built wheel
+        run: |
+          uv venv .smoke
+          uv pip install --python .smoke/bin/python dist/*.whl
+          .smoke/bin/python - <<'PY'
+          import chassis
+
+          expected = "${{ steps.version.outputs.version }}"
+          assert chassis.__version__ == expected, f"{chassis.__version__} != {expected}"
+          print("installed chassis-harness", chassis.__version__)
+          PY
+          .smoke/bin/python examples/quickstart.py
+
+      - name: Upload the distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') && inputs.dry_run != true
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/chassis-harness
+    permissions:
+      contents: read
+      # Trusted publishing: PyPI verifies this workflow's identity, so no API
+      # token is stored anywhere.
+      id-token: write
+    steps:
+      - name: Download the distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

chassis_harness-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.smoke/
+site/
+
+# Environment
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local scratch
+.local/

chassis_harness-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to Chassis are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) with the pre-1.0 caveat
+that a minor release may break the documented surface.
+
+## [0.1.0] - 2026-09-16
+
+First release. The distribution is `chassis-harness`; the import package is
+`chassis`; Python 3.12+.
+
+### Added
+
+- Scoped ownership and reversible effects: every harness-managed effect belongs to
+  exactly one scope, and a failed plugin setup reverts everything that setup created.
+- Versioned capability contracts, provider registry, and immutable capability
+  snapshots.
+- Plugin manifests and author API: `provides`, `requires`, `optional`, permissions,
+  and a resource-oriented context (`ctx.tools`, `ctx.hooks`, `ctx.agents`,
+  `ctx.tasks`, `ctx.secrets`, `ctx.cleanup`).
+- Reactive dependency resolution with deterministic ordering, pending diagnosis,
+  and cycle detection.
+- Immutable runtime generations with atomic publication, leases, draining, and
+  reachability-gated physical disposal (logical unload is not destruction).
+- Scope-owned tool registry and the execution boundary: policy, approval, budget,
+  deadline, hooks, tracing, error normalization, and replay.
+- Scope-owned hook registry with deterministic ordering over every declared
+  boundary: tool execution, agent runs, plugin lifecycle, generation publication
+  and draining, and policy decisions.
+- Hierarchical budget governor: wall clock, tool calls, and child runs enforced at
+  harness boundaries; model calls, tokens, and estimated cost declared and reported,
+  with an explicit escape hatch for code that owns the model call.
+- Secret providers with mandatory redaction across logs, traces, snapshots,
+  diagnostics, replay records, and error strings.
+- LangGraph integration behind a minimal `AgentRuntime` protocol: agent definitions,
+  build-time-keyed graph caching, checkpointing, `Store`, streaming, and
+  interrupt/resume, with the run's immutable snapshot propagated through LangGraph's
+  public runtime context.
+- LangSmith telemetry and runtime snapshots: lifecycle spans and events, generation
+  metadata, canonical hashing, and redaction.
+- Declarative configuration: YAML or JSON desired state, a plugin catalog, drift
+  reporting, and reconciliation through the same path as programmatic composition.
+  A configuration can be passed to `Harness(...)` and is applied on start.
+- Bounded record/replay of tool and model boundaries, with snapshot, lifecycle, and
+  interrupt boundaries recorded as attribution.
+- Diagnostics that explain state from authoritative data: plugins, capabilities,
+  dependencies, generations, tools, hooks, agents, owned effects, desired state, and
+  `explain()` for why a plugin is (in)active.
+- `TestHarness` and deterministic fakes, plus four self-asserting examples and
+  concurrency tests for generation lifetime and shutdown races.
+
+### Known limitations
+
+- In-process Python plugins are trusted code; the policy engine is not a sandbox.
+- Replay does not virtualize clocks, randomness, networks, databases, or the
+  filesystem, and only tool and model boundaries are replayable.
+- Configuration changes are reconciled as replacements, not in-place
+  reconfiguration.
+- An abandoned `AgentRegistry.stream` generator holds its generation lease until it
+  is closed or collected.

chassis_harness-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for considering it. This project optimises for lifecycle correctness, resource
+ownership, and honest documentation — in that order — and the rules below are what
+keep those properties from eroding.
+
+## Set up
+
+```bash
+uv sync
+uv run pytest
+```
+
+[uv](https://docs.astral.sh/uv/) is the canonical project manager; `pyproject.toml`
+and `uv.lock` are the canonical dependency state. Please do not add a parallel
+`requirements.txt` or a second tool for the same job.
+
+## The gates
+
+Every pull request must leave these green. They are the same commands CI runs.
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright          # strict
+uv run pytest
+```
+
+Additional jobs run in CI and should be run if you touch what they cover:
+
+```bash
+uv build                                        # the wheel must build
+uv run mkdocs build --strict                    # if you touched docs/
+uvx --from actionlint-py actionlint .github/workflows/*.yml   # if you touched CI
+```
+
+## What a change should look like
+
+- **One coherent unit per commit**, conventional-commit style
+  (`feat(runtime): …`, `fix(lifecycle): …`, `docs: …`, `test: …`). A commit that mixes
+  a behavioural change with unrelated cleanup will be asked to split.
+- **The change and its tests travel together** when the tests define the same unit.
+- **No placeholder implementations.** A stub, a `TODO: implement`, or a fake fallback
+  presented as functionality is a defect, not a draft.
+- **Clean cutovers.** Migrate every caller and delete what the change obsoletes:
+  aliases, shims, re-exports, dead options. Do not leave a second way to do the same
+  thing beside the new one.
+- **Documentation is part of the change** when it introduces or alters a public API,
+  an invariant, or a limitation.
+
+## Tests worth writing
+
+A test earns its place if a plausible bug would fail it. Prefer behaviour, boundaries,
+invariants, transitions, and real errors over plumbing:
+
+- good: "a leased generation's provider is not disposed while the lease is held";
+- good: "a nested run cannot spend more than its parent has left";
+- not useful: asserting that a function was called, that a field was copied, or that
+  a value is non-empty.
+
+Concurrency claims need concurrency tests: real tasks and event barriers, not
+sequential calls to an async API (`tests/concurrency/` is the model to follow).
+
+Documentation has one test: every relative link in `README.md`, `CHANGELOG.md`, and
+`docs/` must resolve (`tests/test_docs_links.py`).
+
+## Documentation rules
+
+- `docs/` is the product documentation and is published with `mkdocs-material`
+  (`mkdocs.yml`). Cross-boundary links (examples, changelog) are absolute GitHub URLs,
+  because the site only serves `docs/`.
+- State limitations as plainly as capabilities. Chassis does not claim to be a
+  sandbox, does not claim deterministic replay of external systems, and does not claim
+  a budget dimension the harness cannot enforce. Keep it that way.
+- If a documented guarantee changes, update `docs/design.md` and the test that backs
+  it in the same commit.
+
+## Releasing
+
+Maintainers only. Record the change in `CHANGELOG.md` under a `## [x.y.z]` heading, set
+the same version in `pyproject.toml`, then tag `vX.Y.Z`. The release workflow refuses
+to publish unless the tag, the project version, and the changelog agree.
+
+## Conduct
+
+Be specific, be kind, assume good faith. Argue about mechanisms and evidence, not
+about people. Reviews here will name files, lines, and consequences; expect that and
+extend the same precision back.