relayrun 0.1.0

package/dist/cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { createRepo } from "./repo.js";
+import { startRunner } from "./runner.js";
+import { apiKeyHelperPath, keyHint, looksLikeApiKey, SESSION_KEY_ENV, verifyApiKey, } from "./sessionKey.js";
+const run = promisify(execFile);
+/**
+ * Where a published build points when given no `--server`/`--web`.
+ *
+ * These are the two values to change after deploying, and the only ones — the
+ * CLI is installed on other people's machines, so "it works if you also run the
+ * server locally" is not a default anyone else can use. Env vars override them
+ * so a contributor can point at a scratch deployment without editing source.
+ */
+const DEFAULT_SERVER = process.env.RELAY_SERVER ?? "https://relay-production-c9bd.up.railway.app";
+const DEFAULT_WEB = process.env.RELAY_WEB ?? "https://relay-web-green.vercel.app";
+const USAGE = `relayrun — run a Relay session against a repository on this machine
+
+  relayrun [options]
+
+  --repo <path>          Repository to work in (default: current directory)
+  --server <url>         Relay coordination server (default: ${DEFAULT_SERVER})
+  --web <url>            Web app, for the printed link (default: ${DEFAULT_WEB})
+  --mock                 Run the scripted offline agent instead of a real one.
+                         Costs nothing, but ignores what you type and replays
+                         a fixed script. For UI work, not for real answers.
+  --api-key <key>        Bill runs to this key instead of your Claude Code login
+  --session <id>         Reattach to an existing session (requires --token)
+  --token <token>        Runner token for --session
+  --github-repo <o/n>    Open a PR here on publish
+  --github-token <tok>   Token for --github-repo
+  -h, --help             Show this message
+`;
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--")) {
+            if (arg === "-h")
+                args.help = true;
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        // A flag is boolean unless the next token is a value rather than a flag.
+        if (next && !next.startsWith("--")) {
+            args[key] = next;
+            i++;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+function str(args, key) {
+    const v = args[key];
+    return typeof v === "string" ? v : undefined;
+}
+function wsUrlFor(serverUrl, sessionId) {
+    const url = new URL(serverUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("session", sessionId);
+    return url.toString();
+}
+/**
+ * The root of the repository containing `dir`.
+ *
+ * Resolved rather than used as given: `git rev-parse` succeeds from anywhere
+ * inside a repo, but `git clone` needs the root. Running the CLI from a
+ * subdirectory therefore passed the check and then failed at clone time — and
+ * a subdirectory is the normal case, since people run this from wherever they
+ * happen to be. Taking the root also means the session gets the whole
+ * repository, which is what someone naming their project means.
+ */
+async function repoRoot(dir) {
+    try {
+        const { stdout } = await run("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
+        return stdout.trim();
+    }
+    catch {
+        throw new Error(`not a git repository: ${dir}`);
+    }
+}
+/**
+ * Mints a session and the token that proves this process owns it.
+ *
+ * Retried: `pnpm dev` starts every package at once, so the server is routinely
+ * still binding its port when this runs.
+ */
+async function createSession(serverUrl) {
+    const attempts = 10;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const res = await fetch(new URL("/sessions", serverUrl), { method: "POST" });
+            if (!res.ok)
+                throw new Error(`server returned ${res.status}`);
+            return (await res.json());
+        }
+        catch (err) {
+            if (i === attempts - 1) {
+                throw new Error(`could not reach the Relay server at ${serverUrl} — is it running? (${err instanceof Error ? err.message : err})`);
+            }
+            await new Promise((r) => setTimeout(r, 1_000));
+        }
+    }
+    throw new Error("unreachable");
+}
+/**
+ * Resolves what the run will be billed to, before connecting — a key that turns
+ * out to be bad should fail here, not three minutes into someone's session.
+ */
+async function resolveCredentials(args) {
+    // Real is the default. The scripted agent ignores whatever you type and
+    // replays a fixed script, so getting it by accident means watching a
+    // convincing answer to a question you never asked. That failure is worse
+    // than the pennies an unwanted real run costs — ask for the mock by name.
+    if (args.mock)
+        return { mode: "mock", keySource: "mock", keyHint: null };
+    const key = str(args, "api-key") ?? process.env.RELAY_API_KEY;
+    if (!key) {
+        // No explicit key: the SDK uses whatever this machine is already logged in
+        // with, exactly as Claude Code does.
+        return { mode: "real", keySource: "oauth", keyHint: null };
+    }
+    if (!looksLikeApiKey(key)) {
+        throw new Error("that doesn't look like an Anthropic API key (expected sk-ant-…)");
+    }
+    const check = await verifyApiKey(key);
+    if (!check.ok)
+        throw new Error(check.error);
+    const helper = apiKeyHelperPath();
+    if (!helper) {
+        // Falling back to the operator's own login would bill the wrong account
+        // behind a UI saying otherwise — refuse instead.
+        throw new Error("could not create the API key helper, so --api-key can't be honoured");
+    }
+    process.env[SESSION_KEY_ENV] = key;
+    return { mode: "real", keySource: "api-key", keyHint: keyHint(key), apiKeyHelper: helper };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(USAGE);
+        return;
+    }
+    const serverUrl = str(args, "server") ?? DEFAULT_SERVER;
+    const webUrl = str(args, "web") ?? DEFAULT_WEB;
+    const sourcePath = await repoRoot(path.resolve(str(args, "repo") ?? process.cwd()));
+    const credentials = await resolveCredentials(args);
+    const existing = str(args, "session");
+    const existingToken = str(args, "token");
+    if (existing && !existingToken) {
+        throw new Error("--session also needs --token (printed when the session was created)");
+    }
+    const { id, runnerToken } = existing && existingToken
+        ? { id: existing, runnerToken: existingToken }
+        : await createSession(serverUrl);
+    const repo = createRepo({
+        sourcePath,
+        githubRepo: str(args, "github-repo") ?? process.env.RELAY_GITHUB_REPO ?? null,
+        githubToken: str(args, "github-token") ?? process.env.RELAY_GITHUB_TOKEN ?? null,
+    });
+    const billing = credentials.mode === "mock"
+        ? "SCRIPTED MOCK — ignores your instructions, answers are fake"
+        : credentials.keySource === "api-key"
+            ? `real agent — billed to the key ending ${credentials.keyHint}`
+            : "real agent — billed to this machine's Claude Code login";
+    console.log(`\n  repo     ${path.basename(sourcePath)}  (${sourcePath})`);
+    console.log(`  agent    ${billing}`);
+    console.log(`  session  ${id}`);
+    console.log(`\n  Share this link:\n    ${new URL(`/session/${id}`, webUrl)}\n`);
+    if (!existing) {
+        console.log(`  To reattach after a restart:\n    relayrun --session ${id} --token ${runnerToken}\n`);
+    }
+    startRunner({
+        wsUrl: wsUrlFor(serverUrl, id),
+        sessionId: id,
+        token: runnerToken,
+        repo,
+        mode: credentials.mode,
+        keySource: credentials.keySource,
+        keyHint: credentials.keyHint,
+        apiKeyHelper: credentials.apiKeyHelper,
+    });
+}
+main().catch((err) => {
+    console.error(`\n  ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+});

package/dist/emit.js

@@ -0,0 +1 @@
+export {};

package/dist/redact.js

@@ -0,0 +1,12 @@
+const KEY_LIKE = /sk-ant-[A-Za-z0-9_-]+/g;
+/**
+ * Scrubs anything key-shaped out of text bound for the server.
+ *
+ * A failed auth often echoes the key in its message, and anything emitted here
+ * lands in the transcript, every browser in the room, and Postgres. The server
+ * scrubs incoming text as well — this is the same guard at the other end of
+ * the socket, where the text is actually produced.
+ */
+export function redactKeys(text) {
+    return text.replace(KEY_LIKE, (m) => `sk-ant-…${m.slice(-4)}`);
+}

package/dist/repo.js

@@ -0,0 +1,224 @@
+import { execFile } from "node:child_process";
+import { mkdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+// Cap the patch shipped to browsers. A runaway agent that rewrites a lockfile
+// shouldn't push a multi-MB string down every participant's socket.
+const MAX_PATCH_BYTES = 400_000;
+function redactToken(s) {
+    return s.replace(/x-access-token:[^@]+@/g, "x-access-token:***@");
+}
+export function createRepo(config) {
+    // Scratch space under the OS temp dir, not inside the operator's repo — the
+    // clones are disposable and must never show up in their working tree.
+    const root = path.join(tmpdir(), "relayrun");
+    const pristineDir = path.join(root, "pristine");
+    const sessionsDir = path.join(root, "sessions");
+    let pristineReady = null;
+    /**
+     * Serializes git operations per working directory.
+     *
+     * `sessionChanges` and `publishSession` both run a sequence of raw git
+     * commands and both are reachable from more than one caller at once: two
+     * participants joining in the same second each trigger a changes request, and
+     * a publish can land while one is still in flight. Without this, concurrent
+     * `git add -A` calls collide on `.git/index.lock` — caught live against a
+     * two-participant session, where it surfaced as the request failing outright.
+     *
+     * A promise chain per directory rather than a mutex library: the only
+     * property needed is "the next operation waits for the last one."
+     */
+    const repoLocks = new Map();
+    function withRepoLock(dir, fn) {
+        const prior = repoLocks.get(dir) ?? Promise.resolve();
+        // Chained even through a rejection: one failed operation must not wedge
+        // every later caller on this directory.
+        const next = prior.catch(() => { }).then(fn);
+        repoLocks.set(dir, next.catch(() => { }));
+        return next;
+    }
+    // `git clone` copies committed state only — no node_modules, no .DS_Store,
+    // and deliberately none of the operator's uncommitted work.
+    async function ensurePristine() {
+        if (existsSync(pristineDir))
+            return;
+        await mkdir(path.dirname(pristineDir), { recursive: true });
+        await run("git", ["clone", config.sourcePath, pristineDir]);
+    }
+    function ensurePristineOnce() {
+        pristineReady ??= ensurePristine();
+        return pristineReady;
+    }
+    /**
+     * Everything the agent touched this session, relative to the clone's starting
+     * commit. Staging first is what makes new files (the common case) show up at
+     * all; `git diff` alone ignores untracked paths. The working dir is
+     * disposable, so leaving things staged costs nothing.
+     *
+     * Unlocked: publishSession calls this from inside its own lock, and the lock
+     * isn't reentrant.
+     */
+    async function computeSessionChanges(dir) {
+        await run("git", ["add", "-A"], { cwd: dir });
+        const { stdout: numstat } = await run("git", ["diff", "--cached", "--numstat"], {
+            cwd: dir,
+            maxBuffer: 32 * 1024 * 1024,
+        });
+        const files = [];
+        for (const line of numstat.split("\n")) {
+            if (!line.trim())
+                continue;
+            const [ins, del, ...rest] = line.split("\t");
+            files.push({
+                path: rest.join("\t"),
+                // Binary files report "-" rather than a count.
+                insertions: ins === "-" ? 0 : Number(ins) || 0,
+                deletions: del === "-" ? 0 : Number(del) || 0,
+            });
+        }
+        const { stdout: rawPatch } = await run("git", ["diff", "--cached"], {
+            cwd: dir,
+            maxBuffer: 32 * 1024 * 1024,
+        });
+        const patch = Buffer.byteLength(rawPatch) > MAX_PATCH_BYTES
+            ? `${rawPatch.slice(0, MAX_PATCH_BYTES)}\n\n… patch truncated — ${files.length} files changed in total.`
+            : rawPatch;
+        return {
+            files,
+            insertions: files.reduce((n, f) => n + f.insertions, 0),
+            deletions: files.reduce((n, f) => n + f.deletions, 0),
+            patch,
+        };
+    }
+    async function defaultBranch(repo, token) {
+        try {
+            const res = await fetch(`https://api.github.com/repos/${repo}`, {
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    accept: "application/vnd.github+json",
+                },
+            });
+            if (!res.ok)
+                return "main";
+            const json = (await res.json());
+            return json.default_branch ?? "main";
+        }
+        catch {
+            return "main";
+        }
+    }
+    async function doPublish(dir, sessionId, message) {
+        const branch = `relay/session-${sessionId}`;
+        try {
+            const changes = await computeSessionChanges(dir);
+            if (changes.files.length === 0) {
+                return { ok: false, error: "nothing to publish — no files changed" };
+            }
+            await run("git", ["checkout", "-B", branch], { cwd: dir });
+            // Identity is per-clone and disposable; without it `git commit` fails on
+            // machines with no global user.email configured.
+            await run("git", [
+                "-c",
+                "user.email=relay@localhost",
+                "-c",
+                "user.name=Relay",
+                "commit",
+                "-m",
+                message,
+            ], { cwd: dir });
+            // Land the branch in the operator's own repository, by path. The session
+            // clone is deleted when the room empties, so a commit that only exists
+            // there is gone within seconds of the run finishing. Pushing a branch
+            // whose name is unique per session never touches whatever they have
+            // checked out.
+            await run("git", ["push", "--force", config.sourcePath, `HEAD:${branch}`], {
+                cwd: dir,
+            });
+            const { githubRepo, githubToken } = config;
+            if (!githubRepo || !githubToken) {
+                return { ok: true, branch, pushed: false, prUrl: null };
+            }
+            // The token goes in the remote URL for one push and is never persisted to
+            // the clone's config, logged, or sent to a browser.
+            const remote = `https://x-access-token:${githubToken}@github.com/${githubRepo}.git`;
+            await run("git", ["push", "--force", remote, `HEAD:${branch}`], { cwd: dir });
+            const base = await defaultBranch(githubRepo, githubToken);
+            const res = await fetch(`https://api.github.com/repos/${githubRepo}/pulls`, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${githubToken}`,
+                    accept: "application/vnd.github+json",
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    title: message,
+                    head: branch,
+                    base,
+                    body: `Opened from a Relay session (\`${sessionId}\`).\n\n${changes.files.length} files changed, +${changes.insertions} −${changes.deletions}.`,
+                }),
+            });
+            if (!res.ok) {
+                // The branch is pushed either way — say so rather than implying the
+                // whole thing failed.
+                const detail = await res.text();
+                return {
+                    ok: true,
+                    branch,
+                    pushed: true,
+                    prUrl: null,
+                    note: `branch pushed; PR not created (${res.status}) ${redactToken(detail.slice(0, 140))}`,
+                };
+            }
+            const pr = (await res.json());
+            return { ok: true, branch, pushed: true, prUrl: pr.html_url ?? null };
+        }
+        catch (err) {
+            // Never echo the remote URL back — it carries the token.
+            const raw = err instanceof Error ? err.message : String(err);
+            return { ok: false, error: redactToken(raw) };
+        }
+    }
+    return {
+        /**
+         * Just the folder name, for the session header. A watcher needs to know
+         * which codebase they're watching; the operator's full directory layout is
+         * both noise and a needless disclosure.
+         */
+        repoName() {
+            return path.basename(config.sourcePath) || null;
+        },
+        /**
+         * A clone of the pristine copy, so a session can edit and commit freely
+         * without touching the pristine tree, let alone the operator's own.
+         */
+        async prepareWorkingDir(sessionId) {
+            await ensurePristineOnce();
+            const dir = path.join(sessionsDir, sessionId);
+            await rm(dir, { recursive: true, force: true });
+            await mkdir(sessionsDir, { recursive: true });
+            await run("git", ["clone", pristineDir, dir]);
+            return dir;
+        },
+        async disposeWorkingDir(sessionId) {
+            const dir = path.join(sessionsDir, sessionId);
+            await rm(dir, { recursive: true, force: true });
+            // Otherwise repoLocks accumulates one entry per session for the life of
+            // the process.
+            repoLocks.delete(dir);
+        },
+        sessionChanges(dir) {
+            return withRepoLock(dir, () => computeSessionChanges(dir));
+        },
+        /**
+         * Commit the session's work to a branch, push it to the operator's repo,
+         * and open a pull request if a GitHub repo and token are configured.
+         */
+        publishSession(dir, sessionId, message) {
+            // The whole sequence is one queued unit.
+            return withRepoLock(dir, () => doPublish(dir, sessionId, message));
+        },
+    };
+}

package/dist/runner.js

@@ -0,0 +1,201 @@
+import WebSocket from "ws";
+import { runRealAgent } from "./agent/run.js";
+import { runMockAgent } from "./agent/mock.js";
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 15_000;
+export function startRunner(opts) {
+    const { wsUrl, sessionId, token, repo, mode } = opts;
+    let socket = null;
+    let attempts = 0;
+    let workingDir = null;
+    let currentRun = null;
+    // Set when the server says the problem is permanent, so `close` stops
+    // rescheduling and the process can exit instead of spinning.
+    let giveUp = false;
+    function send(msg) {
+        if (socket?.readyState === WebSocket.OPEN)
+            socket.send(JSON.stringify(msg));
+    }
+    const emit = {
+        event: (kind, data) => send({ type: "runner_event", kind, data }),
+        status: (status) => send({ type: "runner_status", status }),
+        agentSession: (id) => send({ type: "runner_agent_session", agentSessionId: id }),
+    };
+    // Prepared on the first instruction rather than at startup: cloning for a
+    // session nobody ever drives is wasted work.
+    async function ensureWorkingDir() {
+        workingDir ??= await repo.prepareWorkingDir(sessionId);
+        return workingDir;
+    }
+    function fail(status, message) {
+        emit.event("agent_error", { message });
+        emit.status(status);
+    }
+    async function handleInstruction(text, resume) {
+        const abort = new AbortController();
+        currentRun = abort;
+        try {
+            const dir = await ensureWorkingDir();
+            if (mode === "mock") {
+                await runMockAgent({ emit, instruction: text, workingDir: dir, signal: abort.signal });
+            }
+            else {
+                await runRealAgent({
+                    emit,
+                    instruction: text,
+                    workingDir: dir,
+                    signal: abort.signal,
+                    resume,
+                    apiKeyHelper: opts.apiKeyHelper,
+                });
+            }
+        }
+        catch (err) {
+            fail("error", err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            if (currentRun === abort)
+                currentRun = null;
+        }
+    }
+    async function handleChangesRequest(requestId) {
+        // Nothing has run yet, so there is nothing to diff — an empty answer is
+        // correct here, not an error.
+        if (!workingDir) {
+            send({
+                type: "runner_changes",
+                requestId,
+                files: [],
+                insertions: 0,
+                deletions: 0,
+                patch: "",
+            });
+            return;
+        }
+        try {
+            const changes = await repo.sessionChanges(workingDir);
+            send({ type: "runner_changes", requestId, ...changes });
+        }
+        catch (err) {
+            console.error("could not read session changes:", err);
+            send({
+                type: "runner_changes",
+                requestId,
+                files: [],
+                insertions: 0,
+                deletions: 0,
+                patch: "",
+            });
+        }
+    }
+    async function handlePublish(title) {
+        if (!workingDir) {
+            send({
+                type: "runner_publish_result",
+                ok: false,
+                error: "this session hasn't run anything yet",
+            });
+            return;
+        }
+        try {
+            const result = await repo.publishSession(workingDir, sessionId, title);
+            send(result.ok
+                ? {
+                    type: "runner_publish_result",
+                    ok: true,
+                    branch: result.branch,
+                    pushed: result.pushed,
+                    prUrl: result.prUrl,
+                    note: result.note,
+                }
+                : { type: "runner_publish_result", ok: false, error: result.error });
+        }
+        catch (err) {
+            console.error("publish failed:", err);
+            send({ type: "runner_publish_result", ok: false, error: "publish failed" });
+        }
+    }
+    function handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        switch (msg.type) {
+            case "runner_ready":
+                // Only now is the socket genuinely attached. Resetting backoff on
+                // "open" instead would make a server that accepts and immediately
+                // rejects look like a healthy connection, and retry it every second
+                // forever.
+                attempts = 0;
+                console.log("connected — waiting for instructions");
+                break;
+            case "runner_rejected":
+                console.error(`\n  ${msg.reason}\n`);
+                if (msg.fatal) {
+                    // Retrying cannot change the answer, and a silent reconnect loop
+                    // against a dead session is worse than stopping: the terminal keeps
+                    // claiming to be connected while nothing works.
+                    giveUp = true;
+                    socket?.close();
+                    process.exitCode = 1;
+                }
+                break;
+            case "run_instruction":
+                void handleInstruction(msg.text, msg.resume);
+                break;
+            case "stop_run":
+                currentRun?.abort();
+                break;
+            case "request_runner_changes":
+                void handleChangesRequest(msg.requestId);
+                break;
+            case "run_publish":
+                void handlePublish(msg.title);
+                break;
+        }
+    }
+    function connect() {
+        const ws = new WebSocket(wsUrl);
+        socket = ws;
+        ws.on("open", () => {
+            send({
+                type: "runner_hello",
+                sessionId,
+                token,
+                repoName: repo.repoName(),
+                mode,
+                keySource: opts.keySource,
+                keyHint: opts.keyHint,
+            });
+        });
+        ws.on("message", (data) => handleMessage(data.toString()));
+        ws.on("error", (err) => {
+            console.error("connection error:", err instanceof Error ? err.message : err);
+        });
+        ws.on("close", () => {
+            if (socket === ws)
+                socket = null;
+            // An in-flight run can no longer report anything, so stop it rather than
+            // letting it spend time (or credit) with nowhere to send the result.
+            currentRun?.abort();
+            if (giveUp) {
+                void repo.disposeWorkingDir(sessionId).finally(() => process.exit(1));
+                return;
+            }
+            const delay = Math.min(RECONNECT_BASE_MS * 2 ** attempts, RECONNECT_MAX_MS);
+            attempts++;
+            console.log(`disconnected — retrying in ${Math.round(delay / 1000)}s`);
+            setTimeout(connect, delay);
+        });
+    }
+    const cleanup = () => {
+        currentRun?.abort();
+        void repo.disposeWorkingDir(sessionId).finally(() => process.exit(0));
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    connect();
+}