run402 4.17.8 → 4.18.0

package/README.md

@@ -63,6 +63,8 @@ run402 allowance export    # print {"address":"0x..."} for funding
 
 ### Public Buzz/Nostr identity attribution
 
+Human accounts connect through <https://console.run402.com/identity-links/connect>: a normal browser, fresh passkey, and Buzz approval, with no terminal/event/passkey credential handling. The CLI commands below are the agent EOA ceremony. `identity link list` preserves every active/revoked record and its proof protocol; public identity links and organization memberships are independently revocable.
+
 ```bash
 run402 identity link nostr begin --pubkey <npub-or-hex> --visibility public
 # Publish the returned proof_content as a standalone Buzz kind-1 event.

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>
 
@@ -76,6 +79,9 @@ function print(result) {
   if (result?.status === "pending") {
     console.error("Buzz control-plane state is pending; follow the single next_actions entry in the JSON response.");
   }
+  if (result?.status === "completed" && result?.completed_buzz_human_adoption) {
+    console.error("Completed: Run402 recorded a terminal consent receipt. The public identity attribution does not grant organization authority; the ordinary owner membership is the only source of organization authority. The identity link and membership can be revoked independently, while the receipt remains completed.");
+  }
 }
 
 async function invoke(operation) {

package/lib/buzz.test.mjs

@@ -120,6 +120,39 @@ describe("run402 buzz CLI", () => {
     assert.deepEqual(authModes, ["wallet", "wallet"]);
   });
 
+  it("explains completed receipt, public identity attribution, and membership as independent effects", async () => {
+    sdk = {
+      buzz: {
+        humanAdoptionOffers: {
+          get: async () => ({
+            status: "completed",
+            completed_buzz_human_adoption: {
+              status: "completed",
+              consent_receipt: { status: "completed" },
+              public_identity_attribution: {
+                human_identity_link_id: `idlnk_${"1".repeat(32)}`,
+                authority_for_organization: false,
+                revoke_independently: true,
+              },
+              organization_authority: {
+                membership_id: `org_${"2".repeat(32)}:prin_human`,
+                role: "owner",
+                source: "org_membership",
+                revoke_independently: true,
+              },
+            },
+          }),
+        },
+      },
+    };
+    await run("adopt", ["offer", "show", `buzzhao_${"3".repeat(32)}`]);
+    assert.equal(JSON.parse(stdout[0]).status, "completed");
+    assert.match(stderr.join("\n"), /terminal consent receipt/i);
+    assert.match(stderr.join("\n"), /public identity attribution.*does not grant organization authority/i);
+    assert.match(stderr.join("\n"), /ordinary owner membership.*only source of organization authority/i);
+    assert.match(stderr.join("\n"), /revoke.*independently/i);
+  });
+
   it("maps a Honey enrollment file to the goal-shaped SDK call and prints only JSON", async () => {
     const directory = mkdtempSync(join(tmpdir(), "run402-buzz-cli-"));
     const grantsPath = join(directory, "grants.json");

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/identity.mjs

@@ -3,7 +3,7 @@ import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { normalizeArgv, assertKnownFlags, flagValue, requirePositionalCount, failUnknownSubcommand } from "./argparse.mjs";
 
-const HELP = `run402 identity link — public proof-backed external agent identities
+const HELP = `run402 identity link — public proof-backed external identities
 
 Usage:
   run402 identity link nostr begin --pubkey <npub|hex> --visibility public [--idempotency-key <key>]
@@ -14,8 +14,15 @@ Usage:
   run402 identity link revoke <identity_link_id>
 
 Security and disclosure:
+  - Human linking is a browser/passkey/Buzz ceremony. Open
+    https://console.run402.com/identity-links/connect; do not paste a signed
+    event, passkey, session, private key, or resource id into the CLI.
+  - A human identity link and an organization membership are independent:
+    either can be revoked without implicitly revoking the other.
+  - list uses the active CLI identity: an agent wallet when present, otherwise
+    the signed-in human control-plane session.
   - begin publishes a standalone public kind-1 Nostr event and creates a durable
-    public run402 proof. Revocation does not erase either historical proof.
+    public run402 proof for the agent. Revocation does not erase either historical proof.
   - the Nostr key and run402 wallet stay separate. This command never accepts,
     derives, reads, or prints an nsec, Nostr private key, mnemonic, or seed.
   - the wallet, agent pubkey, and optional Buzz NIP-OA owner attestation become
@@ -84,7 +91,7 @@ async function list(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 identity link list" });
-  try { console.log(JSON.stringify(await getSdk({ authMode: "wallet" }).identityLinks.list(), null, 2)); }
+  try { console.log(JSON.stringify(await getSdk().identityLinks.list(), null, 2)); }
   catch (error) { reportSdkError(error); }
 }
 

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 } : {}) });
+  }
+}