pair-mcp 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# Pair
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+_"Walk me through how our caching works across regions"_
+
+_"Why are there two User models?"_
+
+_"Let's really dig into how thumbprint extraction works"_
+
+Pair is an MCP that allows agents to walk you through code the way a human would - by scrolling and highlighting in the codebase as they explain answers to your questions. 
+
+The agent controls the cursor and can navigate the file explorer and code editor as it narrates. 
+Interrupt any time to divert the conversation, then return to the original answer with a click. 
+
+>[!WARNING]
+> Make sure you allow sound or this video won't make any sense! 
+
+https://github.com/user-attachments/assets/d4865547-c69d-45f3-8a83-efeb903307b4
+
+>[!NOTE]
+> Some notes on the video above:
+> - the cursor, highlights, and scrolling are the agent, not the user (they are the navigator)
+> - the narration stops when you start typing a question (I interrupt to ask about envars)
+> - clicking the "go back to X" button interrupts and returns to the original narration 
+
+
+Uses your agent harness and then either browser native voice or (optionally) Kokoro as a really good local voice model. 
+
+The first time you select Kokoro expect a delay (5-10 min on most connections) while it initially downloads the model. Future use will be near-instant.
+
+## Installation
+Requires Node.js ≥ 22.12. The installer is written for macOS (elsewhere it warns and carries on).
+
+```
+npm install -g pair-mcp
+pair install                       # or: pair install claude | codex | opencode
+```
+
+To update, run `npm install -g pair-mcp` again. Harness configs point at the global install, so there's nothing to re-run (`npx` won't work for this, since its cache can be cleared).
+
+Or from source:
+
+```
+git clone https://github.com/pirate-baby/pair.git
+cd pair && ./install.sh            # or ./install.sh claude | codex | opencode
+```
+
+Either way, Pair is installed into each of Claude Code, Codex, and opencode that's on your PATH (missing ones are skipped):
+- **Claude Code:** registers the `pair` MCP server (user scope) and sets `MCP_TOOL_TIMEOUT` in `~/.claude/settings.json`, if not already set, so long walkthroughs don't time out
+- **Codex:** adds `[mcp_servers.pair]` to `~/.codex/config.toml`
+- **opencode:** adds `mcp.pair` to `~/.config/opencode/opencode.json(c)`
+- symlinks the `code-walkthrough` skill into each harness's skills directory
+
+Each config file is copied to `<file>.pair-backup` before its first edit. Re-running is safe, and (from source) is how you update after a `git pull`.
+
+While a session is running, Pair serves its UI on `http://localhost:7420` (bound to 127.0.0.1 only). Kokoro is opt-in: the first time you pick it, Pair installs `kokoro-js` into `~/.cache/pair/kokoro` and downloads the ~330 MB model from Hugging Face.
+
+## Usage
+In your harness of choice, tell the agent to walk you through or explain some part of your repo. Pair takes it from there. 
+
+### Sharing walkthroughs
+After a walkthrough plays, ask the agent to "share this walkthrough on the PR". It posts a comment on the current branch's pull request with the [GitHub CLI](https://cli.github.com) (run `gh auth login` first). The comment holds a collapsed transcript, for anyone without Pair, and the script itself. Nothing is added to your codebase, and only people who can see the repo can see it.
+
+To watch one, click **▶ Play in pair** in the comment. That opens Pair's local UI (http://localhost:7420), so it only works while a Pair session is open in your agent. Or ask your agent to "play the walkthrough on PR 123". If the link opens a session for a different repo, or one whose agent is busy elsewhere, Pair lists your other running sessions and their state, so you can open it in the right one. Either way, it plays exactly as written, without regenerating it, and you can still interrupt with questions. Walkthroughs point at symbols and code snippets rather than line numbers, so they're checked against your checkout. If you're on a different commit, Pair tells you which files have changed since the walkthrough was written.
+
+No PR? Ask for a gist instead. Secret gists are unlisted, but anyone with the link can read them.
+
+
+
+## License
+
+[MIT](LICENSE)

package/dist/server/server/src/files.js

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+const IGNORED = new Set([".git", "node_modules", "dist", "build", ".next", ".venv", "venv", "__pycache__", "target", ".DS_Store", ".idea", ".turbo", "coverage"]);
+const MAX_FILE_BYTES = 2_000_000;
+/** Read-only view of the repository the walkthrough is about. */
+export class Workspace {
+    root;
+    gitFiles = null;
+    gitFilesAt = 0;
+    constructor(root) {
+        this.root = root;
+    }
+    setRoot(root) {
+        this.root = root;
+        this.gitFiles = null;
+    }
+    get name() {
+        return path.basename(this.root);
+    }
+    /** Normalizes a user/agent-supplied path to a root-relative POSIX path, rejecting escapes. */
+    rel(p) {
+        const abs = path.isAbsolute(p) && p.startsWith(this.root + path.sep) ? p : path.resolve(this.root, p.replace(/^\/+/, ""));
+        const rel = path.relative(this.root, abs);
+        if (rel.startsWith("..") || path.isAbsolute(rel))
+            throw new Error(`Path escapes the workspace: ${p}`);
+        return rel.split(path.sep).join("/");
+    }
+    async exists(rel) {
+        try {
+            const st = await fs.stat(path.join(this.root, rel));
+            return st.isDirectory() ? "dir" : st.isFile() ? "file" : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async read(rel) {
+        const abs = path.join(this.root, this.rel(rel));
+        const st = await fs.stat(abs);
+        if (st.size > MAX_FILE_BYTES)
+            throw new Error(`File too large to display: ${rel}`);
+        return fs.readFile(abs, "utf8");
+    }
+    async list(dir) {
+        const relDir = dir ? this.rel(dir) : "";
+        const files = await this.trackedFiles();
+        let entries;
+        if (files) {
+            const prefix = relDir ? relDir + "/" : "";
+            const seen = new Map();
+            for (const f of files) {
+                if (!f.startsWith(prefix))
+                    continue;
+                const rest = f.slice(prefix.length);
+                const slash = rest.indexOf("/");
+                const name = slash === -1 ? rest : rest.slice(0, slash);
+                if (!seen.has(name))
+                    seen.set(name, { name, path: prefix + name, dir: slash !== -1 });
+            }
+            entries = [...seen.values()];
+        }
+        else {
+            const dirents = await fs.readdir(path.join(this.root, relDir), { withFileTypes: true });
+            entries = dirents
+                .filter((d) => !IGNORED.has(d.name))
+                .map((d) => ({ name: d.name, path: relDir ? `${relDir}/${d.name}` : d.name, dir: d.isDirectory() }));
+        }
+        return entries.sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1));
+    }
+    /** Git-visible files (tracked + untracked, minus ignored), or null outside a git repo. */
+    trackedFiles() {
+        if (!this.gitFiles || Date.now() - this.gitFilesAt > 10_000) {
+            this.gitFilesAt = Date.now();
+            this.gitFiles = exec("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+                cwd: this.root,
+                maxBuffer: 64 * 1024 * 1024,
+            })
+                .then(({ stdout }) => stdout.split("\0").filter(Boolean))
+                .catch(() => null);
+        }
+        return this.gitFiles;
+    }
+}

package/dist/server/server/src/hub.js

@@ -0,0 +1,381 @@
+import { spawn } from "node:child_process";
+import { createReadStream, existsSync } from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+import { Kokoro } from "./kokoro.js";
+import { SessionRegistry } from "./sessions.js";
+const WEB_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../web");
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript",
+    ".css": "text/css",
+    ".ttf": "font/ttf",
+    ".svg": "image/svg+xml",
+    ".json": "application/json",
+};
+const log = (...args) => console.error("[pair]", ...args);
+/** How long "Thinking…" may show after the user answers before we assume the agent has gone quiet. */
+const AGENT_SILENCE_MS = Number(process.env.PAIR_AGENT_SILENCE_MS) || 90_000;
+/**
+ * Owns the browser UI: serves it, tracks connected tabs, and turns the
+ * asynchronous player events into the blocking outcomes MCP tools return.
+ */
+export class Hub {
+    ws;
+    url = "";
+    clients = new Set();
+    status = null;
+    current = null;
+    main = null;
+    awaitPrompt = null;
+    waiter = null;
+    /** An answer that arrived while no tool call was waiting; handed to the next await_user. */
+    queued = null;
+    connectWaiters = [];
+    kokoro = new Kokoro();
+    ended = null;
+    silenceTimer = null;
+    shared = null;
+    sessions = new SessionRegistry();
+    /** Shown in the session picker, e.g. "Claude Code". */
+    harness = "Unknown agent";
+    constructor(ws) {
+        this.ws = ws;
+        this.kokoro.onStatus = (status) => this.broadcast({ type: "kokoro", status });
+    }
+    async listen(preferredPort) {
+        const server = http.createServer((req, res) => this.handle(req, res).catch((e) => {
+            res.writeHead(500, { "content-type": "text/plain" }).end(String(e.message));
+        }));
+        const wss = new WebSocketServer({ noServer: true });
+        server.on("upgrade", (req, socket, head) => {
+            if (req.url !== "/ws" || !fromLocalPage(req))
+                return socket.destroy();
+            wss.handleUpgrade(req, socket, head, (sock) => this.connect(sock));
+        });
+        for (let port = preferredPort; port < preferredPort + 20; port++) {
+            const ok = await new Promise((resolve) => {
+                server.once("error", () => resolve(false));
+                server.listen(port, "127.0.0.1", () => resolve(true));
+            });
+            if (ok) {
+                this.url = `http://localhost:${port}`;
+                log(`UI at ${this.url} (root: ${this.ws.root})`);
+                await this.sessions.start(this.url, this.ws.root, this.harness).catch((e) => log("session registry:", e));
+                return;
+            }
+        }
+        throw new Error(`No free port in ${preferredPort}-${preferredPort + 19}`);
+    }
+    /** Opens a browser tab if none is connected, and waits for it. */
+    async ensureOpen() {
+        if (this.clients.size)
+            return true;
+        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+        if (!process.env.PAIR_NO_OPEN)
+            spawn(cmd, [this.url], { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+        return new Promise((resolve) => {
+            const t = setTimeout(() => resolve(false), process.env.PAIR_NO_OPEN ? 120_000 : 20_000);
+            this.connectWaiters.push(() => (clearTimeout(t), resolve(true)));
+        });
+    }
+    setStatus(text) {
+        this.status = text;
+        this.broadcast({ type: "status", text });
+    }
+    /** Called on every agent tool call: the agent is still engaged. */
+    touch() {
+        if (this.silenceTimer)
+            clearTimeout(this.silenceTimer);
+        this.silenceTimer = null;
+        this.ended = null;
+    }
+    /** After the user answers, the agent should do *something*. If it never does, don't spin forever. */
+    expectAgent() {
+        if (this.silenceTimer)
+            clearTimeout(this.silenceTimer);
+        this.silenceTimer = setTimeout(() => {
+            this.silenceTimer = null;
+            this.setStatus("No reply from the agent. It may have finished, so continue in its chat, or ask again here.");
+        }, AGENT_SILENCE_MS);
+        this.silenceTimer.unref();
+    }
+    /** Ends the session: the UI says goodbye (if given) and stops taking questions. */
+    endSession(message) {
+        this.touch();
+        this.current = this.main = null;
+        this.awaitPrompt = null;
+        this.queued = null;
+        this.status = null;
+        this.ended = { message };
+        this.settle({ status: "ended" });
+        this.broadcast({ type: "ended", message });
+        this.broadcastMain();
+    }
+    /** Plays a script; resolves when it finishes, the user interjects, or ends the session. */
+    play(script, startAt, signal, onSegment, unattended = false) {
+        this.current = { script, index: startAt };
+        if (!script.aside && !script.transition)
+            this.main = this.current;
+        this.awaitPrompt = null;
+        this.status = null;
+        this.queued = null;
+        this.broadcast({ type: "play", script, startAt, autoplay: true });
+        this.broadcastMain();
+        return this.wait({ scriptId: script.id, resolve: () => { }, onSegment, unattended }, signal);
+    }
+    /** An agent (or the play CLI) is blocked in a call to us, so whatever the user does reaches it now. */
+    agentListening() {
+        return !!this.waiter && !this.waiter.unattended;
+    }
+    /**
+     * Plays a walkthrough opened from a link. If the agent is waiting on us, it's handed
+     * the request so it owns playback (and answers questions). Otherwise we play it
+     * ourselves, and a question waits for the agent's next await_user.
+     */
+    async playShared(source) {
+        if (this.agentListening()) {
+            this.broadcast({ type: "stop" });
+            this.settle({ status: "shared", source });
+            this.expectAgent();
+            this.setStatus("Loading the shared walkthrough…");
+            return "agent";
+        }
+        const script = await this.shared.resolve(source);
+        this.touch();
+        void this.play(script, 0, undefined, undefined, true).then((o) => {
+            if (o.status !== "interrupted")
+                return;
+            // play() only settles: nobody is listening, so keep the question for the agent.
+            if (this.silenceTimer)
+                clearTimeout(this.silenceTimer);
+            this.silenceTimer = null;
+            this.queued = { status: "question", question: o.question, context: o.context };
+            this.setStatus("Your question is saved. To get an answer, tell your agent you asked something in pair.");
+        });
+        return "direct";
+    }
+    mainScript() {
+        return this.main;
+    }
+    /** The main walkthrough, when the user has stepped away from it (an aside or transition is current). */
+    pausedMain() {
+        return this.main && this.current !== this.main ? this.main : null;
+    }
+    mainMessage() {
+        const m = this.pausedMain();
+        return { type: "main", paused: m ? { title: m.script.title, index: m.index, total: m.script.segments.length } : null };
+    }
+    broadcastMain() {
+        this.broadcast(this.mainMessage());
+    }
+    /** Waits for a free-form question typed into the UI. */
+    awaitQuestion(prompt, options, timeoutMs, signal) {
+        if (this.queued) {
+            const q = this.queued;
+            this.queued = null;
+            return Promise.resolve(q);
+        }
+        this.awaitPrompt = { prompt, options };
+        this.broadcast({ type: "await", prompt, options });
+        const timer = setTimeout(() => this.settle({ status: "idle" }), timeoutMs);
+        return this.wait({ scriptId: null, resolve: () => { } }, signal).finally(() => clearTimeout(timer));
+    }
+    wait(w, signal) {
+        this.settle({ status: "cancelled" });
+        return new Promise((resolve) => {
+            w.resolve = resolve;
+            this.waiter = w;
+            this.sessions.update({ listening: this.agentListening() });
+            signal?.addEventListener("abort", () => {
+                if (this.waiter === w) {
+                    this.settle({ status: "cancelled" });
+                    this.broadcast({ type: "stop" });
+                }
+            });
+        });
+    }
+    settle(o) {
+        const w = this.waiter;
+        this.waiter = null;
+        this.sessions.update({ listening: false });
+        w?.resolve(o);
+    }
+    onMessage(msg) {
+        const w = this.waiter;
+        switch (msg.type) {
+            case "segment":
+                if (this.current?.script.id === msg.id)
+                    this.current.index = msg.index;
+                if (w?.scriptId === msg.id)
+                    w.onSegment?.(msg.index);
+                break;
+            case "done":
+                if (w?.scriptId === msg.id)
+                    this.settle({ status: "completed" });
+                break;
+            case "interrupt":
+                if (this.current && this.current.script.id === msg.id)
+                    this.current.index = msg.index;
+                if (w) {
+                    this.expectAgent();
+                    this.settle(w.scriptId
+                        ? { status: "interrupted", index: msg.index, question: msg.question, context: msg.context }
+                        : { status: "question", question: msg.question, context: msg.context, choice: msg.choice });
+                    this.setStatus("Thinking…");
+                }
+                else {
+                    // Nobody is listening right now; hand it to the next await_user call.
+                    this.queued = { status: "question", question: msg.question, context: msg.context, choice: msg.choice };
+                    this.setStatus("Question queued — the agent will pick it up when it checks back in.");
+                }
+                break;
+            case "return": {
+                if (!this.pausedMain())
+                    break;
+                const o = { status: "return", context: msg.context };
+                if (w) {
+                    this.expectAgent();
+                    this.settle(o);
+                    this.setStatus("Heading back…");
+                }
+                else {
+                    this.queued = o;
+                    this.setStatus("Got it — the agent will head back when it checks in.");
+                }
+                break;
+            }
+            case "end":
+                this.endSession(null);
+                break;
+        }
+    }
+    connect(sock) {
+        this.clients.add(sock);
+        const send = (m) => sock.send(JSON.stringify(m));
+        send({ type: "hello", root: this.ws.root, rootName: this.ws.name });
+        send({ type: "status", text: this.status });
+        if (this.ended)
+            send({ type: "ended", message: this.ended.message });
+        send({ type: "kokoro", status: this.kokoro.status });
+        send(this.mainMessage());
+        if (this.current)
+            send({ type: "play", script: this.current.script, startAt: this.current.index, autoplay: false });
+        if (this.waiter && !this.waiter.scriptId)
+            send({ type: "await", prompt: this.awaitPrompt?.prompt ?? null, options: this.awaitPrompt?.options });
+        sock.on("message", (data) => {
+            try {
+                this.onMessage(JSON.parse(String(data)));
+            }
+            catch (e) {
+                log("bad message", e);
+            }
+        });
+        sock.on("close", () => this.clients.delete(sock));
+        this.connectWaiters.splice(0).forEach((f) => f());
+    }
+    broadcast(m) {
+        const data = JSON.stringify(m);
+        for (const c of this.clients)
+            c.send(data);
+    }
+    async handle(req, res) {
+        if (!fromLocalPage(req))
+            return res.writeHead(403, { "content-type": "text/plain" }).end("Forbidden");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const json = (body, status = 200) => res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+        if (url.pathname === "/api/tts/kokoro/enable" && req.method === "POST") {
+            this.kokoro.enable();
+            return json(this.kokoro.status);
+        }
+        if (url.pathname === "/api/tts/kokoro" && req.method === "POST") {
+            try {
+                const { text, voice, speed } = JSON.parse(await readBody(req));
+                return json(await this.kokoro.speak(String(text), String(voice || "af_heart"), Number(speed) || 1));
+            }
+            catch (e) {
+                return json({ error: e.message }, 503);
+            }
+        }
+        if (url.pathname.startsWith("/api/shared/") && req.method === "POST") {
+            if (!this.shared)
+                return json({ error: "Shared walkthroughs aren't available." }, 503);
+            try {
+                const { src } = JSON.parse(await readBody(req));
+                if (url.pathname === "/api/shared/preview") {
+                    const [preview, sessions] = await Promise.all([this.shared.preview(String(src)), this.sessions.list()]);
+                    return json({ ...preview, sessions });
+                }
+                if (url.pathname === "/api/shared/play")
+                    return json({ via: await this.playShared(String(src)) });
+            }
+            catch (e) {
+                return json({ error: e.message }, 400);
+            }
+        }
+        if (url.pathname === "/api/list") {
+            try {
+                return json(await this.ws.list(url.searchParams.get("dir") ?? ""));
+            }
+            catch (e) {
+                return json({ error: e.message }, 400);
+            }
+        }
+        if (url.pathname === "/api/file") {
+            try {
+                return json({ path: url.searchParams.get("path"), content: await this.ws.read(url.searchParams.get("path") ?? "") });
+            }
+            catch (e) {
+                return json({ error: e.message }, 404);
+            }
+        }
+        // "/play?src=…" is a link from a PR comment; the UI reads the query and asks before playing.
+        const rel = url.pathname === "/" || url.pathname === "/play" ? "index.html" : url.pathname.slice(1);
+        const file = path.resolve(WEB_DIR, rel);
+        if (!file.startsWith(WEB_DIR) || !existsSync(file)) {
+            if (!existsSync(path.join(WEB_DIR, "index.html"))) {
+                return res.writeHead(500, { "content-type": "text/plain" }).end("UI not built. Run `npm run build` in the pair repo.");
+            }
+            return res.writeHead(404).end();
+        }
+        res.writeHead(200, { "content-type": MIME[path.extname(file)] ?? "application/octet-stream" });
+        createReadStream(file).pipe(res);
+    }
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (d) => {
+            body += d;
+            if (body.length > 1_000_000)
+                req.destroy(new Error("Request too large"));
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", reject);
+    });
+}
+const LOCAL_HOST = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+/**
+ * Only the Pair UI itself may talk to this server. The Host check defeats DNS
+ * rebinding (a remote page reaching us through its own domain); the Origin check
+ * stops other websites from opening the WebSocket (which would let them feed
+ * "user questions" to the agent) or POSTing to the API. Browsers always send
+ * Origin on WebSocket handshakes and cross-site POSTs; local tools like curl
+ * send none and are allowed.
+ */
+function fromLocalPage(req) {
+    if (!LOCAL_HOST.test(req.headers.host ?? ""))
+        return false;
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    try {
+        const u = new URL(origin);
+        return u.protocol === "http:" && LOCAL_HOST.test(u.host);
+    }
+    catch {
+        return false;
+    }
+}