passalong 0.12.0 → 0.13.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukman Isiaka
+
+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,10 +1,12 @@
 # passalong
 
-Hand finished work to another context.
+Hand work to your AI coding agents, and get back what they did and how they checked it.
 
-Solve something non-trivial in one agent session. Run one command. Open a session in another
-repo, on another machine, or with a teammate, and the agent there already knows the whole story:
-the problem, the decisions and why, the steps, how to verify, and what went wrong along the way.
+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
+speaks MCP or HTTP. See [passalong.dev](https://passalong.dev).
 
 ```sh
 npm i -g passalong
@@ -33,7 +35,7 @@ passalong activity [--all]    what happened while you were away; clears unless -
 passalong list [query]        your guides and your teams', local and synced
 passalong open <id> [--print] view a guide in the browser (or the terminal)
 passalong hub                 open your synced guides in the browser
-passalong works <id>          you tried it and it holds up
+passalong works <id> <shot>   you tried it and it holds up, with a screenshot of it working
 passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 passalong archive <id>        off your board and out of the free tier's count (was `done`)
 passalong promote <id>        deprecated: mark promoted
@@ -67,9 +69,11 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-A receiver who tries the work reports back with `passalong works <id>` or `passalong broken <id> <why>`.
-That is separate from `done`, which means *implemented*: a verdict means it actually runs, a failing
-one has to say why, and the author sees it on their board and in their inbox.
+A receiver who tries the work reports back with `passalong works <id> <screenshot.png>` or
+`passalong broken <id> <why>`. That is separate from `done`, which means *implemented*: a verdict
+means it actually runs. A passing one has to show it — at least one screenshot of it working, kept
+until 5 days after the guide is closed — a failing one has to say why, and the author sees it on
+their board and in their inbox.
 
 Sign in at [the hub](https://passalong.dev/hub) with an email and password, and mint
 an API token there for the CLI and MCP servers — named, revocable, and shown once. Your password

package/bin/passalong

@@ -13,7 +13,8 @@
 //   passalong approve <id>        the work in review is done
 //   passalong reject <id> <why>   not done: back to Ready, and the next agent reads why
 //   passalong release <id>        take work back from whoever holds it, of any kind
-//   passalong attach <image>      upload evidence and print the markdown that points at it
+//   passalong attach <file>       upload a picture or a file and print the markdown that points at it
+//   passalong reply <id> <text>   write to whoever holds it (--file PATH to attach); or leave a note
 //   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
 //   passalong start <id|link>     pull it and take it — one command for "I am doing this"
 //   passalong inbox               guides handed to you that you have not pulled yet
@@ -33,7 +34,7 @@
 //                                 give Solo to @handle, or Team to team/slug, until a date (operator only)
 //   passalong gifts               what has been given away, and what is still running
 //   passalong ungift <gift id>    take one back now
-//   passalong works <id>          you tried it and it holds up
+//   passalong works <id> <shot.png...>  you tried it and it holds up — with a screenshot of it working
 //   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   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
@@ -69,8 +70,11 @@ function flags(argv) {
     const t = argv[i];
     if (t.startsWith("--")) {
       const next = argv[i + 1];
-      if (next === undefined || next.startsWith("-")) out[t.slice(2)] = true;
-      else out[t.slice(2)] = argv[++i];
+      const key = t.slice(2);
+      const value = next === undefined || next.startsWith("-") ? true : argv[++i];
+      // A flag given twice keeps both, so `--file a.pdf --file b.csv` is two files. Nothing else
+      // repeats a flag, so nothing else sees an array.
+      out[key] = key in out && value !== true ? [out[key], value].flat() : value;
     } else out._.push(t);
   }
   return out;
@@ -386,12 +390,33 @@ const commands = {
    * a guide travels as markdown to whoever holds its link, so a file beside it does not travel.
    */
   async attach(f) {
-    const file = f._[0] || die("usage: passalong attach <image> [--name LABEL]");
-    const shot = await passalong.attach(file, { name: f.name || "" }).catch((e) => die(e.message));
+    const file = f._[0] || die("usage: passalong attach <file> [--name LABEL]");
+    // A picture is evidence a page draws; anything else is a file somebody downloads.
+    const isImage = Object.keys(passalong.SHOT_TYPES).some((x) => file.toLowerCase().endsWith(x));
+    const shot = await (isImage ? passalong.attach : passalong.attachFile)(file, {
+      name: f.name || "",
+    }).catch((e) => die(e.message));
     process.stdout.write(`${shot.markdown}\n`);
     console.error(`uploaded ${shot.bytes} bytes → ${shot.url}`);
   },
 
+  /**
+   * Write to whoever holds a guide, or leave a note on one nobody holds yet. The person's side of
+   * `ask`: an agent that stopped to wait hears this when it takes the guide again.
+   */
+  async reply(f) {
+    const id = f._[0] || die("usage: passalong reply <id> <message> [--file PATH ...]");
+    const files = [f.file].flat().filter((x) => typeof x === "string");
+    const said = f._.slice(1).join(" ");
+    if (!said && !files.length) die("say something, or attach a file: passalong reply <id> <message>");
+    const r = await passalong.reply(id, said, { files }).catch((e) => die(e.message));
+    console.error(
+      r?.noted
+        ? `${id} — nobody holds it yet, so this is a note: whoever takes it is handed it first`
+        : `${id} — sent. Whoever holds it reads it the next time it checks in`,
+    );
+  },
+
   async inbox() {
     const rows = await passalong.inbox().catch((e) => die(e.message));
     if (!rows.length) return console.error("inbox empty — nothing handed to you that you haven't pulled");
@@ -603,9 +628,12 @@ const commands = {
   },
 
   async works(f) {
-    const id = f._[0] || die("usage: passalong works <id>");
-    const r = await passalong.verdict(id, true, f._.slice(1).join(" ")).catch((e) => die(e.message));
-    console.error(`${r.id} verified — the author has been told`);
+    const id = f._[0] || die("usage: passalong works <id> <screenshot.png...> [what you checked]");
+    const { images, note } = passalong.proofArgs(f._.slice(1));
+    const r = await passalong.verdict(id, true, note, { images }).catch((e) => die(e.message));
+    console.error(
+      `${r.id} verified with ${images.length || "your"} screenshot${images.length === 1 ? "" : "s"} — the author has been told`,
+    );
   },
 
   async broken(f) {
@@ -861,10 +889,16 @@ const commands = {
         input = JSON.parse(raw || "{}");
       }
       if (!api.loggedIn()) return;
+      // The timeout is cleared as soon as the answer is in. Left running it holds the process open
+      // for the full five seconds after the hook has printed, and a session start or a stop that
+      // waits five seconds for nothing is the hook getting in the way, which it must never do.
+      let timer;
       const r = await Promise.race([
         passalong.now(),
-        new Promise((_, no) => setTimeout(() => no(new Error("timeout")), 5000)),
-      ]);
+        new Promise((_, no) => {
+          timer = setTimeout(() => no(new Error("timeout")), 5000);
+        }),
+      ]).finally(() => clearTimeout(timer));
       if (f.hook === "session") {
         const text = nowText(r);
         if (text)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "passalong",
-  "version": "0.12.0",
-  "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
+  "version": "0.13.1",
+  "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": [
     "mcp",
     "claude-code",
@@ -9,7 +10,11 @@
     "handoff",
     "knowledge-transfer",
     "cli",
-    "markdown"
+    "markdown",
+    "mcp-server",
+    "coding-agents",
+    "task-management",
+    "cursor"
   ],
   "homepage": "https://passalong.dev",
   "repository": {

package/skill/SKILL.md

@@ -66,7 +66,7 @@ machine, another agent session, or a teammate without your branch.
    follow-up gets the guide it came out of, and where that guide has got to — so write it as a
    note on that work rather than as a standalone brief. A session that started from a passalong guide
    (`passalong start` or `pull` on an id, or an agent opened one) usually has context worth adding
-   this way. Whether the guide worked is still its own answer: `passalong works <id>` or
+   this way. Whether the guide worked is still its own answer: `passalong works <id> <screenshot>` or
    `passalong broken <id> <why>`.
 6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the
@@ -98,11 +98,24 @@ pulls a guide, and steps that reproduce a defect are the one list that must neve
 remedy — an agent that follows them reproduces the bug, checks the Verification, finds it false
 because the bug is real, and reports that the guide does not work.
 
+## Say it to a person
+
+Everything below is written for another agent: exact, dense, full of ids and paths. A person reading
+their hub wants two sentences. So every guide carries a `summary:` in its frontmatter — plain
+language, 400 characters at most, no ids, paths or jargon, saying what this is and whether anybody
+has to do anything. It is what they see first; your document is behind it. A guide with no summary is
+refused.
+
+Write it the way you would tell a colleague in the corridor: "Webhook signatures are now checked
+before anything is stored. Done and working; nothing to do." Not: "Implemented HMAC-SHA512 verify in
+billing.ts per the Paystack spec, see PR 412."
+
 ## Guide structure
 
 ```markdown
 ---
 title: <what this accomplishes, as a verb phrase: "Add Paystack webhook verification">
+summary: <one or two plain sentences for a PERSON, 400 characters at most, no ids or paths: what this is and whether anyone has to act>
 author: <git user.name, if known>
 source_context: <repo or product this came from>
 status: published
@@ -135,6 +148,7 @@ Commands to run and what they should print. Test cases. What "done" looks like.
 ```markdown
 ---
 title: <what is broken, in one line: "Undo leaves section drag handles dead">
+summary: <one or two plain sentences for a PERSON: what is broken and whether anyone has to act>
 kind: bug
 severity: <s1 blocker | s2 major | s3 minor | s4 cosmetic>
 area: <which surface it is on>

package/src/api.js

@@ -216,6 +216,10 @@ export const progress = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
 export const handIn = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/hand_in`, { method: "POST", body });
+export const ask = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/ask`, { method: "POST", body });
+export const reply = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/reply`, { method: "POST", body: { body } });
 export const pass = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/pass`, { method: "POST", body });
 export const ack = (id, taken, note = "") =>
@@ -228,6 +232,36 @@ export const ack = (id, taken, note = "") =>
  * the content type as the declaration of what they are. `name` is the label, and it travels in a
  * header rather than the body for the same reason.
  */
+/**
+ * Upload a file that is not a picture, and get back what the server made of it. The server decides
+ * what the bytes are and refuses what it does not keep; `type` and `name` are hints. The name travels
+ * percent-encoded because a header cannot hold what a filename can.
+ */
+export async function uploadFile(bytes, type, name = "") {
+  const t = token();
+  if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
+  const headers = {
+    authorization: `Bearer ${t}`,
+    "content-type": type || "application/octet-stream",
+  };
+  if (name) headers["x-file-name"] = encodeURIComponent(String(name));
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/attachments`, { method: "POST", headers, body: bytes });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    let message = body;
+    try {
+      message = JSON.parse(body).message || body;
+    } catch {}
+    throw new ApiError(res.status, message || res.statusText);
+  }
+  return (await res.json()).attachment;
+}
+
 export async function uploadShot(bytes, type, name = "") {
   const t = token();
   if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");

package/src/capture.js

@@ -65,6 +65,8 @@ export function taskScaffold(sentence, cwd = process.cwd()) {
   const md = template({
     kind: "task",
     title: sentence,
+    // The person typed this sentence, so it is theirs to say to a person as well as to name the task.
+    summary: String(sentence).slice(0, 400),
     author: c.author,
     source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
     target_context: c.repo,

package/src/checks.js

@@ -22,6 +22,26 @@
  * exit code is the whole verdict here, which is also how a CI step decides.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * The shell a check runs in: bash with `pipefail` wherever there is one.
+ *
+ * A plain shell reports a pipeline's last command. `npx jest 2>&1 | grep Tests:` then passes when
+ * jest fails, because grep found the summary line, and `git log main..HEAD | head -60` passes when
+ * git dies with "fatal: ambiguous argument", because head exited 0 — which is exactly how a hand-in
+ * came back marked "ran, it worked here" with the fatal error sitting in its own output. With
+ * pipefail, any failing step fails the check.
+ */
+const BASH =
+  process.platform === "win32" ? "" : ["/bin/bash", "/usr/bin/bash"].find(existsSync) || "";
+
+/**
+ * 141 is 128 + SIGPIPE: the command was still writing when a later step stopped reading, which is
+ * what `| head` does on purpose. Under pipefail that is the pipeline's status, and it is not a
+ * failure — git printed what head wanted and was told to stop.
+ */
+const SIGPIPE = 141;
 
 /** How long a check may run before it is killed. Long enough for a real suite, short of a lease. */
 export const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
@@ -56,15 +76,20 @@ function tail(out, max = OUTPUT_MAX) {
  */
 export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT_MS } = {}) {
   const cmd = String(check?.cmd ?? "").trim();
-  if (!cmd) return { check: check.check, ran: check.ran };
+  // What the agent says happened, in plain words: the person's line of the table. It is the agent's
+  // account and a run never touches it, so it rides along on every shape this returns.
+  const says = check?.says ? { says: check.says } : {};
+  if (!cmd) return { check: check.check, ran: check.ran, ...says };
 
-  const r = spawnSync(cmd, {
-    shell: true,
+  const opts = {
     cwd,
     timeout: timeoutMs,
     encoding: "utf8",
     maxBuffer: 64 * 1024 * 1024,
-  });
+  };
+  const r = BASH
+    ? spawnSync(BASH, ["-o", "pipefail", "-c", cmd], opts)
+    : spawnSync(cmd, { ...opts, shell: true });
 
   const out = tail(`${r.stdout ?? ""}${r.stderr ?? ""}`);
   // `status` is null when the child was killed rather than exited: a timeout, or a signal.
@@ -77,6 +102,7 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
           : `could not run: ${r.error?.message ?? "unknown error"}`;
     return {
       check: check.check,
+      ...says,
       cmd,
       exit: null,
       ok: false,
@@ -84,15 +110,21 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
     };
   }
 
+  const cutShort = Boolean(BASH) && r.status === SIGPIPE;
   return {
     check: check.check,
+    ...says,
     cmd,
     exit: r.status,
-    ok: r.status === 0,
+    ok: r.status === 0 || cutShort,
     // The recorded evidence is what the process printed, not what the agent said about it. An
     // empty run is written out rather than left blank: the exit code is what decided it, and a
     // blank `ran` reads like evidence nobody supplied.
-    ran: out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`,
+    ran:
+      (out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`) +
+      (cutShort
+        ? "\n(exit 141: a later step stopped reading early, as `head` does; not a failure)"
+        : ""),
   };
 }
 

package/src/guide.js

@@ -50,6 +50,19 @@ export const SETTABLE = ["draft", "published", "consumed"];
  * exactly as ambiguous as it was and adds a second state — a guide that exists and cannot be
  * shared — where the point was to have fewer.
  */
+/**
+ * What a guide says to a person, in a sentence or two, and the longest that may be.
+ *
+ * Everything an agent writes is written for another agent: exact, dense, full of ids and paths. A
+ * person scanning their work wants "what is this, and do I need to do anything", so every guide
+ * carries both — the document is the agent's form, and `summary:` is the human one, shown by default
+ * in the hub with the document behind "Show details".
+ *
+ * Said by the author and refused when absent, like `kind`, for the same reason: a summary written
+ * afterwards by something that was not there is a second voice that can say what nobody claimed.
+ */
+export const SUMMARY_MAX = 400;
+
 export const KINDS = ["transfer", "bug", "task"];
 
 // Body sections in the order a guide should present them. The heading text is what the
@@ -290,6 +303,37 @@ export function parseFrontmatter(text) {
   return meta;
 }
 
+/**
+ * Frontmatter fields holding more than this format can: a nested map, a block scalar (`|`), a
+ * sequence under a field that is not a list. `parseFrontmatter` keeps only the key's own line, so
+ * each of these would come back as `""` with its content gone — a design.md's `colors:` block did
+ * exactly that, and a publish would have stored the document with every token wiped. The format
+ * does not grow to hold them (strings and string lists only); the publish refuses them by name
+ * instead, so nothing is lost without its author being told. Mirrors `unheldFields` in
+ * apps/api/src/guide.ts, which is the refusal every client meets.
+ */
+export function unheldFields(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!m) return [];
+  const out = new Set();
+  let key = null;
+  let listKey = null;
+  for (const line of m[1].split(/\r?\n/)) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    if (listKey && /^\s*-\s*/.test(line)) continue;
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
+    if (kv) {
+      key = kv[1];
+      listKey = kv[2].trim() === "" && LIST_FIELDS.has(key) ? key : null;
+      continue;
+    }
+    // Anything else is a line the parser skips: an indented child, or an item under a field
+    // that is not a list. It belongs to the key above it, and that is the key to name.
+    out.add(key ?? line.trim());
+  }
+  return [...out];
+}
+
 function quote(v) {
   const s = String(v ?? "");
   // Quote anything YAML would misread: colons, leading symbols, or empty.
@@ -299,6 +343,9 @@ function quote(v) {
 const META_ORDER = [
   "id",
   "title",
+  // Right under the title: it is what a person reads first about it, so it is what the document
+  // opens with.
+  "summary",
   "kind",
   "created",
   "author",
@@ -416,6 +463,14 @@ export function validate({ meta, body }) {
   // a kind — `parseFrontmatter` seeds it — so what reaches this without one was built field by
   // field in code, and code is exactly what should have to say what it is making.
   const kind = meta.kind;
+  const said = String(meta.summary ?? "").trim();
+  if (!said)
+    errors.push(
+      "say it to a person: add `summary:` — one or two plain sentences, no ids or paths, saying what " +
+        `this is and whether anybody needs to act (${SUMMARY_MAX} characters at most)`,
+    );
+  else if (said.length > SUMMARY_MAX)
+    errors.push(`summary is ${said.length} characters; ${SUMMARY_MAX} at most`);
   if (!kind) errors.push(`say what this is: kind must be one of ${KINDS.join(", ")}`);
   else if (!KINDS.includes(kind)) errors.push(`kind must be one of ${KINDS.join(", ")}`);
   const have = sections(body);
@@ -458,6 +513,10 @@ export function stamp(guide, defaults = {}) {
  */
 export function bugGuide({
   title = "",
+  // What a person reads about it. A bug's own title is that when nothing else was said, and it is
+  // the author's own words, stated here by the caller that knows it is building a bug — not a
+  // default for something an author left off.
+  summary = "",
   problem = "",
   reproduce = "",
   verification = "",
@@ -513,6 +572,7 @@ export function bugGuide({
 
   const meta = {
     title,
+    summary: String(summary || "").trim() || title,
     kind: "bug",
     status,
     tags: ["bug", environment, area].filter(Boolean),
@@ -553,6 +613,7 @@ export function template(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       author: "",
       source_context: "",
       status: "draft",
@@ -589,6 +650,7 @@ function bugTemplate(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       kind: "bug",
       author: "",
       source_context: "",
@@ -629,6 +691,7 @@ function taskTemplate(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       kind: "task",
       author: "",
       source_context: "",

package/src/hooks.js

@@ -30,6 +30,13 @@ export function nowText({ held, waiting = {} }) {
       `Passalong: You hold ${held.id} (${held.kind}): ${held.title || held.id}.`,
     ];
     if (held.note) lines.push(`Last note: "${held.note}".`);
+    // The one thing here that is new information rather than a reminder: the person has written, and
+    // nothing else in the session will say so until the agent next checks in.
+    if (held.replies)
+      lines.push(
+        `${plural(held.replies, "message", "messages")} from the person ${held.replies === 1 ? "is" : "are"} ` +
+          `waiting for you: call take ${held.id} to read ${held.replies === 1 ? "it" : "them"} before anything else.`,
+      );
     if (held.state === "stalled")
       lines.push("It is marked stalled: nobody has heard from its agent in 30 minutes.");
     lines.push(
@@ -55,7 +62,9 @@ export function nowText({ held, waiting = {} }) {
  * would leave it no way to end.
  */
 export function stopVerdict({ held, input = {} }) {
-  if (!held || input.stop_hook_active) return null;
+  // An agent that asked a question was told to stop and wait, so it must be let: blocking it would
+  // make the instruction and the hook contradict each other, and the agent would pick one.
+  if (!held || held.asking || input.stop_hook_active) return null;
   return {
     decision: "block",
     reason:

package/src/mcp.js

@@ -226,6 +226,21 @@ export function nextNote({ next = [], say = "" } = {}, id = "") {
   return lines.length ? `<!-- passalong: next:\n${lines.join("\n")}\n-->` : "";
 }
 
+/**
+ * What the person said to this agent since it last heard, in front of everything else: a reply is
+ * the thing the agent stopped for, and burying it under the guide it already knows is how it gets
+ * missed. See claims.deliver() in apps/api/src/claims.ts.
+ */
+export function repliesNote(replies = []) {
+  if (!Array.isArray(replies) || !replies.length) return "";
+  const lines = replies.map((r) => `  - ${String(r.body).replace(/\n/g, "\n    ")}`);
+  const files = replies.some((r) => String(r.body).includes("/v1/attachments/"))
+    ? "\n  Attached files are private: fetch one with your passalong token, e.g. " +
+      'curl -H "authorization: Bearer $PASSALONG_TOKEN (or the token in ~/.passalong/config.json)" -o <name> <url>.'
+    : "";
+  return `<!-- passalong: the person replied:\n${lines.join("\n")}${files}\n-->`;
+}
+
 /** A refusal that carries the server's own next move, when it sent one. */
 const failWith = (err) => {
   const said = nextNote(err.body || {});
@@ -252,7 +267,9 @@ export function buildServer() {
         "returns it; nobody else can take it here while you hold it, and its sender sees you are " +
         "on it. progress, with a one-line note at each milestone — 30 minutes of silence marks it " +
         "stalled. hand_in when done here. pass, with the reason, when it is not yours or you are " +
-        "stuck. Every answer ends with `next`: what to call now. Follow it, and when it says to " +
+        "stuck. ask, with a question, when you need an answer from the person: you keep what you " +
+        "hold, stop and wait, and take it again once they have replied. Every answer ends with " +
+        "`next`: what to call now. Follow it, and when it says to " +
         "stop, stop. OPEN A GUIDE YOU MEAN TO ACT ON WITH take, NOT get_guide: get_guide only " +
         "reads, and the sender learns nothing. If take says somebody else has it, tell the user " +
         "instead of doing the work twice.\n" +
@@ -261,6 +278,11 @@ export function buildServer() {
         "Collect it as you work rather than writing it from memory at the end. hand_in without " +
         "it is refused, because the write-up and the verdict are both your word for your own " +
         "work and evidence is the part the person reviewing it can check.\n" +
+        "EVERY GUIDE SAYS WHAT IT IS TO A PERSON. The document is for agents: exact, dense, full of " +
+        "ids and paths. Put `summary:` in its frontmatter — one or two plain sentences, 400 " +
+        "characters at most, no ids, paths or jargon, saying what this is and whether anybody has " +
+        "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
+        "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
         "is a spelling that is not one of the three. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
@@ -331,8 +353,13 @@ export function buildServer() {
     const note = nextNote({ next, say }, id);
     // The note is what the agent acts on and it is prose, so it stays in the text half only. The
     // structured half is the answer itself, which is what `outputSchema` below describes.
+    // A reply goes first, in prose: it is what the agent stopped for, and inside the JSON it reads
+    // as one more field.
+    const said = repliesNote(rest.replies);
     return {
-      ...text(`${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`),
+      ...text(
+        `${said ? `${said}\n` : ""}${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`,
+      ),
       structuredContent: rest,
     };
   };
@@ -359,8 +386,9 @@ export function buildServer() {
         `<!-- passalong: ${r.guide.id} is yours` +
         `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}; ` +
         `written to ${r.path}. -->`;
+      const said = repliesNote(r.replies);
       return text(
-        `${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
+        `${said ? `${said}\n\n` : ""}${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
           `\n\n${held}\n${nextNote(r, r.guide.id)}\n${passalong.followUpNote(meta)}`,
       );
     } catch (err) {
@@ -428,6 +456,14 @@ export function buildServer() {
     }
   }
 
+  async function doAsk({ id, question, cwd }) {
+    try {
+      return answer(await passalong.ask(id, question, { cwd: cwd || process.cwd() }), id);
+    } catch (err) {
+      return failWith(err);
+    }
+  }
+
   async function doPass({ id, why, cwd }) {
     try {
       return answer(await passalong.pass(id, why, { cwd: cwd || process.cwd() }), id);
@@ -623,6 +659,12 @@ export function buildServer() {
           .array(
             z.object({
               title: z.string(),
+              summary: z
+                .string()
+                .describe(
+                  "one or two plain sentences for a PERSON, no ids or paths: what this task is and " +
+                    "why it matters. The goal below is for the agent; this is what a person reads",
+                ),
               goal: z.string().describe("what is true when this step is done"),
               acceptance: z.string().describe("checks a person can run, one per line"),
               context: z.string().optional(),
@@ -694,7 +736,14 @@ export function buildServer() {
         "without one marks it stalled. If the answer says you no longer hold it, stop.",
       inputSchema: {
         id: z.string().describe("the id of what you hold"),
-        note: z.string().optional().describe('one line, e.g. "migrating schema, 2 of 5 steps"'),
+        note: z
+          .string()
+          .optional()
+          .describe(
+            'one plain sentence in the first person, as you would tell the person: "Reading ' +
+              'the settings page to find where the toggle goes." Start it with BLOCKED: when ' +
+              "you are stopped and need an answer",
+          ),
         cwd: z
           .string()
           .optional()
@@ -745,6 +794,15 @@ export function buildServer() {
                   "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()
@@ -768,7 +826,13 @@ export function buildServer() {
               "running it and is refused",
           ),
         ok: z.boolean().optional().describe("handoff or bug: did its Verification hold"),
-        note: z.string().optional().describe("one line; required when ok is false"),
+        note: z
+          .string()
+          .describe(
+            "one plain sentence, in the first person, saying what you did and how it went: " +
+              '"Added the toggle to Settings; it survives a reload." It is the first thing the ' +
+              "person reads, and the evidence is behind it. Say what went wrong when ok is false",
+          ),
         writeup: z
           .string()
           .optional()
@@ -805,6 +869,37 @@ export function buildServer() {
     async (args) => doHandIn(args),
   );
 
+  server.registerTool(
+    "ask",
+    {
+      title: "Ask the person",
+      outputSchema: openObject({ id: z.string(), lease_until: z.string() }),
+      annotations: ADDS,
+      description:
+        "You need the person's answer before you can go on. Ask one clear question, with the " +
+        "context it needs to be answered without opening your terminal. You keep what you hold " +
+        "and nobody else can take it. Then STOP and tell the user you are waiting: do not carry " +
+        "on guessing. When they have replied, call take with this id and their reply comes back " +
+        "with it. Use `pass` instead when the work is not yours; a progress note starting " +
+        "BLOCKED: is the older way of saying this, and is not heard as a question.",
+      inputSchema: {
+        id: z.string().describe("passalong id"),
+        question: z
+          .string()
+          .describe(
+            "one clear question in the first person, a few sentences at most, plain text: " +
+              '"Should the dark-mode toggle live in Settings or the header? The header is ' +
+              'crowded on mobile." What you were about to do, if they just say yes, helps',
+          ),
+        cwd: z
+          .string()
+          .optional()
+          .describe("the worktree you are working in; default is the server's cwd"),
+      },
+    },
+    async (args) => doAsk(args),
+  );
+
   server.registerTool(
     "pass",
     {
@@ -930,6 +1025,72 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "attach_file",
+    {
+      title: "Attach a file",
+      annotations: { ...ADDS, openWorldHint: true },
+      description:
+        "Upload a file that is not a picture — a log, a PDF, a CSV, a zip, up to 10MB — and get " +
+        "back the markdown line that points at it. For a guide body or a bug report: put the " +
+        "line there and publishing claims the file. It is private, so only people who can read " +
+        "that guide can download it; for something a reviewer must SEE, use attach_screenshot. " +
+        "Pictures belong to attach_screenshot, not here.",
+      inputSchema: {
+        file: z.string().describe("path to the file on this machine"),
+        name: z.string().default("").describe("label for the file; defaults to its filename"),
+      },
+    },
+    async ({ file, name }) => {
+      try {
+        const got = await passalong.attachFile(file, { name: name || "" });
+        return text(
+          `${JSON.stringify({ id: got.id, url: got.url, bytes: got.bytes }, null, 2)}\n\n` +
+            `Put this in the guide body:\n${got.markdown}`,
+        );
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "reply",
+    {
+      title: "Write to the agent",
+      annotations: ADDS,
+      description:
+        "A person's tool, for someone driving their work from an assistant: write to whoever " +
+        "holds a guide — an answer to a question it asked, or something you thought of since — " +
+        "or, when nobody holds it yet and it is yours, leave a note for whoever takes it. Plain " +
+        "text, 1000 characters. `files` are paths on this machine: a picture is drawn in the " +
+        "thread and anything else is a file to download. Only its author, whoever it is " +
+        "assigned to, or whoever holds it can write; the agent reads it the next time it " +
+        "checks in. Agents answering their own questions do not use this: they use ask and take.",
+      inputSchema: {
+        id: z.string().describe("passalong id"),
+        text: z.string().default("").describe("what to say; may be empty when attaching a file"),
+        files: z
+          .array(z.string())
+          .max(3)
+          .default([])
+          .describe("paths to up to three files or pictures to attach"),
+      },
+    },
+    async ({ id, text: said, files }) => {
+      try {
+        const r = await passalong.reply(id, said, { files });
+        return text(
+          r?.noted
+            ? `Nobody holds ${id} yet, so this is a note: whoever takes it is handed it first.`
+            : `Sent to whoever holds ${id}. It reads this the next time it checks in.`,
+        );
+      } catch (err) {
+        return failWith(err);
+      }
+    },
+  );
+
   server.registerTool(
     "publish_guide",
     {
@@ -1036,6 +1197,13 @@ export function buildServer() {
                     "they go under Problem, where a reader looks first",
                 ),
               title: z.string().describe("what is broken, in one line"),
+              summary: z
+                .string()
+                .optional()
+                .describe(
+                  "one or two plain sentences for a PERSON, no ids or paths: what is broken and " +
+                    "whether anyone needs to act. Defaults to the title",
+                ),
               problem: z
                 .string()
                 .describe(

package/src/passalong.js

@@ -16,6 +16,7 @@ import {
   serialize,
   stamp,
   stripPlaceholders,
+  unheldFields,
   validate,
 } from "./guide.js";
 import * as store from "./store.js";
@@ -60,7 +61,13 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   if (follows) guide.meta.parent = await resolveId(String(follows).trim());
   if (guide.meta.to && !guide.meta.team)
     throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
-  const errors = validate(guide);
+  const errors = [
+    ...unheldFields(markdown).map(
+      (k) =>
+        `frontmatter "${k}" holds more than a string or a list of strings, and it would be dropped — move it into the body (a fenced yaml block keeps it as written)`,
+    ),
+    ...validate(guide),
+  ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
   // A task stays a draft when it is shared. Draft is the column a task waits in until a person
@@ -474,6 +481,9 @@ export async function handIn(
           checks: checks.map((c) => ({
             check: c.check,
             ran: c.ran,
+            // What the agent says happened, in plain words, for the person's table. Left out when
+            // not said: the row then shows the line that was asked and keeps its run folded.
+            ...(c.says ? { says: c.says } : {}),
             // Only present on a check that was run. The server keeps them apart the same way.
             ...(verified(c) ? { cmd: c.cmd, exit: c.exit, ok: c.ok } : {}),
           })),
@@ -517,6 +527,23 @@ export async function pass(id, why, { cwd = process.cwd() } = {}) {
   });
 }
 
+/**
+ * Ask the person a question and wait, keeping what you hold. Not `pass`, which gives the work back,
+ * and not `progress`, which says carry on: the answer to this one is "stop, and take it again when
+ * they have replied", and the reply comes back with that `take`.
+ */
+export async function ask(id, question, { cwd = process.cwd() } = {}) {
+  needsSync("asking");
+  if (!String(question || "").trim())
+    throw new PassalongError("say what you need to know, so the person can answer it");
+  const fence = fenceFor(id, cwd);
+  return api.ask(id, {
+    agent: agent(cwd).agent,
+    question,
+    ...(fence === undefined ? {} : { fence }),
+  });
+}
+
 /**
  * What this worktree's agent holds right now, and what is waiting for it: what the session-start
  * and stop hooks read (src/hooks.js). `held` is null when it holds nothing. Counts are best effort
@@ -548,7 +575,7 @@ export async function now({ cwd = process.cwd() } = {}) {
       x.mine &&
       (x.state === "review" ||
         x.state === "stalled" ||
-        (x.state === "claimed" && /^BLOCKED:/i.test(x.claim?.note || ""))),
+        (x.state === "claimed" && (x.claim?.asking || /^BLOCKED:/i.test(x.claim?.note || "")))),
   ).length;
   const handed = h.status === "fulfilled" ? h.value.handed_in.length : 0;
   return { held, waiting, needs: review + handed + waiting.inbox, agent: who.agent };
@@ -724,6 +751,64 @@ export async function attach(file, { name = "" } = {}) {
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
 }
 
+/**
+ * What a file's extension suggests it is. A hint only: the server reads the bytes and decides, and
+ * refuses what it does not keep. It exists so a `.csv` is filed as CSV and not as generic text.
+ */
+const FILE_HINTS = {
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".csv": "text/csv",
+  ".json": "application/json",
+  ".md": "text/markdown",
+};
+
+/** The most the server keeps of one file. Mirrors ATTACH_MAX in apps/api/src/attachments.ts. */
+const FILE_MAX = 10 * 1024 * 1024;
+
+/**
+ * Attach a file that is not a picture — a log, a PDF, a CSV, a zip — and return the markdown line that
+ * points at it. For a guide body or a bug report, where an agent has the file and nothing else to
+ * show it with. It is private: whoever can read the guide can download it, and nobody else can, so
+ * it is not evidence on a page that travels by link.
+ */
+export async function attachFile(file, { name = "" } = {}) {
+  if (!api.loggedIn())
+    throw new PassalongError("attaching a file needs sync — run `passalong login` first");
+  if (!existsSync(file)) throw new PassalongError(`no file at ${file}`);
+  const bytes = readFileSync(file);
+  if (!bytes.length) throw new PassalongError(`${file} is empty`);
+  if (bytes.length > FILE_MAX)
+    throw new PassalongError(
+      `${file} is ${Math.round(bytes.length / 1024 / 1024)}MB and the limit is 10MB — send a link instead`,
+    );
+  const ext = file.includes(".") ? file.slice(file.lastIndexOf(".")).toLowerCase() : "";
+  const label = (name || basename(file)).replace(/[[\]()]/g, "");
+  const attachment = await api.uploadFile(bytes, FILE_HINTS[ext] || "", name || basename(file));
+  return { ...attachment, markdown: `[${label}](${attachment.url})` };
+}
+
+/**
+ * Write to whoever holds a guide, or leave a note on one nobody holds yet: an answer to a question,
+ * or something thought of since. `files` are paths — a picture is uploaded as one and drawn in the
+ * thread, anything else as a file to download — and each becomes a line of the message. The server
+ * decides who may write and whether anyone is listening, and says so in words.
+ */
+export async function reply(ref, text, { files = [] } = {}) {
+  needsSync("replying");
+  const lines = [];
+  for (const file of files) {
+    const ext = file.includes(".") ? file.slice(file.lastIndexOf(".")).toLowerCase() : "";
+    const got = SHOT_TYPES[ext] ? await attach(file) : await attachFile(file);
+    lines.push(got.markdown);
+  }
+  const body = [String(text || "").trim(), ...lines].filter(Boolean).join("\n");
+  if (!body) throw new PassalongError("say something, or attach a file");
+  return api.reply(await resolveId(ref), body);
+}
+
 /**
  * The line a guide arrives with, saying what a follow-up is and how to write one.
  *
@@ -908,13 +993,40 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * "Correction: …" instead, because measurements, commands and commit ids do not fit in a tweet.
  * The first line is the summary a row shows; the whole thing is what the guide shows.
  */
-export async function verdict(id, ok, note = "") {
+export async function verdict(id, ok, note = "", { images = [] } = {}) {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
   const said = note.trim();
   if (!ok && !said)
     throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  // "It works" is shown, not said: the server refuses one with no screenshot of it working, so
+  // the refusal is said here before anything is uploaded, in the words of the command that fixes it.
+  if (ok && !images.length && !/\/v1\/shots\/[a-z0-9]{6,16}/.test(said))
+    throw new PassalongError(
+      "show it working: passalong works <id> <screenshot.png> [what you checked]",
+    );
+  const guide = await resolveId(id);
+  const shots = [];
+  for (const file of images) shots.push((await attach(file)).markdown);
   const line = said.split("\n")[0].slice(0, 280);
-  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
+  const detail = [said.length > line.length || shots.length ? said : "", ...shots]
+    .filter(Boolean)
+    .join("\n");
+  return api.verdict(guide, ok, line, detail);
+}
+
+/**
+ * The words after `passalong works <id>`, split into the screenshots and the note: an argument is a
+ * screenshot when it names an image file that exists, and everything else is what was checked.
+ */
+export function proofArgs(args) {
+  const images = [];
+  const words = [];
+  for (const a of args) {
+    const ext = a.slice(a.lastIndexOf(".")).toLowerCase();
+    if (SHOT_TYPES[ext] && existsSync(a)) images.push(a);
+    else words.push(a);
+  }
+  return { images, note: words.join(" ") };
 }
 
 /**
@@ -1010,7 +1122,14 @@ export async function planTasks(steps, { cwd = process.cwd() } = {}) {
       ...section("Acceptance", step.acceptance),
       ...section("Out of scope", step.out_of_scope),
     ].join("\n");
-    const meta = { title: step.title, kind: "task", target_context: step.target_context ?? repo };
+    // The summary is the step's own, said by whoever planned it: it is what a person reads about the
+    // task, and this builds the document without guessing one (the server refuses a task without).
+    const meta = {
+      title: step.title,
+      summary: step.summary,
+      kind: "task",
+      target_context: step.target_context ?? repo,
+    };
     const after = (step.after || []).map((j) => ids[j]);
     if (after.length) meta.blocked_by = after;
     ids.push((await share(serialize({ meta, body }), { cwd })).guide.meta.id);