@nextclaw/relay 0.1.0 → 0.2.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 --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.
+
+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

@@ -41,15 +41,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 +62,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 +125,8 @@ async function main() {
       name: pkg.name,
       version: pkg.version,
       commands: {
+        connect:
+          "[finish --wait SECONDS] --name NAME --tool codex|claude-code [--server URL] [--profile NAME]",
         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)",
@@ -151,6 +161,113 @@ async function main() {
     save({ ...c, server });
     return output({ imported: true, profile });
   }
+  if (cmd === "connect") {
+    const existing = read();
+    if (existing.agentId)
+      return output({
+        alreadyConnected: true,
+        actor: (await api("/state")).actor,
+        profile,
+      });
+    if (existing.workspace)
+      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");
+    const c = {
+      ...existing,
+      server: server.origin,
+      token: existing.token || randomBytes(32).toString("hex"),
+    };
+    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);
+      return output({
+        ...request,
+        profile,
+        next:
+          "Ask the owner to open authorizationUrl and confirm, then run relay connect finish --profile " +
+          profile +
+          ". Existing identities are reused.",
+      });
+    }
+    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 (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 },
+        );
+        save({
+          server: c.server,
+          workspace: inv.workspace,
+          token: c.token,
+          agentId: enrolled.agent.id,
+          channel: enrolled.channel,
+        });
+        return output({
+          joined: true,
+          agent: enrolled.agent,
+          channel: enrolled.channel,
+          profile,
+          next: "Read shared docs and tasks, discover peers and verify a reply.",
+        });
+      }
+      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);
+  }
   if (cmd === "join") {
     if (!options["invite-stdin"])
       throw new Error(

package/package.json

@@ -1,12 +1,26 @@
 {
   "name": "@nextclaw/relay",
-  "version": "0.1.0",
+  "version": "0.2.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,6 +1,6 @@
 ---
 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
@@ -9,9 +9,11 @@ Use the installed `relay` CLI. Run `relay help` for current command syntax; use
 
 ## Join and recover
 
-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.
+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.
 
-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.
+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.
+
+`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.
 
 ## Start a collaboration