@parley-im/parley 0.0.0-stage → 0.1.1

package/dist/daemon.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { openSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { paths, cleanEnv } from "./config.js";
+import { readState, isServerUp } from "./state.js";
+// cli.ts in a checkout, cli.js once built for npm.
+const CLI = join(dirname(fileURLToPath(import.meta.url)), import.meta.url.endsWith(".ts") ? "cli.ts" : "cli.js");
+// Starts the server in the background if it isn't running, and waits until
+// it answers. It holds this computer's connection to parley.im.
+export async function ensureServer(config, waitMs = 20_000) {
+    if (!(await isServerUp(config))) {
+        const log = openSync(paths.log, "a");
+        const child = spawn(process.execPath, ["--no-warnings", CLI, "serve"], {
+            detached: true,
+            stdio: ["ignore", log, log],
+            env: cleanEnv(),
+            cwd: paths.home,
+        });
+        child.unref();
+    }
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+        const state = readState();
+        if (state && (await isServerUp(config)))
+            return state;
+        await new Promise((r) => setTimeout(r, 400));
+    }
+    return (await isServerUp(config)) ? readState() : null;
+}
+export async function stopServer() {
+    const state = readState();
+    if (!state)
+        return false;
+    try {
+        process.kill(state.pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/db.js

@@ -0,0 +1,243 @@
+import { DatabaseSync } from "node:sqlite";
+import { randomBytes } from "node:crypto";
+import { readdirSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { paths, ensureHome } from "./config.js";
+import { newKey } from "./seal.js";
+const schema = `
+create table if not exists sessions (
+  id text primary key,
+  token text not null unique,
+  project_dir text not null,
+  project_name text not null,
+  tester text not null,
+  brief text not null,
+  greeting text not null,
+  agent text not null,
+  model text,
+  agent_session_id text,
+  status text not null default 'open',
+  read_through integer not null default 0,
+  reply_limit integer not null default 100,
+  e2e_key text,
+  created_at text not null,
+  updated_at text not null,
+  ended_at text
+);
+create table if not exists turns (
+  id integer primary key autoincrement,
+  session_id text not null references sessions(id),
+  agent text not null,
+  status text not null,
+  activity text not null default '[]',
+  usage text,
+  error text,
+  started_at text not null,
+  ended_at text
+);
+create table if not exists messages (
+  id integer primary key autoincrement,
+  session_id text not null references sessions(id),
+  role text not null,
+  body text not null,
+  images text not null default '[]',
+  -- For tester messages: the turn that answered it (null while waiting).
+  -- For agent and error messages: the turn that produced it.
+  turn_id integer references turns(id),
+  created_at text not null
+);
+create index if not exists messages_session on messages(session_id, id);
+create index if not exists turns_session on turns(session_id, id);
+`;
+const now = () => new Date().toISOString();
+export class Store {
+    db;
+    constructor(file = paths.db) {
+        ensureHome();
+        this.db = new DatabaseSync(file);
+        this.db.exec("pragma journal_mode = wal; pragma busy_timeout = 5000; pragma foreign_keys = on;");
+        this.db.exec(schema);
+        this.addMissingColumns();
+    }
+    // Columns added since a database was first created.
+    addMissingColumns() {
+        const have = new Set(this.db.prepare("pragma table_info(sessions)").all().map((c) => c.name));
+        if (!have.has("read_through"))
+            this.db.exec("alter table sessions add column read_through integer not null default 0");
+        if (!have.has("ended_at"))
+            this.db.exec("alter table sessions add column ended_at text");
+        if (!have.has("reply_limit"))
+            this.db.exec("alter table sessions add column reply_limit integer not null default 100");
+        if (!have.has("e2e_key"))
+            this.db.exec("alter table sessions add column e2e_key text");
+        for (const row of this.db.prepare("select id from sessions where e2e_key is null").all()) {
+            this.db.prepare("update sessions set e2e_key = ? where id = ?").run(newKey(), row.id);
+        }
+        this.db.exec("update sessions set status = 'ended', ended_at = coalesce(ended_at, updated_at) where status not in ('open', 'ended')");
+    }
+    createSession(input) {
+        const id = shortId();
+        const token = randomBytes(18).toString("base64url");
+        const projectName = basename(input.projectDir);
+        const greeting = input.greeting?.trim() ||
+            `Hi ${input.tester}! Thanks for trying ${projectName}. Tell me anything: what you tried, what tripped you up, what you liked. Long rambling brain dumps are perfect.`;
+        const t = now();
+        this.db
+            .prepare(`insert into sessions (id, token, project_dir, project_name, tester, brief, greeting, agent, model, reply_limit, e2e_key, status, created_at, updated_at)
+         values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`)
+            .run(id, token, input.projectDir, projectName, input.tester, input.brief, greeting, input.agent, input.model ?? null, input.replyLimit, newKey(), t, t);
+        this.addMessage(id, "agent", greeting, [], null);
+        return this.session(id);
+    }
+    session(id) {
+        return this.db.prepare("select * from sessions where id = ?").get(id);
+    }
+    sessionByToken(token) {
+        return this.db.prepare("select * from sessions where token = ?").get(token);
+    }
+    sessions(filter = {}) {
+        return this.db
+            .prepare(`select * from sessions
+         where (?1 is null or project_dir = ?1) and (?2 is null or status = ?2)
+         order by updated_at desc`)
+            .all(filter.projectDir ?? null, filter.status ?? null);
+    }
+    // Erases the session: transcript, turns, and screenshots.
+    deleteSession(id) {
+        this.db.prepare("delete from messages where session_id = ?").run(id);
+        this.db.prepare("delete from turns where session_id = ?").run(id);
+        this.db.prepare("delete from sessions where id = ?").run(id);
+        for (const name of readdirSync(paths.uploads)) {
+            if (name.startsWith(`${id}-`))
+                rmSync(join(paths.uploads, name), { force: true });
+        }
+    }
+    end(id) {
+        const t = now();
+        this.db.prepare("update sessions set status = 'ended', ended_at = ?, updated_at = ? where id = ? and status = 'open'").run(t, t, id);
+    }
+    setReplyLimit(id, limit) {
+        this.db.prepare("update sessions set reply_limit = ? where id = ?").run(limit, id);
+    }
+    // Replies the agent has given or tried to give; each one cost something.
+    repliesUsed(id) {
+        const row = this.db.prepare("select count(*) as n from turns where session_id = ? and status in ('done', 'failed')").get(id);
+        return Number(row.n);
+    }
+    // The model that wrote the latest reply, as the agent reported it.
+    latestModel(id) {
+        const row = this.db
+            .prepare("select json_extract(usage, '$.model') as model from turns where session_id = ? and json_extract(usage, '$.model') is not null order by id desc limit 1")
+            .get(id);
+        return row?.model ?? null;
+    }
+    markRead(id, messageId) {
+        this.db.prepare("update sessions set read_through = max(read_through, ?) where id = ?").run(messageId, id);
+    }
+    setAgentSessionId(id, agentSessionId) {
+        this.db.prepare("update sessions set agent_session_id = ? where id = ?").run(agentSessionId, id);
+    }
+    touch(id) {
+        this.db.prepare("update sessions set updated_at = ? where id = ?").run(now(), id);
+    }
+    addMessage(sessionId, role, body, images, turnId) {
+        const result = this.db
+            .prepare("insert into messages (session_id, role, body, images, turn_id, created_at) values (?, ?, ?, ?, ?, ?)")
+            .run(sessionId, role, body, JSON.stringify(images), turnId, now());
+        this.touch(sessionId);
+        return this.message(Number(result.lastInsertRowid));
+    }
+    message(id) {
+        const row = this.db.prepare("select * from messages where id = ?").get(id);
+        return row && parseMessage(row);
+    }
+    messages(sessionId, afterId = 0) {
+        return this.db.prepare("select * from messages where session_id = ? and id > ? order by id").all(sessionId, afterId).map(parseMessage);
+    }
+    // The newest `limit` messages before `beforeId` (or the newest overall),
+    // oldest first, and whether there are more before them.
+    page(sessionId, limit, beforeId) {
+        const rows = this.db
+            .prepare("select * from messages where session_id = ? and (?2 is null or id < ?2) order by id desc limit ?3")
+            .all(sessionId, beforeId ?? null, limit + 1);
+        return { messages: rows.slice(0, limit).reverse().map(parseMessage), more: rows.length > limit };
+    }
+    pending(sessionId) {
+        return this.db
+            .prepare("select * from messages where session_id = ? and role = 'tester' and turn_id is null order by id")
+            .all(sessionId).map(parseMessage);
+    }
+    startTurn(session, messageIds) {
+        const result = this.db
+            .prepare("insert into turns (session_id, agent, status, started_at) values (?, ?, 'running', ?)")
+            .run(session.id, session.agent, now());
+        const turnId = Number(result.lastInsertRowid);
+        const claim = this.db.prepare("update messages set turn_id = ? where id = ?");
+        for (const id of messageIds)
+            claim.run(turnId, id);
+        return this.turn(turnId);
+    }
+    turn(id) {
+        const row = this.db.prepare("select * from turns where id = ?").get(id);
+        return row && parseTurn(row);
+    }
+    turns(sessionId) {
+        return this.db.prepare("select * from turns where session_id = ? order by id").all(sessionId).map(parseTurn);
+    }
+    addActivity(turnId, line) {
+        const turn = this.turn(turnId);
+        if (!turn)
+            return;
+        this.db.prepare("update turns set activity = ? where id = ?").run(JSON.stringify([...turn.activity, line]), turnId);
+    }
+    finishTurn(turnId, status, usage, error) {
+        this.db
+            .prepare("update turns set status = ?, usage = ?, error = ?, ended_at = ? where id = ?")
+            .run(status, usage ? JSON.stringify(usage) : null, error, now(), turnId);
+    }
+    releaseTurn(turnId) {
+        this.db.prepare("update messages set turn_id = null where turn_id = ? and role = 'tester'").run(turnId);
+    }
+    // A turn that never finished (server stopped mid-reply) gives its messages
+    // back to the queue so they are answered when the server comes back.
+    recoverInterrupted() {
+        const stuck = this.db.prepare("select * from turns where status = 'running'").all();
+        const sessions = new Set();
+        for (const turn of stuck) {
+            this.finishTurn(turn.id, "interrupted", null, "Server stopped before the reply finished.");
+            this.releaseTurn(turn.id);
+            sessions.add(turn.session_id);
+        }
+        return [...sessions];
+    }
+    stats(sessionId) {
+        const row = this.db
+            .prepare(`select
+           coalesce(sum(m.role = 'tester'), 0) as tester_messages,
+           coalesce(sum(m.role = 'agent'), 0) as agent_messages,
+           coalesce(sum(m.role = 'tester' and m.id > s.read_through), 0) as unread,
+           max(m.created_at) as last_message_at,
+           max(case when m.role = 'tester' then m.created_at end) as last_tester_at
+         from sessions s left join messages m on m.session_id = s.id
+         where s.id = ?`)
+            .get(sessionId);
+        const turns = this.db
+            .prepare(`select
+           coalesce(sum(status in ('done', 'failed')), 0) as replies,
+           coalesce(sum(json_extract(usage, '$.cost_usd')), 0) as cost_usd
+         from turns where session_id = ?`)
+            .get(sessionId);
+        return { ...row, replies: Number(turns.replies), cost_usd: Number(turns.cost_usd) };
+    }
+}
+function parseMessage(row) {
+    return { ...row, images: JSON.parse(row.images) };
+}
+function parseTurn(row) {
+    return { ...row, activity: JSON.parse(row.activity), usage: row.usage ? JSON.parse(row.usage) : null };
+}
+function shortId() {
+    const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
+    const bytes = randomBytes(6);
+    return [...bytes].map((b) => alphabet[b % alphabet.length]).join("");
+}

package/dist/mcp.js

@@ -0,0 +1,153 @@
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod";
+import { loadConfig } from "./config.js";
+import { Store } from "./db.js";
+import { linkFor, dashboardUrl, isServerUp } from "./state.js";
+import { transcript, summaryLine } from "./transcript.js";
+import { startSession, endSession, setReplyLimit } from "./control.js";
+import { readCredentials } from "./account.js";
+const INSTRUCTIONS = `Parley lets the user hand a tester a link to a private web chat with a read-only Claude or Codex running in their project folder. The tester talks; the agent listens, asks follow-ups, answers questions from the code, and everything is recorded.
+
+Use create_session when the user wants someone to give feedback on a project. Write the brief from what you know about the project and what the user wants to learn. Later, use list_sessions to see which sessions are open, which have new messages, and how many replies each has used and spent; get_transcript to read them; set_reply_limit to give a session more room or less; and end_session when the user is done with one. Links live on parley.im and are end-to-end encrypted; the conversation itself happens on the user's computer, so testers can only get replies while it's awake and the parley server is running.`;
+export async function runMcp() {
+    const config = loadConfig();
+    const store = new Store();
+    const server = new McpServer({ name: "parley", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+    const callerAgent = () => (/codex/i.test(server.server.getClientVersion()?.name ?? "") ? "codex" : "claude");
+    const reply = (text) => ({ content: [{ type: "text", text }] });
+    const currentLink = (id) => linkFor(store.session(id), config);
+    server.registerTool("create_session", {
+        title: "Create a feedback session",
+        description: "Create a parley session: a private link the user can send to a tester. The tester chats with a fresh, read-only " +
+            "agent in the project folder that hears their feedback, answers questions by reading the code, and records everything. " +
+            "Starts the local server and tunnel if needed. Returns the link to give the user.",
+        inputSchema: {
+            project_dir: z.string().describe("Absolute path of the project folder, normally your current working directory."),
+            tester: z.string().describe("Name of the person who will give feedback, e.g. 'Sam'."),
+            brief: z
+                .string()
+                .describe("Instructions for the interviewer, written to it directly. Cover what the project is and its current state, " +
+                "how the tester will try it (URL, build, steps), what the user most wants to learn, known issues not worth " +
+                "digging into, and anything about the tester that helps. A few short paragraphs."),
+            greeting: z
+                .string()
+                .optional()
+                .describe("The first message the tester sees, from the interviewer. Short and warm. A default is used if omitted."),
+            agent: z
+                .enum(["claude", "codex"])
+                .optional()
+                .describe("Which agent interviews the tester. Defaults to whichever agent is calling this tool."),
+            model: z.string().optional().describe("Model override for the interviewer. Usually leave unset."),
+            reply_limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe(`Replies the interviewer may give before the session pauses for the user to add more. Defaults to ${config.replyLimit}.`),
+        },
+    }, async (args) => {
+        let made;
+        try {
+            made = await startSession(store, config, {
+                projectDir: args.project_dir,
+                tester: args.tester,
+                brief: args.brief,
+                greeting: args.greeting,
+                agent: args.agent ?? callerAgent(),
+                model: args.model ?? null,
+                replyLimit: args.reply_limit ?? null,
+            });
+        }
+        catch (error) {
+            return { ...reply(error.message), isError: true };
+        }
+        const { session } = made;
+        const lines = [
+            `Created session ${session.id} for ${session.tester} (${session.agent}, read-only in ${session.project_dir}, up to ${session.reply_limit} replies).`,
+            "",
+            `Link for ${session.tester}: ${linkFor(session, config)}`,
+            `Watch it live on the control panel: ${dashboardUrl(config, session)}`,
+            "",
+        ];
+        if (!readCredentials(config)) {
+            lines.push("This computer isn't signed in to parley.im, so the link only works here. Have the user run `parley login` to share links.");
+        }
+        else if (!made.serverUp) {
+            lines.push("Warning: the parley server didn't come up, so the link won't answer yet. Check ~/.parley/server.log, then run `parley start`.");
+        }
+        else if (!made.shared) {
+            lines.push("Warning: parley.im didn't take the session yet. It will once the connection is back; `parley status` shows it.");
+        }
+        else {
+            lines.push("Everything after the # in the link is the session's encryption key: share the whole link, and only with the tester. " +
+                "Replies come from this computer, so it needs to be awake with parley running.");
+        }
+        return reply(lines.join("\n"));
+    });
+    server.registerTool("list_sessions", {
+        title: "List feedback sessions",
+        description: "List parley sessions, newest activity first, with how many tester messages are new since you last read each one. " +
+            "Open sessions include their current tester link.",
+        inputSchema: {
+            status: z.enum(["open", "ended", "all"]).optional().describe("Defaults to open."),
+            project_dir: z.string().optional().describe("Only sessions for this project folder. Omit for every project."),
+        },
+    }, async (args) => {
+        const status = args.status ?? "open";
+        const sessions = store.sessions({
+            projectDir: args.project_dir ? resolve(args.project_dir) : undefined,
+            status: status === "all" ? undefined : status,
+        });
+        if (!sessions.length)
+            return reply(status === "all" ? "No sessions yet." : `No ${status} sessions.`);
+        const down = status !== "ended" && !(await isServerUp(config))
+            ? "The parley server is not running, so testers can't get replies. Run `parley start` to bring it back.\n\n"
+            : "";
+        return reply(down + sessions.map((s) => summaryLine(store, s, linkFor(s, config))).join("\n\n"));
+    });
+    server.registerTool("get_transcript", {
+        title: "Read a feedback session",
+        description: "Read a parley session as Markdown: the brief, every message, which model interviewed, and paths to screenshots the " +
+            "tester shared. Set only_new to read just what came in since you last read it. Reading marks it read.",
+        inputSchema: {
+            session_id: z.string(),
+            only_new: z.boolean().optional(),
+        },
+    }, async (args) => {
+        const session = store.session(args.session_id);
+        if (!session)
+            return { ...reply(`No session ${args.session_id}.`), isError: true };
+        return reply(transcript(store, session, currentLink(session.id), { onlyNew: args.only_new ?? false }));
+    });
+    server.registerTool("end_session", {
+        title: "End a feedback session",
+        description: "End a parley session for good when the user is done with it. The tester's link stops working entirely and an open " +
+            "page clears itself. The transcript stays readable here. This can't be undone; make a new session to talk again.",
+        inputSchema: { session_id: z.string() },
+    }, async (args) => {
+        const session = store.session(args.session_id);
+        if (!session)
+            return { ...reply(`No session ${args.session_id}.`), isError: true };
+        if (session.status !== "open")
+            return reply(`Session ${session.id} had already ended.`);
+        await endSession(config, store, session.id);
+        return reply(`Ended ${session.id} (${session.tester} on ${session.project_name}). The link no longer works; the transcript is kept. ` +
+            `To erase it completely, the user can run \`parley delete ${session.id}\`.`);
+    });
+    server.registerTool("set_reply_limit", {
+        title: "Change a session's reply limit",
+        description: "Set how many replies the interviewer may give in a session in total. When a session runs out it pauses: the tester " +
+            "can't send more until the limit is raised. Use it when the user wants to give a session more room, or rein it in.",
+        inputSchema: { session_id: z.string(), limit: z.number().int().positive().describe("Total replies allowed, including ones already given.") },
+    }, async (args) => {
+        const session = store.session(args.session_id);
+        if (!session)
+            return { ...reply(`No session ${args.session_id}.`), isError: true };
+        await setReplyLimit(config, store, session.id, args.limit);
+        const used = store.repliesUsed(session.id);
+        return reply(`${session.id} (${session.tester}) may now give ${args.limit} replies in total; ${used} used so far.`);
+    });
+    await server.connect(new StdioServerTransport());
+}

package/dist/models.js

@@ -0,0 +1,10 @@
+// "claude-opus-5-5" reads better as "Opus 5.5". Anything else (Codex models,
+// aliases) is shown as it is.
+export function modelLabel(model) {
+    if (!model)
+        return null;
+    const claude = model.match(/^claude-([a-z]+)-(\d+)-(\d+)(?:-\d{8})?$/);
+    if (claude)
+        return `${claude[1][0].toUpperCase()}${claude[1].slice(1)} ${claude[2]}.${claude[3]}`;
+    return model;
+}