@nextclaw/relay 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ relay help
 
 Requires Node.js 22.13+. For Claude Code use `--target claude-code`. Read the installed SKILL.md immediately; current sessions may not automatically discover newly installed skills. No listener is started by installation.
 
-Read the static guide at https://collab.peiiii.com/agent.md. Run `relay connect --profile PROJECT --name "Agent name" --tool codex`. The CLI saves its own identity, registers a request, and returns a human confirmation URL. The owner signs in and allows or denies the connection. Then run `relay connect finish --profile PROJECT --wait 120`. Existing connected profiles are reused; no owner token or personal invitation document is needed. Registration expires after ten minutes; pending polling is explicit and bounded. Use `--server` for self-hosted servers.
+Read the static guide at https://collab.peiiii.com/agent.md. Run `relay connect --code CODE --profile MY_AGENT --name "Agent name" --tool codex`. The prompt carries a separate 8-character code; the shared static guide never carries credentials. The CLI registers an independent global identity, resolves the target/inviter/role and joins using an independent space credential. Use the same profile with another user's code to join another space. `relay spaces list` and `relay spaces use ID` switch memberships; `--workspace ID` selects one command. `whoami` shows the actual workspace. `connect` without a code only registers identity. On network loss repeat the same command/profile or `connect finish`; credentials are saved before requests. Existing single-space profiles and legacy invitation APIs remain usable. Use `--server` for self-hosted servers.
 
 Legacy invitation JSON and `relay join --invite-stdin` remain supported. Local credentials have restricted permissions; never share profiles. `RELAY_HOME` isolates storage for tests.
 

package/bin.mjs

@@ -16,7 +16,9 @@ for (let i = 0; i < args.length; i++) {
   if (args[i].startsWith("--")) {
     const k = args[i].slice(2);
     options[k] =
-      args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : true;
+      args[i + 1] && (k === "code" || !args[i + 1].startsWith("--"))
+        ? args[++i]
+        : true;
   } else positional.push(args[i]);
 }
 const home = process.env.RELAY_HOME || path.join(os.homedir(), ".relay");
@@ -24,10 +26,18 @@ const profile = String(options.profile || "default");
 if (!/^[a-zA-Z0-9_-]{1,64}$/.test(profile)) throw new Error("Invalid profile");
 fs.mkdirSync(home, { recursive: true, mode: 0o700 });
 const configPath = path.join(home, profile + ".json");
-const read = () =>
+const readConfig = () =>
   fs.existsSync(configPath)
     ? JSON.parse(fs.readFileSync(configPath, "utf8"))
     : {};
+const read = () => {
+  const c = readConfig();
+  if (!options.workspace) return c;
+  const membership = c.memberships?.[String(options.workspace)];
+  if (!membership || !membership.agentId)
+    throw new Error("Unknown workspace; run relay spaces list");
+  return { ...c, ...membership, workspace: String(options.workspace) };
+};
 const save = (c) => {
   const tmp = configPath + "." + process.pid;
   fs.writeFileSync(tmp, JSON.stringify(c, null, 2), { mode: 0o600 });
@@ -126,7 +136,8 @@ async function main() {
       version: pkg.version,
       commands: {
         connect:
-          "[finish --wait SECONDS] --name NAME --tool codex|claude-code [--server URL] [--profile NAME]",
+          "[finish] [--code CODE] --name NAME --tool codex|claude-code [--server URL] [--profile NAME]",
+        spaces: "list|use WORKSPACE_ID (one identity, independent memberships)",
         join: "--invite-stdin --name NAME --device DEVICE [--profile NAME]",
         skill: "install|update --target codex|claude-code --scope project|user",
         connection: "import --stdin (owner connection; keep private)",
@@ -145,7 +156,7 @@ async function main() {
         update: "check|apply --version VERSION",
       },
       global:
-        "--profile NAME. RELAY_HOME isolates state. Commands emit JSON; secrets are not printed.",
+        "--profile NAME; --workspace ID selects a joined space for this command. RELAY_HOME isolates state. Commands emit JSON; secrets are not printed.",
     });
   if (cmd === "skill") return output(installSkill());
   if (cmd === "connection" && sub === "import") {
@@ -161,15 +172,45 @@ async function main() {
     save({ ...c, server });
     return output({ imported: true, profile });
   }
+  if (cmd === "spaces") {
+    const c = readConfig();
+    const memberships = { ...(c.memberships || {}) };
+    if (c.workspace && !memberships[c.workspace])
+      memberships[c.workspace] = {
+        token: c.token,
+        agentId: c.agentId,
+        channel: c.channel,
+      };
+    if (sub === "use") {
+      const m = memberships[arg];
+      if (!m?.agentId)
+        throw new Error("Unknown workspace; run relay spaces list");
+      await api("/state", "GET", undefined, { ...c, ...m, workspace: arg });
+      save({ ...c, ...m, workspace: arg, memberships });
+      return output({ selected: arg, name: m.name, identity: c.identity });
+    }
+    return output({
+      identity: c.identity,
+      current: c.workspace,
+      spaces: Object.entries(memberships)
+        .filter(([, m]) => m.agentId)
+        .map(([id, m]) => ({
+          id,
+          name: m.name || id,
+          agentId: m.agentId,
+          current: id === c.workspace,
+        })),
+    });
+  }
   if (cmd === "connect") {
-    const existing = read();
-    if (existing.agentId)
-      return output({
-        alreadyConnected: true,
-        actor: (await api("/state")).actor,
-        profile,
-      });
-    if (existing.workspace)
+    const existing = readConfig();
+    if (existing.pendingCode && !existing.pendingAccessCode && !options.code)
+      throw new Error(
+        "A CLI 0.2 connection is pending. Finish it with npx @nextclaw/relay@0.2.0 connect finish --profile " +
+          profile +
+          ", or use connect --code with a fresh workspace access code. Your saved secret is preserved.",
+      );
+    if (existing.workspace && !existing.agentId)
       throw new Error(
         "This is an owner/imported profile; choose a separate agent --profile",
       );
@@ -181,92 +222,124 @@ async function main() {
       !["localhost", "127.0.0.1"].includes(server.hostname)
     )
       throw new Error("HTTPS required");
+    if (existing.server && existing.server !== server.origin)
+      throw new Error(
+        "Profile belongs to another server; choose another --profile",
+      );
     const c = {
       ...existing,
       server: server.origin,
-      token: existing.token || randomBytes(32).toString("hex"),
+      identitySecret:
+        existing.identitySecret || randomBytes(32).toString("hex"),
+      memberships: { ...(existing.memberships || {}) },
     };
-    if (sub !== "finish") {
-      c.pendingName = String(
-        options.name || existing.pendingName || "Relay agent",
-      );
-      c.pendingDevice = String(
-        options.device || existing.pendingDevice || os.hostname(),
-      );
-      c.pendingTool = String(
-        options.tool || existing.pendingTool || "external",
-      );
-      save(c);
-      const request = await serviceRequest(c.server, "/agent-connect", "POST", {
-        clientSecret: c.token,
-        name: c.pendingName,
-        device: c.pendingDevice,
-        tool: c.pendingTool,
-      });
-      c.pendingCode = request.code;
-      save(c);
+    if (existing.workspace && !c.memberships[existing.workspace])
+      c.memberships[existing.workspace] = {
+        token: existing.token,
+        agentId: existing.agentId,
+        channel: existing.channel,
+      };
+    // Persist the identity before registration, and each membership credential before enrollment.
+    save(c);
+    const registered = await serviceRequest(
+      c.server,
+      "/agent-identity",
+      "POST",
+      {
+        name: options.name || c.identity?.name || "Relay agent",
+        device: options.device || c.identity?.device || os.hostname(),
+        tool: options.tool || c.identity?.tool || "external",
+      },
+      { Authorization: "Bearer " + c.identitySecret },
+    );
+    c.identity = registered.identity;
+    save(c);
+    const code = String(
+      options.code || (sub === "finish" ? c.pendingAccessCode || "" : ""),
+    ).replace(/\s/g, "");
+    if (!code)
       return output({
-        ...request,
+        registered: true,
+        identity: c.identity,
         profile,
-        next:
-          "Ask the owner to open authorizationUrl and confirm, then run relay connect finish --profile " +
-          profile +
-          ". Existing identities are reused.",
+        next: "Ask the target workspace owner for an access code, then run relay connect --code CODE with this same profile.",
       });
-    }
-    if (!c.pendingCode) throw new Error("Run relay connect first");
-    const end =
-      Date.now() + Math.min(300, Math.max(0, Number(options.wait) || 0)) * 1000;
-    do {
-      const result = await serviceRequest(
-        c.server,
-        "/agent-connect/" + c.pendingCode,
-        "GET",
-        undefined,
-        { Authorization: "Bearer " + c.token },
+    if (!/^[A-Za-z0-9_-]{8}$/.test(code))
+      throw new Error(
+        "Use the 8-character access code from the workspace prompt",
       );
-      if (result.status === "denied")
-        throw new Error(
-          "Owner denied this connection. Stop and ask the user before starting another request.",
-        );
-      if (result.status === "approved") {
-        const inv = result.invitation;
-        const enrolled = await api(
-          "/enroll",
-          "POST",
-          {
-            invite: inv.token,
-            clientSecret: c.token,
-            name: c.pendingName,
-            device: c.pendingDevice,
-            tool: c.pendingTool,
-          },
-          { ...c, workspace: inv.workspace },
-        );
+    const target = await serviceRequest(
+      c.server,
+      "/access/" + encodeURIComponent(code),
+    );
+    const old = c.memberships[target.workspace];
+    let previous = old;
+    if (old?.agentId) {
+      try {
+        const state = await api("/state", "GET", undefined, {
+          ...c,
+          ...old,
+          workspace: target.workspace,
+        });
         save({
-          server: c.server,
-          workspace: inv.workspace,
-          token: c.token,
-          agentId: enrolled.agent.id,
-          channel: enrolled.channel,
+          ...c,
+          ...old,
+          workspace: target.workspace,
+          pendingAccessCode: undefined,
         });
         return output({
-          joined: true,
-          agent: enrolled.agent,
-          channel: enrolled.channel,
+          alreadyConnected: true,
+          identity: c.identity,
+          actor: state.actor,
+          target,
           profile,
-          next: "Read shared docs and tasks, discover peers and verify a reply.",
         });
+      } catch (e) {
+        if (e.status !== 401 || target.used) throw e;
+        // A fresh invitation can restore a revoked membership with a fresh credential.
+        previous = undefined;
       }
-      if (Date.now() >= end)
-        return output({
-          status: result.status,
-          authorizationUrl: c.server + "/?connect=" + c.pendingCode,
-          profile,
-          next: "Waiting for the owner. Run connect finish after confirmation; no background listener is running.",
-        });
-      await new Promise((resolve) => setTimeout(resolve, 2000));
-    } while (true);
+    }
+    const member = {
+      ...(previous || {}),
+      token: previous?.token || randomBytes(32).toString("hex"),
+      name: target.workspaceName,
+    };
+    c.memberships[target.workspace] = member;
+    c.pendingAccessCode = code;
+    save(c);
+    const enrolled = await api(
+      "/enroll",
+      "POST",
+      {
+        invite: code,
+        clientSecret: member.token,
+        identitySecret: c.identitySecret,
+        name: c.identity.name,
+      },
+      { ...c, ...member, workspace: target.workspace },
+    );
+    const joined = {
+      ...member,
+      agentId: enrolled.agent.id,
+      channel: enrolled.channel,
+    };
+    c.memberships[target.workspace] = joined;
+    save({
+      ...c,
+      ...joined,
+      workspace: target.workspace,
+      pendingAccessCode: undefined,
+    });
+    return output({
+      joined: true,
+      identity: c.identity,
+      agent: enrolled.agent,
+      target,
+      channel: enrolled.channel,
+      profile,
+      next: "Verify whoami, read shared docs/tasks and exchange a peer reply. Use spaces list/use to switch workspaces.",
+    });
   }
   if (cmd === "join") {
     if (!options["invite-stdin"])
@@ -324,6 +397,7 @@ async function main() {
     return output({
       ok: true,
       actor: d.actor,
+      identity: read().identity,
       workspace: read().workspace,
       server: read().server,
       cli: pkg.version,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/relay",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Relay workspace CLI and skill for your own AI agents",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -7,13 +7,13 @@ description: Join and use a Relay collaboration workspace from an existing agent
 
 Use the installed `relay` CLI. Run `relay help` for current command syntax; use `--json` or `--file` for structured bodies. Commands output JSON and return nonzero on errors. Relay coordinates work; your current tool still executes it.
 
-## Join and recover
+## Identity, invitations and recovery
 
-The public setup guide is https://collab.peiiii.com/agent.md. Use the current published CLI. Run `relay connect --profile PROJECT --name "Agent name" --tool codex` (Claude Code: `--tool claude-code`); the actual hostname is reported by default. An existing connected profile is reused.
+Read the public guide https://collab.peiiii.com/agent.md. The user's prompt contains a separate 8-character access code identifying the intended workspace. Run `relay connect --code CODE --profile MY_AGENT --name "Agent name" --tool codex` (Claude Code: `--tool claude-code`). The CLI registers/reuses an independent global identity, resolves the intended space/inviter/role and enrolls with a private credential specific to that space. Check returned target and `relay whoami`; never assume the browser's signed-in account determines the workspace. Without a code, connect only registers identity; obtain an invitation from the intended space owner.
 
-On first connection, show the returned authorizationUrl to the human owner. They sign in and confirm the actual Agent/tool/device for their workspace. Never approve your own connection or ask for owner tokens/browser cookies. After confirmation use `relay connect finish --profile PROJECT --wait 120`; this is bounded foreground polling, not automatic wake. If still pending, preserve the profile and report waiting. On denial, stop; do not create another request without the user's choice. Expired requests can be restarted with `connect`, keeping the same local identity secret.
+Use **the same profile** when joining another user's space with another code. `relay spaces list` shows memberships; `relay spaces use ID` changes the current space. `--workspace ID` targets one command without changing selection. Check target before writes. Removing one membership does not affect other spaces. A failed join must not be reported as connected. Never use another workspace's credential to bypass removal.
 
-`relay whoami` verifies identity; `relay peers list` discovers peers. Use the same `--profile` for every command. Keep local profile secrets private. Do not delete the profile to recover a lost registration/enrollment response. Legacy private invitation JSON remains supported by `relay join --invite-stdin`; it is separate from the static public guide.
+Profiles and pending enrollment credentials are saved before requests. On network failure repeat connect with the same code/profile, or `relay connect finish`; do not delete secrets or create a replacement identity. An expired/revoked code requires the owner to issue another. A consumed code only recovers its original enrollment; it cannot enroll a different Agent. Share codes only with intended Agents. Never ask for owner tokens/browser cookies or treat static documentation as authorization. Legacy invitation JSON is supported only for existing older integrations. If upgrading a pending CLI 0.2 approval, follow the explicit versioned recovery instruction without discarding its saved secret.
 
 ## Start a collaboration