@kyleroche/relay 0.1.0 → 0.2.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Kyle Roche
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/dist/container/Dockerfile

@@ -0,0 +1,66 @@
+# relay worker image (docs/WORKERS.md, "Isolation"): everything `relay work` needs, in one Linux VM.
+#
+# `relay work --isolation container --install` builds this with Apple's `container` CLI and creates the container
+# `relay-work` from it, with a named volume at /home/relay. The vendor CLIs' logins, the site token, the clones and
+# the model's shell all live in that volume; the Mac's home directory is never mounted. Everything the image
+# installs goes under /usr/local, because the volume hides whatever the image put in /home/relay.
+#
+# Build arguments:
+#   RELAY_SPEC     what `npm install -g` gets for relay when the build context holds no tarball
+#                  (`@kyleroche/relay@<version>`); a checkout drops its `npm pack` tarball into the context instead
+#   FX_VERSION     fx release (`vX.Y.Z`); `latest` reads https://releases.fx.sh/latest.txt
+#   CLAUDE_SPEC    the Claude Code npm package spec
+FROM docker.io/library/node:24-bookworm-slim
+
+ARG RELAY_SPEC=@kyleroche/relay
+ARG FX_VERSION=latest
+ARG CLAUDE_SPEC=@anthropic-ai/claude-code
+ARG DEBIAN_FRONTEND=noninteractive
+
+# git, curl and CA certificates for the clone and the installers; bubblewrap, socat and ripgrep for Claude Code's own
+# sandbox around the lane's Bash (nested inside the VM: the container is created with the runtime masks off so a
+# user namespace can mount /proc); util-linux for `setpriv`; gh from GitHub's own apt repository.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl git gnupg procps util-linux bubblewrap socat ripgrep less \
+ && install -d -m 0755 /usr/share/keyrings \
+ && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# fx: the release tarball for this architecture, verified against the .sha256 the CDN publishes beside it.
+RUN set -eu; \
+    arch="$(uname -m)"; case "$arch" in aarch64|arm64) arch=aarch64;; x86_64|amd64) arch=x86_64;; *) echo "unsupported arch $arch" >&2; exit 1;; esac; \
+    v="$FX_VERSION"; if [ "$v" = latest ]; then v="$(curl -fsSL https://releases.fx.sh/latest.txt | tr -d '[:space:]')"; fi; \
+    cd /tmp; curl -fsSL "https://releases.fx.sh/$v/fx-linux-$arch.tar.gz" -o fx.tar.gz; \
+    curl -fsSL "https://releases.fx.sh/$v/fx-linux-$arch.tar.gz.sha256" -o fx.sha256; \
+    want="$(tr -d '[:space:]' < fx.sha256 | cut -c1-64)"; have="$(sha256sum fx.tar.gz | cut -c1-64)"; \
+    [ "$want" = "$have" ] || { echo "fx checksum mismatch: $want != $have" >&2; exit 1; }; \
+    tar -xzf fx.tar.gz; install -m 0755 fx /usr/local/bin/fx; rm -f fx fx.tar.gz fx.sha256; \
+    fx --version
+
+# pnpm through corepack (the Node image ships it), Claude Code (its postinstall puts the native binary in place, so
+# it is allowed by name), and relay: a tarball from the build context when a checkout built this image, the npm
+# package otherwise.
+COPY . /tmp/ctx/
+RUN set -eu; \
+    corepack enable && corepack prepare pnpm@latest --activate; \
+    npm install -g --no-fund --no-audit --allow-scripts=@anthropic-ai/claude-code "$CLAUDE_SPEC"; \
+    tgz="$(ls /tmp/ctx/*.tgz 2>/dev/null | head -n1 || true)"; \
+    if [ -n "$tgz" ]; then npm install -g --no-fund --no-audit "$tgz"; else npm install -g --no-fund --no-audit "$RELAY_SPEC"; fi; \
+    npm cache clean --force; rm -rf /tmp/ctx; \
+    claude --version; relay --version
+
+# The worker's user. The volume mounted at /home/relay arrives owned by root; relay-entry hands it over on first boot.
+RUN userdel -r node 2>/dev/null || true; \
+    groupadd -g 1000 relay && useradd -m -u 1000 -g 1000 -s /bin/bash relay
+COPY --chmod=0755 relay-entry /usr/local/bin/relay-entry
+
+ENV RELAY_HOME=/home/relay/.harness \
+    RELAY_ISOLATION=container \
+    HOME=/home/relay
+WORKDIR /home/relay
+ENTRYPOINT ["/usr/local/bin/relay-entry"]
+CMD ["relay", "work"]

package/dist/container/relay-entry

@@ -0,0 +1,31 @@
+#!/bin/sh
+# Entry point of the relay worker image. The container starts as root only to hand the volume at /home/relay to the
+# `relay` user (a fresh volume is an empty ext4 owned by root); then it drops to that user for whatever it was asked
+# to run: `relay work` by default, `bash` for `relay work container shell`, `relay setup --site` at install.
+#
+# Login callback forwarders: `container create --publish 127.0.0.1:<port>:<port>` delivers the Mac browser's redirect
+# to the container's eth0 address, but the login servers the CLIs start (`fx login codex` hands off to Codex's own
+# listener on 1455; fx's own callback is 3000) bind the container's loopback only, so the redirect would be dropped.
+# One socat per port listens on eth0 and forwards to 127.0.0.1, as the relay user, in the background; while no login
+# runs the forwarder just waits (a connection then fails, as it would have anyway). RELAY_LOGIN_PORTS lists the ports
+# (default: packages/core/src/work/container.ts LOGIN_CALLBACK_PORTS); empty turns the forwarders off.
+set -eu
+home=/home/relay
+uid="$(id -u relay)"
+gid="$(id -g relay)"
+if [ "$(stat -c %u "$home")" != "$uid" ]; then chown "$uid:$gid" "$home"; fi
+[ -d "$home/.harness" ] || install -d -o "$uid" -g "$gid" "$home/.harness"
+
+ports="${RELAY_LOGIN_PORTS-3000 1455}"
+if [ -n "$ports" ] && command -v socat >/dev/null 2>&1; then
+  # the image has no `ip`; hostname -I prints every address, the first is eth0's
+  addr="$(hostname -I 2>/dev/null | cut -d" " -f1)"
+  if [ -n "$addr" ]; then
+    for port in $ports; do
+      setpriv --reuid="$uid" --regid="$gid" --init-groups \
+        socat "TCP-LISTEN:$port,bind=$addr,reuseaddr,fork" "TCP:127.0.0.1:$port" >/dev/null 2>&1 &
+    done
+  fi
+fi
+
+exec setpriv --reuid="$uid" --regid="$gid" --init-groups env HOME="$home" USER=relay LOGNAME=relay "$@"

package/dist/hooks/statusline.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Claude Code status line (settings.json `statusLine.command`, installed by `relay setup`). Claude Code passes a JSON
+// document on stdin on every refresh; for claude.ai Pro/Max logins it carries `rate_limits.five_hour` and
+// `rate_limits.seven_day` as { used_percentage, resets_at } (unix seconds), the only documented source of the plan
+// meters the web app's header shows. This script:
+//   1. saves them to <RELAY_HOME>/meters/claude.json (atomic write, 0600; the directory 0700) when present;
+//   2. prints the status line: the command that was there before `relay setup` (recorded in
+//      <RELAY_HOME>/statusline.prev.json) is run with the same stdin and its output passed through, so a user's own
+//      status line keeps working; otherwise a compact default: `<model> · <cwd> · 5h 42% · 7d 44%`.
+// Nothing here can break a session: on any error it prints nothing and exits 0. Stays dependency-free and reads no
+// other file than those two, because it runs on every refresh.
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+const RELAY_HOME = process.env.RELAY_HOME ?? join(homedir(), ".harness");
+const METERS_DIR = join(RELAY_HOME, "meters");
+const PREV_PATH = join(RELAY_HOME, "statusline.prev.json");
+
+function main() {
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf8");
+  } catch {
+    return;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object") return;
+
+  const limits = payload.rate_limits;
+  let meters = null;
+  if (limits && typeof limits === "object") {
+    meters = { subscription: "max", five_hour: windowOf(limits.five_hour), seven_day: windowOf(limits.seven_day), captured_at: new Date().toISOString() };
+    try {
+      writeMeters(meters);
+    } catch {
+      /* a read-only home: the status line still prints */
+    }
+  }
+
+  const prev = previousCommand();
+  if (prev) {
+    const cwd = typeof payload.cwd === "string" && existsSync(payload.cwd) ? payload.cwd : undefined;
+    const r = spawnSync(prev, { shell: true, input: raw, encoding: "utf8", timeout: 5000, env: process.env, ...(cwd ? { cwd } : {}), stdio: ["pipe", "pipe", "ignore"] });
+    if (!r.error && typeof r.stdout === "string") process.stdout.write(r.stdout);
+    return;
+  }
+  const parts = [];
+  const model = payload.model && typeof payload.model.display_name === "string" ? payload.model.display_name : "";
+  if (model) parts.push(model);
+  const dir = (payload.workspace && typeof payload.workspace.current_dir === "string" && payload.workspace.current_dir) || (typeof payload.cwd === "string" ? payload.cwd : "");
+  if (dir) parts.push(basename(dir));
+  if (meters?.five_hour) parts.push(`5h ${meters.five_hour.used_percentage}%`);
+  if (meters?.seven_day) parts.push(`7d ${meters.seven_day.used_percentage}%`);
+  if (parts.length) process.stdout.write(parts.join(" · ") + "\n");
+}
+
+/** { used_percentage, resets_at } with the percentage clamped to 0..100, or null when the window is absent. */
+function windowOf(w) {
+  if (!w || typeof w !== "object" || typeof w.used_percentage !== "number" || !Number.isFinite(w.used_percentage)) return null;
+  const resets = typeof w.resets_at === "number" && Number.isFinite(w.resets_at) ? w.resets_at : null;
+  return { used_percentage: Math.max(0, Math.min(100, Math.round(w.used_percentage))), resets_at: resets };
+}
+
+/** Write <METERS_DIR>/claude.json: temp file beside it, 0600, then rename, so a reader never sees half a file. */
+function writeMeters(meters) {
+  mkdirSync(METERS_DIR, { recursive: true, mode: 0o700 });
+  const target = join(METERS_DIR, "claude.json");
+  const tmp = join(METERS_DIR, `.claude.${process.pid}.tmp`);
+  writeFileSync(tmp, JSON.stringify(meters) + "\n", { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, target);
+}
+
+/** The status-line command `relay setup` replaced, if it recorded one. */
+function previousCommand() {
+  if (!existsSync(PREV_PATH)) return undefined;
+  try {
+    const j = JSON.parse(readFileSync(PREV_PATH, "utf8"));
+    return j && typeof j.command === "string" && j.command.trim() ? j.command : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+try {
+  main();
+} catch {
+  /* never break the session */
+}
+process.exitCode = 0;

package/dist/migrations/008_queue_state.sql

@@ -0,0 +1,13 @@
+-- The doorbell (docs/WORKERS.md, "The loop"): one row whose version moves every time the queue may have changed
+-- (a task opened, a lease released or expired). An idle worker reads it instead of running a claim, and claims only
+-- when the version moved or something is queued, so an empty queue costs the site one cheap query per tick.
+CREATE TABLE IF NOT EXISTS queue_state (
+  one boolean PRIMARY KEY DEFAULT true CHECK (one),  -- exactly one row
+  version bigint NOT NULL DEFAULT 0,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+INSERT INTO queue_state (one, version) VALUES (true, 0) ON CONFLICT DO NOTHING;
+
+-- The poll interval a worker last reported with its heartbeat (ms), so the workers page and `relay work status`
+-- can show how often an idle worker checks in. Null until a worker on this version heartbeats.
+ALTER TABLE workers ADD COLUMN IF NOT EXISTS poll_ms integer;

package/dist/migrations/009_worker_meters.sql

@@ -0,0 +1,5 @@
+-- Plan meters a worker reports with its heartbeat (packages/core/src/meters.ts): the 5-hour and 7-day used
+-- percentages Claude Code hands its status line, saved by relay's status-line script under ~/.harness/meters and sent
+-- along as [{subscription, window, used_percentage, resets_at, captured_at, source}]. Null until a worker on this
+-- version heartbeats; the site shows the freshest reading per window across online and idle workers.
+ALTER TABLE workers ADD COLUMN IF NOT EXISTS meters jsonb;

package/dist/migrations/010_task_state.sql

@@ -0,0 +1,20 @@
+-- Materialized task state (docs/ARCHITECTURE.md, "A task's life"). The feed stays the source of truth: these columns
+-- are a cache of the fold in packages/core/src/db/tasks.ts (deriveTaskStatus) and tasks/station.ts (deriveStation),
+-- written by refreshTaskState (db/task-state.ts) after every write that can change a task (an event with the task's
+-- repo and issue, a claim taken, released or expired, a task created). The flow map and the tasks list read them in
+-- one query instead of folding every task's history on every poll. NULL state means "not computed yet": readers fold
+-- the row and fill it in (backfillTaskState runs once when this migration lands).
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS title text;                      -- the issue title, from the creator or the feed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS state text;                      -- queued | claimed | running | review | done | failed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS station text;                    -- Queue | Claimed | Running | PR | Preview | Review | Merged | Failed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS since timestamptz;               -- when the task entered `station`
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS pr integer;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS pr_url text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS preview_state text;              -- ready | building | failed | none
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS preview_url text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS runner text;                     -- runner:<name> of the worker on it
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS last_error text;                 -- the latest run.failed (or failing run.finished) line
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS cost double precision;           -- folded cost_equiv of the task's step.usage rows
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS state_updated_at timestamptz;    -- when the cache was last written
+CREATE INDEX IF NOT EXISTS tasks_state_idx ON tasks(state);
+CREATE INDEX IF NOT EXISTS tasks_station_idx ON tasks(station);