relaydeck 0.1.0__tar.gz

relaydeck-0.1.0/.dockerignore

@@ -0,0 +1,16 @@
+# Keep the install-test build context lean — only the source tree matters
+# (uv builds the wheel from pyproject). Excluding the venv/git/scratch dirs
+# keeps the build fast and reproducible.
+.git
+.venv
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+.playwright-mcp
+node_modules
+*.png
+.claude
+dist
+build
+*.egg-info

relaydeck-0.1.0/.github/APPROVED_CONTRIBUTORS

@@ -0,0 +1,19 @@
+# GitHub handles approved to bypass the contribution auto-close gate.
+#
+# Format: <username> <capability>
+#   issue   their future ISSUES stay open
+#   pr      their future ISSUES *and* PRs stay open
+#
+# Repository collaborators (write / maintain / admin) are ALWAYS exempt and do
+# not need to be listed here — the gate checks collaborator permission first.
+#
+# Default maintainers (pre-approved for issues + PRs):
+relaydeck pr
+#
+# Maintainers grant access to others by replying on an issue:
+#   `lgtmi`  -> adds the issue author with capability `issue`
+#   `lgtm`   -> adds the issue author with capability `pr`
+# The approve-contributor workflow appends the entry below automatically.
+#
+# One entry per line, e.g.:
+#   octocat pr

relaydeck-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,67 @@
+name: Bug report
+description: Report something in relaydeck that's broken
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before you start:** read [CONTRIBUTING.md](https://github.com/relaydeck/relaydeck/blob/main/CONTRIBUTING.md).
+
+        New issues from first-time contributors are auto-closed by default. Maintainers review auto-closed issues and reopen the worthwhile ones. Issues that don't meet the quality bar in CONTRIBUTING.md may not be reopened or receive a reply.
+
+        Keep this short. If it doesn't fit on one screen, it's too long. Write in your own voice.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: Be specific. Include the exact error / log output if any.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps that trigger the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: relaydeck version
+      description: Output of `relaydeck --version` (e.g. 0.1.0).
+    validations:
+      required: false
+
+  - type: dropdown
+    id: harness
+    attributes:
+      label: Harness involved (if any)
+      options:
+        - "Not harness-specific"
+        - "pi / relaydeck-native"
+        - "Claude Code"
+        - "Codex CLI"
+        - "Cursor CLI"
+        - "OpenCode"
+        - "Antigravity"
+        - "Other"
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      description: e.g. macOS 15.4, Ubuntu 24.04.
+    validations:
+      required: false

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

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & ideas
+    url: https://github.com/relaydeck/relaydeck/discussions
+    about: Ask questions or float ideas in Discussions instead of opening an issue.
+  - name: Security report
+    url: https://github.com/relaydeck/relaydeck/security/advisories/new
+    about: Report a vulnerability privately (see SECURITY.md) — do not open a public issue.

relaydeck-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,46 @@
+name: Change / feature proposal
+description: Propose a change or feature (required for first-time contributors before opening a PR)
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before you start:** read [CONTRIBUTING.md](https://github.com/relaydeck/relaydeck/blob/main/CONTRIBUTING.md).
+
+        New issues from first-time contributors are auto-closed by default. Maintainers review auto-closed issues and reopen the worthwhile ones. Issues that don't meet the quality bar in CONTRIBUTING.md may not be reopened or receive a reply.
+
+        Open a proposal **before** sending a PR — PRs from contributors who haven't been approved with `lgtm` are auto-closed.
+
+        Keep this short. If it doesn't fit on one screen, it's too long. Write in your own voice.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What do you want to change?
+      description: Be specific and concise.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why?
+      description: What problem does this solve? Who is it for?
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How? (optional)
+      description: Brief technical approach if you have one in mind. Note if it's a plugin vs. a core change — relaydeck keeps its core minimal and pushes features into plugins.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: implement
+    attributes:
+      label: Implementation
+      options:
+        - label: I'd like to implement this myself if approved
+          required: false

relaydeck-0.1.0/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  # Keep GitHub Actions pinned-but-fresh. Security-relevant for the
+  # pull_request_target gate + the OIDC publish workflow. Grouped so all
+  # action bumps arrive as a single PR (one commit) rather than one per action.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "chore(actions)"
+    groups:
+      github-actions:
+        patterns: ["*"]
+
+  # Python dependencies declared in pyproject.toml. Grouped into one PR.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels: ["dependencies"]
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      python:
+        patterns: ["*"]

relaydeck-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,30 @@
+<!--
+  Before opening a PR, read CONTRIBUTING.md.
+
+  PRs from contributors who haven't been approved with `lgtm` on an issue are
+  auto-closed. Open a proposal issue first, get `lgtm`, then send the PR.
+
+  The one rule: you must understand your code. Using AI to write it is fine;
+  submitting code you can't explain is not.
+-->
+
+## What & why
+
+<!-- What does this change and why? Link the approved issue: Closes #NNN -->
+
+Closes #
+
+## How
+
+<!-- Brief technical summary. If this adds a capability, did you ship the web
+     affordance too? (The dashboard is the primary interface; the CLI is at
+     parity, not ahead.) -->
+
+## Checklist
+
+- [ ] I understand this code and can explain how it works.
+- [ ] I opened a proposal issue and a maintainer replied `lgtm`.
+- [ ] Tests added/updated; `uv run pytest -q -m "not e2e"` is green locally.
+- [ ] `uv run relaydeck plugin verify` passes (if plugins/manifests changed).
+- [ ] New CLI capability ships its web affordance in the same PR (parity).
+- [ ] I did **not** edit `CHANGELOG.md` (maintainers curate it) unless asked.

relaydeck-0.1.0/.github/workflows/approve-contributor.yml

@@ -0,0 +1,117 @@
+name: Approve Contributor
+
+# A maintainer comment of `lgtmi` (issues) or `lgtm` (issues + PRs) on an issue
+# adds that issue's author to .github/APPROVED_CONTRIBUTORS so the gates stop
+# auto-closing their submissions.
+#
+# Adapted, with thanks, from the pi project (earendil-works/pi).
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  approve:
+    if: ${{ !github.event.issue.pull_request }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Update contributor approval
+        id: update
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const fs = require('fs');
+            const APPROVED_FILE = '.github/APPROVED_CONTRIBUTORS';
+            const VALID_CAPABILITIES = new Set(['issue', 'pr']);
+            const issueAuthor = context.payload.issue.user.login;
+            const commenter = context.payload.comment.user.login;
+            const body = (context.payload.comment.body || '').trim();
+
+            let target;
+            if (/\blgtmi\b/i.test(body)) target = 'issue';
+            else if (/\blgtm\b/i.test(body)) target = 'pr';
+            else { core.setOutput('status', 'skipped'); return; }
+
+            try {
+              const { data } = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner, repo: context.repo.repo, username: commenter,
+              });
+              if (!['admin', 'maintain', 'write'].includes(data.permission)) {
+                console.log(`${commenter} lacks write access`);
+                core.setOutput('status', 'skipped'); return;
+              }
+            } catch {
+              core.setOutput('status', 'skipped'); return;
+            }
+
+            function parse(content) {
+              const entries = [];
+              const users = new Map();
+              for (const line of content.split('\n')) {
+                const t = line.trim();
+                if (!t || t.startsWith('#')) { entries.push({ type: 'other', line }); continue; }
+                const parts = t.split(/\s+/);
+                if (parts.length !== 2 || !VALID_CAPABILITIES.has(parts[1].toLowerCase())) {
+                  entries.push({ type: 'other', line }); continue;
+                }
+                const entry = { type: 'user', username: parts[0], normalizedUser: parts[0].toLowerCase(), capability: parts[1].toLowerCase() };
+                entries.push(entry);
+                users.set(entry.normalizedUser, entry);
+              }
+              return { entries, users };
+            }
+
+            function stringify(entries) {
+              const out = [...entries];
+              while (out.length && out[out.length - 1].type === 'other' && out[out.length - 1].line.trim() === '') out.pop();
+              return out.map(e => e.type === 'user' ? `${e.username} ${e.capability}` : e.line).join('\n') + '\n';
+            }
+
+            const { entries, users } = parse(fs.readFileSync(APPROVED_FILE, 'utf8'));
+            const existing = users.get(issueAuthor.toLowerCase());
+            const existingCap = existing?.capability ?? null;
+
+            if (existingCap === 'pr' || existingCap === target) {
+              core.setOutput('status', 'already'); core.setOutput('capability', existingCap); return;
+            }
+            if (existing) existing.capability = target;
+            else entries.push({ type: 'user', username: issueAuthor, normalizedUser: issueAuthor.toLowerCase(), capability: target });
+
+            fs.writeFileSync(APPROVED_FILE, stringify(entries));
+            core.setOutput('status', existingCap ? 'updated' : 'added');
+            core.setOutput('capability', target);
+
+      - name: Commit and push
+        if: steps.update.outputs.status == 'added' || steps.update.outputs.status == 'updated'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github/APPROVED_CONTRIBUTORS
+          git diff --staged --quiet || git commit -m "chore: approve contributor ${{ github.event.issue.user.login }}"
+          git push
+
+      - name: Comment on issue
+        if: steps.update.outputs.status != 'skipped'
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const author = context.payload.issue.user.login;
+            const cap = '${{ steps.update.outputs.capability }}';
+            const status = '${{ steps.update.outputs.status }}';
+            let body;
+            if (status === 'already') body = `@${author} is already approved.`;
+            else if (cap === 'issue') body = `@${author} approved for issues — your future issues won't be auto-closed. PRs still need \`lgtm\`.`;
+            else body = `@${author} approved for issues and PRs — welcome, and thanks for contributing.`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner, repo: context.repo.repo,
+              issue_number: context.issue.number, body,
+            });

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

@@ -0,0 +1,134 @@
+name: ci
+
+on:
+  # Gate runs before a PR merges. With rebase-only + required status checks,
+  # this covers main without also double-running on every push to it.
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# Cancel any superseded run for the same ref so a fast follow-up
+# push doesn't pile a long queue.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest + plugin verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          # Cache uv's wheel cache so subsequent runs avoid the cold
+          # download of fastapi/uvicorn/torch-adjacent deps.
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install project + dev deps
+        run: uv sync --frozen
+
+      - name: Run test suite
+        # Single source of truth. Auth tests, durability tests, and
+        # the usage-limits showcase plugin all live in tests/.
+        # Excludes `e2e`: those need a real harness binary + LLM API
+        # key and run in the dedicated `e2e` workflow.
+        run: uv run pytest -q -m "not e2e"
+
+      - name: Verify plugin manifests + lockfile
+        # `relaydeck plugin verify` parses every plugin.toml and writes the
+        # plugins.lock baseline. CI runs it as a smoke check — if the
+        # set of manifest-backed plugins diverges from what the loader
+        # accepts, this command exits non-zero before downstream tests
+        # have a chance to mask the regression.
+        run: uv run relaydeck plugin verify
+
+      - name: Daemon smoke test
+        # Boot the daemon, hit /healthz (public), hit /api/agents with
+        # the on-disk token (authenticated), then tear down. Catches
+        # regressions in the auth middleware, the token bootstrap, and
+        # the basic API wiring even when unit tests still pass.
+        run: |
+          set -euo pipefail
+          export RELAYDECK_CONFIG_HOME=$RUNNER_TEMP/relaydeck-cfg
+          mkdir -p "$RELAYDECK_CONFIG_HOME"
+          uv run relaydeck serve --port 8765 &
+          DAEMON_PID=$!
+          # Wait up to 15s for /healthz to come up.
+          for i in $(seq 1 30); do
+            if curl -sf http://127.0.0.1:8765/healthz >/dev/null; then
+              break
+            fi
+            sleep 0.5
+          done
+          curl -sf http://127.0.0.1:8765/healthz
+          # An unauthenticated /api/agents must 401.
+          code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8765/api/agents)
+          [ "$code" = "401" ] || { echo "expected 401 without token, got $code"; exit 1; }
+          # With the token, it must 200.
+          TOKEN=$(cat "$HOME/.relaydeck/auth-token")
+          curl -sf -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/api/agents >/dev/null
+          kill $DAEMON_PID
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dev deps
+        # Use the project's locked ruff (in dev deps) so CI and local
+        # runs see the same version. `uv sync` includes dev by default.
+        run: uv sync --frozen
+
+      - name: Ruff check (soft)
+        # CI lints with `--exit-zero` for now: the codebase has known
+        # style debt unrelated to the platform foundation work, and we
+        # don't want green-tests-but-red-CI noise. Once the catalog is
+        # cleaned up, drop --exit-zero and treat lint as a gate.
+        run: uv run ruff check relaydeck tests --exit-zero
+
+  build:
+    name: build (sdist + wheel)
+    runs-on: ubuntu-latest
+    timeout-minutes: 6
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist + wheel
+        # Pre-release insurance: catches packaging regressions (missing package
+        # data, bad metadata, a wheel that doesn't include plugins/) on every PR
+        # instead of at `release.yml` publish time.
+        run: uv build
+
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*

relaydeck-0.1.0/.github/workflows/docker-fast.yml

@@ -0,0 +1,59 @@
+name: docker-fast
+
+# PR fast lane for Docker-based bucket tests. Phase 1 runs B1 (zero) only;
+# Phase 2 adds B2 (pi-only). Both buckets in parallel, ≤10 min budget.
+#
+# Supersedes the previous install.yml workflow (which only built the slim
+# install image and ran scripts/install-smoke.sh). B1 covers everything
+# install.yml did plus the doctor-honesty and degradation assertions.
+#
+# Nightly full-matrix coverage (B3 onward) lands in a separate docker-full
+# workflow in Phase 4.
+
+on:
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  bucket:
+    name: docker / B${{ matrix.bucket }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        # Phase 1: B1 (zero) only. Phase 2 appends:
+        #   - { bucket: 2, name: pi-only, image: pi, dockerfile: Dockerfile.pi }
+        include:
+          - bucket: 1
+            name: zero
+            image: base
+            dockerfile: Dockerfile.base
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build relaydeck-test:${{ matrix.image }}
+        run: |
+          docker build \
+            -f tests/docker/${{ matrix.dockerfile }} \
+            -t relaydeck-test:${{ matrix.image }} \
+            .
+
+      - name: Run docker tests (B${{ matrix.bucket }} / ${{ matrix.name }})
+        run: |
+          docker run --rm \
+            -e RELAYDECK_TEST_BUCKET=${{ matrix.name }} \
+            relaydeck-test:${{ matrix.image }} \
+            pytest -m docker --confcutdir=/src/tests/docker -c /src/pyproject.toml -o addopts= -p no:cacheprovider /src/tests/docker/ -v --junitxml=/tmp/junit.xml || RC=$?
+          exit ${RC:-0}
+
+      # If pytest fails, the JUnit XML and the daemon log are useful artifacts
+      # for diagnosis. Docker doesn't preserve files after `--rm` finishes,
+      # so the test must have written them to a host-mounted volume; Phase 1
+      # keeps the simple path and re-runs locally with `make test-docker` for
+      # failure triage. Phase 2 wires a proper /tmp/junit mount + upload-artifact.

relaydeck-0.1.0/.github/workflows/e2e.yml

@@ -0,0 +1,77 @@
+name: e2e
+
+# Runs the `e2e` pytest marker against real harness binaries + a real
+# LLM endpoint. Kept in a dedicated workflow so the fast unit-test CI
+# stays free of API latency + cost.
+#
+# Triggers:
+#   - pull_request to main: end-to-end smoke gate before merge
+#   - workflow_dispatch: manual re-run when investigating a regression
+#
+# Cost ceiling: the smoke test issues a single short prompt to the
+# cheapest free-tier model on OpenRouter. Concurrency cancels stacked
+# runs so a fast follow-up push doesn't queue. Job timeout is 5 min.
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pi-smoke:
+    name: pytest -m e2e (pi)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Skip silently when the secret is missing -- e.g. on a fork PR or
+    # a workflow_dispatch run from a contributor without org access.
+    # The job appears as 'skipped' in the UI rather than 'failed'.
+    # Gated on the org owner so it runs on the canonical repo and still
+    # skips on forks (which won't have the OPENROUTER_API_KEY secret).
+    if: ${{ github.event_name == 'workflow_dispatch' || github.repository_owner == 'relaydeck' }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install project + dev deps
+        run: uv sync --frozen
+
+      - name: Install pi (npm)
+        # @mariozechner/pi-coding-agent installs the `pi` binary into
+        # the npm-global bin dir. Pinning to a specific version would
+        # make the test reproducible -- left floating for now so we
+        # notice when upstream changes the CLI surface.
+        run: |
+          npm install -g @mariozechner/pi-coding-agent
+          pi --help | head -3
+
+      - name: Run E2E suite
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          # Pi reads the API key from this env var by default when
+          # `--provider openrouter` is set.
+          # Model slug is read from the repo-level Actions variable
+          # `RELAYDECK_E2E_MODEL` so it can be swapped without code changes
+          # (Settings -> Secrets and variables -> Actions -> Variables).
+          # Fallback covers the case where the variable hasn't been set
+          # yet -- pick something currently reachable on openrouter.
+          RELAYDECK_E2E_MODEL: ${{ vars.RELAYDECK_E2E_MODEL || 'openai/gpt-4o-mini' }}
+          RELAYDECK_E2E_HEADLESS: "1"
+        run: |
+          if [ -z "${OPENROUTER_API_KEY:-}" ]; then
+            echo "::warning::OPENROUTER_API_KEY not set; skipping e2e suite"
+            exit 0
+          fi
+          uv run pytest -v -m e2e --tb=short