om-harness 1.0.0__tar.gz

om_harness-1.0.0/.env.example

@@ -0,0 +1,20 @@
+# om-harness provider API keys.
+# Copy this file to `.env` (or export the variables in your shell).
+# om-harness reads keys from the environment only; it never stores secrets
+# in its config file, sessions, checkpoints, or logs.
+#
+# Only the providers you intend to use need a key. Set none to run fully
+# offline with the built-in mock provider (`om-harness run --mock ...`).
+
+# OpenAI
+# OPENAI_API_KEY=sk-...
+
+# Anthropic
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# Google AI Studio (Gemini)
+# GOOGLE_API_KEY=...
+
+# Optional overrides (see docs/configuration.md)
+# OM_HARNESS_DEFAULT_MODEL=openai:gpt-4o-mini
+# OM_HARNESS_APPROVAL_POLICY=ask

om_harness-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    name: check (py${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy src
+
+      - name: Tests
+        run: uv run pytest --cov=om_harness --cov-fail-under=85

om_harness-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build & verify distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run checks
+        run: |
+          uv sync --frozen
+          uv run ruff format --check .
+          uv run ruff check .
+          uv run mypy src
+          uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test the wheel in a fresh venv
+        run: |
+          uv venv /tmp/smoke
+          VIRTUAL_ENV=/tmp/smoke uv pip install dist/*.whl
+          /tmp/smoke/bin/python -c "import om_harness; print(om_harness.__version__)"
+          /tmp/smoke/bin/om-harness --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing (preferred)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # Uses OIDC trusted publishing when configured on PyPI; otherwise set
+      # the API key in the pypi environment as the password variable.
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_KEY }}
+
+  github-release:
+    name: GitHub release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

om_harness-1.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# om-harness runtime state (sessions, checkpoints, events)
+.om-harness/
+
+# Local secrets / env
+.env
+.env.*
+!.env.example
+
+# Editors
+.idea/
+.vscode/
+
+# Local agent tooling state
+.mimosa/
+.zcode/

om_harness-1.0.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-07
+
+First stable release of the om-harness coding-agent harness.
+
+### Added
+
+- **Interactive shell** (`om-harness` / `chat`): one-input-box, always-on status
+  line (model · thinking · mode · context gauge), keybindings, slash commands
+  with autocomplete, and an arrow-key model selector.
+- **Live streaming**: agent thinking, tool calls, file-change diffs, and shell
+  command output render in real time during a turn.
+- **`/timeout` slash command** (and `/config set agent_timeout|tool_timeout
+  <seconds|off>`): show, set, or disable the whole-turn agent timeout and the
+  per-tool-call timeout. `off`/`0` → `None`, which `asyncio.timeout` and
+  `wait_for` treat as no timeout; changes apply live and persist to
+  `~/.om-harness/config/config.toml`.
+- **Skills**: instruction packs (`SKILL.md`) discovered from `~/.agents/skills`,
+  the repo's `.agents/skills`, config extra dirs, and installed plugins; loaded
+  on demand via a read-only `skill` tool.
+- **Plugins**: git-installable (`om-harness install`, `plugins`, `uninstall`)
+  into `~/.om-harness/plugins`, with provenance records and shallow updates.
+- **Orchestration**: plan-as-data strategies, topological wave scheduling with a
+  concurrency semaphore, retries with backoff, and per-task timeouts.
+- **Tool safety**: argv-list execution, shell-metacharacter rejection, hard
+  timeouts, output caps, scrubbed environment, and strict repo-root path
+  confinement (the `skill` tool is the sole documented exemption — name, not
+  path).
+- **Durable state**: SQLite-backed sessions, tasks, and checkpoints; JSONL
+  event log; crash-atomic writes; secret redaction at publish time.
+- **Web client**: reference HTML UI with SSE event streaming.
+- **Config**: TOML files (`om-harness.toml` / `pyproject.toml`), env-var
+  overrides, and `/config set` with immediate live application.
+
+### Fixed
+
+- **Live-stream freeze**: the REPL live pump drained the event bus by positional
+  offset into a 1000-event bounded deque; streaming token deltas (one per delta)
+  crossed that cap at ~4800 characters and froze the view while the agent kept
+  running. Events now carry a monotonic `seq` and consumers drain via
+  `bus.cursor` / `bus.since()`, which is immune to history eviction; history
+  window raised to 10,000.
+- **Bottom status bar disappearing during streaming**: it was a prompt
+  `bottom_toolbar`, which only exists while `prompt()` is active. A turn now runs
+  a minimal pinned app (toolbar-only layout, refreshed each second) under
+  `patch_stdout` so output scrolls above the bar; fails safely back to the
+  previous plain-await behavior on non-TTY or unsupported terminals.
+
+## [Unreleased]
+
+<!-- Add new entries here, above the latest release. -->

om_harness-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,189 @@
+# Contributing to om-harness
+
+Thanks for your interest! This guide gets you from clone to first merged
+PR. It also documents the practices the codebase follows so new code looks
+like old code.
+
+## Development setup
+
+Requirements: [uv](https://docs.astral.sh/uv/) and Python 3.11+ (any of
+3.11/3.12/3.13).
+
+```bash
+git clone https://github.com/omkumar01/om-harness
+cd om-harness
+uv sync                 # creates .venv and installs everything
+uv run om-harness --version
+uv run pytest           # the full suite runs offline — no API keys needed
+```
+
+With provider keys set (`OPENAI_API_KEY`, …) you can also run the live
+integration round-trips:
+
+```bash
+uv run pytest -m integration
+```
+
+## Quality gates
+
+All PRs must pass the same checks CI runs (Linux + Windows, Python 3.11 and
+3.13):
+
+```bash
+make check          # or: uv run python scripts/check.py
+```
+
+which runs, in order:
+
+1. `uv run ruff format --check .`
+2. `uv run ruff check .`
+3. `uv run mypy src`
+4. `uv run pytest --cov=om_harness --cov-fail-under=85`
+
+Auto-fix formatting/lint before committing:
+
+```bash
+make format         # ruff format + ruff check --fix
+```
+
+## Test-driven development
+
+This project is developed test-first. Before implementing a module or
+behavior, its contract is expressed as tests; implementation is the minimum
+that passes them, then refactoring. Practically:
+
+- tests live in `tests/unit/` (mirroring `src/om_harness/` layout),
+  `tests/e2e/` (complete flows in temp git repos), and
+  `tests/integration/` (live provider round-trips, deselected by default);
+- the default suite must stay **deterministic and offline** — provider
+  calls are scripted with PydanticAI `FunctionModel`/`TestModel`, which
+  exercise the real agent loop without network;
+- async race coverage uses sentinels + `asyncio.wait_for`, never real
+  sleeps.
+
+When fixing a bug: add the failing test that reproduces it first.
+
+## Architecture rules
+
+These are enforced in review (see [docs/architecture.md](docs/architecture.md)):
+
+- `models/` and `config/` are pure: no I/O, no imports from runtime layers.
+- Runtime services depend on each other through narrow protocols (e.g.
+  `Coordinator` depends on the `TaskExecutor` protocol, not `AgentRunner`).
+- Presentation (`cli/`, `ui/`) touches the runtime only via
+  `harness.Harness` and the event stream.
+- Provider SDK imports live only inside `providers/registry.make_model`.
+- Every user-visible runtime operation publishes a typed `Event`.
+
+## Common tasks
+
+### Add a tool
+
+1. Define the tool in `src/om_harness/tools/<area>.py`:
+
+```python
+class FormatCodeArgs(BaseModel):
+    path: str = Field(description="Repo-relative path")
+
+
+class FormatCode(BaseTool[FormatCodeArgs]):
+    name = "format_code"
+    description = "Run the repository formatter on one file."
+    permission = Permission.mutating
+    Args = FormatCodeArgs
+
+    async def run(self, args: FormatCodeArgs) -> ToolResult:
+        path = resolve_in_repo(self.ctx, args.path)
+        ...
+        return ToolResult(output=f"formatted {args.path}")
+```
+
+2. Register it in `tools/build_default_registry`.
+3. Add tests: happy path, permission gating (`read_only`/`mutating`/
+   `destructive`), error paths, path confinement.
+
+### Add a provider
+
+For OpenAI-compatible endpoints, **no code is needed** — users register
+them via `models.json` (see [docs/configuration.md](docs/configuration.md));
+the URL safety policy and key handling live in
+`src/om_harness/providers/models_json.py`.
+
+For non-OpenAI-compatible providers:
+
+1. Add a `ProviderSpec` to `PROVIDERS` in `src/om_harness/providers/base.py`
+   (prefix, env keys, default/strong models).
+2. Add a construction branch in `providers/registry.make_model`.
+3. Add a registry test (availability, parsing) and an integration test in
+   `tests/integration/` gated on the env key.
+
+### Add an orchestration strategy
+
+1. Extend `StrategyKind` and the planner heuristic.
+2. Prefer expressing the strategy as plan *shape* (tasks + dependencies);
+   only add coordinator behavior when the pattern truly isn't a DAG
+   property.
+3. Add deterministic scheduling tests (see the sentinel pattern in
+   `tests/unit/test_orchestration.py`).
+
+### Change a runtime contract
+
+Contracts live in `src/om_harness/models/`. They are versioned API for
+sessions/checkpoints on disk and event consumers, so:
+
+- keep changes additive where possible,
+- if serialization changes, bump `HarnessConfig.version` and note a
+  migration in the PR description.
+
+## Running the CLI locally
+
+```bash
+uv run om-harness init
+uv run om-harness run "summarize this repo" -v
+uv run om-harness chat
+# web reference client (needs the `web` extra):
+uv sync --extra web
+uv run python -m om_harness.ui.web.server
+```
+
+om-harness state lives in `.om-harness/` of whatever repository you're in —
+safe to delete at any time.
+
+## Releasing
+
+Releases publish to **both** PyPI and GitHub Releases automatically:
+
+1. Bump `version` in `pyproject.toml` and `__version__` in
+   `src/om_harness/__init__.py` (same value) in a PR.
+2. After it merges, tag the release and push the tag:
+   `git tag v0.2.0 && git push origin v0.2.0`.
+3. The `Release` workflow builds the wheel/sdist, runs all checks,
+   smoke-tests the wheel in a fresh venv, publishes to PyPI, and creates a
+   GitHub Release with the artifacts.
+
+Setup (maintainers, one-time):
+
+- Add a `PYPI_API_KEY` secret (or configure PyPI trusted publishing for the
+  `pypi` environment) — the workflow supports both.
+- PyPI project name: `om-harness`; the CLI command is also `om-harness`.
+
+Users can install either way:
+
+```bash
+uv tool install om-harness                                  # PyPI
+uv tool install git+https://github.com/omkumar01/om-harness  # GitHub
+```
+
+## Commit / PR conventions
+
+- Small, focused PRs with tests.
+- Conventional commit style is appreciated (`feat:`, `fix:`, `docs:`,
+  `refactor:`, `test:`, `chore:`).
+- The CI must be green before review.
+
+## Reporting issues
+
+Include: the command run, `om-harness doctor --json` output, the relevant
+`.om-harness/events/*.jsonl` excerpt (redacted automatically), and expected
+vs. actual behavior. **Never paste API keys** — om-harness redacts its own
+logs; check before you paste anything manually.

om_harness-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 om-harness contributors
+
+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.

om_harness-1.0.0/Makefile

@@ -0,0 +1,28 @@
+.PHONY: check format lint type tests coverage e2e clean
+
+# Full verification suite (same commands CI runs).
+check:
+	uv run python scripts/check.py
+
+format:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+lint:
+	uv run ruff format --check .
+	uv run ruff check .
+
+type:
+	uv run mypy src
+
+tests:
+	uv run pytest
+
+coverage:
+	uv run pytest --cov=om_harness --cov-report=term-missing
+
+e2e:
+	uv run pytest tests/e2e -v
+
+clean:
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov dist