@parley-im/parley 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,308 @@
+import { createServer } from "node:http";
+import { readFileSync, writeFileSync, existsSync, createReadStream } from "node:fs";
+import { join, extname, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { loadConfig, paths } from "./config.js";
+import { Store } from "./db.js";
+import { Runner, mediaTypeFor } from "./runner.js";
+import { Conversations, Problem, MAX_TEXT, ownsUpload } from "./api.js";
+import { RelayLink } from "./relay.js";
+import { createSession } from "./control.js";
+import { readCredentials, relay as registry, ownerName } from "./account.js";
+import { writeState, clearState } from "./state.js";
+const WEB = join(dirname(fileURLToPath(import.meta.url)), "..", "web");
+const MAX_UPLOAD = 10 * 1024 * 1024;
+// Long polls end well before any proxy's idle timeout.
+const POLL_MS = 25_000;
+const STATIC_TYPES = {
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".html": "text/html; charset=utf-8",
+};
+// Two local servers: your control panel (and your view of each session), and
+// local tester links for development or when you're not signed in. Shared
+// links go through parley.im instead, over the connection in relay.ts.
+export async function serve() {
+    const config = loadConfig();
+    const store = new Store();
+    const runner = new Runner(store, config);
+    const api = new Conversations(store, runner, config);
+    const link = new RelayLink(store, runner, api, config);
+    const state = {
+        pid: process.pid,
+        port: config.port,
+        dashboardPort: config.dashboardPort,
+        startedAt: new Date().toISOString(),
+    };
+    const tester = createServer((req, res) => handleTester(req, res).catch((e) => fail(res, e)));
+    const dashboard = createServer((req, res) => handleDashboard(req, res).catch((e) => fail(res, e)));
+    async function handleTester(req, res) {
+        const url = new URL(req.url ?? "/", "http://x");
+        if (url.pathname === "/health")
+            return json(res, { ok: true, pid: process.pid });
+        if (url.pathname.startsWith("/static/"))
+            return sendStatic(res, url.pathname.slice(8));
+        const m = url.pathname.match(/^\/s\/([A-Za-z0-9_-]{16,})(\/.*)?$/);
+        const session = m && store.sessionByToken(m[1]);
+        if (!session)
+            return notFound(res);
+        // An ended session's link is dead: no transcript, no screenshots, nothing.
+        if (session.status !== "open") {
+            if ((m[2] ?? "/") === "/")
+                return sendFile(res, 410, "ended.html");
+            return problem(res, 410, "ended", "This parley has ended.");
+        }
+        return handleSession(req, res, { session, base: `/s/${m[1]}`, owner: false, images: "url" }, m[2] ?? "/", url);
+    }
+    async function handleDashboard(req, res) {
+        // Bound to 127.0.0.1, but any web page you visit can still send requests
+        // to localhost. The Host check stops DNS rebinding; the Origin check stops
+        // other sites from posting here.
+        const host = req.headers.host ?? "";
+        if (!/^(localhost|127\.0\.0\.1):\d+$/.test(host))
+            return text(res, 403, "Forbidden");
+        if (req.method !== "GET" && req.headers.origin && req.headers.origin !== `http://${host}`) {
+            return text(res, 403, "Forbidden");
+        }
+        const url = new URL(req.url ?? "/", "http://x");
+        if (url.pathname === "/health")
+            return json(res, { ok: true, pid: process.pid });
+        if (url.pathname === "/")
+            return sendStatic(res, "panel.html");
+        if (url.pathname.startsWith("/static/"))
+            return sendStatic(res, url.pathname.slice(8));
+        if (url.pathname === "/api/panel") {
+            return json(res, {
+                server: { pid: process.pid, startedAt: state.startedAt, ownerName: ownerName(config), replyLimit: config.replyLimit },
+                relay: link.status,
+                sessions: store.sessions().map((s) => api.ownerView(s)),
+            });
+        }
+        // After `parley login` or `parley logout`.
+        if (url.pathname === "/api/relay/restart" && req.method === "POST") {
+            link.restart();
+            return json(res, { ok: true });
+        }
+        if (url.pathname === "/api/sessions" && req.method === "POST") {
+            const body = await readJson(req, 100_000);
+            let session;
+            try {
+                session = createSession(store, config, {
+                    projectDir: String(body.projectDir ?? ""),
+                    tester: String(body.tester ?? ""),
+                    brief: String(body.brief ?? ""),
+                    greeting: body.greeting ? String(body.greeting) : null,
+                    agent: (body.agent === "codex" ? "codex" : "claude"),
+                    model: body.model ? String(body.model) : null,
+                    replyLimit: body.replyLimit ? Number(body.replyLimit) : null,
+                });
+            }
+            catch (error) {
+                return problem(res, 400, "invalid", error.message);
+            }
+            const shared = await share(session);
+            return json(res, { ...api.ownerView(session), shared });
+        }
+        const action = url.pathname.match(/^\/api\/sessions\/([a-z0-9]+)\/(end|delete|limit)$/);
+        if (action && req.method === "POST") {
+            const session = store.session(action[1]);
+            if (!session)
+                return notFound(res);
+            if (action[2] === "limit") {
+                const limit = Number((await readJson(req, 1000)).limit);
+                if (!Number.isInteger(limit) || limit < 1)
+                    return problem(res, 400, "invalid", "The limit has to be a whole number above zero.");
+                runner.setReplyLimit(session.id, limit);
+                return json(res, { ok: true });
+            }
+            runner.end(session.id);
+            if (action[2] === "delete")
+                store.deleteSession(session.id);
+            // parley.im forgets it too; if it can't be reached now, the next
+            // connection's sync catches it up.
+            const creds = readCredentials(config);
+            if (creds) {
+                await (action[2] === "delete" ? registry.remove(creds, session) : registry.end(creds, session)).catch((error) => console.error(`parley.im didn't hear about ${session.id}: ${error.message}`));
+            }
+            return json(res, { ok: true });
+        }
+        const m = url.pathname.match(/^\/o\/([a-z0-9]+)(\/.*)?$/);
+        const session = m && store.session(m[1]);
+        if (!session)
+            return notFound(res);
+        return handleSession(req, res, { session, base: `/o/${m[1]}`, owner: true, images: "url" }, m[2] ?? "/", url);
+    }
+    // Registers a new session with parley.im so its link works there.
+    async function share(session) {
+        const creds = readCredentials(config);
+        if (!creds)
+            return false;
+        try {
+            await registry.register(creds, session);
+            return true;
+        }
+        catch (error) {
+            console.error(`parley.im didn't take ${session.id}: ${error.message}`);
+            return false;
+        }
+    }
+    async function handleSession(req, res, scope, rest, url) {
+        const { session } = scope;
+        try {
+            if (rest === "/" && req.method === "GET") {
+                const from = ownerName(config);
+                const html = readFileSync(join(WEB, "chat.html"), "utf8")
+                    .replaceAll("{{TITLE}}", escapeHtml(`${session.project_name} · parley`))
+                    .replaceAll("{{PREVIEW_TITLE}}", escapeHtml(`${from ? `${from} wants` : "Someone wants"} your feedback on ${session.project_name}`))
+                    .replaceAll("{{PREVIEW_TEXT}}", escapeHtml(`A private chat about ${session.project_name}.`))
+                    .replace("{{CONFIG}}", JSON.stringify({ base: scope.base, owner: scope.owner, maxText: MAX_TEXT }).replaceAll("<", "\\u003c"));
+                return send(res, 200, "text/html; charset=utf-8", html);
+            }
+            if (rest === "/api/state" && req.method === "GET")
+                return json(res, api.state(scope));
+            if (rest === "/api/history" && req.method === "GET")
+                return json(res, api.history(scope, Number(url.searchParams.get("before"))));
+            if (rest === "/api/updates" && req.method === "GET")
+                return updates(res, scope, url);
+            if (rest === "/api/messages" && req.method === "POST") {
+                const body = await readJson(req, MAX_TEXT * 4 + 10_000);
+                const textBody = String(body.text ?? "").trim();
+                const images = (Array.isArray(body.images) ? body.images : []).map(String).filter((name) => ownsUpload(session, name));
+                api.check(scope, textBody, images.length);
+                return json(res, api.post(scope, textBody, images));
+            }
+            if (rest === "/api/uploads" && req.method === "POST") {
+                if (scope.owner)
+                    throw new Problem(403, "read_only", "Your view is read-only.");
+                const type = String(req.headers["content-type"] ?? "").split(";")[0];
+                const ext = Object.entries({ ".png": "image/png", ".jpg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp" }).find(([, t]) => t === type)?.[0];
+                if (!ext)
+                    throw new Problem(415, "not_an_image", "Images only: PNG, JPEG, GIF or WebP.");
+                if (!api.allow(session.id))
+                    throw new Problem(429, "slow_down", "That's a lot of uploads very fast. Give it a few seconds.");
+                const data = await readBody(req, MAX_UPLOAD);
+                const name = `${session.id}-${randomBytes(9).toString("base64url")}${ext}`;
+                writeFileSync(join(paths.uploads, name), data);
+                return json(res, { name, url: `${scope.base}/uploads/${name}` });
+            }
+            const upload = rest.match(/^\/uploads\/([A-Za-z0-9_.-]+)$/);
+            if (upload && req.method === "GET") {
+                const name = upload[1];
+                const file = join(paths.uploads, name);
+                if (!ownsUpload(session, name) || !existsSync(file))
+                    return notFound(res);
+                res.writeHead(200, { "content-type": mediaTypeFor(name) ?? "application/octet-stream", "cache-control": "private, max-age=86400" });
+                return createReadStream(file).pipe(res);
+            }
+            return notFound(res);
+        }
+        catch (error) {
+            if (error instanceof Problem)
+                return problem(res, error.status, error.code, error.message);
+            throw error;
+        }
+    }
+    async function updates(res, scope, url) {
+        const after = Number(url.searchParams.get("after") ?? 0);
+        if (url.searchParams.get("epoch") !== runner.epoch || !Number.isFinite(after)) {
+            return json(res, { epoch: runner.epoch, reset: true });
+        }
+        // The response closes early only if the client goes away.
+        const aborted = new AbortController();
+        res.on("close", () => aborted.abort());
+        const events = await runner.wait(scope.session.id, after, POLL_MS, aborted.signal);
+        if (aborted.signal.aborted)
+            return;
+        if (events === null)
+            return json(res, { epoch: runner.epoch, reset: true });
+        json(res, {
+            epoch: runner.epoch,
+            seq: events.at(-1)?.seq ?? after,
+            events: events.map(({ event }) => api.eventView(event, scope)).filter(Boolean),
+        });
+    }
+    tester.listen(config.port, "127.0.0.1");
+    dashboard.listen(config.dashboardPort, "127.0.0.1");
+    await Promise.all([tester, dashboard].map((server) => new Promise((resolve, reject) => {
+        server.once("listening", resolve);
+        server.once("error", reject);
+    })));
+    writeState(state);
+    console.log(`parley: control panel http://localhost:${config.dashboardPort}, local links on ${config.port}`);
+    link.start();
+    runner.resume();
+    const shutdown = () => {
+        link.stop();
+        runner.stopAll();
+        clearState(process.pid);
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    // One bad turn (say, a session deleted mid-reply) shouldn't take every
+    // other tester's link down with it.
+    process.on("unhandledRejection", (error) => console.error("unhandled:", error));
+}
+function sendFile(res, status, name) {
+    send(res, status, STATIC_TYPES[extname(name)], readFileSync(join(WEB, name)));
+}
+function sendStatic(res, name) {
+    if (!/^[a-z0-9-]+\.(js|css|svg|html)$/.test(name))
+        return notFound(res);
+    const file = join(WEB, name);
+    if (!existsSync(file))
+        return notFound(res);
+    send(res, 200, STATIC_TYPES[extname(name)], readFileSync(file));
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(Object.assign(new Error("Too large"), { status: 413 }));
+                req.destroy();
+            }
+            else
+                chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+async function readJson(req, limit) {
+    return JSON.parse((await readBody(req, limit)).toString() || "{}");
+}
+function send(res, status, type, body) {
+    res.writeHead(status, { "content-type": type, "cache-control": "no-store", "x-content-type-options": "nosniff" });
+    res.end(body);
+}
+function json(res, body) {
+    send(res, 200, "application/json; charset=utf-8", JSON.stringify(body));
+}
+// Errors the page can show as they are: a code to act on, words to display.
+function problem(res, status, code, message) {
+    send(res, status, "application/json; charset=utf-8", JSON.stringify({ error: code, message }));
+}
+function text(res, status, body) {
+    send(res, status, "text/plain; charset=utf-8", body);
+}
+function notFound(res) {
+    sendFile(res, 404, "missing.html");
+}
+function fail(res, error) {
+    if (res.headersSent)
+        return res.end();
+    if (error?.status === 413)
+        return problem(res, 413, "too_big", "That's too big to send.");
+    if (error instanceof SyntaxError)
+        return problem(res, 400, "bad_request", "Bad request.");
+    console.error(error);
+    problem(res, 500, "broken", "Something broke on this end.");
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}

package/dist/state.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { paths } from "./config.js";
+import { readCredentials } from "./account.js";
+export function readState() {
+    if (!existsSync(paths.state))
+        return null;
+    try {
+        return JSON.parse(readFileSync(paths.state, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(state) {
+    writeFileSync(paths.state, JSON.stringify(state, null, 2) + "\n");
+}
+export function clearState(pid) {
+    if (readState()?.pid === pid)
+        rmSync(paths.state, { force: true });
+}
+// Signed in: a parley.im link with the session's key after the "#", which
+// browsers keep to themselves. Not signed in: a link that only works on this
+// computer, for development.
+export function linkFor(session, config) {
+    if (readCredentials(config))
+        return `${config.relayUrl}/s/${session.token}#${session.e2e_key}`;
+    return `http://localhost:${config.port}/s/${session.token}`;
+}
+export const isShared = (config) => readCredentials(config) !== null;
+export function dashboardUrl(config, session) {
+    return `http://localhost:${config.dashboardPort}${session ? `/o/${session.id}` : "/"}`;
+}
+export async function isServerUp(config) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${config.dashboardPort}/health`, { signal: AbortSignal.timeout(1500) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/transcript.js

@@ -0,0 +1,53 @@
+import { join } from "node:path";
+import { paths } from "./config.js";
+const agentName = (s) => (s.agent === "codex" ? "Codex" : "Claude");
+const time = (iso) => new Date(iso).toLocaleString("en-US", { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+// Which model(s) answered, and on what login, from the recorded turns.
+export function interviewer(store, session) {
+    const models = new Set();
+    const auths = new Set();
+    for (const turn of store.turns(session.id)) {
+        if (typeof turn.usage?.model === "string")
+            models.add(turn.usage.model);
+        if (typeof turn.usage?.auth === "string")
+            auths.add(turn.usage.auth === "none" ? "your subscription" : turn.usage.auth);
+    }
+    const details = [[...models].join(", "), [...auths].join(", ")].filter(Boolean).join(", on ");
+    return details ? `${agentName(session)} (${details})` : agentName(session);
+}
+// The record of a session as Markdown, with screenshot paths your agent can
+// open. With `onlyNew`, just the messages since you last read it. Either way
+// it marks everything shown as read.
+export function transcript(store, session, link, { onlyNew = false } = {}) {
+    const messages = store.messages(session.id, onlyNew ? session.read_through : 0);
+    const stats = store.stats(session.id);
+    const lines = [];
+    lines.push(`# Feedback from ${session.tester} on ${session.project_name}${onlyNew ? " (new since you last read)" : ""}`, "", `- Session: ${session.id}, ${session.status === "open" ? "open" : `ended ${time(session.ended_at ?? session.updated_at)}, link no longer works`}`, `- Interviewer: ${interviewer(store, session)}, started ${time(session.created_at)}`, `- Project: ${session.project_dir}`, ...(session.status === "open" ? [`- Tester link: ${link}`] : []), `- Messages: ${stats.tester_messages} from ${session.tester}, ${stats.agent_messages} from ${agentName(session)}`, `- Replies: ${stats.replies} of ${session.reply_limit}${spend(stats.cost_usd)}`, "");
+    if (!onlyNew)
+        lines.push("## Brief", "", session.brief.trim(), "", "## Conversation", "");
+    if (!messages.length)
+        lines.push("_Nothing new._");
+    for (const m of messages) {
+        const who = m.role === "tester" ? session.tester : m.role === "agent" ? agentName(session) : "Parley (error shown to tester)";
+        lines.push(`### ${who} · ${time(m.created_at)} · #${m.id}`, "", m.body.trim());
+        for (const image of m.images)
+            lines.push("", `Screenshot: ${join(paths.uploads, image)}`);
+        lines.push("");
+    }
+    if (messages.length)
+        store.markRead(session.id, messages.at(-1).id);
+    return lines.join("\n");
+}
+const spend = (usd) => (usd ? `, about $${usd.toFixed(2)} at API prices` : "");
+export function summaryLine(store, session, link) {
+    const stats = store.stats(session.id);
+    const unread = stats.unread ? `, ${stats.unread} new since you last read` : "";
+    const heard = stats.last_tester_at ? `last heard from ${time(stats.last_tester_at)}` : "hasn't said anything yet";
+    const status = session.status === "open" ? "open" : `ended ${time(session.ended_at ?? session.updated_at)}`;
+    return [
+        `${session.id}  ${session.tester} on ${session.project_name}  [${status}, ${agentName(session)}]`,
+        `  ${stats.tester_messages} message${stats.tester_messages === 1 ? "" : "s"} from ${session.tester}${unread}; ${heard}`,
+        `  ${stats.replies} of ${session.reply_limit} replies used${spend(stats.cost_usd)}`,
+        ...(session.status === "open" ? [`  ${link}`] : []),
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@parley-im/parley",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Send someone a link. They talk to a read-only Claude or Codex in your project, on your computer, and you get everything they said.",
+  "keywords": [
+    "claude",
+    "codex",
+    "feedback",
+    "user-testing",
+    "interview",
+    "mcp",
+    "agent"
+  ],
+  "homepage": "https://parley.im/docs",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "parley": "bin/parley"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "web"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "check": "tsc --noEmit",
+    "test": "node --no-warnings --test test/server.test.ts test/markdown.test.ts test/seal.test.ts",
+    "test:relay": "node --no-warnings --test test/relay.e2e.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^26.6.4",
+    "jsdom": "^29.1.1",
+    "typescript": "^7.0.2"
+  }
+}