plures 1.9.1 → 1.10.0

package/README.md

@@ -48,7 +48,8 @@ if (event.type === "task.completed" && event.data.result?.agreement === 1) {
 - `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.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. `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).
+- `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).
+- `plures.github.repos()`, `.connect(app, "owner/repo")`, `.turnOn(app)`, `.status(app)`, `.disconnect(app)`: Map with GitHub from code. Plures sets the repo's map key secret and opens a pull request adding the workflow; `turnOn` merges it. Installing the Plures GitHub App needs a browser once (`install_url`). From a terminal: `npx plures map github connect`, then `npx plures map github on`.
 - `plures.quality.sample({ rubric, output, input? })`: send every output; a share is graded by people against the rubric, with personal details taken out first. `plures.quality.rubrics.create({ name, question, options, sample_rate })`, `.retrieve(name)` (score by day, this week against the four before, drift), `.list()`, `.update()`, `.del()`. `plures.quality.compare({ release, input, a, b })` and `plures.quality.release(name)` for blind release checks. `plures.quality.export(rubric)` returns graded samples for evals or fine tuning.
 - `plures.testMix.set({ unanimous: 70, split: 20, tie: 5, expired: 5 })`, `.get()`, `.clear()`: with a test key, makes a share of test tasks split, tie or expire at random so you can test routing to your team without changing your agent. A task can override it with `metadata.test_mix`, and `metadata.test_outcome` beats both.
 - `plures.routing.get()`, `plures.routing.set({ groups, rules, team })`: named teams of your own people and rules by category, like `{ groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }`. What you send replaces what's there; the rest stays.

package/dist/cli.cjs

@@ -5,16 +5,16 @@
 var import_node_child_process = require("child_process");
 var import_node_fs = require("fs");
 
-// src/index.ts
+// src/index.js
 var VERSION = "1.9.1";
 var PluresError = class extends Error {
+  status;
+  type;
   constructor(message, status, type) {
     super(message);
     this.status = status;
     this.type = type;
   }
-  status;
-  type;
 };
 var Plures = class {
   base;
@@ -24,7 +24,8 @@ var Plures = class {
   ua;
   constructor(apiKey, opts = {}) {
     const key2 = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
-    if (!key2) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
+    if (!key2)
+      throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
     this.apiKey = key2;
     this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
     this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
@@ -42,7 +43,8 @@ var Plures = class {
         continue;
       }
       const data = await r.json().catch(() => ({}));
-      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+      if (!r.ok)
+        throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
       return data;
     }
   }
@@ -60,8 +62,10 @@ var Plures = class {
       const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
       for (; ; ) {
         const t = await this.tasks.retrieve(id);
-        if (t.status !== "pending") return t;
-        if (Date.now() > end) return t;
+        if (t.status !== "pending")
+          return t;
+        if (Date.now() > end)
+          return t;
         await sleep(opts.intervalMs ?? 3e3);
       }
     }
@@ -122,6 +126,23 @@ var Plures = class {
       return r.text();
     }
   };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app2, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app2) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app2) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app2)}/github`)
+  };
   /**
    * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
    * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -167,19 +188,24 @@ var Plures = class {
   static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
     const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
     const t = Number(parts.t);
-    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
-    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
+    if (!t || !parts.v1)
+      throw new Error("Missing Plures-Signature header");
+    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec)
+      throw new Error("Webhook timestamp is too old");
     const key2 = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
     const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key2, new TextEncoder().encode(`${t}.${rawBody}`)));
     const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
-    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
+    if (!timingSafeEqual(expected, parts.v1))
+      throw new Error("Webhook signature does not match");
     return JSON.parse(rawBody);
   }
 };
 function timingSafeEqual(a, b) {
-  if (a.length !== b.length) return false;
+  if (a.length !== b.length)
+    return false;
   let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  for (let i = 0; i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -301,11 +327,58 @@ async function workflow() {
   (0, import_node_fs.writeFileSync)(path, await r.text());
   console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
 
-Then add two repository secrets (Settings, Secrets and variables, Actions):
+Then add a repository secret (Settings, Secrets and variables, Actions):
   ${cyan("PLURES_MAP_KEY")}      a map key: ${dim(`${base}/dashboard/apps/${app}/map`)} or ${dim("POST /api/v1/apps/" + app + "/map_keys")}
-  ${cyan("ANTHROPIC_API_KEY")}   or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}
+Optional: ${cyan("ANTHROPIC_API_KEY")}, or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}, to map on your own key for free.
+Without it Plures maps it: the first map is free.
 
-Or let Plures do all of this: ${bold("Map with GitHub")} on the app's map page.`);
+Or let Plures do all of this: ${bold("npx plures map github connect")}.`);
+}
+function originRepo() {
+  const u = (0, import_node_child_process.spawnSync)("git", ["remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(u)?.[1];
+}
+async function github(action, arg) {
+  const p = client();
+  const show = (g) => {
+    if (!g.connected) return console.log(`${bold(app)} has no repo connected. Run ${cyan("npx plures map github connect")} in the repo, or pass ${cyan("owner/repo")}.`);
+    const on = g.mapping_on ? cyan("on") : coral("off until the pull request is merged");
+    console.log(`${bold(app)} maps from ${bold(g.repo)}: mapping ${on}.
+  Pull request  ${g.pull_request?.state} ${dim(g.pull_request?.url ?? "")}
+  Mapped by     ${g.mapped_by === "your_anthropic_key" ? "your Anthropic key, free" : g.mapped_by === "plures" ? `Plures${g.first_map_free ? ", first map free" : ""}` : coral("needs ANTHROPIC_API_KEY in the repo's secrets")}
+  Latest run    ${g.latest_run ? `${g.latest_run.conclusion ?? g.latest_run.status} ${dim(g.latest_run.url)}` : dim("none yet")}
+  Map           ${g.mapped_at ? `uploaded ${g.mapped_at}` : dim("arrives a few minutes after the first run")}`);
+    if (g.pull_request?.state === "open") console.log(`
+Turn it on: ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}`);
+  };
+  try {
+    if (!action || action === "status") return show(await p.github.status(app));
+    if (action === "on") {
+      const r = await p.github.turnOn(app);
+      console.log(r.already_merged ? "Mapping was already on." : `${bold("Mapping is on.")} The first run is starting on GitHub.`);
+      return show(await p.github.status(app));
+    }
+    if (action === "off") {
+      await p.github.disconnect(app);
+      return console.log(`Disconnected. The repo's map key is revoked. Delete ${cyan(".github/workflows/plures-map.yml")} in the repo to stop runs.`);
+    }
+    if (action === "connect") {
+      const repo = arg ?? originRepo();
+      if (!repo) die("Pass the repo as owner/name, or run this inside a clone of it.");
+      const list = await p.github.repos();
+      if (!list.installed || !list.data.some((r) => r.repo.toLowerCase() === repo.toLowerCase()))
+        die(`The Plures GitHub App can't reach ${repo} yet. Open this once, pick the repo, then run this again:
+  ${list.install_url}?app=${app}`);
+      const g = await p.github.connect(app, repo);
+      console.log(`${bold("Pull request opened")} in ${repo}: ${g.pull_request?.url}
+It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}, or merge it on GitHub.`);
+      return;
+    }
+    die("npx plures map github [connect [owner/repo] | on | off]");
+  } catch (e) {
+    if (e instanceof PluresError) die(e.message);
+    throw e;
+  }
 }
 async function main() {
   const [cmd, sub, arg] = argv;
@@ -316,6 +389,8 @@ async function main() {
   npx plures map upload [file]         upload ${FILE}
   npx plures map guide                 print the steps for any coding agent
   npx plures map workflow              add a GitHub Action that maps on every push
+  npx plures map github connect        let Plures add that Action by pull request
+  npx plures map github on             merge it, which turns mapping on
 
 Docs: https://plures.si/docs`);
     return;
@@ -323,6 +398,7 @@ Docs: https://plures.si/docs`);
   if (sub === "upload") return upload(arg ?? FILE);
   if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
   if (sub === "workflow") return workflow();
+  if (sub === "github") return github(arg, argv[3]);
   return map();
 }
 main().catch((e) => die(String(e?.message ?? e)));

package/dist/cli.js

@@ -1,13 +1,215 @@
 #!/usr/bin/env node
-import {
-  Plures,
-  PluresError,
-  VERSION
-} from "./chunk-23ZYPCPM.js";
 
 // src/cli.ts
 import { spawnSync, spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
+
+// src/index.js
+var VERSION = "1.9.1";
+var PluresError = class extends Error {
+  status;
+  type;
+  constructor(message, status, type) {
+    super(message);
+    this.status = status;
+    this.type = type;
+  }
+};
+var Plures = class {
+  base;
+  apiKey;
+  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+  app;
+  ua;
+  constructor(apiKey, opts = {}) {
+    const key2 = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
+    if (!key2)
+      throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
+    this.apiKey = key2;
+    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
+    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
+    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
+  }
+  async req(method, path, body, headers = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const r = await fetch(this.base + path, {
+        method,
+        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (r.status >= 500 && attempt < 2) {
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok)
+        throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+      return data;
+    }
+  }
+  tasks = {
+    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
+    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
+    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
+    list: (params = {}) => {
+      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
+    },
+    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
+    /** Polls until the task is settled. Prefer webhooks in production. */
+    waitFor: async (id, opts = {}) => {
+      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
+      for (; ; ) {
+        const t = await this.tasks.retrieve(id);
+        if (t.status !== "pending")
+          return t;
+        if (Date.now() > end)
+          return t;
+        await sleep(opts.intervalMs ?? 3e3);
+      }
+    }
+  };
+  /**
+   * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
+   * so an agent running unchanged sends a share of decisions to your team.
+   * A single task can override it with metadata.test_mix.
+   */
+  testMix = {
+    get: () => this.req("GET", "/api/v1/test_mix"),
+    /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
+    set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
+    clear: () => this.req("DELETE", "/api/v1/test_mix")
+  };
+  /**
+   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+   */
+  routing = {
+    get: () => this.req("GET", "/api/v1/routing"),
+    set: (update) => this.req("PUT", "/api/v1/routing", update)
+  };
+  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+  apps = {
+    list: () => this.req("GET", "/api/v1/apps"),
+    /** { name: "Support agent" }, with an optional id like "support-agent". */
+    create: (params) => this.req("POST", "/api/v1/apps", params),
+    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
+    /** Rename it, change its id (its tasks move with it), or make it the default. */
+    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
+    /** Only an app with no tasks can be deleted. */
+    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
+  };
+  /**
+   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+   * writes the map; Plures gets only the map. guide() returns the steps it follows.
+   */
+  maps = {
+    guide: async () => {
+      const r = await fetch(`${this.base}/api/v1/map_guide`);
+      return r.text();
+    },
+    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),
+    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),
+    keys: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map_keys`),
+    revokeKey: (app2, id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app2)}/map_keys/${encodeURIComponent(id)}`),
+    /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
+    startRun: (app2) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/map_runs`, {}),
+    runs: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/map_runs`),
+    /** 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)}`);
+      return r.text();
+    }
+  };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app2) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app2)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app2, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app2) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app2)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app2) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app2)}/github`)
+  };
+  /**
+   * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
+   * early, and compare two versions blind before you ship. Personal details are taken out first.
+   */
+  quality = {
+    /** Send every output; the rubric's sample rate decides which ones people grade. */
+    sample: (p) => this.req("POST", "/api/v1/samples", p),
+    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
+    /** How often people preferred the new version, with a 95% range and a verdict. */
+    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+    rubrics: {
+      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+      create: (p) => this.req("POST", "/api/v1/rubrics", p),
+      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
+      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
+    },
+    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+    export: async (rubric, opts = {}) => {
+      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
+      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
+      if (!r.ok) {
+        const d = await r.json().catch(() => ({}));
+        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
+      }
+      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    }
+  };
+  /** 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");
+  /** Creates a task and waits for people to answer it. */
+  async verify(params, opts = {}) {
+    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
+    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+  }
+  /**
+   * Checks the Plures-Signature header on a webhook and returns the parsed event.
+   * Pass the raw request body exactly as received. Throws if the signature is wrong
+   * or older than toleranceSec.
+   */
+  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
+    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
+    const t = Number(parts.t);
+    if (!t || !parts.v1)
+      throw new Error("Missing Plures-Signature header");
+    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec)
+      throw new Error("Webhook timestamp is too old");
+    const key2 = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key2, new TextEncoder().encode(`${t}.${rawBody}`)));
+    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (!timingSafeEqual(expected, parts.v1))
+      throw new Error("Webhook signature does not match");
+    return JSON.parse(rawBody);
+  }
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// src/cli.ts
 var argv = process.argv.slice(2);
 var flag = (name) => {
   const i = argv.indexOf(`--${name}`);
@@ -124,11 +326,58 @@ async function workflow() {
   writeFileSync(path, await r.text());
   console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
 
-Then add two repository secrets (Settings, Secrets and variables, Actions):
+Then add a repository secret (Settings, Secrets and variables, Actions):
   ${cyan("PLURES_MAP_KEY")}      a map key: ${dim(`${base}/dashboard/apps/${app}/map`)} or ${dim("POST /api/v1/apps/" + app + "/map_keys")}
-  ${cyan("ANTHROPIC_API_KEY")}   or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}
+Optional: ${cyan("ANTHROPIC_API_KEY")}, or ${cyan("CLAUDE_CODE_OAUTH_TOKEN")} from ${dim("claude setup-token")}, to map on your own key for free.
+Without it Plures maps it: the first map is free.
 
-Or let Plures do all of this: ${bold("Map with GitHub")} on the app's map page.`);
+Or let Plures do all of this: ${bold("npx plures map github connect")}.`);
+}
+function originRepo() {
+  const u = spawnSync("git", ["remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  return /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(u)?.[1];
+}
+async function github(action, arg) {
+  const p = client();
+  const show = (g) => {
+    if (!g.connected) return console.log(`${bold(app)} has no repo connected. Run ${cyan("npx plures map github connect")} in the repo, or pass ${cyan("owner/repo")}.`);
+    const on = g.mapping_on ? cyan("on") : coral("off until the pull request is merged");
+    console.log(`${bold(app)} maps from ${bold(g.repo)}: mapping ${on}.
+  Pull request  ${g.pull_request?.state} ${dim(g.pull_request?.url ?? "")}
+  Mapped by     ${g.mapped_by === "your_anthropic_key" ? "your Anthropic key, free" : g.mapped_by === "plures" ? `Plures${g.first_map_free ? ", first map free" : ""}` : coral("needs ANTHROPIC_API_KEY in the repo's secrets")}
+  Latest run    ${g.latest_run ? `${g.latest_run.conclusion ?? g.latest_run.status} ${dim(g.latest_run.url)}` : dim("none yet")}
+  Map           ${g.mapped_at ? `uploaded ${g.mapped_at}` : dim("arrives a few minutes after the first run")}`);
+    if (g.pull_request?.state === "open") console.log(`
+Turn it on: ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}`);
+  };
+  try {
+    if (!action || action === "status") return show(await p.github.status(app));
+    if (action === "on") {
+      const r = await p.github.turnOn(app);
+      console.log(r.already_merged ? "Mapping was already on." : `${bold("Mapping is on.")} The first run is starting on GitHub.`);
+      return show(await p.github.status(app));
+    }
+    if (action === "off") {
+      await p.github.disconnect(app);
+      return console.log(`Disconnected. The repo's map key is revoked. Delete ${cyan(".github/workflows/plures-map.yml")} in the repo to stop runs.`);
+    }
+    if (action === "connect") {
+      const repo = arg ?? originRepo();
+      if (!repo) die("Pass the repo as owner/name, or run this inside a clone of it.");
+      const list = await p.github.repos();
+      if (!list.installed || !list.data.some((r) => r.repo.toLowerCase() === repo.toLowerCase()))
+        die(`The Plures GitHub App can't reach ${repo} yet. Open this once, pick the repo, then run this again:
+  ${list.install_url}?app=${app}`);
+      const g = await p.github.connect(app, repo);
+      console.log(`${bold("Pull request opened")} in ${repo}: ${g.pull_request?.url}
+It adds one workflow file. Review it, then turn mapping on with ${cyan("npx plures map github on")}${app !== "default" ? ` --app ${app}` : ""}, or merge it on GitHub.`);
+      return;
+    }
+    die("npx plures map github [connect [owner/repo] | on | off]");
+  } catch (e) {
+    if (e instanceof PluresError) die(e.message);
+    throw e;
+  }
 }
 async function main() {
   const [cmd, sub, arg] = argv;
@@ -139,6 +388,8 @@ async function main() {
   npx plures map upload [file]         upload ${FILE}
   npx plures map guide                 print the steps for any coding agent
   npx plures map workflow              add a GitHub Action that maps on every push
+  npx plures map github connect        let Plures add that Action by pull request
+  npx plures map github on             merge it, which turns mapping on
 
 Docs: https://plures.si/docs`);
     return;
@@ -146,6 +397,7 @@ Docs: https://plures.si/docs`);
   if (sub === "upload") return upload(arg ?? FILE);
   if (sub === "guide") return void console.log(await (await fetch(`${base}/api/v1/map_guide`)).text());
   if (sub === "workflow") return workflow();
+  if (sub === "github") return github(arg, argv[3]);
   return map();
 }
 main().catch((e) => die(String(e?.message ?? e)));

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.9.1";
+var VERSION = "1.10.0";
 var PluresError = class extends Error {
   constructor(message, status, type) {
     super(message);
@@ -142,6 +142,23 @@ var Plures = class {
       return r.text();
     }
   };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/github`)
+  };
   /**
    * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
    * early, and compare two versions blind before you ship. Personal details are taken out first.

package/dist/index.d.cts

@@ -350,7 +350,30 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.9.1";
+declare const VERSION = "1.10.0";
+type GitHubLink = {
+    object: "github_link";
+    app: string;
+    installed: boolean;
+    install_url: string;
+    connected: boolean;
+    repo?: string;
+    pull_request?: {
+        url: string | null;
+        state: "open" | "merged" | "closed" | "unknown";
+    };
+    mapping_on?: boolean;
+    mapped_by?: "plures" | "your_anthropic_key" | "needs_key";
+    first_map_free?: boolean;
+    latest_run?: {
+        status: string;
+        conclusion: string | null;
+        url: string;
+        created_at: string;
+    } | null;
+    mapped_at?: string | null;
+    connected_at?: string;
+};
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -487,6 +510,45 @@ declare class Plures {
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
+    /**
+     * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+     * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+     * everything after that works here.
+     */
+    github: {
+        /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+        repos: () => Promise<{
+            object: "list";
+            installed: boolean;
+            install_url: string;
+            data: {
+                object: "github_repo";
+                repo: string;
+                private: boolean;
+                account: string;
+                default_branch: string;
+            }[];
+        }>;
+        /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+        status: (app: string) => Promise<GitHubLink>;
+        /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+        connect: (app: string, repo: string) => Promise<GitHubLink>;
+        /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+        turnOn: (app: string) => Promise<{
+            object: "github_merge";
+            app: string;
+            merged: true;
+            already_merged: boolean;
+            sha: string | null;
+        }>;
+        /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+        disconnect: (app: string) => Promise<{
+            object: "github_link";
+            app: string;
+            connected: false;
+            deleted: true;
+        }>;
+    };
     /**
      * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
      * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -578,4 +640,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 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 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 };

package/dist/index.d.ts

@@ -350,7 +350,30 @@ type WebhookEvent = {
     created_at: string;
     data: Task;
 };
-declare const VERSION = "1.9.1";
+declare const VERSION = "1.10.0";
+type GitHubLink = {
+    object: "github_link";
+    app: string;
+    installed: boolean;
+    install_url: string;
+    connected: boolean;
+    repo?: string;
+    pull_request?: {
+        url: string | null;
+        state: "open" | "merged" | "closed" | "unknown";
+    };
+    mapping_on?: boolean;
+    mapped_by?: "plures" | "your_anthropic_key" | "needs_key";
+    first_map_free?: boolean;
+    latest_run?: {
+        status: string;
+        conclusion: string | null;
+        url: string;
+        created_at: string;
+    } | null;
+    mapped_at?: string | null;
+    connected_at?: string;
+};
 declare class PluresError extends Error {
     readonly status: number;
     readonly type: string;
@@ -487,6 +510,45 @@ declare class Plures {
         /** The GitHub Actions workflow that maps a repo on every push to its main branch. */
         workflow: (app: string, branch?: string) => Promise<string>;
     };
+    /**
+     * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+     * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+     * everything after that works here.
+     */
+    github: {
+        /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+        repos: () => Promise<{
+            object: "list";
+            installed: boolean;
+            install_url: string;
+            data: {
+                object: "github_repo";
+                repo: string;
+                private: boolean;
+                account: string;
+                default_branch: string;
+            }[];
+        }>;
+        /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+        status: (app: string) => Promise<GitHubLink>;
+        /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+        connect: (app: string, repo: string) => Promise<GitHubLink>;
+        /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+        turnOn: (app: string) => Promise<{
+            object: "github_merge";
+            app: string;
+            merged: true;
+            already_merged: boolean;
+            sha: string | null;
+        }>;
+        /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+        disconnect: (app: string) => Promise<{
+            object: "github_link";
+            app: string;
+            connected: false;
+            deleted: true;
+        }>;
+    };
     /**
      * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
      * early, and compare two versions blind before you ship. Personal details are taken out first.
@@ -578,4 +640,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 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 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 };

package/dist/index.js

@@ -1,9 +1,199 @@
-import {
-  Plures,
-  PluresError,
-  VERSION,
-  index_default
-} from "./chunk-23ZYPCPM.js";
+// src/index.ts
+var VERSION = "1.10.0";
+var PluresError = class extends Error {
+  constructor(message, status, type) {
+    super(message);
+    this.status = status;
+    this.type = type;
+  }
+  status;
+  type;
+};
+var Plures = class {
+  base;
+  apiKey;
+  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
+  app;
+  ua;
+  constructor(apiKey, opts = {}) {
+    const key = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
+    if (!key) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
+    this.apiKey = key;
+    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
+    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
+    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
+  }
+  async req(method, path, body, headers = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const r = await fetch(this.base + path, {
+        method,
+        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
+        body: body ? JSON.stringify(body) : void 0
+      });
+      if (r.status >= 500 && attempt < 2) {
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      const data = await r.json().catch(() => ({}));
+      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
+      return data;
+    }
+  }
+  tasks = {
+    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
+    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
+    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
+    list: (params = {}) => {
+      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
+    },
+    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
+    /** Polls until the task is settled. Prefer webhooks in production. */
+    waitFor: async (id, opts = {}) => {
+      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
+      for (; ; ) {
+        const t = await this.tasks.retrieve(id);
+        if (t.status !== "pending") return t;
+        if (Date.now() > end) return t;
+        await sleep(opts.intervalMs ?? 3e3);
+      }
+    }
+  };
+  /**
+   * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
+   * so an agent running unchanged sends a share of decisions to your team.
+   * A single task can override it with metadata.test_mix.
+   */
+  testMix = {
+    get: () => this.req("GET", "/api/v1/test_mix"),
+    /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
+    set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
+    clear: () => this.req("DELETE", "/api/v1/test_mix")
+  };
+  /**
+   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
+   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
+   */
+  routing = {
+    get: () => this.req("GET", "/api/v1/routing"),
+    set: (update) => this.req("PUT", "/api/v1/routing", update)
+  };
+  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
+  apps = {
+    list: () => this.req("GET", "/api/v1/apps"),
+    /** { name: "Support agent" }, with an optional id like "support-agent". */
+    create: (params) => this.req("POST", "/api/v1/apps", params),
+    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
+    /** Rename it, change its id (its tasks move with it), or make it the default. */
+    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
+    /** Only an app with no tasks can be deleted. */
+    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
+  };
+  /**
+   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
+   * writes the map; Plures gets only the map. guide() returns the steps it follows.
+   */
+  maps = {
+    guide: async () => {
+      const r = await fetch(`${this.base}/api/v1/map_guide`);
+      return r.text();
+    },
+    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),
+    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),
+    keys: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_keys`),
+    revokeKey: (app, id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/map_keys/${encodeURIComponent(id)}`),
+    /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
+    startRun: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`, {}),
+    runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
+    /** 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)}`);
+      return r.text();
+    }
+  };
+  /**
+   * Map with GitHub: Plures adds a workflow to your repo by pull request and keeps the app's map
+   * current on every push. Installing the Plures GitHub App needs a browser once (installUrl);
+   * everything after that works here.
+   */
+  github = {
+    /** Repos the Plures GitHub App can reach. installed is false until you install it at install_url. */
+    repos: () => this.req("GET", "/api/v1/github/repos"),
+    /** Where an app's GitHub link stands: repo, pull request, mapping on, latest run, last map. */
+    status: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/github`),
+    /** Connects a repo ("owner/name"): sets its map key secret and opens the pull request. */
+    connect: (app, repo) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github`, { repo }),
+    /** Turns mapping on by merging the pull request. The repo's own rules (reviews, checks) still apply. */
+    turnOn: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/github/merge`, {}),
+    /** Revokes the repo's map key. Delete the workflow file in the repo to stop runs. */
+    disconnect: (app) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/github`)
+  };
+  /**
+   * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
+   * early, and compare two versions blind before you ship. Personal details are taken out first.
+   */
+  quality = {
+    /** Send every output; the rubric's sample rate decides which ones people grade. */
+    sample: (p) => this.req("POST", "/api/v1/samples", p),
+    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
+    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
+    /** How often people preferred the new version, with a 95% range and a verdict. */
+    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+    rubrics: {
+      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
+      create: (p) => this.req("POST", "/api/v1/rubrics", p),
+      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
+      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
+      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
+    },
+    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
+    export: async (rubric, opts = {}) => {
+      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
+      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
+      if (!r.ok) {
+        const d = await r.json().catch(() => ({}));
+        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
+      }
+      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    }
+  };
+  /** 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");
+  /** Creates a task and waits for people to answer it. */
+  async verify(params, opts = {}) {
+    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
+    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
+  }
+  /**
+   * Checks the Plures-Signature header on a webhook and returns the parsed event.
+   * Pass the raw request body exactly as received. Throws if the signature is wrong
+   * or older than toleranceSec.
+   */
+  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
+    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
+    const t = Number(parts.t);
+    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
+    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`)));
+    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
+    return JSON.parse(rawBody);
+  }
+};
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var index_default = Plures;
 export {
   Plures,
   PluresError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plures",
-  "version": "1.9.1",
+  "version": "1.10.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",

package/dist/chunk-23ZYPCPM.js

@@ -1,186 +0,0 @@
-// src/index.ts
-var VERSION = "1.9.1";
-var PluresError = class extends Error {
-  constructor(message, status, type) {
-    super(message);
-    this.status = status;
-    this.type = type;
-  }
-  status;
-  type;
-};
-var Plures = class {
-  base;
-  apiKey;
-  /** The app tasks go to when they don't name one. From opts.app or PLURES_APP. */
-  app;
-  ua;
-  constructor(apiKey, opts = {}) {
-    const key = apiKey ?? (typeof process !== "undefined" ? process.env?.PLURES_API_KEY : void 0);
-    if (!key) throw new Error("Pass your Plures API key, or set PLURES_API_KEY. Get a free test key at https://plures.si/?for=developers#join");
-    this.apiKey = key;
-    this.ua = opts.userAgent ?? `plures-js/${VERSION}`;
-    this.app = opts.app ?? (typeof process !== "undefined" ? process.env?.PLURES_APP : void 0) ?? null;
-    this.base = (opts.baseUrl ?? (typeof process !== "undefined" ? process.env?.PLURES_BASE_URL : void 0) ?? "https://plures.si").replace(/\/$/, "");
-  }
-  async req(method, path, body, headers = {}) {
-    for (let attempt = 0; ; attempt++) {
-      const r = await fetch(this.base + path, {
-        method,
-        headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua, ...body ? { "content-type": "application/json" } : {}, ...this.app ? { "plures-app": this.app } : {}, ...headers },
-        body: body ? JSON.stringify(body) : void 0
-      });
-      if (r.status >= 500 && attempt < 2) {
-        await sleep(500 * 2 ** attempt);
-        continue;
-      }
-      const data = await r.json().catch(() => ({}));
-      if (!r.ok) throw new PluresError(data?.error?.message ?? `HTTP ${r.status}`, r.status, data?.error?.type ?? "api_error");
-      return data;
-    }
-  }
-  tasks = {
-    /** Sends a question to verified people. Pass an idempotency key to make retries safe. */
-    create: (params, opts = {}) => this.req("POST", "/api/v1/tasks", params, opts.idempotencyKey ? { "idempotency-key": opts.idempotencyKey } : {}),
-    retrieve: (id) => this.req("GET", `/api/v1/tasks/${encodeURIComponent(id)}`),
-    list: (params = {}) => {
-      const q = new URLSearchParams(Object.entries(params).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
-      return this.req("GET", `/api/v1/tasks${q.size ? `?${q}` : ""}`);
-    },
-    cancel: (id) => this.req("POST", `/api/v1/tasks/${encodeURIComponent(id)}/cancel`),
-    /** Polls until the task is settled. Prefer webhooks in production. */
-    waitFor: async (id, opts = {}) => {
-      const end = Date.now() + (opts.timeoutMs ?? 10 * 6e4);
-      for (; ; ) {
-        const t = await this.tasks.retrieve(id);
-        if (t.status !== "pending") return t;
-        if (Date.now() > end) return t;
-        await sleep(opts.intervalMs ?? 3e3);
-      }
-    }
-  };
-  /**
-   * Test keys only. How test tasks behave when they don't set metadata.test_outcome,
-   * so an agent running unchanged sends a share of decisions to your team.
-   * A single task can override it with metadata.test_mix.
-   */
-  testMix = {
-    get: () => this.req("GET", "/api/v1/test_mix"),
-    /** For example { unanimous: 70, split: 20, tie: 5, expired: 5 }. Pass null to turn it off. */
-    set: (mix) => this.req("PUT", "/api/v1/test_mix", { mix }),
-    clear: () => this.req("DELETE", "/api/v1/test_mix")
-  };
-  /**
-   * Where tasks go. set() replaces what you send (team, groups or rules) and keeps the rest.
-   * For example { groups: [{ name: "Finance", emails: ["ap@acme.com"] }], rules: [{ category: "refunds", route: "team", group: "Finance" }] }.
-   */
-  routing = {
-    get: () => this.req("GET", "/api/v1/routing"),
-    set: (update) => this.req("PUT", "/api/v1/routing", update)
-  };
-  /** Your apps. Each agent you run can be its own app, with its own tasks, ledger view and map. */
-  apps = {
-    list: () => this.req("GET", "/api/v1/apps"),
-    /** { name: "Support agent" }, with an optional id like "support-agent". */
-    create: (params) => this.req("POST", "/api/v1/apps", params),
-    retrieve: (id) => this.req("GET", `/api/v1/apps/${encodeURIComponent(id)}`),
-    /** Rename it, change its id (its tasks move with it), or make it the default. */
-    update: (id, params) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(id)}`, params),
-    /** Only an app with no tasks can be deleted. */
-    del: (id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(id)}`)
-  };
-  /**
-   * Agent maps: where each app's agent needs a person. Your coding agent reads your code and
-   * writes the map; Plures gets only the map. guide() returns the steps it follows.
-   */
-  maps = {
-    guide: async () => {
-      const r = await fetch(`${this.base}/api/v1/map_guide`);
-      return r.text();
-    },
-    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),
-    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),
-    keys: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_keys`),
-    revokeKey: (app, id) => this.req("DELETE", `/api/v1/apps/${encodeURIComponent(app)}/map_keys/${encodeURIComponent(id)}`),
-    /** Starts a map run where Plures runs Claude (CI with no Anthropic key). npx plures map does this. */
-    startRun: (app) => this.req("POST", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`, {}),
-    runs: (app) => this.req("GET", `/api/v1/apps/${encodeURIComponent(app)}/map_runs`),
-    /** 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)}`);
-      return r.text();
-    }
-  };
-  /**
-   * Quality: people grade a sample of your agent's outputs against a rubric, so you see drift
-   * early, and compare two versions blind before you ship. Personal details are taken out first.
-   */
-  quality = {
-    /** Send every output; the rubric's sample rate decides which ones people grade. */
-    sample: (p) => this.req("POST", "/api/v1/samples", p),
-    /** A blind release check: a is the current version's output, b the new one's, for the same input. */
-    compare: (p) => this.req("POST", "/api/v1/comparisons", p),
-    /** How often people preferred the new version, with a 95% range and a verdict. */
-    release: (name, opts = {}) => this.req("GET", `/api/v1/releases/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
-    rubrics: {
-      list: (opts = {}) => this.req("GET", `/api/v1/rubrics${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
-      /** { name: "reply_quality", question: "Is this reply correct and kind?", options: ["Good", "Okay", "Bad"], sample_rate: 0.05 } */
-      create: (p) => this.req("POST", "/api/v1/rubrics", p),
-      retrieve: (name, opts = {}) => this.req("GET", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`),
-      update: (name, p) => this.req("PATCH", `/api/v1/rubrics/${encodeURIComponent(name)}${p.app ? `?app=${encodeURIComponent(p.app)}` : ""}`, p),
-      del: (name, opts = {}) => this.req("DELETE", `/api/v1/rubrics/${encodeURIComponent(name)}${opts.app ? `?app=${encodeURIComponent(opts.app)}` : ""}`)
-    },
-    /** Graded samples as JSON lines (input, output, grade, score, agreement), for fine tuning or an eval set. */
-    export: async (rubric, opts = {}) => {
-      const q = new URLSearchParams(Object.entries({ app: opts.app ?? this.app ?? void 0, since: opts.since }).filter(([, v]) => v));
-      const r = await fetch(`${this.base}/api/v1/rubrics/${encodeURIComponent(rubric)}/export${q.size ? `?${q}` : ""}`, { headers: { authorization: `Bearer ${this.apiKey}`, "user-agent": this.ua } });
-      if (!r.ok) {
-        const d = await r.json().catch(() => ({}));
-        throw new PluresError(d?.error?.message ?? `HTTP ${r.status}`, r.status, d?.error?.type ?? "api_error");
-      }
-      return (await r.text()).split("\n").filter(Boolean).map((l) => JSON.parse(l));
-    }
-  };
-  /** 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");
-  /** Creates a task and waits for people to answer it. */
-  async verify(params, opts = {}) {
-    const t = await this.tasks.create(params, { idempotencyKey: opts.idempotencyKey });
-    return t.status === "pending" ? this.tasks.waitFor(t.id, { timeoutMs: opts.timeoutMs }) : t;
-  }
-  /**
-   * Checks the Plures-Signature header on a webhook and returns the parsed event.
-   * Pass the raw request body exactly as received. Throws if the signature is wrong
-   * or older than toleranceSec.
-   */
-  static async verifyWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
-    const parts = Object.fromEntries((signatureHeader ?? "").split(",").map((p) => p.split("=", 2)));
-    const t = Number(parts.t);
-    if (!t || !parts.v1) throw new Error("Missing Plures-Signature header");
-    if (Math.abs(Date.now() / 1e3 - t) > toleranceSec) throw new Error("Webhook timestamp is too old");
-    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`)));
-    const expected = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
-    if (!timingSafeEqual(expected, parts.v1)) throw new Error("Webhook signature does not match");
-    return JSON.parse(rawBody);
-  }
-};
-function timingSafeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-var index_default = Plures;
-
-export {
-  VERSION,
-  PluresError,
-  Plures,
-  index_default
-};