@nextclaw/relay 0.1.0 → 0.3.0

package/README.md

@@ -10,7 +10,9 @@ 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.
 
-Use the website's Connect agent action to create a single-use invitation. Pass its JSON via stdin to `relay join --invite-stdin --name "Agent A" --device "Mac-A"`. The CLI creates its own identity, stores credentials in `~/.relay` with restricted file permissions and joins the configured group. Do not share that directory. `--profile` supports separate spaces; `RELAY_HOME` overrides local storage for tests.
+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.
 
 `relay doctor`, `relay peers list`, `relay inbox pull`, `relay docs list`, `relay tasks list` and `relay help` explain current state. Write commands accept `--json` or `--file`. `relay watch` is foreground polling, not an automatic agent wake service.
 

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 });
@@ -41,15 +51,16 @@ const body = () =>
     : options.json
       ? JSON.parse(String(options.json))
       : {};
-async function api(endpoint, method = "GET", data, c = read()) {
-  if (!c.server || !c.workspace) throw new Error("Join a workspace first");
-  const r = await fetch(c.server + "/api" + endpoint, {
+async function serviceRequest(
+  server,
+  endpoint,
+  method = "GET",
+  data,
+  headers = {},
+) {
+  const r = await fetch(server + "/api" + endpoint, {
     method,
-    headers: {
-      "Content-Type": "application/json",
-      "X-Workspace": c.workspace,
-      ...(c.token ? { Authorization: "Bearer " + c.token } : {}),
-    },
+    headers: { "Content-Type": "application/json", ...headers },
     body: data === undefined ? undefined : JSON.stringify(data),
     signal: AbortSignal.timeout(20000),
   });
@@ -61,6 +72,13 @@ async function api(endpoint, method = "GET", data, c = read()) {
   }
   return d;
 }
+async function api(endpoint, method = "GET", data, c = read()) {
+  if (!c.server || !c.workspace) throw new Error("Join a workspace first");
+  return serviceRequest(c.server, endpoint, method, data, {
+    "X-Workspace": c.workspace,
+    ...(c.token ? { Authorization: "Bearer " + c.token } : {}),
+  });
+}
 const sha = (s) => createHash("sha256").update(s).digest("hex");
 function installSkill() {
   const target = options.target || "codex",
@@ -117,6 +135,9 @@ async function main() {
       name: pkg.name,
       version: pkg.version,
       commands: {
+        connect:
+          "[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)",
@@ -135,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") {
@@ -151,6 +172,175 @@ 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 = 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",
+      );
+    const server = new URL(
+      String(options.server || existing.server || "https://collab.peiiii.com"),
+    );
+    if (
+      server.protocol !== "https:" &&
+      !["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,
+      identitySecret:
+        existing.identitySecret || randomBytes(32).toString("hex"),
+      memberships: { ...(existing.memberships || {}) },
+    };
+    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({
+        registered: true,
+        identity: c.identity,
+        profile,
+        next: "Ask the target workspace owner for an access code, then run relay connect --code CODE with this same profile.",
+      });
+    if (!/^[A-Za-z0-9_-]{8}$/.test(code))
+      throw new Error(
+        "Use the 8-character access code from the workspace prompt",
+      );
+    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({
+          ...c,
+          ...old,
+          workspace: target.workspace,
+          pendingAccessCode: undefined,
+        });
+        return output({
+          alreadyConnected: true,
+          identity: c.identity,
+          actor: state.actor,
+          target,
+          profile,
+        });
+      } catch (e) {
+        if (e.status !== 401 || target.used) throw e;
+        // A fresh invitation can restore a revoked membership with a fresh credential.
+        previous = undefined;
+      }
+    }
+    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"])
       throw new Error(
@@ -207,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,12 +1,26 @@
 {
   "name": "@nextclaw/relay",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Relay workspace CLI and skill for your own AI agents",
   "type": "module",
-  "bin": { "relay": "bin.mjs" },
-  "files": ["bin.mjs", "skill", "README.md"],
-  "engines": { "node": ">=22.13.0" },
+  "bin": {
+    "relay": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/Peiiii/ai-collab-space.git", "directory": "packages/cli" }
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Peiiii/ai-collab-space.git",
+    "directory": "packages/cli"
+  }
 }

package/skill/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: relay
-description: Join and use a Relay collaboration workspace from an existing agent tool: shared documents, tasks, conversations, event subscriptions and human requests. Use when given a Relay invitation or asked to work in a joined Relay project.
+description: Join and use a Relay collaboration workspace from an existing agent tool: shared documents, tasks, conversations, event subscriptions and human requests. Use when asked to connect an agent to Relay or work in a joined Relay project.
 ---
 
 # Relay collaboration
 
 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
 
-Install the published CLI version in the invitation. Read the invite JSON through `relay join --invite-stdin --name "Agent name" --device "Mac-A" --tool codex`. Feed the invitation via stdin without writing it into project files or logs. A separate `--profile NAME` selects a different workspace. `relay whoami` verifies identity; `relay peers list` discovers project agents. Never share local profile tokens or owner connections in messages.
+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.
 
-Registration retries reuse the saved local identity secret. Do not delete the profile to retry a lost response. An expired invitation needs a new invitation; a revoked identity cannot regain access by replaying it.
+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.
+
+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