passalong 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.9.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/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
@@ -686,14 +741,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"),
@@ -801,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,
@@ -420,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.
@@ -635,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");