backseat-harness 0.1.0__tar.gz

backseat_harness-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.whl
+
+# Virtual envs / tooling
+.venv/
+venv/
+.pyddock/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+# (uv.lock is intentionally committed)
+
+# Local tooling config (per-developer, not project artifacts)
+.kiro/
+.kilo/
+.opencode/
+.pyddock/
+
+# Throwaway live-run scratch workspace (disposable, not a project artifact)
+test_workspace/
+
+# Task workspace (operator/agent working notes; never committed)
+.backseat/
+
+# Personal planning notes (local only)
+TODO.md
+
+# OS / editor
+.DS_Store
+Thumbs.db
+# Playwright MCP browser artifacts (disposable snapshots/logs)
+.playwright-mcp/

backseat_harness-0.1.0/LICENSE

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

backseat_harness-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: backseat-harness
+Version: 0.1.0
+Summary: Meta-harness that drives an off-the-shelf CLI agent one small step at a time, with an adversarial operator reviewing each turn.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: chat-mother-forker>=0.2.1
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: psutil>=5.9
+Requires-Dist: ptyprocess; sys_platform != 'win32'
+Requires-Dist: python-multipart
+Requires-Dist: pywinpty>=2.0; sys_platform == 'win32'
+Requires-Dist: uvicorn[standard]
+Requires-Dist: websockets
+Description-Content-Type: text/markdown
+
+# backseat-harness
+
+Simple, single-task agent loops. _Buckle up, you're not at the wheel anymore._
+
+## What it does
+
+backseat-harness automates vibecoding toward a goal. You write the goal once, as the requirements for finishing a task. The harness drives an off-the-shelf CLI coding agent (opencode, claude, or kiro-cli) one small step at a time toward it. This is the "managed" agent session. After each step, a separate operator agent reviews the whole change, code, tests, and transcript, and writes the next prompt. That is the ordinary vibecoding loop (prompt, work, review, next prompt) that coding models are already trained to follow.
+
+The managed agent keeps the long-horizon context across the whole task, instead of passing lossy summaries between agents. The operator is a fresh, adversarial reviewer: it starts each review cold and reads the full diff itself, along with a transcript of the managed agent session. Rather than a fixed pipeline of stages, it is a continuous, unstructured adversary. Each managed turn is a plain session of the provider's own CLI, so you can intervene and `takeover` a lane and drive it yourself at any time.
+
+## Requirements
+
+- Python 3.11 or newer.
+- At least one provider CLI on your PATH, installed and signed in: `claude`, `kiro-cli`, or `opencode`. Each CLI uses its own login.
+- Managed runs are auto-approved, since a non-interactive run has nobody to answer a prompt.
+
+## Quick start
+
+The quick start sets up [Caddy](https://caddyserver.com) in front of the web interface (HTTPS + a login prompt).
+
+1. Install the tool:
+
+   ```bash
+   uv tool install backseat-harness
+   ```
+
+2. Install caddy and write the caddyfile (caddy is installed with `winget` if it is missing; on Windows this must run from an elevated, Administrator shell):
+
+   ```bash
+   backseat-harness setup-caddy   # installs caddy, opens the site port, writes ~/.backseat/caddyfile
+   ```
+
+   <!-- TODO: the Linux branch (apt/dnf/pacman + ufw/firewalld) and the LaunchAgent daemon install are untested -->
+
+3. Install and start the daemon (caddy is expected on `PATH`):
+
+   ```bash
+   backseat-harness daemon install
+   ```
+
+4. Open the local web page and sign in — `https://localhost:8443` (or the hostname you configured for Caddy).
+
+## Upgrading
+
+```bash
+uv tool upgrade backseat-harness
+backseat-harness daemon restart   # restart the daemon on the new version
+```
+
+## Web interface
+
+The main workflow, in brief:
+
+1. **Register a workspace** — add a folder (it gets a `.backseat/` marker) and open it.
+
+   ![backseat-harness web interface: sign-in and workspaces page](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-mainpage-example.png)
+
+2. **Start a chat** — from the workspace web UI (New chat), your IDE, or the CLI of your choice. Discuss a plan for your idea interactively with the agent.
+
+   ![Workspace page](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-workspace-example.png)
+
+3. **Generate a task from the chat** — the ✨ Task button distils the finished chat into task requirements (`goal.md`).
+
+   ![Generate a task from the chat](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-chat-generate-task.png)
+
+4. **The task completes autonomously** — the daemon runs it to the goal: managed agent step, operator review, next step.
+
+5. **Amend or takeover** — after a run, add a brief to guide/redirect it, or Takeover to drive the managed session yourself. On exit the task continues autonomously.
+
+   ![Task page: checklist, Run and Takeover](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-task-example.png)
+
+For simpler requests, skip the chat: **add a task directly** with a name and goal, and let it run (fire-and-forget).
+
+## Configuration
+
+Two optional files under `~/.backseat/`:
+
+**`config.toml`** — providers, models, timeouts, loop budgets, web port. Layered: `~/.backseat/config.toml`, then `.backseat/config.toml` in the workspace, then `.backseat/tasks/<slug>/config.toml`; higher layers win. See [`examples/.backseat/config.toml`](examples/.backseat/config.toml).
+
+**`caddyfile`** — when present, the web interface is served over HTTPS with a login prompt (`auto` mode). A minimal file:
+
+<!-- caddyfile-example:start -->
+```
+site.lan:8443 {
+	tls internal
+	basic_auth {
+		alice <bcrypt hash>
+	}
+	reverse_proxy 127.0.0.1:8090
+}
+```
+<!-- caddyfile-example:end -->
+
+Replace `<bcrypt hash>` with `caddy hash-password`; the `reverse_proxy` port must match `[web] port` (default 8090). `backseat-harness setup-caddy` writes this file for you. The web app itself listens on `127.0.0.1` only.
+
+Choose the serving mode with `--mode` on `web`, or `--web` on the daemon: `auto` (caddy when the caddyfile exists), `direct` (plain http only), `caddy` (caddyfile required), `none` (CLI only).
+
+## CLI
+
+Everything the web does is also a subcommand:
+
+```bash
+backseat-harness init <slug> [goal]        # scaffold a task lane
+backseat-harness run <slug> "goal"         # create and drive a task
+backseat-harness run <slug> "brief"        # resume with an instruction for this run
+backseat-harness takeover <slug>           # drive the managed session yourself, then resume
+backseat-harness generate-task <provider>:<conversation_id>   # task from a chat
+backseat-harness status <slug>
+backseat-harness list
+```
+
+The daemon runs ready lanes unattended, one at a time per workspace:
+
+```bash
+backseat-harness register-workspace /path/to/workspace
+backseat-harness daemon install            # register and start (Task Scheduler / systemd / LaunchAgent)
+backseat-harness daemon status|restart|stop
+backseat-harness daemon install --uninstall
+```
+
+Daemon output goes to `~/.backseat/daemon.log`; `daemon run --web` serves the web interface from the same process.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

backseat_harness-0.1.0/README.md

@@ -0,0 +1,133 @@
+# backseat-harness
+
+Simple, single-task agent loops. _Buckle up, you're not at the wheel anymore._
+
+## What it does
+
+backseat-harness automates vibecoding toward a goal. You write the goal once, as the requirements for finishing a task. The harness drives an off-the-shelf CLI coding agent (opencode, claude, or kiro-cli) one small step at a time toward it. This is the "managed" agent session. After each step, a separate operator agent reviews the whole change, code, tests, and transcript, and writes the next prompt. That is the ordinary vibecoding loop (prompt, work, review, next prompt) that coding models are already trained to follow.
+
+The managed agent keeps the long-horizon context across the whole task, instead of passing lossy summaries between agents. The operator is a fresh, adversarial reviewer: it starts each review cold and reads the full diff itself, along with a transcript of the managed agent session. Rather than a fixed pipeline of stages, it is a continuous, unstructured adversary. Each managed turn is a plain session of the provider's own CLI, so you can intervene and `takeover` a lane and drive it yourself at any time.
+
+## Requirements
+
+- Python 3.11 or newer.
+- At least one provider CLI on your PATH, installed and signed in: `claude`, `kiro-cli`, or `opencode`. Each CLI uses its own login.
+- Managed runs are auto-approved, since a non-interactive run has nobody to answer a prompt.
+
+## Quick start
+
+The quick start sets up [Caddy](https://caddyserver.com) in front of the web interface (HTTPS + a login prompt).
+
+1. Install the tool:
+
+   ```bash
+   uv tool install backseat-harness
+   ```
+
+2. Install caddy and write the caddyfile (caddy is installed with `winget` if it is missing; on Windows this must run from an elevated, Administrator shell):
+
+   ```bash
+   backseat-harness setup-caddy   # installs caddy, opens the site port, writes ~/.backseat/caddyfile
+   ```
+
+   <!-- TODO: the Linux branch (apt/dnf/pacman + ufw/firewalld) and the LaunchAgent daemon install are untested -->
+
+3. Install and start the daemon (caddy is expected on `PATH`):
+
+   ```bash
+   backseat-harness daemon install
+   ```
+
+4. Open the local web page and sign in — `https://localhost:8443` (or the hostname you configured for Caddy).
+
+## Upgrading
+
+```bash
+uv tool upgrade backseat-harness
+backseat-harness daemon restart   # restart the daemon on the new version
+```
+
+## Web interface
+
+The main workflow, in brief:
+
+1. **Register a workspace** — add a folder (it gets a `.backseat/` marker) and open it.
+
+   ![backseat-harness web interface: sign-in and workspaces page](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-mainpage-example.png)
+
+2. **Start a chat** — from the workspace web UI (New chat), your IDE, or the CLI of your choice. Discuss a plan for your idea interactively with the agent.
+
+   ![Workspace page](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-workspace-example.png)
+
+3. **Generate a task from the chat** — the ✨ Task button distils the finished chat into task requirements (`goal.md`).
+
+   ![Generate a task from the chat](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-chat-generate-task.png)
+
+4. **The task completes autonomously** — the daemon runs it to the goal: managed agent step, operator review, next step.
+
+5. **Amend or takeover** — after a run, add a brief to guide/redirect it, or Takeover to drive the managed session yourself. On exit the task continues autonomously.
+
+   ![Task page: checklist, Run and Takeover](https://raw.githubusercontent.com/portablestew/backseat-harness/main/docs/media/web-task-example.png)
+
+For simpler requests, skip the chat: **add a task directly** with a name and goal, and let it run (fire-and-forget).
+
+## Configuration
+
+Two optional files under `~/.backseat/`:
+
+**`config.toml`** — providers, models, timeouts, loop budgets, web port. Layered: `~/.backseat/config.toml`, then `.backseat/config.toml` in the workspace, then `.backseat/tasks/<slug>/config.toml`; higher layers win. See [`examples/.backseat/config.toml`](examples/.backseat/config.toml).
+
+**`caddyfile`** — when present, the web interface is served over HTTPS with a login prompt (`auto` mode). A minimal file:
+
+<!-- caddyfile-example:start -->
+```
+site.lan:8443 {
+	tls internal
+	basic_auth {
+		alice <bcrypt hash>
+	}
+	reverse_proxy 127.0.0.1:8090
+}
+```
+<!-- caddyfile-example:end -->
+
+Replace `<bcrypt hash>` with `caddy hash-password`; the `reverse_proxy` port must match `[web] port` (default 8090). `backseat-harness setup-caddy` writes this file for you. The web app itself listens on `127.0.0.1` only.
+
+Choose the serving mode with `--mode` on `web`, or `--web` on the daemon: `auto` (caddy when the caddyfile exists), `direct` (plain http only), `caddy` (caddyfile required), `none` (CLI only).
+
+## CLI
+
+Everything the web does is also a subcommand:
+
+```bash
+backseat-harness init <slug> [goal]        # scaffold a task lane
+backseat-harness run <slug> "goal"         # create and drive a task
+backseat-harness run <slug> "brief"        # resume with an instruction for this run
+backseat-harness takeover <slug>           # drive the managed session yourself, then resume
+backseat-harness generate-task <provider>:<conversation_id>   # task from a chat
+backseat-harness status <slug>
+backseat-harness list
+```
+
+The daemon runs ready lanes unattended, one at a time per workspace:
+
+```bash
+backseat-harness register-workspace /path/to/workspace
+backseat-harness daemon install            # register and start (Task Scheduler / systemd / LaunchAgent)
+backseat-harness daemon status|restart|stop
+backseat-harness daemon install --uninstall
+```
+
+Daemon output goes to `~/.backseat/daemon.log`; `daemon run --web` serves the web interface from the same process.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

backseat_harness-0.1.0/publish-to-pypi.ps1

@@ -0,0 +1,38 @@
+# publish-to-pypi.ps1 - Publish to PyPI: clean, build, upload to testpypi, then pypi.
+
+$ErrorActionPreference = "Stop"
+
+# Determine project name from the git repo root
+$repoRoot = git rev-parse --show-toplevel 2>$null
+if ($LASTEXITCODE -ne 0 -or -not $repoRoot) { throw "Not inside a git repository" }
+$ProjectName = Split-Path -Leaf $repoRoot
+Write-Host "Project name: $ProjectName"
+
+# Clean dist
+Write-Host "Cleaning dist/..."
+if (Test-Path dist) { Remove-Item -Recurse -Force dist }
+
+# Build
+Write-Host "> uv build"
+uv build
+if ($LASTEXITCODE -ne 0) { throw "Build failed" }
+
+# Upload to testpypi
+Write-Host "> uvx twine upload --repository testpypi dist/*"
+uvx twine upload --repository testpypi dist/*
+if ($LASTEXITCODE -ne 0) { throw "testpypi upload failed" }
+
+# Hint for testing
+Write-Host "`nTo test from testpypi:"
+Write-Host "  uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ $ProjectName"
+
+# Pause for confirmation
+$response = Read-Host "`nType 'y' to upload to pypi (anything else aborts)"
+if ($response -ne 'y') { Write-Host "Aborted."; exit 0 }
+
+# Upload to pypi
+Write-Host "> uvx twine upload --repository $ProjectName dist/*"
+uvx twine upload --repository $ProjectName dist/*
+if ($LASTEXITCODE -ne 0) { throw "pypi upload failed" }
+
+Write-Host "`nDone!"

backseat_harness-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "backseat-harness"
+description = "Meta-harness that drives an off-the-shelf CLI agent one small step at a time, with an adversarial operator reviewing each turn."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dynamic = ["version"]
+dependencies = [
+    # Chat history access: search/fork/checkpoint of managed sessions.
+    # Compaction-by-fork and operator review both depend on it, so it is core.
+    # 0.2.0 first shipped the public library API (fork_chat / find_chats /
+    # ChatRef.size_bytes); 0.2.1 adds the public load_chat that turn capture uses
+    # for a full, untruncated transcript.
+    "chat-mother-forker>=0.2.1",
+    # Pid liveliness for the process registry (~/.backseat/db.sqlite): a stored
+    # pid is only trustworthy alongside psutil's create_time() to catch pid
+    # reuse, which is what the task-row claim and orphan sweep check against.
+    "psutil>=5.9",
+    # Web interface (task web-interface §3 scaffold).
+    "fastapi",
+    "uvicorn[standard]",
+    "websockets",
+    "jinja2",
+    "httpx",
+    "python-multipart",
+    "pywinpty>=2.0; sys_platform=='win32'",
+    "ptyprocess; sys_platform!='win32'",
+]
+
+[project.scripts]
+backseat-harness = "backseat_harness.cli:main"
+
+# Version lives in exactly one place: src/backseat_harness/__init__.py (__version__).
+# Hatchling reads it from there for both `uv build` and PyPI publishing.
+[tool.hatch.version]
+path = "src/backseat_harness/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/backseat_harness"]
+
+# The sdist is for building the wheel, so it carries pyproject.toml, README,
+# LICENSE and src/ -- not the repo's dev tooling (trunk), agent config, caches,
+# or local harness state.
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.backseat",
+    "/.kilo",
+    "/.kiro",
+    "/.opencode",
+    "/.playwright-mcp",
+    "/.pyddock",
+    "/.pytest_cache",
+    "/.ruff_cache",
+    "/.trunk",
+    "/test_workspace",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

backseat_harness-0.1.0/src/backseat_harness/__init__.py

@@ -0,0 +1,35 @@
+"""backseat-harness: drive an off-the-shelf CLI agent one small step at a time.
+
+A meta-harness that spawns a managed CLI agent (Claude Code, opencode, kiro-cli),
+lets it take a single turn, then hands a fresh adversarial *operator* the
+transcript plus a durable checklist to review progress and decide the next prompt.
+
+__version__ is the single source of truth for the package version. pyproject.toml
+reads it from here (via tool.hatch.version), so this is the only place to edit
+before a release.
+"""
+
+__version__ = "0.1.0"
+
+from backseat_harness.models import (
+    Binding,
+    Generation,
+    LedgerEntry,
+    TaskResult,
+    TaskState,
+    TurnOutcome,
+    Verdict,
+    VerdictKind,
+)
+
+__all__ = [
+    "__version__",
+    "Binding",
+    "Generation",
+    "LedgerEntry",
+    "TaskResult",
+    "TaskState",
+    "TurnOutcome",
+    "Verdict",
+    "VerdictKind",
+]

backseat_harness-0.1.0/src/backseat_harness/capture.py

@@ -0,0 +1,38 @@
+"""Full-session transcript capture: a reviewable artifact of the managed work.
+
+After each managed turn the harness overwrites ``.backseat/tasks/<slug>/transcript.md``
+so the operator (and a human) can inspect what the agent actually did --
+including full, untruncated tool-call results, which the middle-truncated
+compaction fork deliberately drops.
+
+The transcript comes from chat-mother-forker's ``load_chat`` (via history.py):
+the *complete* session for this task's marker, already annotated with turn
+headers and ``TOOL_CALL``/``TOOL_RESULT`` labels. It is a single file rewritten
+each turn; because compaction forks each generation into a fresh session, the
+loaded session naturally tracks the current generation's work.
+
+The captured text is run through ``marker.redact`` before it is written, for the
+same reason the operator fork is: if the operator reads and quotes the file, an
+unredacted root UUID would make the operator's own stored session match the
+task's marker search -- and the newest match wins, pointing sizing and
+compaction at the operator instead of the managed agent. The generation ordinal
+stays visible.
+"""
+
+from __future__ import annotations
+
+from backseat_harness import history
+from backseat_harness import marker as marker_mod
+
+
+def capture(search: str, history_provider: str, root_uuid: str) -> str | None:
+    """Load the managed session's full transcript, redacted and ready to write.
+
+    Returns the string to write, or ``None`` when there is nothing to capture
+    yet (no matching session, or an empty one). Callers treat ``None`` as "skip
+    writing a file this turn".
+    """
+    transcript = history.load_full_transcript(search, history_provider)
+    if not transcript.strip():
+        return None
+    return marker_mod.redact(transcript, root_uuid)