passalong 0.13.1 → 0.14.0

package/README.md

@@ -5,13 +5,14 @@ Hand work to your AI coding agents, and get back what they did and how they chec
 Write a task, a bug or a finished change once. The agent that takes it starts knowing what done
 looks like and what was already decided, reports as it goes, and hands back a write-up with the
 evidence for each thing you asked for, which you approve or send back. One agent per job, and
-everyone can see who has what. Works with Claude Code, Cursor, Gemini, ChatGPT, or anything that
+everyone can see who has what. Works with Claude Code, Codex, ChatGPT, Claude, or anything that
 speaks MCP or HTTP. See [passalong.dev](https://passalong.dev).
 
 ```sh
 npm i -g passalong
 passalong setup      # installs the Claude Code capture skill + registers the MCP server
 passalong login      # optional: sync guides across machines and get share links
+codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ```
 
 ## The loop

package/bin/passalong

@@ -39,7 +39,7 @@
 //   passalong archive <id>        off your board and out of the free tier's count (was `done`)
 //   passalong rm <id>             delete a guide locally and from sync
 //   passalong export [dir]        dump every guide as plain markdown (default ./passalong-export)
-//   passalong login [token]       sign in with your email and password, or attach this machine with a token
+//   passalong login [token]       sign in from the browser, or attach this machine with a token
 //   passalong me [--handle H] [--name N] [--email E]   who you are to teammates
 //   passalong team                current team and its members
 //   passalong team create <name>  start a team (you become its owner)
@@ -51,7 +51,7 @@
 //   passalong mcp                 run the MCP server over stdio
 //   passalong version             print the installed version (also -v, --version)
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -94,6 +94,86 @@ const tty = process.stdout.isTTY && process.stdin.isTTY;
  * Written against readline rather than a dependency because this package has none beyond the MCP
  * SDK and zod, and asking for a line of text is not where that changes.
  */
+/** Open a page in the default browser, and say nothing if there is none to open. */
+function openPage(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {}).unref();
+  } catch {}
+}
+
+/**
+ * Sign in by approving in the browser: show a code, wait, and be handed a token. No password is
+ * typed here and no token is pasted between windows. Needs no terminal to ask on, so an agent can
+ * run it and tell the person which page to open.
+ */
+async function browserLogin() {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("hex");
+  const start = await api.deviceStart(challenge, `${hostname()} cli`).catch((e) => die(e.message));
+  console.error(`Open ${start.url}`);
+  console.error(`and check the page shows the code ${start.code}, then press Approve.`);
+  if (tty) openPage(start.url);
+  console.error("Waiting for you to approve it here… (Ctrl-C to stop)");
+  const until = Date.now() + start.expires_in * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, start.interval * 1000));
+    const got = await api.devicePoll(start.id, verifier).catch((e) => die(e.message));
+    if (!got) continue;
+    store.writeConfig({ token: got.token, api: api.baseUrl() });
+    console.error(`signed in (account ${got.account}) on ${api.baseUrl()}. Sync is on.`);
+    console.error("Attach other machines with:");
+    console.error(`  passalong login ${got.token}`);
+    console.error("(keep it private — it is a credential, not a password)");
+    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    return;
+  }
+  die("nobody approved it in time. Run `passalong login` again.");
+}
+
+/** The old way, kept for anyone who asks for it with `--email`: an email and a password, typed here. */
+async function passwordLogin(f) {
+// An account you cannot sign in to is one that dies with this file. This used to mint one
+  // silently and then suggest adding a password afterwards; it asks up front instead.
+  if (!tty)
+    die(
+      "no terminal to ask on. Sign in at " +
+        `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
+    );
+
+  const email = f.email || (await ask("Email: "));
+  if (!email) die("an email is needed to sign in");
+  const password = await ask("Password: ", { hidden: true });
+  if (!password) die("a password is needed to sign in");
+
+  const label = `${hostname()} cli`;
+  let who = await api.signIn(email, password, { label }).catch((e) => e);
+  if (who instanceof Error) {
+    // 401 is "no such account, or the wrong password", said the same way on purpose so the API
+    // does not confirm which addresses exist. The CLI has to ask rather than guess, because
+    // creating an account for a mistyped address is worse than being told to try again.
+    if (who.status !== 401) die(who.message);
+    const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
+    if (yes !== "y" && yes !== "yes")
+      die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
+    const again = await ask("Choose a password: ", { hidden: true });
+    if (again !== password) die("those did not match");
+    who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
+  }
+
+  store.writeConfig({ token: who.token, api: api.baseUrl() });
+  console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
+  console.error("Attach other machines with:");
+  console.error(`  passalong login ${who.token}`);
+  console.error("(keep it private — it is a credential, not a password)");
+  console.error("Give teammates a name to address you by: passalong me --handle <you>");
+}
+
 async function ask(question, { hidden = false } = {}) {
   const { createInterface } = await import("node:readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
@@ -698,40 +778,11 @@ const commands = {
         return;
       }
     }
-    // An account you cannot sign in to is one that dies with this file. This used to mint one
-    // silently and then suggest adding a password afterwards; it asks up front instead.
-    if (!tty)
-      die(
-        "no terminal to ask on. Sign in at " +
-          `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
-      );
-
-    const email = f.email || (await ask("Email: "));
-    if (!email) die("an email is needed to sign in");
-    const password = await ask("Password: ", { hidden: true });
-    if (!password) die("a password is needed to sign in");
-
-    const label = `${hostname()} cli`;
-    let who = await api.signIn(email, password, { label }).catch((e) => e);
-    if (who instanceof Error) {
-      // 401 is "no such account, or the wrong password", said the same way on purpose so the API
-      // does not confirm which addresses exist. The CLI has to ask rather than guess, because
-      // creating an account for a mistyped address is worse than being told to try again.
-      if (who.status !== 401) die(who.message);
-      const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
-      if (yes !== "y" && yes !== "yes")
-        die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
-      const again = await ask("Choose a password: ", { hidden: true });
-      if (again !== password) die("those did not match");
-      who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
-    }
-
-    store.writeConfig({ token: who.token, api: api.baseUrl() });
-    console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
-    console.error("Attach other machines with:");
-    console.error(`  passalong login ${who.token}`);
-    console.error("(keep it private — it is a credential, not a password)");
-    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    // Passwords are for someone who asks: `--email` keeps the prompts. Everyone else is sent to the
+    // browser, which works with no terminal at all — an agent can start it, and the person it is
+    // working for clicks once.
+    if (f.email || f.password) return passwordLogin(f);
+    return browserLogin();
   },
 
   async me(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [
@@ -14,7 +14,7 @@
     "mcp-server",
     "coding-agents",
     "task-management",
-    "cursor"
+    "codex"
   ],
   "homepage": "https://passalong.dev",
   "repository": {

package/src/api.js

@@ -126,6 +126,32 @@ export async function signIn(email, password, { make = false, label = "" } = {})
  * still live and still right for the invite page, which mints before it claims, and because
  * removing a published export is a breaking change for anyone who imported it.
  */
+/**
+ * Sign this machine in from the browser. `challenge` is the sha256, in hex, of a secret kept here;
+ * what comes back is a short code to show, the page to open, and how often to ask whether it was
+ * approved. Nothing in the answer is a credential.
+ */
+export const deviceStart = (challenge, label) =>
+  call("/v1/device/start", { method: "POST", auth: false, body: { challenge, label } });
+
+/** `null` while nobody has said yes; the account and its token once somebody has. */
+export async function devicePoll(id, verifier) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/device/poll`, {
+      method: "POST",
+      headers: { ...CLIENT, "content-type": "application/json" },
+      body: JSON.stringify({ id, verifier }),
+    });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (res.status === 202) return null;
+  const said = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ApiError(res.status, said.message || res.statusText);
+  return said;
+}
+
 export const createAccount = () => call("/v1/accounts", { method: "POST", auth: false });
 export const me = () => call("/v1/me");
 export const updateMe = (patch) => call("/v1/me", { method: "PATCH", body: patch });

package/src/guide.js

@@ -709,3 +709,101 @@ function taskTemplate(meta = {}) {
 export function stripPlaceholders(body) {
   return body.replace(/^<!-- passalong:.*?-->\n?/gm, "").trim();
 }
+
+// ---- reading a guide in parts, and how big one may be -----------------------------------------
+// Mirrors apps/api/src/sections.ts — apps/api/test/sections.test.mjs holds the two to the same
+// answers. Most of what is stored is a few very large guides (six of 123 held 72% of the text), and
+// an agent that wants only the Acceptance of a long task should not read the rest first.
+
+/** Over this a guide is large: its readers are offered the outline first, and its author a warning. */
+export const GUIDE_WARN = 20_000;
+/** Over this a new guide is refused by the server. A guide stored before it existed may keep its size. */
+export const GUIDE_MAX = 60_000;
+
+/** Where each heading starts, outside the frontmatter and outside code fences. */
+function headingLines(markdown) {
+  const fm = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(markdown);
+  const bodyStart = fm ? fm[0].length : 0;
+  const lines = [];
+  let fence = "";
+  let at = bodyStart;
+  for (const raw of markdown.slice(bodyStart).split("\n")) {
+    const mark = /^\s*(```|~~~)/.exec(raw)?.[1];
+    if (mark) fence = fence ? (fence === mark ? "" : fence) : mark;
+    const m = !fence && !mark ? /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(raw) : null;
+    if (m) lines.push({ heading: m[2].trim(), level: m[1].length, start: at });
+    at += raw.length + 1;
+  }
+  return lines;
+}
+
+/** The end of the section that begins at lines[i]: the next heading at its level or above. */
+function sectionEnd(lines, i, total) {
+  for (let j = i + 1; j < lines.length; j++)
+    if (lines[j].level <= lines[i].level) return lines[j].start;
+  return total;
+}
+
+/** Every heading, with the characters in its section (nested ones included). */
+export function outline(markdown) {
+  const lines = headingLines(markdown);
+  return lines.map((l, i) => ({
+    heading: l.heading,
+    level: l.level,
+    chars: sectionEnd(lines, i, markdown.length) - l.start,
+  }));
+}
+
+/** One section by its heading — exact, then by its start, then by what it contains. */
+export function section(markdown, name) {
+  const lines = headingLines(markdown);
+  const want = String(name ?? "")
+    .trim()
+    .toLowerCase();
+  if (!want) return null;
+  const at = (test) => lines.findIndex((l) => test(l.heading.toLowerCase()));
+  const i = [
+    at((h) => h === want),
+    at((h) => h.startsWith(want)),
+    at((h) => h.includes(want)),
+  ].find((n) => n >= 0);
+  if (i === undefined) return null;
+  return {
+    heading: lines[i].heading,
+    text: markdown.slice(lines[i].start, sectionEnd(lines, i, markdown.length)).trimEnd(),
+  };
+}
+
+/** What a guide's author is told when it is on the large side. */
+export function sizeWarning(chars) {
+  return chars > GUIDE_WARN
+    ? `this guide is ${chars.toLocaleString("en")} characters, and over ${GUIDE_WARN.toLocaleString("en")} ` +
+        "it is read by outline first. Put logs, dumps and long output in a file (attach_file) and " +
+        "link it; keep the guide to what the next agent has to act on."
+    : null;
+}
+
+/**
+ * What an agent is shown instead of a large guide: who it is, what it is, and where its parts are.
+ * `path` is where the whole of it was written, for a search rather than a read.
+ */
+export function outlineText(markdown, { id = "", path = "" } = {}) {
+  const { meta } = parse(markdown);
+  const rows = outline(markdown)
+    .filter((h) => h.level <= 3)
+    .map(
+      (h) => `${"  ".repeat(h.level - 1)}- ${h.heading} (${h.chars.toLocaleString("en")} chars)`,
+    );
+  return [
+    `${meta.title || id} — ${meta.kind || "guide"}, ${markdown.length.toLocaleString("en")} characters`,
+    meta.summary ? `Summary: ${meta.summary}` : "",
+    "",
+    "Sections:",
+    ...rows,
+    "",
+    `Read one with get_guide ref=${id} section="<heading>", or the whole thing with full=true.` +
+      (path ? ` The full text is also on disk at ${path}, if you only need to search it.` : ""),
+  ]
+    .filter((l, i, a) => l !== "" || a[i - 1] !== "")
+    .join("\n");
+}

package/src/mcp.js

@@ -9,7 +9,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import * as api from "./api.js";
 import { refusal, runChecks } from "./checks.js";
-import { AREAS, BUG_SECTIONS, parse, SECTIONS, TASK_SECTIONS, template } from "./guide.js";
+import {
+  AREAS,
+  BUG_SECTIONS,
+  GUIDE_WARN,
+  outlineText,
+  parse,
+  SECTIONS,
+  section as sectionOf,
+  sizeWarning,
+  TASK_SECTIONS,
+  template,
+} from "./guide.js";
 import * as passalong from "./passalong.js";
 
 /**
@@ -396,7 +407,7 @@ export function buildServer() {
       if (h)
         return fail({
           message:
-            `${err.message}. Somebody else is on it here${h.note ? ` (last said: "${h.note}")` : ""}. ` +
+            `${err.message}. Somebody else is on it here${h.agent ? ` (agent ${h.agent}${h.host ? ` on ${h.host}` : ""})` : ""}${h.note ? ` (last said: "${h.note}")` : ""}. ` +
             "Tell the user before doing this work too; get_guide reads it without taking it.",
         });
       return failWith(err);
@@ -787,36 +798,44 @@ export function buildServer() {
           ),
         checks: z
           .array(
-            z.object({
-              check: z
-                .string()
-                .describe(
-                  "the line this answers, in the guide's own words: an Acceptance line on a task, " +
-                    "a Verification line on a handoff or a bug",
-                ),
-              says: z
-                .string()
-                .optional()
-                .describe(
-                  'what happened, in one plain sentence for a PERSON: "Swagger lists all six ' +
-                    'endpoints, each with request and response schemas." It is the row they read ' +
-                    "in the review table; the evidence stays folded behind it. Strongly " +
-                    "recommended: a check without one shows only the line it answers",
-                ),
-              ran: z
-                .string()
-                .optional()
-                .describe("what you ran for it, and what came back; not needed when `cmd` is set"),
-              cmd: z
-                .string()
-                .optional()
-                .describe(
-                  "the shell command that proves this line, run here before the hand-in lands — " +
-                    "its exit code decides the check and its output is recorded as the evidence. " +
-                    "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
-                    '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
-                ),
-            }),
+            // A bare string is a check line with nothing behind it. Let it through to the server's
+            // refusal, which says what to send, rather than a schema error that says only "expected
+            // object".
+            z.preprocess(
+              (v) => (typeof v === "string" ? { check: v } : v),
+              z.object({
+                check: z
+                  .string()
+                  .describe(
+                    "the line this answers, in the guide's own words: an Acceptance line on a task, " +
+                      "a Verification line on a handoff or a bug",
+                  ),
+                says: z
+                  .string()
+                  .optional()
+                  .describe(
+                    'what happened, in one plain sentence for a PERSON: "Swagger lists all six ' +
+                      'endpoints, each with request and response schemas." It is the row they read ' +
+                      "in the review table; the evidence stays folded behind it. Strongly " +
+                      "recommended: a check without one shows only the line it answers",
+                  ),
+                ran: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "what you ran for it, and what came back; not needed when `cmd` is set",
+                  ),
+                cmd: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "the shell command that proves this line, run here before the hand-in lands — " +
+                      "its exit code decides the check and its output is recorded as the evidence. " +
+                      "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
+                      '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
+                  ),
+              }),
+            ),
           )
           .optional()
           .describe(
@@ -928,7 +947,9 @@ export function buildServer() {
       title: "Get guide",
       annotations: READS,
       description:
-        "READ a transfer guide by passalong id or share link and return its full markdown. Also " +
+        "READ a transfer guide by passalong id or share link and return its markdown. A guide over " +
+        "20,000 characters comes back as an outline (its headings and their sizes) unless you ask " +
+        "for `section`, for one part, or `full`, for all of it. Also " +
         "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
         "Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide " +
         "you have not committed to. If you are about to DO the work, call take instead: " +
@@ -940,12 +961,38 @@ export function buildServer() {
           .string()
           .optional()
           .describe("directory to write .passalong/<id>.md into; default is the server's cwd"),
+        section: z
+          .string()
+          .optional()
+          .describe("read only the part under this heading, e.g. Acceptance; see the outline"),
+        outline: z
+          .boolean()
+          .optional()
+          .describe("just the headings and their sizes, whatever the guide's length"),
+        full: z
+          .boolean()
+          .optional()
+          .describe("the whole document, even one over 20,000 characters"),
       },
     },
-    async ({ ref, cwd }) => {
+    async ({ ref, cwd, section, outline, full }) => {
       try {
         const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
         const meta = parse(markdown).meta;
+        if (section) {
+          const part = sectionOf(markdown, section);
+          if (!part)
+            return text(
+              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref, path })}`,
+            );
+          return text(
+            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; the whole guide is at ${path} -->`,
+          );
+        }
+        if (outline || (!full && markdown.length > GUIDE_WARN))
+          return text(
+            `${outlineText(markdown, { id: meta.id || ref, path })}\n\n<!-- passalong: ${from}; written to ${path} -->`,
+          );
         const lead = leadFor(meta);
         const siblings = await related(meta);
         // Follow-ups are more context for this guide, so they come with it — after the document,
@@ -1144,6 +1191,7 @@ export function buildServer() {
           parent: guide.meta.parent || "",
           notified,
           path,
+          ...(sizeWarning(markdown.length) ? { warning: sizeWarning(markdown.length) } : {}),
           // A task does not go live on publish, and an agent that reports "queued it" has told
           // the user something untrue. Said in the result so it is said to them.
           ...(guide.meta.kind === "task" && guide.meta.status === "draft"