plures 1.15.0 → 1.16.0

package/README.md

@@ -44,10 +44,12 @@ if (event.type === "task.completed" && event.data.result?.agreement === 1) {
 
 ## API
 
+- `plures.check(id, data, overrides?)`: run a check from your app's map, one line before the action it guards: `const check = await plures.check("refunds", { order_total, reason }); if (check.answer !== "Approve") return`. The check saved on Plures supplies the question, options, which fields people see (the rest come back in `kept_private`), who decides, how often, its conditions and what happens on a timeout, so you change them on Plures, not in code. `checked` says whether a person looked; `skipped_because` says why not. Overrides: `question`, `options`, `verifiers`, `team`, `route`, `sample`, `timeout`, `always`.
+- `npx plures check add <id> --app <app>`: Claude Code puts that line before the action on a new branch. On GitHub (the dashboard's **Add it to my code**) Plures then opens a pull request.
 - `plures.tasks.create(params, { idempotencyKey? })`: send a task. Params: `question`, `options` (2 to 8, strings or `{ id, label }`), `context`, `image_url`, `audio_url` or `video_url` with `media_seconds` (a clip up to 180 seconds that people play through before answering), `sensitive`, `instructions`, `verifiers` (1, 3, 5, 7 or 9), `max_verifiers`, `presence_check` (default true), `webhook_url`, `metadata`, `expires_in`, `route` (`"team"` sends it straight to your own people, $0.05 per internal vote live), `category` (matches your routing rules) and `team` (one of your named teams), `team_votes` and `team_unanimous` (internal consensus: how many of your team vote, and whether they must all agree; a split goes to the team's lead).
 - `plures.tasks.retrieve(id)`, `plures.tasks.list({ status?, limit?, starting_after?, app? })`, `plures.tasks.cancel(id)`
 - `new Plures(key, { app: "support-agent" })` or `PLURES_APP`: send everything to one of your apps. `plures.apps.list()`, `.create({ name, id? })`, `.retrieve(id)`, `.update(id, { name?, id?, default? })`, `.del(id)`. Each app keeps its own tasks, ledger view, map and quality.
-- `plures.maps.guide()`, `.retrieve(app)`, `.upload(app, map)`, `.setCheckpoint(app, id, status)`: the agent map, where your agent needs a person. Or run `npx plures map` in your repo: your own coding agent reads the code and only the map is sent.
+- `plures.maps.guide()`, `.retrieve(app)`, `.upload(app, map, { branch? })` (a branch other than main gets its own map, compared with main and noted on its pull request), `.setCheckpoint(app, id, status)`: the agent map, where your agent needs a person. Or run `npx plures map` in your repo: your own coding agent reads the code and only the map is sent.
 - `plures.maps.createKey(app, { label? })`, `.keys(app)`, `.revokeKey(app, id)`: map keys for CI, which can only read and upload that app's map. `.workflow(app, branch?)` returns the GitHub Action that maps on every push; `npx plures map workflow` writes it to `.github/workflows/plures-map.yml`. Or use **Map with GitHub** on the app's map page and Plures opens the pull request for you, then **Turn on mapping** merges it. `plures.maps.startRun(app)` and `.runs(app)`: in CI with no Claude key, `npx plures map` starts a run where Plures runs Claude (first map free, then Claude's cost plus 30%, at most $5).
 - In your terminal, `npx plures map` opens your map page so you can watch it build (`--no-open` to skip), keeps one live line of what it's reading, and ends by drawing the map's flows with the checks Plures suggests. On GitHub and other CI it prints a plain log.
 - `npx plures map` shows each file as Claude Code reads it and sends the file names (never their contents) to Plures, so the map page shows the reading live and the map builds itself when it lands. `plures.maps.progress(app, { session, phase, events })` is the call behind it.

package/dist/{chunk-JSR4MDEK.js → chunk-Z75ZTXHZ.js}

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.15.0";
+var VERSION = "1.16.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -100,7 +100,8 @@ var Plures = class {
     },
     retrieve: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map`),
     /** Uploads a new version. Checks you already added or dismissed keep that. */
-    upload: (app, map) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map),
+    /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+    upload: (app, map, opts = {}) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map, opts.branch ? { "plures-branch": opts.branch } : {}),
     setCheckpoint: (app, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app)}/map/checkpoints/${encodeURIComponent(id)}`, { status }),
     /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
     createKey: (app, opts = {}) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_keys`, opts),
@@ -111,6 +112,8 @@ var Plures = class {
     runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
     /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
     progress: (app, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map/progress`, p),
+    /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+    checkPr: (app, id, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/checks/${encodeURIComponent(id)}/pr`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app, branch = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(branch)}`);
@@ -168,6 +171,32 @@ var Plures = class {
   };
   /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
   balance = () => this.req("GET", "/api/v1/balance");
+  /**
+   * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+   * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+   * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+   * overridden for this call. `answer` is the option to act on: what people chose, the first option
+   * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+   * when it timed out set to hold.
+   */
+  async check(id, data = {}, overrides = {}, opts = {}) {
+    const t = await this.req("POST", `/api/v1/checks/${encodeURIComponent(id)}`, { data, ...overrides }, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {});
+    const final = t.status === "pending" ? await this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+    const opt = (k) => final.options.find((o) => o.id === k)?.label ?? k ?? null;
+    const first = final.options[0]?.label ?? null;
+    const timedOut = final.status === "expired" || final.status === "pending";
+    const answer = final.status === "completed" ? opt(final.result?.answer) : final.status === "skipped" ? first : timedOut && t.on_timeout === "proceed" ? first : null;
+    return {
+      ...final,
+      check: t.check,
+      on_timeout: t.on_timeout,
+      kept_private: t.kept_private ?? [],
+      skipped_because: t.skipped_because ?? null,
+      answer,
+      checked: final.status !== "skipped",
+      timed_out: timedOut
+    };
+  }
   /** Creates a task and waits for people to answer it. */
   async verify(params, opts = {}) {
     const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });

package/dist/cli.cjs

@@ -30,7 +30,7 @@ var import_node_path = require("path");
 var import_node_fs = require("fs");
 
 // src/index.ts
-var VERSION = "1.15.0";
+var VERSION = "1.16.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -131,7 +131,8 @@ var Plures = class {
     },
     retrieve: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map`),
     /** Uploads a new version. Checks you already added or dismissed keep that. */
-    upload: (app2, map2) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app2)}/map`, map2),
+    /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+    upload: (app2, map2, opts = {}) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app2)}/map`, map2, opts.branch ? { "plures-branch": opts.branch } : {}),
     setCheckpoint: (app2, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app2)}/map/checkpoints/${encodeURIComponent(id)}`, { status }),
     /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
     createKey: (app2, opts = {}) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/map_keys`, opts),
@@ -142,6 +143,8 @@ var Plures = class {
     runs: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map_runs`),
     /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
     progress: (app2, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/map/progress`, p),
+    /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+    checkPr: (app2, id, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/checks/${encodeURIComponent(id)}/pr`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app2, branch2 = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app2)}&branch=${encodeURIComponent(branch2)}`);
@@ -199,6 +202,32 @@ var Plures = class {
   };
   /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
   balance = () => this.req("GET", "/api/v1/balance");
+  /**
+   * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+   * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+   * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+   * overridden for this call. `answer` is the option to act on: what people chose, the first option
+   * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+   * when it timed out set to hold.
+   */
+  async check(id, data = {}, overrides = {}, opts = {}) {
+    const t = await this.req("POST", `/api/v1/checks/${encodeURIComponent(id)}`, { data, ...overrides }, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {});
+    const final = t.status === "pending" ? await this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+    const opt = (k) => final.options.find((o) => o.id === k)?.label ?? k ?? null;
+    const first = final.options[0]?.label ?? null;
+    const timedOut = final.status === "expired" || final.status === "pending";
+    const answer = final.status === "completed" ? opt(final.result?.answer) : final.status === "skipped" ? first : timedOut && t.on_timeout === "proceed" ? first : null;
+    return {
+      ...final,
+      check: t.check,
+      on_timeout: t.on_timeout,
+      kept_private: t.kept_private ?? [],
+      skipped_because: t.skipped_because ?? null,
+      answer,
+      checked: final.status !== "skipped",
+      timed_out: timedOut
+    };
+  }
   /** Creates a task and waits for people to answer it. */
   async verify(params, opts = {}) {
     const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
@@ -446,11 +475,19 @@ async function upload(file) {
   }
   if (!fancy) console.log(dim(`Sending the map to Plures. No source code is sent.`));
   let m;
+  const gitBranch = (0, import_node_child_process.spawnSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).stdout?.trim();
+  const branchName = process.env.PLURES_BRANCH || process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || (gitBranch && gitBranch !== "HEAD" ? gitBranch : "");
   try {
-    m = await client().maps.upload(app, map2);
+    m = await client().maps.upload(app, map2, branchName ? { branch: branchName } : {});
   } catch (e) {
     die(e instanceof PluresError ? `Plures said: ${e.message}` : String(e));
   }
+  if (m.branch) console.log(`${bold(`Branch ${m.branch}`)}: compared with the main map${m.main_version ? ` (version ${m.main_version})` : ""}, not replacing it.${m.pull_request ? ` Noted on ${m.pull_request}` : ""}`);
+  if (m.changes && (m.changes.added.length || m.changes.removed.length || m.changes.renamed.length || m.changes.risky.length)) {
+    const c2 = m.changes;
+    console.log(`${dim("Changes:")} ${[c2.added.length ? `${c2.added.length} new` : "", c2.renamed.length ? `${c2.renamed.length} renamed, checks kept` : "", c2.removed.length ? `${c2.removed.length} removed` : ""].filter(Boolean).join(", ") || "no new actions"}`);
+    for (const r of c2.risky) console.log(`  ${coral("no check")}  ${r.label} ${dim(`score ${r.score}: ${r.why.join("; ")}`)}`);
+  }
   if (fancy) drawMap(m, m.url ?? `${base}/dashboard/apps/${m.app}/map`);
   else report(m);
 }
@@ -669,8 +706,87 @@ It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plur
     throw e;
   }
 }
+async function checkAdd(id) {
+  if (!id) die("npx plures check add <check id> [--app <app>]");
+  const cl = client();
+  const report2 = async (p) => {
+    if (process.env.GITHUB_ACTIONS) await cl.maps.checkPr(app, id, p).catch(() => {
+    });
+  };
+  const fail = async (msg) => {
+    await report2({ error: msg });
+    die(msg);
+  };
+  let m;
+  try {
+    m = await cl.maps.retrieve(app);
+  } catch (e) {
+    return fail(e instanceof PluresError ? e.message : String(e));
+  }
+  const cp0 = m.checkpoints.find((x) => x.id === id || x.category === id);
+  const cp = cp0;
+  if (!cp0) return fail(`No check called ${id} on ${app}'s map.`);
+  const action = m.nodes.find((n) => n.id === cp.at);
+  const cid = cp.id ?? id;
+  if (!cp.code) return fail(`The check ${cid} has no drafted question yet. Edit it on Plures first.`);
+  if (!hasClaude()) return fail("Claude Code isn't installed here, so nothing could add the line. Copy it from the check's page instead.");
+  const git = (...a) => (0, import_node_child_process.spawnSync)("git", a, { encoding: "utf8" });
+  if (git("status", "--porcelain").stdout.trim()) return fail("This repo has changes that aren't committed. Commit or stash them first.");
+  const childEnv = { ...process.env };
+  const ownClaude = Boolean(process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_AUTH_TOKEN);
+  if (!ownClaude && process.env.CI) {
+    try {
+      const run = await cl.maps.startRun(app);
+      childEnv.ANTHROPIC_BASE_URL = run.base_url;
+      childEnv.ANTHROPIC_API_KEY = run.token;
+    } catch (e) {
+      return fail(e instanceof PluresError ? e.message : String(e));
+    }
+  }
+  const where = action?.file ? `${action.file}${action.line ? ` near line ${action.line}` : ""}` : "the code";
+  console.log(`Adding the check ${bold(cid)} before ${bold(action?.label ?? cp.at)}, in ${where}.`);
+  const prompt = `Add one Plures human check to this codebase. Change as little as possible.
+
+Where: just before the step "${action?.label ?? cp.at}"${action?.via ? ` (it goes through ${action.via})` : ""}, in ${where}. Find the exact place; the line may have moved.
+
+What to add, adapted to the file's language and style (for Python: \`check = plures.check("${cid}", fields)\` and \`check.answer\`):
+
+${cp.code}
+
+- fields: an object with the values a person needs to decide, taken from variables already in scope at that point${cp.draft?.show?.length ? `. Use these field names: ${cp.draft.show.join(", ")}` : ""}. Never pass secrets, card numbers or passwords.
+- If the answer isn't the first option, the agent must not do the step: return, skip, or raise, whichever fits the code around it.
+- If the file has no Plures client yet, add one: JavaScript or TypeScript \`import { Plures } from "plures"\` and \`const plures = new Plures(process.env.PLURES_API_KEY${app !== "default" ? `, { app: "${app}" }` : ""})\`; Python \`from plures import Plures\` and \`plures = Plures(os.environ["PLURES_API_KEY"]${app !== "default" ? `, app="${app}"` : ""})\`. Keep to how the project sets up other clients.
+- If the package isn't a dependency yet, add "plures" to package.json dependencies, or plures to requirements.txt or pyproject.toml, whichever the project uses. Don't run installers.
+- Don't change anything else, don't reformat, don't add tests, and don't run commands.`;
+  const code = await new Promise((resolve) => {
+    const p = (0, import_node_child_process.spawn)("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Edit,Write"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
+    p.on("close", (n) => resolve(n ?? 1));
+    p.on("error", () => resolve(1));
+  });
+  const changed = git("status", "--porcelain").stdout.trim();
+  if (code !== 0 || !changed) return fail("Claude Code didn't change any files, so there's nothing to review. Copy the line from the check's page instead.");
+  const br = `plures/check-${cid.replace(/[^a-z0-9_-]+/gi, "-")}-${Date.now().toString(36)}`;
+  for (const a of [["checkout", "-b", br], ["add", "-A"], ["commit", "-m", `Add the Plures check ${cid} before ${(action?.label ?? cp.at).toLowerCase()}`]]) {
+    const r = git(...a);
+    if (r.status !== 0) return fail(`git ${a[0]} failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
+  }
+  if (!process.env.GITHUB_ACTIONS) {
+    console.log(`
+${cyan("\u2713")} The check is on the branch ${bold(br)}. Review it with ${cyan("git show")}, then push it and open a pull request.`);
+    return;
+  }
+  const push = git("push", "-u", "origin", br);
+  if (push.status !== 0) return fail(`Pushing the branch failed: ${(push.stderr || push.stdout).trim().slice(0, 200)}`);
+  try {
+    const r = await cl.maps.checkPr(app, cid, { branch: br });
+    console.log(`${cyan("\u2713")} Pull request: ${r.pull_request ?? "opened"}`);
+  } catch (e) {
+    die(e instanceof PluresError ? e.message : String(e));
+  }
+}
 async function main() {
   const [cmd, sub, arg] = argv;
+  if (cmd === "check" && sub === "add") return checkAdd(arg);
   if (cmd !== "map") {
     console.log(`Plures
 
@@ -681,6 +797,7 @@ async function main() {
   npx plures map github connect        let Plures add that Action by pull request
   npx plures map github on             merge it, which turns mapping on
   npx plures map github run            map now on GitHub, and watch it build
+  npx plures check add <id>            put a check into your code, on a new branch
 
 Docs: https://plures.si/docs`);
     return;

package/dist/cli.js

@@ -3,7 +3,7 @@ import {
   Plures,
   PluresError,
   VERSION
-} from "./chunk-JSR4MDEK.js";
+} from "./chunk-Z75ZTXHZ.js";
 
 // src/cli.ts
 import { spawnSync, spawn } from "child_process";
@@ -228,11 +228,19 @@ async function upload(file) {
   }
   if (!fancy) console.log(dim(`Sending the map to Plures. No source code is sent.`));
   let m;
+  const gitBranch = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).stdout?.trim();
+  const branchName = process.env.PLURES_BRANCH || process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || (gitBranch && gitBranch !== "HEAD" ? gitBranch : "");
   try {
-    m = await client().maps.upload(app, map2);
+    m = await client().maps.upload(app, map2, branchName ? { branch: branchName } : {});
   } catch (e) {
     die(e instanceof PluresError ? `Plures said: ${e.message}` : String(e));
   }
+  if (m.branch) console.log(`${bold(`Branch ${m.branch}`)}: compared with the main map${m.main_version ? ` (version ${m.main_version})` : ""}, not replacing it.${m.pull_request ? ` Noted on ${m.pull_request}` : ""}`);
+  if (m.changes && (m.changes.added.length || m.changes.removed.length || m.changes.renamed.length || m.changes.risky.length)) {
+    const c2 = m.changes;
+    console.log(`${dim("Changes:")} ${[c2.added.length ? `${c2.added.length} new` : "", c2.renamed.length ? `${c2.renamed.length} renamed, checks kept` : "", c2.removed.length ? `${c2.removed.length} removed` : ""].filter(Boolean).join(", ") || "no new actions"}`);
+    for (const r of c2.risky) console.log(`  ${coral("no check")}  ${r.label} ${dim(`score ${r.score}: ${r.why.join("; ")}`)}`);
+  }
   if (fancy) drawMap(m, m.url ?? `${base}/dashboard/apps/${m.app}/map`);
   else report(m);
 }
@@ -451,8 +459,87 @@ It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plur
     throw e;
   }
 }
+async function checkAdd(id) {
+  if (!id) die("npx plures check add <check id> [--app <app>]");
+  const cl = client();
+  const report2 = async (p) => {
+    if (process.env.GITHUB_ACTIONS) await cl.maps.checkPr(app, id, p).catch(() => {
+    });
+  };
+  const fail = async (msg) => {
+    await report2({ error: msg });
+    die(msg);
+  };
+  let m;
+  try {
+    m = await cl.maps.retrieve(app);
+  } catch (e) {
+    return fail(e instanceof PluresError ? e.message : String(e));
+  }
+  const cp0 = m.checkpoints.find((x) => x.id === id || x.category === id);
+  const cp = cp0;
+  if (!cp0) return fail(`No check called ${id} on ${app}'s map.`);
+  const action = m.nodes.find((n) => n.id === cp.at);
+  const cid = cp.id ?? id;
+  if (!cp.code) return fail(`The check ${cid} has no drafted question yet. Edit it on Plures first.`);
+  if (!hasClaude()) return fail("Claude Code isn't installed here, so nothing could add the line. Copy it from the check's page instead.");
+  const git = (...a) => spawnSync("git", a, { encoding: "utf8" });
+  if (git("status", "--porcelain").stdout.trim()) return fail("This repo has changes that aren't committed. Commit or stash them first.");
+  const childEnv = { ...process.env };
+  const ownClaude = Boolean(process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_AUTH_TOKEN);
+  if (!ownClaude && process.env.CI) {
+    try {
+      const run = await cl.maps.startRun(app);
+      childEnv.ANTHROPIC_BASE_URL = run.base_url;
+      childEnv.ANTHROPIC_API_KEY = run.token;
+    } catch (e) {
+      return fail(e instanceof PluresError ? e.message : String(e));
+    }
+  }
+  const where = action?.file ? `${action.file}${action.line ? ` near line ${action.line}` : ""}` : "the code";
+  console.log(`Adding the check ${bold(cid)} before ${bold(action?.label ?? cp.at)}, in ${where}.`);
+  const prompt = `Add one Plures human check to this codebase. Change as little as possible.
+
+Where: just before the step "${action?.label ?? cp.at}"${action?.via ? ` (it goes through ${action.via})` : ""}, in ${where}. Find the exact place; the line may have moved.
+
+What to add, adapted to the file's language and style (for Python: \`check = plures.check("${cid}", fields)\` and \`check.answer\`):
+
+${cp.code}
+
+- fields: an object with the values a person needs to decide, taken from variables already in scope at that point${cp.draft?.show?.length ? `. Use these field names: ${cp.draft.show.join(", ")}` : ""}. Never pass secrets, card numbers or passwords.
+- If the answer isn't the first option, the agent must not do the step: return, skip, or raise, whichever fits the code around it.
+- If the file has no Plures client yet, add one: JavaScript or TypeScript \`import { Plures } from "plures"\` and \`const plures = new Plures(process.env.PLURES_API_KEY${app !== "default" ? `, { app: "${app}" }` : ""})\`; Python \`from plures import Plures\` and \`plures = Plures(os.environ["PLURES_API_KEY"]${app !== "default" ? `, app="${app}"` : ""})\`. Keep to how the project sets up other clients.
+- If the package isn't a dependency yet, add "plures" to package.json dependencies, or plures to requirements.txt or pyproject.toml, whichever the project uses. Don't run installers.
+- Don't change anything else, don't reformat, don't add tests, and don't run commands.`;
+  const code = await new Promise((resolve) => {
+    const p = spawn("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Edit,Write"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
+    p.on("close", (n) => resolve(n ?? 1));
+    p.on("error", () => resolve(1));
+  });
+  const changed = git("status", "--porcelain").stdout.trim();
+  if (code !== 0 || !changed) return fail("Claude Code didn't change any files, so there's nothing to review. Copy the line from the check's page instead.");
+  const br = `plures/check-${cid.replace(/[^a-z0-9_-]+/gi, "-")}-${Date.now().toString(36)}`;
+  for (const a of [["checkout", "-b", br], ["add", "-A"], ["commit", "-m", `Add the Plures check ${cid} before ${(action?.label ?? cp.at).toLowerCase()}`]]) {
+    const r = git(...a);
+    if (r.status !== 0) return fail(`git ${a[0]} failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
+  }
+  if (!process.env.GITHUB_ACTIONS) {
+    console.log(`
+${cyan("\u2713")} The check is on the branch ${bold(br)}. Review it with ${cyan("git show")}, then push it and open a pull request.`);
+    return;
+  }
+  const push = git("push", "-u", "origin", br);
+  if (push.status !== 0) return fail(`Pushing the branch failed: ${(push.stderr || push.stdout).trim().slice(0, 200)}`);
+  try {
+    const r = await cl.maps.checkPr(app, cid, { branch: br });
+    console.log(`${cyan("\u2713")} Pull request: ${r.pull_request ?? "opened"}`);
+  } catch (e) {
+    die(e instanceof PluresError ? e.message : String(e));
+  }
+}
 async function main() {
   const [cmd, sub, arg] = argv;
+  if (cmd === "check" && sub === "add") return checkAdd(arg);
   if (cmd !== "map") {
     console.log(`Plures
 
@@ -463,6 +550,7 @@ async function main() {
   npx plures map github connect        let Plures add that Action by pull request
   npx plures map github on             merge it, which turns mapping on
   npx plures map github run            map now on GitHub, and watch it build
+  npx plures check add <id>            put a check into your code, on a new branch
 
 Docs: https://plures.si/docs`);
     return;

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.15.0";
+var VERSION = "1.16.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -127,7 +127,8 @@ var Plures = class {
     },
     retrieve: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map`),
     /** Uploads a new version. Checks you already added or dismissed keep that. */
-    upload: (app, map) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map),
+    /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+    upload: (app, map, opts = {}) => this.req("PUT", `/api/v1/apps/${encodeURIComponent(app)}/map`, map, opts.branch ? { "plures-branch": opts.branch } : {}),
     setCheckpoint: (app, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app)}/map/checkpoints/${encodeURIComponent(id)}`, { status }),
     /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
     createKey: (app, opts = {}) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_keys`, opts),
@@ -138,6 +139,8 @@ var Plures = class {
     runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
     /** While mapping, which files the coding agent is reading, shown live on the map page. File names only. npx plures map does this. */
     progress: (app, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map/progress`, p),
+    /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+    checkPr: (app, id, p) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/checks/${encodeURIComponent(id)}/pr`, p),
     /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
     workflow: async (app, branch = "main") => {
       const r = await fetch(`${this.base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(branch)}`);
@@ -195,6 +198,32 @@ var Plures = class {
   };
   /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
   balance = () => this.req("GET", "/api/v1/balance");
+  /**
+   * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+   * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+   * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+   * overridden for this call. `answer` is the option to act on: what people chose, the first option
+   * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+   * when it timed out set to hold.
+   */
+  async check(id, data = {}, overrides = {}, opts = {}) {
+    const t = await this.req("POST", `/api/v1/checks/${encodeURIComponent(id)}`, { data, ...overrides }, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {});
+    const final = t.status === "pending" ? await this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+    const opt = (k) => final.options.find((o) => o.id === k)?.label ?? k ?? null;
+    const first = final.options[0]?.label ?? null;
+    const timedOut = final.status === "expired" || final.status === "pending";
+    const answer = final.status === "completed" ? opt(final.result?.answer) : final.status === "skipped" ? first : timedOut && t.on_timeout === "proceed" ? first : null;
+    return {
+      ...final,
+      check: t.check,
+      on_timeout: t.on_timeout,
+      kept_private: t.kept_private ?? [],
+      skipped_because: t.skipped_because ?? null,
+      answer,
+      checked: final.status !== "skipped",
+      timed_out: timedOut
+    };
+  }
   /** Creates a task and waits for people to answer it. */
   async verify(params, opts = {}) {
     const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });

package/dist/index.d.cts

@@ -4,6 +4,32 @@ type Option = {
 };
 /** "verifiers" asks ID verified people first; "team" goes straight to your own people ($0.05 per internal vote live). */
 type Route = "verifiers" | "team";
+type CheckOverrides = {
+    question?: string;
+    options?: string[];
+    instructions?: string;
+    verifiers?: number;
+    team?: string;
+    route?: "verifiers" | "team";
+    /** Check this one even if the sample or a condition would skip it. */ always?: boolean;
+    /** Share of calls people check, 0 to 1, for this call. */ sample?: number;
+    /** Seconds people have to answer. */ timeout?: number;
+    metadata?: Record<string, unknown>;
+    webhook_url?: string;
+};
+type CheckExtra = {
+    check: string;
+    on_timeout: "proceed" | "hold";
+    kept_private?: string[];
+    skipped_because?: string;
+};
+type CheckResult = Task & Omit<CheckExtra, "kept_private" | "skipped_because"> & {
+    /** The option to act on, by label. */ answer: string | null;
+    /** false when the check wasn't needed this time (a sample or a condition). */ checked: boolean;
+    timed_out: boolean;
+    kept_private: string[];
+    skipped_because: string | null;
+};
 type TaskStatus = "pending" | "completed" | "expired" | "canceled" | "skipped";
 type Result = {
     answer: string | null;
@@ -253,6 +279,30 @@ type MapKey = {
     created_at: string;
     last_used_at: string | null;
 };
+type MapChanges = {
+    since: number | null;
+    added: {
+        id: string;
+        label: string;
+        score: number | null;
+        checked: boolean;
+    }[];
+    removed: {
+        id: string;
+        label: string;
+    }[];
+    renamed: {
+        from: string;
+        to: string;
+        label: string;
+    }[];
+    risky: {
+        id: string;
+        label: string;
+        score: number;
+        why: string[];
+    }[];
+};
 type StoredAgentMap = AgentMap & {
     object: "agent_map";
     app: string;
@@ -260,6 +310,23 @@ type StoredAgentMap = AgentMap & {
     created_at?: string;
     via?: string;
     url?: string;
+    /** Set for a branch map: the branch, the main map version it's compared with, and its pull request. */
+    branch?: string;
+    main_version?: number | null;
+    pull_request?: string | null;
+    changes?: MapChanges;
+    engine?: {
+        version: string;
+        actions: Record<string, {
+            score: number;
+            factors: string[];
+            oversight: {
+                mode: string;
+                rate: number | null;
+                verifiers: number;
+            };
+        }>;
+    };
 };
 type Rubric = {
     object: "rubric";
@@ -352,7 +419,7 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.15.0";
+declare const VERSION = "1.16.0";
 type GitHubLink = {
     object: "github_link";
     app: string;
@@ -469,7 +536,10 @@ declare class Plures {
         guide: () => Promise<string>;
         retrieve: (app: string) => Promise<StoredAgentMap>;
         /** Uploads a new version. Checks you already added or dismissed keep that. */
-        upload: (app: string, map: AgentMap) => Promise<StoredAgentMap>;
+        /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+        upload: (app: string, map: AgentMap, opts?: {
+            branch?: string;
+        }) => Promise<StoredAgentMap>;
         setCheckpoint: (app: string, id: string, status: "added" | "dismissed" | "suggested") => Promise<StoredAgentMap>;
         /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
         createKey: (app: string, opts?: {
@@ -525,6 +595,17 @@ declare class Plures {
             phase: string;
             received: number;
         }>;
+        /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+        checkPr: (app: string, id: string, p: {
+            branch: string;
+        } | {
+            error: string;
+        }) => Promise<{
+            object: "check_pr";
+            check: string;
+            opened: boolean;
+            pull_request?: string;
+        }>;
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
@@ -654,6 +735,18 @@ declare class Plures {
     };
     /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
     balance: () => Promise<Balance>;
+    /**
+     * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+     * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+     * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+     * overridden for this call. `answer` is the option to act on: what people chose, the first option
+     * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+     * when it timed out set to hold.
+     */
+    check(id: string, data?: Record<string, unknown>, overrides?: CheckOverrides, opts?: {
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<CheckResult>;
     /** Creates a task and waits for people to answer it. */
     verify(params: CreateTask, opts?: {
         timeoutMs?: number;
@@ -667,4 +760,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type CheckOverrides, type CheckResult, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapChanges, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };

package/dist/index.d.ts

@@ -4,6 +4,32 @@ type Option = {
 };
 /** "verifiers" asks ID verified people first; "team" goes straight to your own people ($0.05 per internal vote live). */
 type Route = "verifiers" | "team";
+type CheckOverrides = {
+    question?: string;
+    options?: string[];
+    instructions?: string;
+    verifiers?: number;
+    team?: string;
+    route?: "verifiers" | "team";
+    /** Check this one even if the sample or a condition would skip it. */ always?: boolean;
+    /** Share of calls people check, 0 to 1, for this call. */ sample?: number;
+    /** Seconds people have to answer. */ timeout?: number;
+    metadata?: Record<string, unknown>;
+    webhook_url?: string;
+};
+type CheckExtra = {
+    check: string;
+    on_timeout: "proceed" | "hold";
+    kept_private?: string[];
+    skipped_because?: string;
+};
+type CheckResult = Task & Omit<CheckExtra, "kept_private" | "skipped_because"> & {
+    /** The option to act on, by label. */ answer: string | null;
+    /** false when the check wasn't needed this time (a sample or a condition). */ checked: boolean;
+    timed_out: boolean;
+    kept_private: string[];
+    skipped_because: string | null;
+};
 type TaskStatus = "pending" | "completed" | "expired" | "canceled" | "skipped";
 type Result = {
     answer: string | null;
@@ -253,6 +279,30 @@ type MapKey = {
     created_at: string;
     last_used_at: string | null;
 };
+type MapChanges = {
+    since: number | null;
+    added: {
+        id: string;
+        label: string;
+        score: number | null;
+        checked: boolean;
+    }[];
+    removed: {
+        id: string;
+        label: string;
+    }[];
+    renamed: {
+        from: string;
+        to: string;
+        label: string;
+    }[];
+    risky: {
+        id: string;
+        label: string;
+        score: number;
+        why: string[];
+    }[];
+};
 type StoredAgentMap = AgentMap & {
     object: "agent_map";
     app: string;
@@ -260,6 +310,23 @@ type StoredAgentMap = AgentMap & {
     created_at?: string;
     via?: string;
     url?: string;
+    /** Set for a branch map: the branch, the main map version it's compared with, and its pull request. */
+    branch?: string;
+    main_version?: number | null;
+    pull_request?: string | null;
+    changes?: MapChanges;
+    engine?: {
+        version: string;
+        actions: Record<string, {
+            score: number;
+            factors: string[];
+            oversight: {
+                mode: string;
+                rate: number | null;
+                verifiers: number;
+            };
+        }>;
+    };
 };
 type Rubric = {
     object: "rubric";
@@ -352,7 +419,7 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.15.0";
+declare const VERSION = "1.16.0";
 type GitHubLink = {
     object: "github_link";
     app: string;
@@ -469,7 +536,10 @@ declare class Plures {
         guide: () => Promise<string>;
         retrieve: (app: string) => Promise<StoredAgentMap>;
         /** Uploads a new version. Checks you already added or dismissed keep that. */
-        upload: (app: string, map: AgentMap) => Promise<StoredAgentMap>;
+        /** A branch other than the main one gets its own map, compared with main, and noted on its pull request. */
+        upload: (app: string, map: AgentMap, opts?: {
+            branch?: string;
+        }) => Promise<StoredAgentMap>;
         setCheckpoint: (app: string, id: string, status: "added" | "dismissed" | "suggested") => Promise<StoredAgentMap>;
         /** A key that can only read and upload this app's map, for CI. The key is in the response once. */
         createKey: (app: string, opts?: {
@@ -525,6 +595,17 @@ declare class Plures {
             phase: string;
             received: number;
         }>;
+        /** After npx plures check add pushed a branch with the check in it: Plures opens the pull request. Pass error instead if adding it failed. */
+        checkPr: (app: string, id: string, p: {
+            branch: string;
+        } | {
+            error: string;
+        }) => Promise<{
+            object: "check_pr";
+            check: string;
+            opened: boolean;
+            pull_request?: string;
+        }>;
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
@@ -654,6 +735,18 @@ declare class Plures {
     };
     /** Your prepaid credit. A live task that could cost more than available_cents is refused with a 402 insufficient_credits error. */
     balance: () => Promise<Balance>;
+    /**
+     * Runs a check from your app's map and waits for the decision. Send the data by name; the check
+     * saved on Plures supplies the question, options, guidance, which fields people see (the rest
+     * never leave Plures), who decides, how often and what happens on a timeout. Any of those can be
+     * overridden for this call. `answer` is the option to act on: what people chose, the first option
+     * when the check wasn't needed (a sample or a condition) or timed out set to go ahead, and null
+     * when it timed out set to hold.
+     */
+    check(id: string, data?: Record<string, unknown>, overrides?: CheckOverrides, opts?: {
+        timeoutMs?: number;
+        idempotencyKey?: string;
+    }): Promise<CheckResult>;
     /** Creates a task and waits for people to answer it. */
     verify(params: CreateTask, opts?: {
         timeoutMs?: number;
@@ -667,4 +760,4 @@ declare class Plures {
     static verifyWebhook(rawBody: string, signatureHeader: string | null, secret: string, toleranceSec?: number): Promise<WebhookEvent>;
 }
 
-export { type AgentMap, type App, type Balance, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };
+export { type AgentMap, type App, type Balance, type CheckOverrides, type CheckResult, type Consensus, type CreateTask, type Escalation, type GitHubLink, type MapChanges, type MapCheckpoint, type MapDraft, type MapKey, type MapNode, type Mix, type Option, Plures, PluresError, type Release, type Result, type Route, type Routing, type RoutingRule, type RoutingUpdate, type Rubric, type RubricParams, type Sample, type StoredAgentMap, type Task, type TaskStatus, type TeamTally, type TeamVote, type TestMix, VERSION, type WebhookEvent, Plures as default };

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   PluresError,
   VERSION,
   index_default
-} from "./chunk-JSR4MDEK.js";
+} from "./chunk-Z75ZTXHZ.js";
 export {
   Plures,
   PluresError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Human judgment as an API for AI agents. Send a decision to ID verified people and get their consensus back.",
   "keywords": [
     "human-in-the-loop",