sys-buddy 1.2.0__tar.gz

sys_buddy-1.2.0/.dockerignore

@@ -0,0 +1,37 @@
+.git
+.github
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+*.egg-info
+.DS_Store
+
+# runtime db (mounted via volume, not baked into the image)
+*.db
+*.db-wal
+*.db-shm
+
+# dev/editor
+.vscode
+.idea
+.claude
+
+# docs & non-runtime project material
+sessions
+design
+reference
+CONTRIBUTING.md
+DOGFOOD.md
+DECISIONS.md
+KICKOFF.md
+SPEC.md
+v2.md
+
+# already produced by CI, not needed to build the image
+tests
+docker-compose.yml
+Dockerfile
+.dockerignore
+.env
+.env.example

sys_buddy-1.2.0/.env.example

@@ -0,0 +1,12 @@
+# Copy to .env and fill in for `docker compose up`. All are optional for local testing.
+
+# Public https origin (e.g. your tunnel) used to build pairing/invite links.
+# Required for a real "serve" deployment — remote mode enforces auth over it.
+SYS_BUDDY_PUBLIC_URL=
+
+# Agent-token lifetime in seconds. Defaults to no expiry, or 24h once
+# SYS_BUDDY_PUBLIC_URL is set.
+SYS_BUDDY_TOKEN_TTL=
+
+# Optional Slack webhook for broker notifications.
+SLACK_WEBHOOK_URL=

sys_buddy-1.2.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Code owners for sys-buddy.
+# Every pull request touching these paths requires review from an owner listed
+# here before it can be merged. The catch-all below makes @tooney92 the required
+# reviewer for ALL changes — combined with branch protection on `main`, nothing
+# reaches main without the owner's approval.
+* @tooney92

sys_buddy-1.2.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+<!-- Thanks for contributing to sys-buddy! Fill this in so the owner can review quickly. -->
+
+## What & why
+<!-- What does this PR change, and what problem does it solve? -->
+
+## How it was tested
+<!-- e.g. `uv run pytest -q` output; any manual/Playwright checks against the local broker -->
+- [ ] `uv run pytest -q` passes locally
+
+## Notes for the reviewer
+<!-- Anything the maintainer should look at closely, trade-offs, follow-ups. -->

sys_buddy-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+# Runs on every PR and on pushes to main. Making these checks *required* in branch
+# protection is what turns them from advisory into a merge gate — see the PR that adds
+# this file for the one-time settings step.
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Run the suite
+        run: uv run pytest -q
+
+  version-guard:
+    name: version not hand-edited
+    # Only on PRs, and skip release-please's own release PR — that one legitimately
+    # bumps the version. Everyone else must leave the version to the release pipeline.
+    if: github.event_name == 'pull_request' && !startsWith(github.head_ref, 'release-please')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Fail if the version was bumped by hand
+        run: |
+          base="origin/${{ github.base_ref }}"
+          if git diff "$base"...HEAD -- pyproject.toml | grep -qE '^\+[[:space:]]*version[[:space:]]*='; then
+            echo "::error::Don't bump the version in a PR — releases are automated (see CONTRIBUTING.md §8). Remove the pyproject.toml version change; the release bot sets it."
+            exit 1
+          fi
+          if git diff "$base"...HEAD -- src/sys_buddy/__init__.py | grep -qE '^\+.*__version__[[:space:]]*='; then
+            echo "::error::Don't set __version__ by hand — it derives from the package metadata."
+            exit 1
+          fi
+          echo "OK — no manual version edit."

sys_buddy-1.2.0/.github/workflows/pr-title.yml

@@ -0,0 +1,38 @@
+name: PR Title
+
+# We squash-merge, so the PR TITLE becomes the commit on main — and release-please
+# reads those commits to compute the version and changelog. This check refuses a PR
+# whose title isn't a valid Conventional Commit, so the release machinery never sees
+# a malformed message. See CONTRIBUTING.md §8 for the types.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint-title:
+    name: conventional PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Must match the type→bump table in CONTRIBUTING.md §8.
+          types: |
+            feat
+            fix
+            docs
+            chore
+            refactor
+            test
+            ci
+          # Subject after the "type:" — just require it to be non-empty and not
+          # Sentence-cased-into-a-Title, keeping titles terse and imperative.
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject after "type:" should start lower-case and be a short
+            imperative summary, e.g. "feat: add docker packaging".

sys_buddy-1.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,79 @@
+name: Release
+
+# One workflow, three jobs. release-please keeps a Release PR open, auto-versioned from
+# Conventional-Commit history; merging that PR cuts a GitHub release + tag. The publish
+# jobs run in the SAME workflow, gated on `release_created`, rather than in a separate
+# workflow triggered by the release event — a release created with the built-in
+# GITHUB_TOKEN does not trigger other workflows, so chaining here is what makes publish
+# actually fire.
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    name: release PR / tag
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # OIDC for PyPI Trusted Publishing — no stored token/secret
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No password: — Trusted Publishing authenticates via the OIDC token above.
+
+  publish-docker:
+    name: publish image to ghcr.io
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write   # push to ghcr.io — uses the built-in token, no account needed
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ needs.release-please.outputs.version }}
+            ghcr.io/${{ github.repository }}:latest

sys_buddy-1.2.0/.gitignore

@@ -0,0 +1,39 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Dependencies / build (add stack-specific entries as the project grows)
+node_modules/
+dist/
+build/
+
+# Claude Code — local per-user settings (approvals, allowlist). .mcp.json IS tracked.
+.claude/settings.local.json
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# sys-buddy runtime database
+*.db
+*.db-wal
+*.db-shm
+
+# Playwright MCP scratch output (screenshots/snapshots from browser-driven checks)
+.playwright-mcp/

sys_buddy-1.2.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.77"]
+    }
+  }
+}

sys_buddy-1.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.2.0"
+}

sys_buddy-1.2.0/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changelog
+
+All notable changes to **sys-buddy** are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project uses
+[Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH`:
+
+- **MAJOR** — incompatible changes to the tool/wire contract or agent-visible behavior.
+- **MINOR** — new, backwards-compatible capability.
+- **PATCH** — backwards-compatible fixes.
+
+Each release is also git-tagged `vX.Y.Z` and has a fuller note in `releases/vX.Y.Z.md`.
+
+## [1.2.0](https://github.com/tooney92/sys-buddy/compare/v1.1.1...v1.2.0) (2026-07-25)
+
+
+### Added
+
+* version awareness — /api/version, single-sourced version, GUI banner ([2506b8a](https://github.com/tooney92/sys-buddy/commit/2506b8a26a107061585600ac7a116d0ffd87f3b7))
+* version awareness (/api/version + GUI update banner) ([4e23c5b](https://github.com/tooney92/sys-buddy/commit/4e23c5b1eaa5b94cd5bab07414719e22368ffec9))
+
+## [Unreleased]
+
+### Added
+- **Version awareness in the desktop app.** A new unauthenticated `GET /api/version`
+  reports the version the broker process is actually *running*. The desktop app compares
+  three numbers — installed (on disk), running (from the endpoint), and, if the user opts
+  in, the latest published GitHub release — and shows a banner when they disagree: a
+  "restart needed" warning when the broker is serving older code than what's installed
+  (the drift that hid a migration in 1.1.0/1.1.1), or an "update available" note with the
+  release notes inline when GitHub has something newer. The GitHub check is strictly
+  opt-in — the app makes no external request unless the toggle is on.
+- **Version is single-sourced.** `sys_buddy.__version__` now derives from the installed
+  package metadata rather than a second hand-edited literal, so `pyproject.toml` is the
+  one place to bump it; a test fails the build if the two ever drift.
+- **Docker packaging.** A multi-stage root `Dockerfile` (built with `uv`) and
+  `docker-compose.yml` run the broker as a single container, non-root, with a persisted
+  `sys-buddy-data` volume for the SQLite DB. Defaults to `serve` (auth-enforced) — never
+  `local`, which is unauthenticated and must not be reachable off-box. A `Makefile`
+  wraps the common flows and `.env.example` documents the tunnel setup for remote use.
+
+### Backlog
+- Tracked in `v2.md` — stronger auth (mTLS / OAuth 2.1); image/screenshot attachments;
+  non-HTTP / `interface_type` contracts; auto-revoke on completion + reopenable tasks +
+  token timer; multi-process presence & wait-cap accounting.
+
+## [1.1.1] — 2026-07-24
+
+### Fixed
+- **Broker crashed on startup against a database created before 1.1.0.** The index on
+  `contracts(todo_id)` was declared in the schema block, which runs *before* the
+  migration that adds the column. On a fresh database the table is created with the
+  column so it worked; on an existing (pre-todos) database the `CREATE TABLE IF NOT
+  EXISTS` was a no-op and the index creation raised `no such column: todo_id`, aborting
+  boot. The index is now created after the migrations, once the column is guaranteed to
+  exist. Regression test added exercising an existing pre-todos database — the whole
+  test suite used fresh databases, which is why this shipped in 1.1.0.
+
+## [1.1.0] — 2026-07-24
+
+Todos: a task can carry several deliverables instead of exactly one. Additive — a task
+with no todos behaves and renders exactly as it did in 1.0.1.
+
+### Added
+- **Todos — several deliverables under one task.** Each todo has its own contract chain
+  and its own `proposed → locked → built → verified` march. Agent-proposed and
+  peer-accepted, with no human approval gate (the same authority `propose_contract`
+  already had). Proposing IS the creator's consent, so you cannot propose work that
+  binds only other people; accepting agrees on WHAT, while the contract on that todo is
+  a separate, later agreement about HOW. Declines are recorded as a list beside the
+  acceptances (with a reason) rather than a status a state machine would have to unwind;
+  `repropose_todo` issues a new version and resets every acceptance, so nobody is held
+  to a scope they did not read. Dropping is mutual — every named party consents — with
+  a host override via `sys-buddy todo drop`.
+- **Seats are not participants.** A todo reuses the task's existing seats and names
+  which of them it binds. A seat that is not a party can read the todo, but is not bound
+  by it, is not in its contract's quorum, and does not block it.
+- **Todos on the dashboard.** The stepper TRUNCATES to three nodes (`open`,
+  `pre-flight assessments`, `todos`) when a task has todos, the last carrying a progress
+  bar and the `⚠ N awaiting acceptance` count; the five later phases move INTO each todo
+  as a mini-stepper. The right column becomes the todo LIST, pending first with a `⚠`;
+  selecting a todo swaps the panel to that todo's own contract card. ONE message thread
+  for the task, with a `⟨todo⟩` chip marking which deliverable a message belongs to. The
+  task-list row gains the same rollup (`2/6 verified ⚠1`).
+- **Always-listening presence.** An agent parked in `wait_for_message` shows a live
+  pulsing dot and a `listening — 42m` streak on the dashboard. Stored as an EXPIRY, not
+  a boolean, so a broker that dies with agents parked cannot leave rows claiming to be
+  listening forever.
+- **`releases/` + `features/` write-ups.** `features/v1.1.0/` carries the release notes,
+  eight dashboard screenshots (light and dark), and `seed_demo.py`, which reproduces
+  every screen locally in three commands.
+
+### Changed
+- **A task's state is now DERIVED from its todos, not set by an agent.** Agents no
+  longer call `_transition` on a task that has todos. This is agent-visible behaviour,
+  and it is the reason todos was worth the cost: a rollup cannot disagree with its parts
+  the way an agent-set task state can drift from them. `verified` requires ALL live
+  todos; `stuck` is never derived, because one stuck deliverable must not freeze the
+  other five.
+- **Contract lock is pushed, not polled.** When a contract locks, the broker notifies
+  the roles that already signed instead of leaving them to poll.
+- **`staging_url` is collected at host setup**, with validation strictness keyed to the
+  task's connectivity and `localhost` permitted for same-machine tasks.
+- `messages.todo_id` is stored at post time; the dashboard's `⟨todo⟩` chip reads the
+  column rather than scraping "todo #N" out of prose, with the regex kept only as a
+  fallback for rows written before the column existed.
+- Decision D11 recorded: the dashboard never issues commands (read-only; it surfaces
+  state and tells the human what to type). The host's `[Drop todo]` affordance therefore
+  prints the CLI line to type instead of mutating anything.
+- `CONTRIBUTING.md` expanded into a full contributor guide — fork-and-PR walkthrough
+  (including how to recover an existing clone that can't push), environment setup with
+  `uv`, branch/commit conventions, the "tests green **and** proven live in the local
+  dashboard" definition of done, the changelog requirement, and the security invariants
+  a patch must not break (`local` mode is unauthenticated; peer content is DATA).
+- `README.md` now carries **Versioning and releases**, **Contributing**, and **License**
+  sections pointing at `CHANGELOG.md`, `CONTRIBUTING.md`, and `LICENSE`; the repo-layout
+  block lists the governance docs, and the stale test count is corrected.
+
+### Migration
+- None required. The `todos`, `todo_decisions` and `todo_drop_consents` tables and the
+  `contracts.todo_id` / `messages.todo_id` columns are added automatically on broker
+  start, `NULL` on every existing row.
+- **Restart any long-running broker.** A process started before this release keeps
+  serving its old code against an unmigrated database, so none of the above appears.
+
+## [1.0.1] — 2026-07-23
+
+### Fixed
+- **Dashboard thread ordering.** The message/event thread sorted by minute-precision
+  time, so items within the same minute — and message↔event interleaving — could
+  render out of creation order. The API (`_messages_for`, `_events_for`) now sends a
+  raw `created_at` timestamp per item, and the dashboard sorts by it (sub-second),
+  falling back to the old minute sort only if the API is stale — safe during a broker
+  restart, when `ui.html` (served from disk) can be newer than the running `api.py`.
+
+## [1.0.0] — 2026-07-23
+First tagged release — the sys-buddy broker for cross-human AI agent collaboration.
+
+### Added
+- **Broker over MCP (HTTP)** with two modes (local / remote); remote authenticates agents
+  by scoped bearer token, with `rotate_token` and single-use invites.
+- **Pairing & onboarding** — invite links, browser join page, and a pywebview **desktop app**
+  (host a task / join as a buddy / wire Claude).
+- **Pre-flight readiness** gate — agents must pass a short quiz (proving they read the Rules
+  of Engagement) before messaging or changing status.
+- **Rules of Engagement** — standing counter-instructions against prompt injection (peer
+  messages are DATA; the only fetchable URL is the signed `staging_url`).
+- **Messaging** — `send_message` (question / answer / status_update / contract_proposal),
+  directed or broadcast; `check_messages` / `wait_for_message` / `ack_messages`.
+- **Contract flow** — `propose_contract` / `lock_contract` / `get_contract` /
+  `reopen_negotiations`: versioned, mutually-locked, immutable-once-locked.
+- **Lifecycle** — `report_status` (ready / checked / blocked / verified / stuck; debug tasks
+  use resolved), with strikes.
+- **Read-only dashboard** with live updates over SSE.
+
+### Changed
+- **`get_contract` now returns the PROPOSED contract**, not only locked ones: it exposes the
+  proposed shape plus who has signed / who is awaiting, with the **`staging_url` withheld
+  until every role signs**. This removes the "sign-then-see" deadlock where an assessor was
+  told to review via `get_contract` but saw nothing until it locked — which it can't do
+  until they sign. The `staging_url` stays the single trusted, signed source (SSRF-guarded).
+
+[Unreleased]: https://github.com/tooney92/sys-buddy/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/tooney92/sys-buddy/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/tooney92/sys-buddy/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/tooney92/sys-buddy/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/tooney92/sys-buddy/releases/tag/v1.0.0

sys_buddy-1.2.0/CLAUDE.md

@@ -0,0 +1,37 @@
+# sys-buddy — working notes for Claude
+
+sys-buddy is an authenticated, contract-enforcing MCP broker that lets two developers'
+AI coding agents collaborate across the internet. **The broker enforces; agents request.**
+Source of truth: `SPEC.md`. Build brief: `KICKOFF.md`. Deviations/decisions: `DECISIONS.md`.
+
+## Stack
+- Python 3.11+, FastMCP (HTTP transport), SQLite (WAL). Env & deps via **`uv`**.
+- One process, three surfaces: `/mcp` (MCP tools) · `/pair` (pairing REST) · `/ui` + `/api/*` (read-only dashboard).
+- Dashboard is a single self-contained file at `src/sys_buddy/ui.html`, served at `/ui`.
+- Run the broker: `uv run sys-buddy local` (loopback `:8787`, no auth) or `uv run sys-buddy serve` (remote, auth enforced).
+- Tests: `uv run pytest -q`.
+
+## Local testing & deploy workflow (owner-directed)
+- **We test LOCALLY.** A `git push` / publish is NEVER a prerequisite for testing. E2E runs
+  against the **local** broker: `uv run sys-buddy local` on `:8787`, driving the dashboard at
+  `http://127.0.0.1:8787/ui` with **Playwright**. Backend behaviour is covered by `pytest`.
+- **Push/publish happens ONLY on the owner's explicit directive, and ONLY AFTER** local pytest +
+  Playwright are green — never to unblock a test.
+- The dashboard needs a viewer token. Mint one against the **local** db with
+  `uv run sys-buddy host-viewer`, then open `/ui?v=<token>`. Ask for seeds against the LOCAL db —
+  never "deploy + seed on a remote."
+- If a task needs data, **CREATE it via the real flow first** (`task create` → `propose_contract`
+  → `lock_contract` → `report_status`) rather than waiting on a seed.
+
+## Feature DONE
+= `pytest` green **AND** the change proven live in Playwright against the local dashboard.
+
+## "pwr" — prove it live
+When the owner says **"pwr"**, drive the just-finished change in a real browser via the Playwright
+MCP: boot a seeded local broker, navigate the dashboard, screenshot the relevant screens
+(list, task view, light + dark, mobile), and confirm it actually works before reporting done.
+
+## Playwright MCP
+Declared in `.mcp.json` (tracked) and auto-approved via `enabledMcpjsonServers` in
+`.claude/settings.local.json`. MCP tools bind at session start — a freshly added server needs a
+session restart to load.