passalong 0.8.0 → 0.11.0

package/bin/passalong

@@ -12,7 +12,7 @@
 //   passalong work [--once] [--agent CMD]  run an agent on each ready task here, one after another
 //   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 a task back from the agent holding it, stalled or not
+//   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 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"
@@ -332,8 +332,12 @@ const commands = {
 
   async release(f) {
     const id = f._[0] || die("usage: passalong release <id>");
-    await passalong.releaseTask(id).catch((e) => die(e.message));
-    console.error(`${id} is back in Ready — it says where the last agent left it`);
+    const r = await passalong.release(id).catch((e) => die(e.message));
+    const from = Number(r?.from) || 1;
+    console.error(
+      `${id} is back in Ready${from > 1 ? `, taken back from ${from} places` : ""}` +
+        " — whoever had it has been told",
+    );
   },
 
   async ready(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",

package/src/api.js

@@ -176,8 +176,11 @@ export const setStatus = (id, status) =>
   call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
 export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
 /** Does it actually work? `note` is required when it does not. */
-export const verdict = (id, ok, note = "") =>
-  call(`/v1/guides/${id}/verdict`, { method: "PUT", body: { ok, note } });
+export const verdict = (id, ok, note = "", detail = "") =>
+  call(`/v1/guides/${id}/verdict`, {
+    method: "PUT",
+    body: { ok, note, ...(detail ? { detail } : {}) },
+  });
 
 export const tasks = () => call("/v1/tasks");
 export const nextTask = (body) => call("/v1/tasks/next", { method: "POST", body });
@@ -189,8 +192,9 @@ export const approveTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/approve`, { method: "POST", body: {} });
 export const rejectTask = (id, why) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/reject`, { method: "POST", body: { why } });
-export const releaseTask = (id) =>
-  call(`/v1/tasks/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
+/** Take work back from whoever holds it, of any kind. `/v1/tasks/…/release` is the old path. */
+export const release = (id) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
 /** The four verbs every guide answers to. See docs/V2.md §11. */
 export const working = () => call("/v1/working");
 export const handedIn = () => call("/v1/handed_in");

package/src/mcp.js

@@ -29,11 +29,62 @@ const text = (s) => ({ content: [{ type: "text", text: s }] });
  * evidence is collected while the work happens, not reconstructed from memory once it is done.
  * Mirrors KEEP_EVIDENCE in apps/api/src/mcp-http.ts.
  */
+const WHERE_THE_LINE_GOES =
+  "WHERE THE LINE GOES DEPENDS ON WHAT THE IMAGE IS EVIDENCE OF. Proof that work you are handing i" +
+  "n holds — a screen that renders right, a total that matches — goes in that check's `ran` on han" +
+  "d_in, and nothing is published: a check answered with a picture is shown, which is what the han" +
+  "d-in asks for. Only an image that is part of a DOCUMENT goes in a guide body — the screenshot i" +
+  "n a bug report, a diagram a guide is explaining — and then it must be in the markdown, because " +
+  "a guide travels as markdown to whoever holds its link and evidence beside the document does not" +
+  " travel at all; publishing claims whatever the markdown names, so attach first and publish afte" +
+  "r. DO NOT PUBLISH A GUIDE TO CARRY SCREENSHOTS. Six images and a caption each is a hand-in, not" +
+  " a document, and wrapping them in Problem / Solution shape / Decisions / Steps / Verification t" +
+  "o make them publishable is how a set of pictures becomes fifteen hundred words nobody asked for" +
+  ". png, jpg, webp or gif.";
+
+/**
+ * What a screenshot has to be a screenshot OF.
+ *
+ * "A check is run or shown" made a picture mandatory, and an agent short of one built a page to
+ * photograph: it added `src/app/notes-preview`, shot that, then `rm -rf`'d it and published the
+ * shots as evidence that the real screen rendered. The rule was satisfied and almost nothing was
+ * proved — the measure had become the target, and the page the picture showed no longer existed.
+ *
+ * Mirrors SHOOT_THE_REAL_THING in apps/api/src/mcp-http.ts.
+ */
+const SHOOT_THE_REAL_THING =
+  "SHOOT THE RUNNING THING, NOT SOMETHING YOU BUILT TO SHOOT. A screenshot is worth what the sc" +
+  "reen behind it is worth: the real route in the real app, reached the way a reader would reac" +
+  "h it. A scratch page, a story, a harness or a component rendered on its own is a picture of " +
+  "your scaffolding, and it can look right while the thing the guide is about does not. If the " +
+  "only way you could get a picture was to build something, that is not evidence the real scree" +
+  "n works — say what you built and why in `writeup`, and leave the check to the commands that " +
+  "do hold. NEVER DELETE WHAT YOUR EVIDENCE POINTS AT: a shot of a page you removed afterwards " +
+  "is one nobody can take again, including you.";
+
 const KEEP_EVIDENCE =
   "KEEP YOUR EVIDENCE AS YOU GO. hand_in needs it: the commands you ran and what came back, the " +
   "test summary, the link to the change. Copy each one when it happens — at the end you will be " +
   "writing from memory, which is the thing evidence is here to replace.\n\n";
 
+/**
+ * Said in front of every guide an agent has to locate things in for itself — a bug and a task.
+ *
+ * The failure it is here to stop: an agent lists one directory, or opens the one file it expected,
+ * and concludes from that. It then reports that a thing is absent, or that it found the only
+ * occurrence, having never looked past the place it happened to start. The conclusion is confident
+ * and wrong, and nothing downstream can tell, because the evidence it brings is real — it is just
+ * evidence of a search that was too small.
+ *
+ * Mirrors SEARCH_WIDE in apps/api/src/mcp-http.ts.
+ */
+const SEARCH_WIDE =
+  "SEARCH THE WHOLE TREE BEFORE YOU CONCLUDE. Listing a directory, or reading the one file you " +
+  "expected, tells you what is in that directory — not whether the thing exists, and not whether " +
+  "you have found all of it. Before you report that something is absent, is the only one, or is " +
+  'already handled, search across the repository and let the output be your reason. "I looked" ' +
+  "is a claim; the search and what it printed is evidence.\n\n";
+
 /**
  * What to say in front of a guide whose kind changes what the reader should do with it.
  *
@@ -48,6 +99,8 @@ function leadFor(meta) {
       "THIS IS A BUG REPORT, NOT WORK TO REPEAT. Do not follow Reproduce as instructions " +
       "— those steps produce the defect. Fix what Problem describes, then check " +
       "Verification and answer with hand_in.\n\n" +
+      SEARCH_WIDE +
+      SHOOT_THE_REAL_THING +
       KEEP_EVIDENCE
     );
   if (meta.kind === "task")
@@ -57,6 +110,8 @@ function leadFor(meta) {
       "under Acceptance holds. Opening it here does not make it yours: to work on it, call take " +
       "with its id in the repo it is for, so no other agent can. Then progress, and hand_in " +
       "with a write-up.\n\n" +
+      SEARCH_WIDE +
+      SHOOT_THE_REAL_THING +
       KEEP_EVIDENCE
     );
   // A transfer guide is handed over untouched: it is a document to follow, and anything in front
@@ -326,7 +381,7 @@ export function buildServer() {
     }
   }
 
-  async function doHandIn({ id, ok, note, evidence, checks, markdown, report, pr, cwd }) {
+  async function doHandIn({ id, ok, note, evidence, checks, writeup, markdown, report, pr, cwd }) {
     try {
       // A check that names a command is run here, before anything is recorded, and its exit code
       // decides it rather than the agent's account of it. A failure is refused with the command's
@@ -346,6 +401,7 @@ export function buildServer() {
         note: note || "",
         evidence: evidence || "",
         checks: done.checks,
+        writeup: writeup || "",
         markdown,
         report,
         pr: pr || "",
@@ -640,18 +696,22 @@ export function buildServer() {
       outputSchema: handInOut,
       annotations: ADDS,
       description:
-        "Done here, with proof. Every hand-in carries what you ran and what came back. On a TASK " +
-        "send `checks`: one entry per Acceptance line, each with that line and the evidence for " +
-        "it — that is what its author reads, line against line, instead of hunting through a wall " +
-        "of output for the part that answers each one. Give a check `cmd` when a command proves " +
-        "it: the command is run here before the hand-in lands, a non-zero exit refuses it, and " +
-        "what it printed is recorded instead of your account of it. Use `ran` for a check no " +
-        "command can settle. `evidence` is the same thing as one block, " +
-        "for a handoff or a bug, which have no Acceptance lines. A task also takes `markdown`, a " +
-        "transfer guide about what you did and decided — this publishes it and attaches it. A " +
-        "handoff or a bug takes `ok`, whether its Verification held here, and `note` saying what " +
-        "went wrong when it did not. More context than a note holds goes in a follow-up: " +
-        "publish_guide with `parent` set to this id.",
+        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a " +
+        "bug — each with that line and the evidence for it. That is what its author reads, line " +
+        "against line, instead of hunting through a wall of output for the part that answers each " +
+        "one, AND IT IS HOW YOU KNOW YOU ARE DONE: every line has one. Give a check `cmd` when a " +
+        "command proves it: the command is run here before the hand-in lands, a non-zero exit " +
+        "refuses it, and what it printed is recorded instead of your account of it. Use `ran` for " +
+        "a check no command can settle. `evidence` as one block is the older shape and still " +
+        "works. A task also takes `markdown`, a transfer guide about what you did and decided — " +
+        "this publishes it and attaches it. A handoff or a bug takes `ok`, whether its " +
+        "Verification held here, and `note` saying what went wrong when it did not. DO NOT " +
+        "publish a guide to carry your evidence: it belongs on this call, and a second document " +
+        'titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you ' +
+        "had to adapt something, that goes in `writeup` and the next reader of the guide is shown " +
+        "it — that is its home. A follow-up guide is for work somebody else should now do, not " +
+        "for answering.",
       inputSchema: {
         id: z.string().describe("passalong id"),
         evidence: z
@@ -664,7 +724,12 @@ export function buildServer() {
         checks: z
           .array(
             z.object({
-              check: z.string().describe("the Acceptance line this answers, in the task's words"),
+              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",
+                ),
               ran: z
                 .string()
                 .optional()
@@ -676,14 +741,28 @@ export function buildServer() {
                   "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", and write `ran` instead',
+                    '"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("task: one entry per Acceptance line, in the order you worked them"),
+          .describe(
+            "one entry per line the guide asks for — Acceptance on a task, Verification on a " +
+              "handoff or a bug — in the order you worked them. Each is RUN (`cmd`) or SHOWN (an " +
+              "attach_screenshot line in `ran`). Pasting a command you typed into `ran` is not " +
+              "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"),
+        writeup: z
+          .string()
+          .optional()
+          .describe(
+            "handoff or bug: what you had to adapt to make it work here — a version, a name, a " +
+              "step that needed something the guide does not mention. Prose, and optional: leave " +
+              "it out when it worked as written. The next person to open the guide is shown it, " +
+              "which is why it does not need to be a guide of its own",
+          ),
         markdown: z
           .string()
           .optional()
@@ -779,19 +858,44 @@ export function buildServer() {
       title: "Attach a screenshot",
       annotations: { ...ADDS, openWorldHint: true },
       description:
-        "Upload an image from this machine as evidence, and get back the markdown line that " +
-        "points at it. Put that line in the guide body — a guide travels as markdown to whoever " +
-        "holds its link, so evidence beside the document does not travel at all. Publishing " +
-        "claims whatever the markdown names, so attach first and publish after. png, jpg, webp " +
-        "or gif.",
+        "Upload an image as evidence — a path in `file`, or the bytes in `data` when you have " +
+        "the image and no file — and get back the markdown line that points at it. " +
+        WHERE_THE_LINE_GOES,
       inputSchema: {
-        file: z.string().describe("path to the image on this machine"),
+        file: z
+          .string()
+          .default("")
+          .describe("path to the image on this machine; leave out when sending `data`"),
+        data: z
+          .string()
+          .default("")
+          .describe(
+            "the image itself, base64 (a data: URL is fine), for when you have the bytes and no " +
+              "file — a browser tool that hands back an image inline and never writes to disk. " +
+              "5MB; larger belongs in create_upload",
+          ),
+        type: z
+          .string()
+          .default("image/png")
+          .describe("media type of `data`: image/png, image/jpeg, image/webp or image/gif"),
         name: z.string().default("").describe("label for the image; defaults to its filename"),
       },
     },
-    async ({ file, name }) => {
+    async ({ file, data, type, name }) => {
       try {
-        const shot = await passalong.attach(file, { name: name || "" });
+        if (!file && !data) {
+          return fail(
+            new Error(
+              "send `file` (a path on this machine) or `data` (the image, base64). If your " +
+                "screenshot is a tool result you cannot write out, capture it to a file instead " +
+                "— a headless browser's page.screenshot({ path }) or your platform's capture " +
+                "command — and pass that path.",
+            ),
+          );
+        }
+        const shot = data
+          ? await passalong.attachBytes(data, { name: name || "", type: type || "image/png" })
+          : await passalong.attach(file, { name: name || "" });
         return text(
           `${JSON.stringify({ id: shot.id, url: shot.url, bytes: shot.bytes }, null, 2)}\n\n` +
             `Put this in the guide body:\n${shot.markdown}`,

package/src/passalong.js

@@ -7,6 +7,7 @@ import { hostname } from "node:os";
 import { basename, join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
+import { refusal, runChecks } from "./checks.js";
 import {
   bugGuide,
   ID_RE,
@@ -412,6 +413,7 @@ export async function handIn(
     note = "",
     evidence = "",
     checks = [],
+    writeup = "",
     markdown,
     report,
     pr = "",
@@ -419,6 +421,21 @@ export async function handIn(
   } = {},
 ) {
   needsSync("handing work in");
+  // A check that names a command is run here, before anything is sent.
+  //
+  // The MCP server did this and this function did not, so "put the command in `cmd` and it is
+  // executed here" was true over one transport and a quiet lie over the other: a `cmd` handed to
+  // this function was passed along as a string nothing had executed. Checks that already carry an
+  // exit came from the server's own runner and are left alone, so nothing runs twice.
+  const pending = checks.filter((c) => c?.cmd && typeof c?.exit !== "number" && c?.exit !== null);
+  if (pending.length) {
+    const done = runChecks(pending, { cwd });
+    const byCheck = new Map(done.checks.map((c) => [c.check, c]));
+    checks = checks.map((c) => byCheck.get(c.check) ?? c);
+    if (done.failed) {
+      throw new Error(refusal(done.failed, { ran: done.ran, total: checks.length }));
+    }
+  }
   // Checks are evidence, sorted against the lines they answer: bringing them is bringing it. A
   // check whose command was actually run is exempt from the length rule — its exit code is the
   // evidence, and `test -f dist/app.js` exiting 0 says more than any sentence about it would.
@@ -446,6 +463,9 @@ export async function handIn(
         }
       : {}),
     ...(report ? { report, pr } : {}),
+    // Left out when there is nothing to say, rather than sent as "": most hand-ins have nothing
+    // to adapt, and the field is for the ones that do.
+    ...(writeup ? { writeup } : {}),
     ...(typeof ok === "boolean" ? { ok } : {}),
   });
 }
@@ -539,9 +559,16 @@ export async function rejectTask(id, why) {
   return r;
 }
 
-export async function releaseTask(id) {
-  needsSync("releasing a task");
-  const r = await api.releaseTask(id);
+/**
+ * Take it back from whoever is holding it — a task, a handoff or a bug, and from all of them at
+ * once when several people hold the same handoff in different repos.
+ *
+ * It was tasks only, which left an asymmetry nobody chose: the author of a handoff could mark it
+ * done or give it to somebody else, and had no way to simply have it back.
+ */
+export async function release(id) {
+  needsSync("taking work back");
+  const r = await api.release(id);
   store.remove(id);
   return r;
 }
@@ -624,6 +651,46 @@ export const SHOT_TYPES = {
  * Local because it reads a path. An agent in a terminal has one; a hosted assistant does not, and
  * reaches the same route through `attach_screenshot` on the HTTP server instead.
  */
+/**
+ * The same upload, for an agent that has the image and not a path to it.
+ *
+ * `attach()` takes a path because a screenshot usually lands on disk. An agent driving a browser
+ * often has the opposite: the pane hands back an image as a tool result and never writes a file, so
+ * the only door into evidence was one it could not open. It did what anyone would — swapped to
+ * `grep` and `tsc` checks and put what it saw in `writeup` — and said so itself: "a grep proves the
+ * code changed, not that the screen renders right."
+ *
+ * Base64 in a tool call, which the HTTP server's instructions rightly warn against, because there
+ * the alternative is `create_upload` and a curl. Here there is no alternative for bytes held in
+ * memory, and this server is a local process talking to the same upload the file path uses.
+ */
+export async function attachBytes(data, { name = "", type = "image/png" } = {}) {
+  if (!api.loggedIn())
+    throw new PassalongError("attaching evidence needs sync — run `passalong login` first");
+  const allowed = new Set(Object.values(SHOT_TYPES));
+  if (!allowed.has(type))
+    throw new PassalongError(`screenshots must be ${[...allowed].join(", ")} — ${type} is not one`);
+  let bytes;
+  try {
+    // A data: URL is what several browser tools hand back, so it is accepted rather than made the
+    // caller's problem to strip.
+    bytes = Buffer.from(String(data).replace(/^data:[^,]*,/, ""), "base64");
+  } catch {
+    throw new PassalongError("`data` is not base64");
+  }
+  if (!bytes.length) throw new PassalongError("`data` decoded to nothing");
+  // The server's own ceiling, checked here so a large paste fails before it is sent rather than
+  // after. Anything bigger belongs in create_upload, which streams from a file.
+  if (bytes.length > 5 * 1024 * 1024)
+    throw new PassalongError(
+      `that image is ${Math.round(bytes.length / 1024 / 1024)}MB and the limit is 5MB — ` +
+        "write it to a file and use create_upload, which streams",
+    );
+  const label = name || "screenshot";
+  const shot = await api.uploadShot(bytes, type, label);
+  return { ...shot, markdown: `![${label}](${shot.url})` };
+}
+
 export async function attach(file, { name = "" } = {}) {
   if (!api.loggedIn())
     throw new PassalongError("attaching evidence needs sync — run `passalong login` first");
@@ -808,11 +875,21 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
  * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
  */
+/**
+ * Say whether a guide held, and why at the length that takes.
+ *
+ * The reason used to be one field, capped at 280 characters by the row it was written for — so an
+ * agent that had run the Verification and found it did not hold published a guide called
+ * "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 = "") {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
-  if (!ok && !note.trim())
-    throw new PassalongError("say what went wrong: passalong failed <id> <what happened>");
-  return api.verdict(await resolveId(id), ok, note.trim());
+  const said = note.trim();
+  if (!ok && !said)
+    throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  const line = said.split("\n")[0].slice(0, 280);
+  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
 }
 
 /**