passalong 0.9.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.9.0",
+  "version": "0.12.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

@@ -1,7 +1,18 @@
 // Client for the hosted sync API (apps/api). Everything here is optional: with no token the
 // CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
+import { readFileSync } from "node:fs";
 import { readConfig } from "./store.js";
 
+/**
+ * This build's version, sent on every authenticated call as `x-passalong-version`. The server
+ * refuses a CLI below its floor (apps/api/src/clients.ts), because the rules it enforces deploy on
+ * merge and the text telling an agent how to follow them only arrives with a reinstall.
+ */
+export const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+const CLIENT = { "x-passalong-version": VERSION };
+
 export const DEFAULT_API = "https://passalong.dev";
 
 export class ApiError extends Error {
@@ -24,7 +35,7 @@ export function loggedIn() {
 }
 
 async function call(path, { method = "GET", body, auth = true, raw = false } = {}) {
-  const headers = {};
+  const headers = { ...CLIENT };
   if (auth) {
     const t = token();
     if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
@@ -220,7 +231,7 @@ export const ack = (id, taken, note = "") =>
 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");
-  const headers = { authorization: `Bearer ${t}`, "content-type": type };
+  const headers = { ...CLIENT, authorization: `Bearer ${t}`, "content-type": type };
   // A header is latin-1: a filename with an accent in it throws on the way out rather than at the
   // server, and the label is not worth failing an upload over.
   if (name) headers["x-shot-name"] = String(name).replace(/[^\x20-\x7e]/g, "");

package/src/guide.js

@@ -127,8 +127,22 @@ export function sectionsFor(kind) {
 }
 
 /** The sections it cannot be published without. */
+/**
+ * The sections a kind cannot do without, and the one that has none.
+ *
+ * A transfer is context exchange. Context is whatever the next agent needs to not start cold —
+ * a decision and why, a constraint, where the bodies are — and none of that arrives in six fixed
+ * headings. Requiring `## Problem` and `## Steps` made every short note into a document: of 56
+ * follow-ups in real use, the ones that fill this template average 599 words and ten of sixteen
+ * were never opened by anyone, while the ones that ignored it average 137 words and every single
+ * one was opened. The template was not raising the floor, it was padding to reach it.
+ *
+ * A task and a bug keep theirs, because theirs are not prose. `## Acceptance` is the list a
+ * hand-in answers line by line, and `## Reproduce` is how a reader sees the defect. Those earn
+ * their requirement by being read mechanically; `## Steps` on a piece of context does not.
+ */
 const REQUIRED = {
-  transfer: ["Problem", "Steps"],
+  transfer: [],
   bug: ["Problem", "Reproduce"],
   task: ["Goal", "Acceptance"],
 };
@@ -255,10 +269,21 @@ export function parseFrontmatter(text) {
   // Only the lists every guide has. `blocked_by` is a task's, and defaulting it would write an
   // empty one into every guide anybody re-shares.
   for (const k of ["stack_assumptions", "tags"]) if (meta[k] === undefined) meta[k] = [];
-  // What it is, said rather than inferred. An unknown spelling is left alone for `validate()` to
-  // refuse by name: quietly turning `kind: buggy` into a transfer guide is the same guess this is
-  // here to remove.
-  if (!String(meta.kind ?? "").trim()) meta.kind = "transfer";
+  // Absent is absent. It is NOT a transfer guide.
+  //
+  // This line, and the sentence publish_guide tells every agent — "kind: task (the default)" —
+  // disagreed for thirteen days. An agent that left `kind:` off, believing what it had been told,
+  // got a transfer guide. 162 of 200 guides in real use are labelled transfer; their titles are
+  // tasks and bug reports. Everything downstream followed from that: a transfer has no states, so
+  // nothing could show as in progress; it demands Problem and Steps, so a two-line correction was
+  // padded to six sections; and there is nowhere to report into one, so agents published a second
+  // guide to carry what they had found.
+  //
+  // So it stays empty and `validate()` refuses it by name. The back-compat this default protected
+  // is a guide written before kinds existed being re-shared; that guide is re-shared once with an
+  // explicit `kind: transfer`, which is a sentence its author can write, unlike thirteen days of
+  // mislabelled work nobody could see.
+  meta.kind = String(meta.kind ?? "").trim();
   // Both ends of this module: what it reads and what it writes are in one style, so a guide
   // written before there was a rule comes back normalised and goes out normalised.
   meta.tags = tagList(meta.tags);
@@ -305,6 +330,10 @@ export function serializeFrontmatter(meta) {
   ];
   const out = [];
   for (const key of keys) {
+    // A kind nobody stated is left unstated. Writing `kind: ""` would put an answer in the
+    // document that its author never gave, and the next parse would read it back as a stated
+    // empty rather than an absent one — which is the whole distinction validate() turns on.
+    if (key === "kind" && !String(meta[key] ?? "").trim()) continue;
     const v = key === "tags" ? tagList(meta[key]) : meta[key];
     if (Array.isArray(v)) {
       out.push(v.length ? `${key}: [${v.map(quote).join(", ")}]` : `${key}: []`);
@@ -497,8 +526,9 @@ export function bugGuide({
 
 /** A draft with the section skeleton. Placeholders are HTML comments so they vanish when rendered. */
 export function template(meta = {}) {
-  // A task unless asked otherwise: most guides assign work. The transfer skeleton writes its kind
-  // out, since an absent kind: still means transfer to every client already installed.
+  // A task unless asked otherwise: most guides assign work. Every skeleton writes its kind out —
+  // absent is now refused rather than read as transfer, so a template that left it off would
+  // produce a document its own author could not publish.
   if (meta.kind === "bug") return bugTemplate(meta);
   if (meta.kind !== "transfer") return taskTemplate(meta);
   const body = [

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
@@ -206,7 +261,9 @@ 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" +
-        `kind: task (the default) is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
+        "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(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
         "alone, and treat Acceptance as the definition of done. hand_in with `markdown`: a " +
         "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
@@ -326,7 +383,19 @@ export function buildServer() {
     }
   }
 
-  async function doHandIn({ id, ok, note, evidence, checks, writeup, markdown, report, pr, cwd }) {
+  async function doHandIn({
+    id,
+    ok,
+    note,
+    evidence,
+    checks,
+    writeup,
+    risk,
+    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
@@ -347,6 +416,7 @@ export function buildServer() {
         evidence: evidence || "",
         checks: done.checks,
         writeup: writeup || "",
+        risk: risk || "",
         markdown,
         report,
         pr: pr || "",
@@ -686,14 +756,16 @@ 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(
             "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",
+              "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"),
@@ -706,6 +778,15 @@ export function buildServer() {
               "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",
           ),
+        risk: z
+          .string()
+          .optional()
+          .describe(
+            "what this could break, in one line — the part of a PR template's Risk that is " +
+              "worth reading: a shared helper changed, a migration that cannot be undone, a " +
+              "route other clients call. Optional; leave it out when there is nothing specific, " +
+              'rather than writing "low risk". Its author reads it before accepting the work',
+          ),
         markdown: z
           .string()
           .optional()
@@ -801,19 +882,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,
@@ -357,8 +358,16 @@ export async function finishTask(
   requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
-    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
-      .guide.meta.id;
+    // A task's report is a transfer guide, and this code is what is making one — so it says so
+    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
+    // agent's hand-in because its write-up left a line off would be this function's omission
+    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
+    // author's to leave open, because the caller already knows the answer.
+    report = (
+      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
+        cwd,
+      })
+    ).guide.meta.id;
   }
   if (!report)
     throw new PassalongError(
@@ -413,6 +422,7 @@ export async function handIn(
     evidence = "",
     checks = [],
     writeup = "",
+    risk = "",
     markdown,
     report,
     pr = "",
@@ -420,6 +430,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.
@@ -427,8 +452,16 @@ export async function handIn(
   else requireEvidence(evidence);
   if (!report && markdown) {
     const g = parse(markdown);
-    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
-      .guide.meta.id;
+    // A task's report is a transfer guide, and this code is what is making one — so it says so
+    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
+    // agent's hand-in because its write-up left a line off would be this function's omission
+    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
+    // author's to leave open, because the caller already knows the answer.
+    report = (
+      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
+        cwd,
+      })
+    ).guide.meta.id;
   }
   const fence = fenceFor(id, cwd);
   return api.handIn(id, {
@@ -450,6 +483,8 @@ export async function handIn(
     // 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 } : {}),
+    // What it could break, for the reviewer. Left out when empty, like the write-up.
+    ...(risk ? { risk } : {}),
     ...(typeof ok === "boolean" ? { ok } : {}),
   });
 }
@@ -635,6 +670,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");
@@ -657,6 +732,11 @@ export async function attach(file, { name = "" } = {}) {
  * found doing it. Whoever opens the original, person or agent, gets its follow-ups with it, which
  * is why context belongs there rather than in a one-line verdict note.
  *
+ * What an agent did and found working on the guide is not context for it: that is the hand-in,
+ * and the note says so. It used to list "what you found doing it" among the things to publish, on
+ * every `take`, while hand_in said a follow-up was not for answering — the agent followed the one
+ * it read last, and the author got a second guide to review with the evidence inside it.
+ *
  * Trailing, like the handoff nudge, so it never sits in front of the frontmatter. It is here and
  * not only in the server's instructions because an agent reads the payload it is working from and
  * skims everything else — the same reason the bug lead is inside the document. For a bug, the
@@ -673,9 +753,10 @@ export function followUpNote(meta = {}) {
     );
   return (
     "<!-- passalong: a follow-up is more context for this guide, written as its own guide. If " +
-    "this guide needs more — a missing detail, a step that needed explaining, what changed since, " +
-    `what you found doing it — publish that with publish_guide parent=${meta.id}, and whoever ` +
-    "opens this guide gets it too. -->"
+    "this guide needs more — a missing detail, a step that needed explaining, what changed since " +
+    `— publish that with publish_guide parent=${meta.id}, and whoever opens this guide gets it ` +
+    "too. What you did and found working on it is not a follow-up: it goes on hand_in, in " +
+    "`checks` and `writeup`. -->"
   );
 }