passalong 0.3.1 → 0.5.0

package/src/passalong.js

@@ -1,6 +1,9 @@
 // The operations Passalong exposes. Both surfaces (bin/passalong and the MCP server) call these,
 // so anything an agent can do through MCP a human can do from the terminal and vice versa.
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { basename, join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
@@ -59,7 +62,10 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   const errors = validate(guide);
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
-  if (guide.meta.status === "draft")
+  // A task stays a draft when it is shared. Draft is the column a task waits in until a person
+  // says it is ready for an agent — `ready()` — and an agent that drafts one over MCP comes
+  // through here too, so publishing on share would let a task queue itself with nobody reading it.
+  if (guide.meta.status === "draft" && guide.meta.kind !== "task")
     guide = { ...guide, meta: { ...guide.meta, status: "published" } };
 
   let url = guide.meta.url || null;
@@ -190,19 +196,231 @@ export async function pull(ref, { cwd = process.cwd(), write = true } = {}) {
   }
   let path = null;
   if (write) {
-    const dir = join(cwd, ".passalong");
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    // A pulled guide carries its own share URL in the frontmatter, and that URL needs no account
-    // to read. Committing this directory would publish the guide to anyone who can see the repo,
-    // so the directory ignores itself. Delete this file if you do want guides in the repo.
-    const ignore = join(dir, ".gitignore");
-    if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
-    path = join(dir, `${guide.meta.id}.md`);
+    path = join(localDir(cwd), `${guide.meta.id}.md`);
     writeFileSync(path, serialize(guide));
   }
   return { guide, from, path, markdown: serialize(guide) };
 }
 
+/**
+ * `.passalong/` in a working directory, made if it is missing.
+ *
+ * A pulled guide carries its own share URL in the frontmatter, and that URL needs no account to
+ * read. Committing this directory would publish the guide to anyone who can see the repo, so the
+ * directory ignores itself. Delete its .gitignore if you do want guides in the repo.
+ */
+function localDir(cwd) {
+  const dir = join(cwd, ".passalong");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const ignore = join(dir, ".gitignore");
+  if (!existsSync(ignore)) writeFileSync(ignore, "*\n");
+  return dir;
+}
+
+/**
+ * Who this worktree is to the task queue, minted the first time it asks.
+ *
+ * A claim belongs to an agent, not an account: one person runs several, and "no two agents on one
+ * task" means nothing if the server cannot tell them apart. The id lives in the worktree's own
+ * `.passalong/agent.json`, so a restarted session in the same worktree is the same agent and gets
+ * its task back, and a second worktree of the same repo is a different agent. Per machine would
+ * let two worktrees on one laptop share a lock; per session would lose the task on every restart.
+ */
+export function agent(cwd = process.cwd()) {
+  const c = context(cwd);
+  const root = c.root || cwd;
+  const file = join(localDir(root), "agent.json");
+  let id = "";
+  try {
+    id = String(JSON.parse(readFileSync(file, "utf8")).id || "");
+  } catch {}
+  if (!/^[a-z0-9]{8,64}$/.test(id)) {
+    id = randomBytes(12).toString("hex");
+    writeFileSync(file, `${JSON.stringify({ id }, null, 2)}\n`);
+  }
+  return { agent: id, host: hostname(), repo: c.repo, worktree: root };
+}
+
+/** This worktree's agent if it has one, without creating it. `agent` is "" when there is none. */
+function knownAgent(cwd = process.cwd()) {
+  const c = context(cwd);
+  const root = c.root || cwd;
+  let id = "";
+  try {
+    id = String(JSON.parse(readFileSync(join(root, ".passalong", "agent.json"), "utf8")).id || "");
+  } catch {}
+  return { agent: /^[a-z0-9]{8,64}$/.test(id) ? id : "", repo: c.repo };
+}
+
+function needsSync(what) {
+  if (!api.loggedIn())
+    throw new PassalongError(
+      `${what} needs sync — the queue lives on the server (run \`passalong login\`)`,
+    );
+}
+
+/** Every task you can see, with where it is and who has it. */
+export async function tasks() {
+  needsSync("the task queue");
+  return (await api.tasks()).tasks;
+}
+
+/**
+ * Take the next task for this worktree's repo, or get back the one this worktree already holds.
+ * `null` when there is nothing to do. The guide is written to `.passalong/<id>.md` like a pull.
+ */
+export async function nextTask({ cwd = process.cwd(), any = false } = {}) {
+  needsSync("taking a task");
+  const { task } = await api.nextTask({ ...agent(cwd), any });
+  if (!task) return null;
+  const guide = parse(task.markdown);
+  const path = join(localDir(agent(cwd).worktree), `${task.id}.md`);
+  writeFileSync(path, task.markdown);
+  store.save(guide);
+  return { ...task, path };
+}
+
+/** Word from the agent holding a task: renews its lease, and `note` becomes the board's line. */
+export async function taskProgress(id, note, { cwd = process.cwd() } = {}) {
+  needsSync("reporting progress");
+  const { agent: a } = agent(cwd);
+  return api.taskProgress(id, note ? { agent: a, note } : { agent: a });
+}
+
+/**
+ * The work is done: the task moves to review with a transfer guide about it attached.
+ *
+ * Pass `markdown` and this writes that guide too, with `parent:` naming the task, so the write-up
+ * and the finish are one step and neither can be skipped or pointed at the wrong guide. Pass
+ * `report` instead when the guide is already published.
+ */
+export async function finishTask(
+  id,
+  { report, markdown, pr = "", note = "", cwd = process.cwd() } = {},
+) {
+  needsSync("finishing a task");
+  if (!report && markdown) {
+    const g = parse(markdown);
+    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
+      .guide.meta.id;
+  }
+  if (!report)
+    throw new PassalongError(
+      "finishing needs the write-up: `markdown` for a transfer guide about the work, or `report` with the id of one",
+    );
+  return api.finishTask(id, { agent: agent(cwd).agent, report, pr, note });
+}
+
+/**
+ * The four verbs every guide answers to, whatever its kind (docs/V2.md §11). Each answer carries
+ * `next`, the calls that make sense from here, and `say` when the move is to stop.
+ *
+ * take: this worktree's agent takes guide `id`, or with no id the next one waiting for it. The
+ * document is written to `.passalong/<id>.md`, like a pull, so the agent works from a file.
+ */
+export async function take(id, { cwd = process.cwd(), any = false } = {}) {
+  needsSync("taking work");
+  const who = agent(cwd);
+  const r = await api.take({ ...who, ...(id ? { id: await resolveId(id) } : {}), any });
+  if (!r.guide?.markdown) return r;
+  const path = join(localDir(who.worktree), `${r.guide.id}.md`);
+  writeFileSync(path, r.guide.markdown);
+  store.save(parse(r.guide.markdown));
+  return { ...r, path };
+}
+
+/** Word from the agent that holds it: the lease starts again, and `note` is what the hub shows. */
+export async function progress(id, note, { cwd = process.cwd() } = {}) {
+  needsSync("reporting progress");
+  return api.progress(id, { agent: agent(cwd).agent, ...(note ? { note } : {}) });
+}
+
+/**
+ * Done here. A task hands in a write-up — `markdown`, published with `parent:` naming the task, or
+ * `report`, the id of one already published — for its author to review against Acceptance. Any
+ * other guide hands in whether its Verification held: `ok`, and a `note` when it did not.
+ */
+export async function handIn(
+  id,
+  { ok, note = "", markdown, report, pr = "", cwd = process.cwd() } = {},
+) {
+  needsSync("handing work in");
+  if (!report && markdown) {
+    const g = parse(markdown);
+    report = (await share(serialize({ meta: { ...g.meta, parent: id }, body: g.body }), { cwd }))
+      .guide.meta.id;
+  }
+  return api.handIn(id, {
+    agent: agent(cwd).agent,
+    note,
+    ...(report ? { report, pr } : {}),
+    ...(typeof ok === "boolean" ? { ok } : {}),
+  });
+}
+
+/** Not this agent's to do: what it held is open again, and `why` goes to whoever is next. */
+export async function pass(id, why, { cwd = process.cwd() } = {}) {
+  needsSync("passing work");
+  if (!String(why || "").trim())
+    throw new PassalongError("say why you are passing it, so whoever is next knows");
+  return api.pass(id, { agent: agent(cwd).agent, why });
+}
+
+/**
+ * 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
+ * — a hook must never fail a session over a count.
+ */
+export async function now({ cwd = process.cwd() } = {}) {
+  needsSync("seeing what you hold");
+  // Read, never minted: the hooks run in every repo a session opens, and a worktree that has never
+  // taken anything has no agent — and should not be given a .passalong/ folder for asking.
+  const who = knownAgent(cwd);
+  const { working } = await api.working();
+  const held = (who.agent && working.find((w) => w.agent === who.agent && w.by?.you)) || null;
+  const waiting = { ready: 0, inbox: 0 };
+  if (!held) {
+    const [t, i] = await Promise.allSettled([api.tasks(), api.inbox()]);
+    if (t.status === "fulfilled")
+      waiting.ready = t.value.tasks.filter(
+        (x) => x.state === "ready" && x.target === who.repo,
+      ).length;
+    if (i.status === "fulfilled") waiting.inbox = i.value.guides.length;
+  }
+  return { held, waiting, agent: who.agent };
+}
+
+/**
+ * The gate, a person's three answers to a task. Approve: the work in review is done. Reject: it
+ * goes back to Ready with `why` on it for the next agent. Release: a task an agent holds, live or
+ * stalled, goes back to Ready with a note saying where that agent left it.
+ *
+ * The local copy is dropped after each, so the next read of the task fetches what the server made
+ * of it — a reject or a release rewrites the document, and a stale copy would hide exactly the
+ * line the next reader needs.
+ */
+export async function approveTask(id) {
+  needsSync("approving a task");
+  const r = await api.approveTask(id);
+  store.remove(id);
+  return r;
+}
+
+export async function rejectTask(id, why) {
+  needsSync("rejecting a task");
+  if (!String(why || "").trim()) throw new PassalongError("say why: the next agent reads it");
+  const r = await api.rejectTask(id, why);
+  store.remove(id);
+  return r;
+}
+
+export async function releaseTask(id) {
+  needsSync("releasing a task");
+  const r = await api.releaseTask(id);
+  store.remove(id);
+  return r;
+}
+
 /**
  * Pull a guide *and* take the handoff: the two halves of starting work, in one call.
  *
@@ -252,9 +470,8 @@ export function handoffNudge(meta = {}) {
   if (!meta.to && !meta.team) return "";
   return (
     "<!-- passalong: this guide was handed to someone. If you are about to do the work, call " +
-    "start_guide instead of get_guide — it takes the handoff so the sender stops guessing. " +
-    "If you are only reading, or it turns out not to be yours, answer with ack_guide taken=false " +
-    "and a reason. -->"
+    "take instead of get_guide — it takes the handoff so the sender stops guessing. " +
+    "If you are only reading, or it turns out not to be yours, answer with pass with a reason. -->"
   );
 }
 
@@ -296,6 +513,85 @@ export async function attach(file, { name = "" } = {}) {
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
 }
 
+/**
+ * The line a guide arrives with, saying what a follow-up is and how to write one.
+ *
+ * A follow-up is more context for a guide, written as its own guide with `parent` naming the
+ * original — a missing detail, a step that needed explaining, what changed since, what someone
+ * 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.
+ *
+ * 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
+ * context worth adding is usually the fix, when it is worth repeating somewhere else: that is a
+ * transfer guide, and the bug is what it adds context to.
+ */
+export function followUpNote(meta = {}) {
+  if (!meta.id) return "";
+  if (meta.kind === "bug")
+    return (
+      "<!-- passalong: once this is fixed, if the fix is worth repeating somewhere else, that is " +
+      "more context for this bug: publish it as a transfer guide with publish_guide " +
+      `parent=${meta.id}, and whoever opens this bug gets it too. -->`
+    );
+  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. -->"
+  );
+}
+
+/** What heads a guide's follow-ups when they are handed to an agent. Same words on both servers. */
+export const FOLLOW_UPS_LEAD =
+  "FOLLOW-UPS — more context added to this guide, oldest first. Read them before acting; where " +
+  "one contradicts the original, the follow-up is newer.";
+
+/**
+ * A guide's follow-ups as the server lists them, oldest first, or [] when there are none, when
+ * sync is off, or when anything goes wrong. Context is never worth failing a pull over: the guide
+ * itself is what was asked for, and it is already in hand.
+ *
+ * Only with sync, because follow-ups live on the server and are scoped to what this account can
+ * read — the same condition `resolve()` uses to look a guide up there. Fetching them records no
+ * pull on them: reading context for a guide is not opening those guides.
+ *
+ * `markdown` asks for each one's content too (capped server-side). The api calls are injectable
+ * so this can be tested without a network.
+ */
+export async function followUpGuides(
+  meta = {},
+  { markdown = false, children = api.children, loggedIn = api.loggedIn } = {},
+) {
+  if (!meta.id || !loggedIn()) return [];
+  try {
+    const { guides = [] } = await children(meta.id, { markdown });
+    const listed = (Array.isArray(guides) ? guides : []).filter((g) => g?.id);
+    // With content the server already sends oldest first; the plain listing is newest first.
+    return markdown ? listed : listed.reverse();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A guide's follow-ups with their content, formatted to go after the document for an agent — the
+ * same shape the remote server's get_guide returns — or "" when there are none.
+ */
+export async function followUps(meta = {}, deps = {}) {
+  const guides = (await followUpGuides(meta, { ...deps, markdown: true })).filter(
+    (g) => typeof g.markdown === "string",
+  );
+  if (!guides.length) return "";
+  return [
+    FOLLOW_UPS_LEAD,
+    ...guides.map(
+      (g) => `--- follow-up ${g.id}: ${g.title || "untitled"} ---\n${g.markdown.trimEnd()}`,
+    ),
+  ].join("\n\n");
+}
+
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
 export async function list(query = "", { remote = true, scope = "" } = {}) {
   const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);
@@ -400,11 +696,149 @@ export async function setStatus(id, status) {
     throw new PassalongError(`status must be one of ${STATUSES.join(", ")}`);
   const { guide } = await resolve(id);
   const next = { ...guide, meta: { ...guide.meta, status } };
-  store.save(next);
+  // The server first. Saved the other way round, a refusal left the local copy saying what the
+  // server had just refused — a teammate's `ready` on someone else's task read as done here.
   if (api.loggedIn() && guide.meta.url) await api.setStatus(id, status);
+  store.save(next);
   return next;
 }
 
+/**
+ * Move a task from Draft to Ready: a person has read it and an agent may take it.
+ *
+ * Only tasks. Every other kind is published the moment it is shared, so "ready" on one would
+ * either do nothing or reopen something archived under a name that does not say so.
+ */
+export async function ready(id) {
+  const { guide } = await resolve(id);
+  if (guide.meta.kind !== "task")
+    throw new PassalongError(`${guide.meta.id || id} is not a task — ready is for tasks in Draft`);
+  if (guide.meta.status !== "draft")
+    throw new PassalongError(`${guide.meta.id} is not in Draft (status: ${guide.meta.status})`);
+  return setStatus(guide.meta.id, "published");
+}
+
+/**
+ * One goal as several tasks, written as drafts in order. Each step may name the earlier steps it
+ * needs by position (`after: [0, 1]`), and those become its `blocked_by`, so the queue hands them
+ * out in an order that works and runs the independent ones side by side.
+ *
+ * Only earlier steps: a step that waits on itself or on a later one is a plan that never finishes,
+ * and it is refused before anything is written rather than discovered as a queue that never moves.
+ * Every step lands in Draft — a wrong decomposition is several agents building the wrong thing at
+ * once, so a person reads the plan before any of it runs.
+ */
+export async function planTasks(steps, { cwd = process.cwd() } = {}) {
+  if (!Array.isArray(steps) || !steps.length)
+    throw new PassalongError("a plan needs at least one step");
+  steps.forEach((step, i) => {
+    for (const j of step.after || [])
+      if (!Number.isInteger(j) || j < 0 || j >= i)
+        throw new PassalongError(
+          `step ${i} ("${step.title}") can only wait on an earlier step, not ${j}`,
+        );
+  });
+  const repo = context(cwd).repo;
+  const ids = [];
+  for (const step of steps) {
+    const section = (name, text) =>
+      String(text || "").trim() ? [`## ${name}`, String(text).trim(), ""] : [];
+    const body = [
+      ...section("Goal", step.goal),
+      ...section("Context", step.context),
+      ...section("Constraints", step.constraints),
+      ...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 };
+    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);
+  }
+  return ids;
+}
+
+/** What an agent started by `work()` is told. The task itself goes in too, so it cannot start blind. */
+export function workPrompt(t) {
+  return [
+    `You hold passalong task ${t.id}, and no other agent can take it while you do.`,
+    `It is written to ${t.path}; here it is:`,
+    "",
+    t.markdown.trim(),
+    "",
+    "Do it in this repo. There are no Steps: work out how to reach Goal within Constraints, and",
+    "leave Out of scope alone. Call the passalong MCP tool progress with id",
+    `${t.id} and a one-line status at each milestone — 30 minutes of silence stalls the task.`,
+    "When every Acceptance check holds, commit what you changed as one commit whose message",
+    `starts with "${t.id}: " — several tasks share this worktree, and a reviewer reads each one's`,
+    "change on its own. Then call hand_in with id",
+    `${t.id}, \`pr\` set to that commit's hash, and \`markdown\`: a transfer guide saying what you`,
+    "did, what you decided and why, and how you checked each Acceptance line. If either call",
+    "says you no longer hold the task, stop.",
+    "",
+    "Nobody reads what you print: this session runs unattended. If something only a person can",
+    "do stands between you and an Acceptance line — a permission, a secret, a decision — call",
+    `progress with id ${t.id} and a note starting "BLOCKED: " that says exactly what you`,
+    "need, leave the task unfinished and uncommitted, and stop. The board shows that note.",
+  ].join("\n");
+}
+
+/**
+ * Work the queue from this worktree: take the next task, hand it to an agent, and when the agent
+ * has finished it take the next, until there is nothing left.
+ *
+ * The agent runs in this worktree, so it is the same agent to the queue — its progress and
+ * hand_in land on the claim this took. `agent` is a command the prompt is appended to;
+ * `claude -p` by default, or whatever PASSALONG_AGENT says.
+ *
+ * An agent that exits without finishing stops the loop. Asking for the next task would hand the
+ * same one back, since a worktree holds one task at a time, and the loop would run the agent on it
+ * forever. The task stays claimed here, for the next run to resume or a person to release.
+ */
+export async function work({
+  cwd = process.cwd(),
+  agent = process.env.PASSALONG_AGENT || "claude -p",
+  any = false,
+  once = false,
+  onTask = () => {},
+} = {}) {
+  needsSync("working the queue");
+  const [command, ...args] = agent.trim().split(/\s+/);
+  const finished = [];
+  for (;;) {
+    const t = await nextTask({ cwd, any });
+    if (!t) return { finished, stopped: "empty" };
+    onTask(t);
+    const run = spawnSync(command, [...args, workPrompt(t)], {
+      cwd,
+      stdio: "inherit",
+      env: { ...process.env, PASSALONG_TASK: t.id, PASSALONG_TASK_PATH: t.path },
+    });
+    const state = (await tasks()).find((x) => x.id === t.id)?.state;
+    if (state !== "review")
+      return {
+        finished,
+        stopped: "unfinished",
+        task: t.id,
+        state,
+        exit: run.status ?? run.error?.message,
+      };
+    finished.push(t.id);
+    if (once) return { finished, stopped: "once" };
+  }
+}
+
+/**
+ * Make every task you wrote that is still in Draft ready, and return their ids. For the moment a
+ * planner has written several and you have read them all. Only your own: moving a task into the
+ * queue is its author's call.
+ */
+export async function readyDrafts() {
+  const drafts = (await tasks()).filter((t) => t.mine && t.state === "draft");
+  for (const t of drafts) await ready(t.id);
+  return drafts.map((t) => t.id);
+}
+
 export async function remove(id) {
   // Server first: if it refuses (not the author), the local copy must survive too.
   if (api.loggedIn()) {