plures 1.7.1 → 1.10.0

package/README.md

@@ -48,6 +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, 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
-var VERSION = "1.7.1";
+// 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);
       }
     }
@@ -108,7 +112,36 @@ 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),
-    setCheckpoint: (app2, id, status) => this.req("PATCH", `/api/v1/apps/${encodeURIComponent(app2)}/map/checkpoints/${encodeURIComponent(id)}`, { status })
+    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
@@ -155,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));
@@ -181,6 +219,7 @@ var flag = (name) => {
   argv.splice(i, 2);
   return v;
 };
+var branch = flag("branch");
 var app = flag("app") ?? process.env.PLURES_APP ?? "default";
 var key = flag("key") ?? process.env.PLURES_API_KEY;
 var base = flag("base-url") ?? process.env.PLURES_BASE_URL ?? "https://plures.si";
@@ -198,7 +237,7 @@ function die(msg) {
 }
 function client() {
   if (!key) die("Set PLURES_API_KEY (a free pk_test_ key works), or pass --key. Get one at https://plures.si/?for=developers#join");
-  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}` });
+  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}${process.env.GITHUB_ACTIONS ? " github-actions" : ""}` });
 }
 async function upload(file) {
   if (!(0, import_node_fs.existsSync)(file)) die(`No ${file} here. Run npx plures map to make one, or pass the file's path.`);
@@ -252,19 +291,95 @@ With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
     return;
   }
   const before = (0, import_node_fs.existsSync)(FILE) ? (0, import_node_fs.statSync)(FILE).mtimeMs : 0;
-  console.log(`Reading this repo on your machine with Claude Code. ${dim("Only the map leaves it.")}
+  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 || argv.includes("--plures-claude"))) {
+    let run;
+    try {
+      run = await client().maps.startRun(app);
+    } catch (e) {
+      die(e instanceof PluresError ? e.message : String(e));
+    }
+    childEnv.ANTHROPIC_BASE_URL = run.base_url;
+    childEnv.ANTHROPIC_API_KEY = run.token;
+    console.log(dim(run.free ? "Plures is mapping this repo. Your first map is free." : `Plures is mapping this repo, at most $${(run.max_cents / 100).toFixed(2)} from your credit.`));
+  }
+  console.log(`Reading this repo ${process.env.CI ? "on this runner" : "on your machine"} with Claude Code. ${dim("Only the map is sent to Plures.")}
 `);
   const prompt = `${guide}
 
 Write the map to ${FILE} in the current directory now. Read the code; don't run it or change anything else.`;
   const code = await new Promise((resolve) => {
-    const p = (0, import_node_child_process.spawn)("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"] });
+    const p = (0, import_node_child_process.spawn)("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
     p.on("close", (n) => resolve(n ?? 1));
     p.on("error", () => resolve(1));
   });
   if (code !== 0 || !(0, import_node_fs.existsSync)(FILE) || (0, import_node_fs.statSync)(FILE).mtimeMs === before) die(`Claude Code didn't write ${FILE}. Ask it directly, then run npx plures map upload.`);
   await upload(FILE);
 }
+async function workflow() {
+  const def = (0, import_node_child_process.spawnSync)("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { encoding: "utf8" }).stdout?.trim().replace(/^origin\//, "");
+  const b = branch ?? (def || "main");
+  const r = await fetch(`${base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(b)}`).catch(() => null);
+  if (!r?.ok) die("Couldn't reach Plures for the workflow. Check your connection.");
+  const path = ".github/workflows/plures-map.yml";
+  (0, import_node_fs.mkdirSync)(".github/workflows", { recursive: true });
+  (0, import_node_fs.writeFileSync)(path, await r.text());
+  console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
+
+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")}
+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("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;
   if (cmd !== "map") {
@@ -273,12 +388,17 @@ async function main() {
   npx plures map [--app <id>]          map this repo's agent and upload it
   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;
   }
   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-N4GCKRA6.js";
 
 // src/cli.ts
 import { spawnSync, spawn } from "child_process";
-import { existsSync, readFileSync, statSync } from "fs";
+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}`);
@@ -16,6 +218,7 @@ var flag = (name) => {
   argv.splice(i, 2);
   return v;
 };
+var branch = flag("branch");
 var app = flag("app") ?? process.env.PLURES_APP ?? "default";
 var key = flag("key") ?? process.env.PLURES_API_KEY;
 var base = flag("base-url") ?? process.env.PLURES_BASE_URL ?? "https://plures.si";
@@ -33,7 +236,7 @@ function die(msg) {
 }
 function client() {
   if (!key) die("Set PLURES_API_KEY (a free pk_test_ key works), or pass --key. Get one at https://plures.si/?for=developers#join");
-  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}` });
+  return new Plures(key, { baseUrl: base, app, userAgent: `plures-cli/${VERSION}${process.env.GITHUB_ACTIONS ? " github-actions" : ""}` });
 }
 async function upload(file) {
   if (!existsSync(file)) die(`No ${file} here. Run npx plures map to make one, or pass the file's path.`);
@@ -87,19 +290,95 @@ With plures-mcp connected, just ask: ${cyan("Map this app for Plures")}`);
     return;
   }
   const before = existsSync(FILE) ? statSync(FILE).mtimeMs : 0;
-  console.log(`Reading this repo on your machine with Claude Code. ${dim("Only the map leaves it.")}
+  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 || argv.includes("--plures-claude"))) {
+    let run;
+    try {
+      run = await client().maps.startRun(app);
+    } catch (e) {
+      die(e instanceof PluresError ? e.message : String(e));
+    }
+    childEnv.ANTHROPIC_BASE_URL = run.base_url;
+    childEnv.ANTHROPIC_API_KEY = run.token;
+    console.log(dim(run.free ? "Plures is mapping this repo. Your first map is free." : `Plures is mapping this repo, at most $${(run.max_cents / 100).toFixed(2)} from your credit.`));
+  }
+  console.log(`Reading this repo ${process.env.CI ? "on this runner" : "on your machine"} with Claude Code. ${dim("Only the map is sent to Plures.")}
 `);
   const prompt = `${guide}
 
 Write the map to ${FILE} in the current directory now. Read the code; don't run it or change anything else.`;
   const code = await new Promise((resolve) => {
-    const p = spawn("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"] });
+    const p = spawn("claude", ["-p", prompt, "--allowedTools", "Read,Grep,Glob,Write,Bash(git rev-parse:*),Bash(git remote:*)"], { stdio: ["ignore", "inherit", "inherit"], env: childEnv });
     p.on("close", (n) => resolve(n ?? 1));
     p.on("error", () => resolve(1));
   });
   if (code !== 0 || !existsSync(FILE) || statSync(FILE).mtimeMs === before) die(`Claude Code didn't write ${FILE}. Ask it directly, then run npx plures map upload.`);
   await upload(FILE);
 }
+async function workflow() {
+  const def = spawnSync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { encoding: "utf8" }).stdout?.trim().replace(/^origin\//, "");
+  const b = branch ?? (def || "main");
+  const r = await fetch(`${base}/api/v1/map_workflow?app=${encodeURIComponent(app)}&branch=${encodeURIComponent(b)}`).catch(() => null);
+  if (!r?.ok) die("Couldn't reach Plures for the workflow. Check your connection.");
+  const path = ".github/workflows/plures-map.yml";
+  mkdirSync(".github/workflows", { recursive: true });
+  writeFileSync(path, await r.text());
+  console.log(`${bold("Wrote " + path)}: maps this repo on every push to ${b}.
+
+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")}
+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("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;
   if (cmd !== "map") {
@@ -108,12 +387,17 @@ async function main() {
   npx plures map [--app <id>]          map this repo's agent and upload it
   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;
   }
   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)));