run402 4.17.9 → 4.18.1

package/cli.mjs

@@ -45,6 +45,8 @@ Commands:
   grants      Per-project capability grants for agent/CI principals (create, revoke)
   delegates   Scoped deploy credentials for agents (create, list, revoke, rotate)
   events      What happened to your project since you last looked (cursored feed)
+  rooms       Coordinate with the other agents on your project (who/send/ack)
+  claims      Say what you're working on before you collide (advisory)
   errors      Grouped error fingerprints + a promote/revert verdict (release-baselined)
   jobs        Submit and inspect platform-managed jobs
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
@@ -273,6 +275,16 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "rooms": {
+    const { run } = await import("./lib/rooms.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "claims": {
+    const { run } = await import("./lib/claims.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "errors": {
     const { run } = await import("./lib/errors.mjs");
     await run(sub, rest);

package/lib/buzz.mjs

@@ -22,6 +22,9 @@ The four independent states are:
 Canonical workflows:
   run402 buzz status
   run402 buzz adopt offer --org <org_id> --identity-link <idlnk_id> [--deployment-context-file <json>]
+      --org                       the Run402 organization id as "run402 org whoami" returns it (a UUID)
+      --deployment-context-file   JSON with exactly these five non-empty strings, and no others:
+                                  project_id, release_id, live_url, source_revision, verified_at
   run402 buzz install --org <org_id> --community <buzz:community:host> --authority <hex-pubkey>
   run402 buzz enroll --installation <buzzci_id> --identity-link <idlnk_id> --grants-file <json> --expires-at <ISO-8601>
 

package/lib/claims.mjs

@@ -0,0 +1,165 @@
+/**
+ * `run402 claims` — advisory work claims for agent coordination.
+ *
+ * Gateway subsystem: add-agent-messaging (/orgs/v1/:org_id/rooms/:room_key/claims).
+ * A claim declares "I'm working on X until T" so concurrent agents discover
+ * collisions BEFORE they happen. Claims are ADVISORY: creating a conflicting
+ * claim succeeds and reports the complete conflict set — nothing, ever, is
+ * blocked by a claim (deploys included). JSON to stdout (pipe contract).
+ */
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError } from "./sdk-errors.mjs";
+import {
+  normalizeArgv,
+  hasHelp,
+  assertKnownFlags,
+  assertAllowedValue,
+  parseIntegerFlag,
+  flagValue,
+  positionalArgs,
+  requirePositionalCount,
+  failUnknownSubcommand,
+} from "./argparse.mjs";
+import { resolveRoom, withPresenceRetry } from "./rooms-context.mjs";
+
+export const MODES = ["exclusive", "shared"];
+
+const ROOM_FLAGS = ["--project", "--org", "--room"];
+
+const HELP = `run402 claims — say what you're working on before you collide
+
+Usage:
+  run402 claims create <resource> [--mode exclusive|shared] [--ttl <seconds>]
+  run402 claims list [--all]
+  run402 claims release <claim_id>
+
+Resources (namespaced; conflicts never cross namespaces):
+  repo:<glob>        Repo paths — repo:src/auth/** (glob overlap detection)
+  function:<name>    A deployed function by name
+  table:<name>       A database table
+  deploy             The deploy itself (a soft mutex by convention)
+  <free-form>        Anything else (exact-match overlap)
+
+Advisory, always:
+  Creating a conflicting claim SUCCEEDS — the response carries the complete
+  conflicts[] (holder, resource, mode, expiry) and the deploy-path responses
+  surface other agents' claims automatically. A claim never blocks anything;
+  it makes collisions visible before they happen. Claims auto-expire (default
+  1h, max 24h) so a dead session cannot wedge the room; <=32 active per
+  presence.
+
+Room addressing:
+  Default room of the active project with no flags; --project <id> for another
+  project; --org <org_id> --room <key> (or RUN402_ROOM=<org_id>/<key>) for a
+  named org room.
+
+Options:
+  --mode <m>        exclusive (default) — one worker; shared — parallel-safe.
+  --ttl <seconds>   Claim lifetime (default 3600, max 86400).
+  --note <text>     Why you're claiming it (shown to everyone).
+  --all             list: include released/expired history.
+
+Tip: claim before you edit, release when you hand off — and put the handoff
+     in \`run402 rooms send\` so the room's timeline tells the story.
+
+Examples:
+  run402 claims create repo:src/auth/** --note "migrating to passkeys"
+  run402 claims create deploy --ttl 900
+  run402 claims list
+  run402 claims release clm_1a
+`;
+
+async function create(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--mode", "--ttl", "--note"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(a, valueFlags);
+  requirePositionalCount(positionals, valueFlags, {
+    min: 1, max: 1, command: "run402 claims create <resource>", missing: "<resource>",
+  });
+  const mode = flagValue(a, "--mode") ?? "exclusive";
+  assertAllowedValue(mode, MODES, "--mode");
+  const ttl = flagValue(a, "--ttl");
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const created = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
+      getSdk().rooms.createClaim(room.orgId, room.roomKey, {
+        resource: positionals[0],
+        mode,
+        ttlSeconds: ttl != null ? parseIntegerFlag("--ttl", ttl, { min: 1, max: 86400 }) : undefined,
+        note: flagValue(a, "--note") ?? undefined,
+        presenceId: presenceId ?? undefined,
+      }));
+    console.log(JSON.stringify(created, null, 2));
+    const conflicts = Array.isArray(created.conflicts) ? created.conflicts : [];
+    if (conflicts.length > 0) {
+      console.error(`Granted with ${conflicts.length} conflict(s) — advisory, nothing is blocked. Coordinate via run402 rooms send.`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ROOM_FLAGS, "--all", "--help", "-h"], ROOM_FLAGS);
+  requirePositionalCount(positionalArgs(a, ROOM_FLAGS), ROOM_FLAGS, {
+    min: 0, max: 0, command: "run402 claims list", missing: "",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const page = await getSdk().rooms.listClaims(room.orgId, room.roomKey, {
+      includeInactive: a.includes("--all"),
+    });
+    console.log(JSON.stringify(page, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function release(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
+  const positionals = positionalArgs(a, ROOM_FLAGS);
+  requirePositionalCount(positionals, ROOM_FLAGS, {
+    min: 1, max: 1, command: "run402 claims release <claim_id>", missing: "<claim_id>",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    console.log(JSON.stringify(await getSdk().rooms.releaseClaim(room.orgId, room.roomKey, positionals[0]), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+export async function run(sub, args) {
+  const argv = Array.isArray(args) ? args : [];
+  if (!sub || hasHelp([sub, ...argv])) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "create": {
+      await create(argv);
+      break;
+    }
+    case "list": {
+      await list(argv);
+      break;
+    }
+    case "release": {
+      await release(argv);
+      break;
+    }
+    default:
+      failUnknownSubcommand("claims", sub, {
+        hint: "Run `run402 claims --help` for usage.",
+      });
+  }
+}

package/lib/command-manifest.mjs

@@ -200,6 +200,14 @@ export const COMMAND_MANIFEST = [
 
   // ── events / errors (flat, merged runners) ───────────────────────────────
   { path: ["events"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
+  { path: ["rooms", "who"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["rooms", "send"], positionals: [p("body")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["hello"], runStyle: "sub" },
+  { path: ["rooms", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["rooms", "get"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
+  { path: ["rooms", "ack"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
+  { path: ["claims", "create"], positionals: [p("resource")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["deploy"], runStyle: "sub" },
+  { path: ["claims", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["claims", "release"], positionals: [p("claim_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["clm_1"], runStyle: "sub" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────

package/lib/credentials.mjs

@@ -36,6 +36,7 @@ Subcommands:
   status --project <id>               Show one cached entry, redacted
   import --project <id> --service-key-stdin
   import --project <id> --service-key-env <env>
+  import --project <id> --anon-key-env <env>   Rotate only the anon key
   export --project <id> --reveal       Print cached keys, including secrets
   remove --project <id>                Remove one cached key entry
 
@@ -44,6 +45,9 @@ Notes:
   - list/status never reveal full keys.
   - export requires --reveal.
   - import accepts service keys through stdin or an environment variable, not argv.
+  - import writes the whole entry, so the FIRST import must supply a service key.
+    Afterwards --anon-key-env alone rotates the anon key and keeps the cached
+    service key, so an anon rotation never puts a service key through a shell.
 `;
 
 function parseProjectKeyFlags(args, extraKnown = [], valueFlagsExtra = []) {
@@ -143,7 +147,7 @@ async function status(args) {
   console.log(JSON.stringify(redactedEntry(id, getProject(id)), null, 2));
 }
 
-function readSecretInput(parsed) {
+function readSecretInput(parsed, { projectId, anonEnv, existing } = {}) {
   const fromEnv = flagValue(parsed, "--service-key-env");
   const fromStdin = parsed.includes("--service-key-stdin");
   if (fromEnv && fromStdin) {
@@ -161,6 +165,23 @@ function readSecretInput(parsed) {
     return value.trim();
   }
   if (fromStdin) return readFileSync(0, "utf-8").trim();
+
+  // Anon-only rotation: the caller passed --anon-key-env and the entry already
+  // caches a service key. Reuse it rather than making them round-trip a service
+  // key through --reveal and a shell just to change the anon key.
+  if (anonEnv && existing?.service_key) return existing.service_key;
+
+  // Still no service key. Report the flags the caller actually passed — an error
+  // that names only the service-key flags reads as "--anon-key-env is not a flag".
+  if (anonEnv) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Importing an anon key also requires a service key, because import writes the whole cache entry and no service key is cached for ${projectId} yet.`,
+      hint: "Add --service-key-stdin or --service-key-env <env> to this first import. Once an entry exists, --anon-key-env alone rotates the anon key and keeps the cached service key.",
+      details: { project_id: projectId, anon_key_env: anonEnv },
+    });
+  }
+
   fail({
     code: "BAD_USAGE",
     message: "Import requires --service-key-stdin or --service-key-env <env>.",
@@ -178,16 +199,19 @@ async function importKey(args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys import: ${rest[0]}` });
   }
   const id = requireProjectFlag(projectId, "run402 credentials project-keys import --project <id> --service-key-stdin");
-  const serviceKey = readSecretInput(parsed);
-  if (!serviceKey) {
-    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
-  }
+  // Resolve --anon-key-env before requiring a service key, so a missing service
+  // key can report against the flags actually passed and an anon-only rotation
+  // can reuse the cached service key.
   const anonEnv = flagValue(parsed, "--anon-key-env");
   const anonKey = anonEnv ? process.env[anonEnv] : undefined;
   if (anonEnv && !anonKey) {
     fail({ code: "BAD_ENV", message: `Environment variable ${anonEnv} is empty or unset.`, details: { env: anonEnv } });
   }
   const existing = getProject(id);
+  const serviceKey = readSecretInput(parsed, { projectId: id, anonEnv, existing });
+  if (!serviceKey) {
+    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
+  }
   saveProject(id, {
     anon_key: anonKey ?? existing?.anon_key ?? "",
     service_key: serviceKey,

package/lib/pay.mjs

@@ -16,11 +16,13 @@ Usage:
 
 Options:
   --method <M>              HTTP method (default: GET)
-  --body <json-or-text>     Request body (not valid with GET/HEAD)
+  --body <json-or-text>     Request body — the ONLY way to send a payload
+                            (not valid with GET/HEAD)
   --max-usd <amount>        Maximum payment in USD (default: 0.10)
   --idempotency-key <key>   Forward a stable Idempotency-Key to the seller
   --require-receipt         Require verified merchant evidence
-  --json                    Print the response and payment receipt as JSON
+  --json                    No-op; pay always prints JSON. Takes no value —
+                            to send a payload use --body
   --help, -h                Show this help
 
 Examples:
@@ -50,10 +52,11 @@ export async function run(args = [], deps = {}) {
   );
   const positionals = positionalArgs(parsed, VALUE_FLAGS);
   if (positionals.length !== 1) {
+    const stray = positionals[1];
     fail({
       code: "BAD_USAGE",
-      message: positionals.length === 0 ? "URL required." : `Unexpected argument: ${positionals[1]}`,
-      hint: "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]",
+      message: positionals.length === 0 ? "URL required." : `Unexpected argument: ${stray}`,
+      hint: strayArgumentHint(parsed, stray),
     });
   }
 
@@ -113,6 +116,34 @@ export function parseUsdMicros(value) {
   return micros;
 }
 
+const USAGE_HINT = "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]";
+
+// `--json` selects output format and takes no value; `--body` sends the payload.
+// Reaching for `--json '<payload>'` is the predictable confusion, and it lands
+// here as a stray positional. Name the flag the caller actually wanted.
+export function strayArgumentHint(parsed, stray) {
+  if (typeof stray !== "string") return USAGE_HINT;
+  const jsonIndex = parsed.indexOf("--json");
+  if (jsonIndex !== -1 && parsed[jsonIndex + 1] === stray) {
+    return `--json only selects JSON output and takes no value; the request body flag is --body. Retry with: --method POST --body '${stray}'`;
+  }
+  if (looksLikeJson(stray)) {
+    return `To send this payload, pass it as a body: --method POST --body '${stray}'`;
+  }
+  return USAGE_HINT;
+}
+
+function looksLikeJson(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
+  try {
+    JSON.parse(trimmed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function validateUrl(value) {
   try {
     const parsed = new URL(value);

package/lib/pay.test.mjs

@@ -1,7 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
-import { parseUsdMicros, run } from "./pay.mjs";
+import { parseUsdMicros, run, strayArgumentHint } from "./pay.mjs";
 
 describe("run402 pay", () => {
   it("converts decimal USD to micros without floating-point rounding", () => {
@@ -10,6 +10,28 @@ describe("run402 pay", () => {
     assert.equal(parseUsdMicros("0"), 0);
   });
 
+  // `--json` selects output format, `--body` sends the payload. An agent
+  // reaching for `--json '<payload>'` gets a stray positional; the hint has to
+  // name --body or the usage error reads as "the payload was accepted".
+  it("points --json '<payload>' at --body", () => {
+    const payload = '{"kind":"anon"}';
+    const hint = strayArgumentHint(["https://s.example/x", "--json", payload], payload);
+    assert.match(hint, /--json only selects JSON output and takes no value/);
+    assert.match(hint, /--body '\{"kind":"anon"\}'/);
+  });
+
+  it("points a bare JSON positional at --body even without --json", () => {
+    const payload = '{"kind":"anon"}';
+    const hint = strayArgumentHint(["https://s.example/x", payload], payload);
+    assert.match(hint, /pass it as a body: --method POST --body/);
+  });
+
+  it("falls back to plain usage for a stray non-JSON argument", () => {
+    const hint = strayArgumentHint(["https://s.example/x", "stray"], "stray");
+    assert.equal(hint, "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]");
+    assert.equal(strayArgumentHint(["https://s.example/x"], undefined), hint);
+  });
+
   it("delegates to SDK pay.fetch and prints the receipt", async () => {
     let captured;
     const output = [];

package/lib/rooms-context.mjs

@@ -0,0 +1,132 @@
+/**
+ * Shared room resolution + per-checkout session state for the agent-messaging
+ * commands (`run402 messages`, `run402 claims`).
+ *
+ * Room addressing (precedence):
+ *   --org <org_id> + --room <key>   explicit (named org rooms)
+ *   RUN402_ROOM=<org_id>/<key>      env form of the same
+ *   (default)                       the project's DEFAULT room — the room key
+ *                                   IS the project id; org resolved via the
+ *                                   project overview (`rooms.forProject`).
+ *
+ * Session state lives at ./.run402/messaging.json (per-checkout — the house
+ * discipline of one worktree per agent session makes per-checkout equal
+ * per-session). It caches, per room: the session's presence_id + name and the
+ * read cursor. Add `.run402/` to .gitignore. Two sessions sharing one checkout
+ * share a presence (coherent, just undifferentiated); RUN402_PRESENCE_ID
+ * overrides for harnesses that multiplex.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./sdk-errors.mjs";
+import { resolveProjectId } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+
+export const ROOM_ENV = "RUN402_ROOM";
+export const PRESENCE_ENV = "RUN402_PRESENCE_ID";
+
+const STATE_DIR = ".run402";
+const STATE_FILE = "messaging.json";
+
+/** Resolve the addressed room to { orgId, roomKey } (one SDK lookup at most). */
+export async function resolveRoom({ org, room, project } = {}) {
+  if (room && !org) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--room names an org room and needs --org <org_id> beside it.",
+      hint: "For the project's default room, omit both (or pass --project). For a named room: --org <org_id> --room <key>.",
+    });
+  }
+  if (org && room) return { orgId: org, roomKey: room };
+  const envRoom = (process.env[ROOM_ENV] ?? "").trim();
+  if (envRoom) {
+    const slash = envRoom.indexOf("/");
+    if (slash <= 0 || slash === envRoom.length - 1) {
+      fail({
+        code: "BAD_USAGE",
+        message: `${ROOM_ENV} must be "<org_id>/<room_key>".`,
+        details: { value: envRoom },
+      });
+    }
+    return { orgId: envRoom.slice(0, slash), roomKey: envRoom.slice(slash + 1) };
+  }
+  const projectId = resolveProjectId(project);
+  const scoped = await getSdk().rooms.forProject(projectId);
+  return { orgId: scoped.orgId, roomKey: scoped.roomKey };
+}
+
+function statePath() {
+  return join(process.cwd(), STATE_DIR, STATE_FILE);
+}
+
+function loadState() {
+  try {
+    const raw = readFileSync(statePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && parsed.rooms && typeof parsed.rooms === "object"
+      ? parsed
+      : { rooms: {} };
+  } catch {
+    return { rooms: {} };
+  }
+}
+
+function saveState(state) {
+  try {
+    const dir = join(process.cwd(), STATE_DIR);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`);
+  } catch {
+    // Best-effort cache: an unwritable checkout degrades to stateless calls.
+  }
+}
+
+const roomStateKey = (orgId, roomKey) => `${orgId}/${roomKey}`;
+
+export function getRoomState(orgId, roomKey) {
+  return loadState().rooms[roomStateKey(orgId, roomKey)] ?? {};
+}
+
+export function updateRoomState(orgId, roomKey, patch) {
+  const state = loadState();
+  const key = roomStateKey(orgId, roomKey);
+  state.rooms[key] = { ...(state.rooms[key] ?? {}), ...patch };
+  saveState(state);
+}
+
+/** The session's presence id for a room: env override, else the checkout cache. */
+export function cachedPresenceId(orgId, roomKey) {
+  const env = (process.env[PRESENCE_ENV] ?? "").trim();
+  if (env) return env;
+  const cached = getRoomState(orgId, roomKey).presence_id;
+  return typeof cached === "string" && cached ? cached : null;
+}
+
+/**
+ * Run a room call that carries the cached presence. On PRESENCE_EXPIRED (410 —
+ * this session's presence aged out), drop the cache and retry ONCE without a
+ * presence_id so the gateway's resolve-or-create issues a fresh one.
+ */
+export async function withPresenceRetry(orgId, roomKey, call) {
+  const presenceId = cachedPresenceId(orgId, roomKey);
+  try {
+    return await call(presenceId);
+  } catch (err) {
+    const code = err?.body?.code ?? err?.code;
+    if (code === "PRESENCE_EXPIRED" && presenceId) {
+      updateRoomState(orgId, roomKey, { presence_id: null, name: null });
+      return call(null);
+    }
+    throw err;
+  }
+}
+
+/** Cache the presence a response attributed this session to. */
+export function rememberPresence(orgId, roomKey, presence) {
+  if (!presence || typeof presence !== "object") return;
+  const id = presence.presence_id;
+  const name = presence.name;
+  if (typeof id === "string" && id) {
+    updateRoomState(orgId, roomKey, { presence_id: id, ...(typeof name === "string" ? { name } : {}) });
+  }
+}