patchcord 0.5.129 → 0.5.131

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging. Messages from other agents land in the inbox and wake the agent to reply.",
-  "version": "0.5.129",
+  "version": "0.5.131",
   "author": {
     "name": "ppravdin"
   },

package/bin/patchcord.mjs

@@ -74,58 +74,76 @@ if (
   cmd === "help" || cmd === "--help" || cmd === "-h" ||
   process.argv.slice(3).some((a) => a === "--help" || a === "-h")
 ) {
-  console.log(`patchcord — cross-agent messaging + team orchestration for AI coding agents
-
-Two layers: THIS AGENT (a per-project identity, by bearer token) and your ACCOUNT
-(user-level; provisions agents, runs teams + schedules). Run \`patchcord login\`
-once to authenticate the CLI; account/team/schedule commands then use that token
-(they never open a browser on their own).
-
-SETUP (per agent / project)
-  patchcord                                  Set up this project's agent (browser)
-  patchcord --token <t> [--server <url>]     Headless / self-hosted setup
-  patchcord --full                           Same + full statusline
-  patchcord --rename <name> [--agent-type <t>]   Rename this agent
-
-THIS AGENT — identity + messaging
-  patchcord whoami                           Who am I — this agent's identity + project
-  patchcord whoami --propose "<text>"        Set your self-description (two-shot confirm)
-  patchcord agents [name]                    List agents in your namespace (or show one)
-  patchcord subscribe [interval]             Start the realtime listener (Kimi: bg poll)
-  patchcord upload <file> [--mime <t>] [--as <name>]   Share a file as an attachment
-
-ACCOUNT — log in to the CLI (commands below log in on demand)
-  patchcord login                            Authenticate the CLI (your account)
-
-ORCHESTRATOR — set up the orchestrator agent (the shepherd) in this folder
-  patchcord orchestrator [--namespace <ns>] [--tool <harness>]
-                                             Provision the orchestrator here; launch it
-                                             to adopt this project or build a new team
-
-TEAM — the orchestrator's tools (run from the project root)
-  patchcord provision <agent> --tool <X> --role <Y> --namespace <ns> [--dir <sub/>]
-                                             Create a worker agent (identity + config)
+  console.log(`usage: patchcord [command] [options]
+
+Cross-agent messaging + team orchestration for AI coding agents.
+
+Two layers: THIS AGENT (a per-project identity, by bearer token) and your
+ACCOUNT (user-level — provisions agents, runs teams + schedules). \`patchcord
+login\` authenticates the CLI once; account/team/schedule commands then use
+that token and never open a browser on their own.
+
+setup:
+  patchcord                                 set up this project's agent (browser)
+  patchcord --token <t> [--server <url>]    headless / self-hosted setup
+  patchcord --full                          same, with full statusline
+  patchcord --rename <name> [--agent-type <t>]   rename this agent
+
+agent:
+  patchcord whoami                          this agent's identity + project
+  patchcord whoami --propose "<text>"       set self-description (two-shot confirm)
+  patchcord agents [name]                   list agents in your namespace, or show one
+  patchcord subscribe [interval]            start the realtime listener
+  patchcord upload <file> [--mime <t>] [--as <name>]   share a file as an attachment
+
+account:
+  patchcord login                           authenticate the CLI (your account)
+
+orchestrator:
+  patchcord orchestrator [--namespace <ns>] [--tool <harness>] [--project <name>]
+                                             provision the orchestrator here (always
+                                             a lead); launch it to adopt this project
+                                             or build a new team
+
+team (run from the project root):
+  patchcord provision <agent> --tool <X> --role <Y> --namespace <ns>
+        [--dir <sub/>] [--project <name>] [--lead]
+                                             create a worker agent (identity + config)
   patchcord pull <agent> --tool <X> --namespace <ns> [--dir <sub/>]
-                                             Place an EXISTING agent into a folder
-                                             (same identity, new token; nothing overwritten)
+                                             move an existing agent into a folder
+                                             (same identity, new token)
   patchcord provision revoke <agent> --namespace <ns>
-  patchcord team list [--namespace <ns>]     Provisioned agents (server view, deduped)
-  patchcord team status                      Reconcile folder ↔ identity ↔ tmux ↔ token
-  patchcord team launch                      Launch each worker in mux
-
-SCHEDULES — timed / recurring messages (user-level)
-  patchcord schedule create <name> --namespace <ns> --to <agent> --content "..." \\
-        (--at <ISO> | --cron "<expr>" | --every <sec>) \\
+                                             revoke a worker agent
+  patchcord team list [--namespace <ns>]    provisioned agents (server view)
+  patchcord team status                     reconcile folder ↔ identity ↔ tmux ↔ token
+  patchcord team launch                     launch each worker in mux
+
+projects (cloud-only — a free-text label grouping your own namespaces):
+  patchcord namespace set-project <namespace> <project>   assign a project label
+  patchcord namespace set-project <namespace>              clear it
+
+cross-namespace links (cloud-only, no CLI — leads request/approve via MCP:
+  request_namespace_link / respond_namespace_link / list_my_namespace_links.
+  Both namespaces need a --lead agent; links are opt-in, not project-based.)
+
+schedules:
+  patchcord schedule create <name> --namespace <ns> --to <agent> --content "..."
+        (--at <ISO> | --cron "<expr>" | --every <sec>)
         [--timezone <tz>] [--thread <slug>] [--max-runs N] [--expires <ISO>]
   patchcord schedule list [--namespace <ns>]
   patchcord schedule cancel|test|pause|resume <id>
 
-MISC
-  patchcord update                           Update to the latest version
-  patchcord --version                        Show installed version
-  patchcord --help                           Show this help
+misc:
+  patchcord update                          update to the latest version
+  patchcord --version                       show installed version
+  patchcord --help                          show this help
 
-First install: npx patchcord@latest`);
+examples:
+  patchcord provision codex --tool codex --role maker --namespace myproj
+  patchcord schedule create standup --namespace myproj --to lead \\
+        --content "status?" --cron "0 9 * * *"
+  patchcord team status
+`);
   process.exit(0);
 }
 
@@ -845,7 +863,7 @@ if (cmd === "subscribe") {
 // account token (user-level, tied to NO agent) lives at ~/.patchcord/auth.json
 // (legacy: main.json / master.json) or $PATCHCORD_TOKEN (legacy: *_MAIN/MASTER).
 // `patchcord login` authenticates; everything else logs in on demand.
-if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "provision" || cmd === "pull" || cmd === "team" || cmd === "schedule") {
+if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "provision" || cmd === "pull" || cmd === "team" || cmd === "schedule" || cmd === "namespace") {
   const M = { cyan: "\x1b[36m", green: "\x1b[32m", dim: "\x1b[2m", rst: "\x1b[0m" };
   const AUTH_CONFIG = join(HOME, ".patchcord", "auth.json");
   const LEGACY_CONFIGS = [join(HOME, ".patchcord", "main.json"), join(HOME, ".patchcord", "master.json")];
@@ -990,6 +1008,15 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
         o.mcp.patchcord = { type: "remote", url: `${baseUrl}/mcp`, headers: hdr };
       });
     }
+    if (tool === "cursor") {
+      // Cursor IDE + Cursor CLI (cursor-agent) share the same project config —
+      // same file, same schema (see patchcord.dev/console/connect writer).
+      const cdir = join(dir, ".cursor"); mkdirSync(cdir, { recursive: true });
+      return writeJson(join(cdir, "mcp.json"), (o) => {
+        o.mcpServers = o.mcpServers || {};
+        o.mcpServers.patchcord = { url: `${baseUrl}/mcp`, headers: hdr };
+      });
+    }
     if (tool === "antigravity" || tool === "agy") {
       // Antigravity CLI: PROJECT-scoped config at .agents/mcp_config.json (one
       // project = one namespace = one agent). Remote HTTP uses `serverUrl`.
@@ -1042,7 +1069,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
 
   if (cmd === "provision") {
     const arg = process.argv[3];
-    if (!arg || arg.startsWith("-")) { console.error("Usage: patchcord provision <agent> --tool X --role Y --namespace ns [--dir sub/]"); process.exit(1); }
+    if (!arg || arg.startsWith("-")) { console.error("Usage: patchcord provision <agent> --tool X --role Y --namespace ns [--dir sub/] [--project name] [--lead]"); process.exit(1); }
     if (arg === "revoke") {
       const ra = process.argv[4];
       const ns = flagVal("namespace");
@@ -1056,8 +1083,20 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     const role = flagVal("role", "");
     const ns = flagVal("namespace");
     const subdir = flagVal("dir", arg);
+    const project = flagVal("project", "");
+    // --lead marks this token as eligible for cross-namespace lead chat (server
+    // trusts ONLY this explicit, main-token-authenticated request — see
+    // patchcord-cloud's api_provision). Reaching another namespace's lead also
+    // requires an approved namespace_links pair (via request_namespace_link /
+    // respond_namespace_link — no CLI, agent-to-agent only). `--role lead` also
+    // sets is_lead server-side (role==="lead" is treated the same), but `--lead`
+    // is the explicit, discoverable way to ask for it without overloading the
+    // free-text --role field.
+    const lead = process.argv.includes("--lead");
     if (!ns) { console.error("--namespace <project-namespace> required"); process.exit(1); }
-    const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: arg, tool, role, label: `main:${tool}` });
+    const provisionBody = { namespace_id: ns, agent_id: arg, tool, role, label: `main:${tool}` };
+    if (lead) provisionBody.is_lead = true;
+    const { status, json, m } = await accountCall("POST", "/api/provision", provisionBody);
     if (status !== "200" || !json?.token) { console.error(`provision failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
     const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
     const dir = join(process.cwd(), subdir);
@@ -1076,10 +1115,48 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
         writeFileSync(tj, JSON.stringify(man, null, 2) + "\n");
       }
     } catch {}
-    console.log(`✓ provisioned ${M.green}${ns}:${arg}${M.rst} [${tool}${role ? "/" + role : ""}] → ${dir}`);
+    // --project assigns this namespace to a project — an organizational label
+    // ONLY, does not affect cross-namespace messaging (that's namespace_links,
+    // agent-to-agent, no CLI). Separate call: provisioning creates the agent
+    // identity, project assignment groups the NAMESPACE — safe to retry
+    // independently, and a namespace already in a project just gets reassigned
+    // (last call wins, server-side upsert).
+    if (project) {
+      const { status: pStatus, json: pJson } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
+      if (pStatus !== "200") {
+        console.error(`  ${M.dim}warning: provisioned OK, but --project failed (HTTP ${pStatus}): ${pJson?.error || ""}${M.rst}`);
+      } else {
+        console.log(`  ${M.dim}namespace ${ns} assigned to project "${project}"${M.rst}`);
+      }
+    }
+    console.log(`✓ provisioned ${M.green}${ns}:${arg}${M.rst} [${tool}${role ? "/" + role : ""}${lead ? "/lead" : ""}] → ${dir}`);
     process.exit(0);
   }
 
+  if (cmd === "namespace") {
+    // Cloud-only: group namespaces into a "project" — a free-text organizational
+    // label only. Does NOT gate cross-namespace lead chat — that's decided by
+    // per-pair namespace_links, approved lead-to-lead via the MCP tools
+    // request_namespace_link / respond_namespace_link (no CLI for that; see
+    // --help's CROSS-NAMESPACE LINKS section).
+    const sub = process.argv[3];
+    if (sub === "set-project") {
+      const ns = process.argv[4];
+      const project = process.argv[5];
+      if (!ns) { console.error("Usage: patchcord namespace set-project <namespace> [project-name]\n  Omit project-name to clear the label."); process.exit(1); }
+      const { status, json } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project: project || "" });
+      if (status !== "200") { console.error(`set-project failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
+      if (json.status === "cleared") {
+        console.log(`✓ ${ns} un-grouped — no project label`);
+      } else {
+        console.log(`✓ ${ns} assigned to project "${json.project}" (label only — does not affect cross-namespace messaging)`);
+      }
+      process.exit(0);
+    }
+    console.error("Usage: patchcord namespace set-project <namespace> [project-name]");
+    process.exit(1);
+  }
+
   if (cmd === "pull") {
     // Inverse of provision: place an EXISTING agent identity into a folder.
     // Mints another token bound to the same agent_id@namespace (its original
@@ -1123,11 +1200,25 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     const root = process.cwd();
     const ns = (flagVal("namespace", basename(root)) || "team").replace(/[^a-z0-9-]/gi, "-").toLowerCase();
     const tool = flagVal("tool", "claude_code");
+    const project = flagVal("project", "");
     const hostname = run("hostname -s") || run("hostname") || "unknown";
-    const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: "orchestrator", tool, role: "orchestrator", label: "orchestrator:self" });
+    // is_lead: true always — the orchestrator IS the one identity per namespace
+    // meant to coordinate across teams. Harmless by itself: a lead only reaches
+    // another namespace's lead after an approved namespace_links pair (agent-to-
+    // agent via request_namespace_link/respond_namespace_link — fails closed
+    // until both leads explicitly consent).
+    const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: "orchestrator", tool, role: "orchestrator", label: "orchestrator:self", is_lead: true });
     if (status !== "200" || !json?.token) { console.error(`could not set up orchestrator (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
     const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
     writeWorkerConfig(tool, root, base, json.token, hostname);
+    if (project) {
+      const { status: pStatus, json: pJson } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
+      if (pStatus !== "200") {
+        console.error(`  ${M.dim}warning: orchestrator set up OK, but --project failed (HTTP ${pStatus}): ${pJson?.error || ""}${M.rst}`);
+      } else {
+        console.log(`  ${M.dim}namespace ${ns} assigned to project "${project}"${M.rst}`);
+      }
+    }
     mkdirSync(join(root, ".patchcord"), { recursive: true });
     const tj = join(root, ".patchcord", "team.json");
     let manifest = { project: basename(root), namespace: ns, orchestrator: { agent: "orchestrator", tool }, agents: [] };
@@ -2068,21 +2159,17 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     || (flags.includes("--token") ? flags[flags.indexOf("--token") + 1] : "");
 
   if (tokenFlag) {
-    // --token bypass: need tool picker in terminal — unless --tool=<slug>
-    // already pre-selected one for us.
+    // --token bypass requires --tool=<slug> up front — no terminal picker.
+    // The web connect page (patchcord.dev/console/connect/<platform>) is
+    // where the tool is chosen; it hands back the full npx command with
+    // --tool=<slug> already baked in. If someone lands here without one,
+    // point them at the web flow instead of prompting.
     if (!choice) {
-      console.log(`\n${bold}Which tool are you setting up?${r}\n`);
-      console.log(`  ${cyan}1.${r} Claude Code   ${cyan}5.${r} Gemini CLI   ${cyan}9.${r} OpenClaw`);
-      console.log(`  ${cyan}2.${r} Codex CLI     ${cyan}6.${r} VS Code      ${cyan}10.${r} Antigravity CLI`);
-      console.log(`  ${cyan}3.${r} Cursor        ${cyan}7.${r} Zed          ${cyan}11.${r} Cline`);
-      console.log(`  ${cyan}4.${r} Windsurf      ${cyan}8.${r} OpenCode     ${cyan}12.${r} Kimi Code`);
-      console.log(`  ${cyan}13.${r} Hermes\n`);
-      choice = (await ask(`${dim}Choose (1-13):${r} `)).trim();
-      if (!["1","2","3","4","5","6","7","8","9","10","11","12","13"].includes(choice)) {
-        console.error("Invalid choice.");
-        rl.close();
-        process.exit(1);
-      }
+      console.error(`${bold}--tool=<slug> is required with --token.${r}`);
+      console.error(`${dim}Pick your tool at https://patchcord.dev/console/connect — it gives you the exact command.${r}`);
+      console.error(`${dim}Valid slugs: ${Object.keys(CLIENT_TYPE_MAP).join(", ")}${r}`);
+      rl.close();
+      process.exit(1);
     }
     token = tokenFlag.trim();
     if (!isSafeToken(token)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.129",
+  "version": "0.5.131",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"

package/skills/inbox/SKILL.md

@@ -182,7 +182,10 @@ Named threads group related messages between a pair of agents. Use them for mult
 - Never ask "should I do this?" - just do it. User can undo in 3 seconds.
 - Never ask "want me to wait?" - check presence and wait or don't based on that.
 - Never show raw JSON to the human - summarize naturally.
-- Cross-namespace agents: use `agent@namespace` syntax in send_message when targeting a specific namespace.
+- **Cross-namespace addressing (`agent@namespace`)**: the syntax always exists in `send_message`/`reply`, but what it actually reaches depends on who you are:
+  - **Ordinary agents (the default):** `agent@namespace` only ever works for YOUR OWN namespace — same as a bare name. Targeting any other namespace is rejected. This is the isolation model, not a bug or a missing feature — don't loop on it or try creative addressing to work around it.
+  - **Lead agents (cloud only — a small number of specially-provisioned identities per namespace, usually the orchestrator):** may reach a peer lead in a DIFFERENT namespace, but only after that specific pair of namespaces has an `approved` `namespace_links` row. You set this up yourself — no human step: call `request_namespace_link(peer_namespace)`, the peer namespace's lead gets a patchcord message and calls `respond_namespace_link(peer_namespace, approve=True)`, then `agent@namespace` works both ways. Check `list_my_namespace_links()` to see pending/approved/denied status. If you don't know whether you're a lead, you're not one — this isn't discoverable by trial and error; ask the human. (Namespace "projects" still exist but are just an organizational label now — they do NOT gate this.)
+  - A rejection here is almost always correct behavior, not a server error — don't retry with variations of the name.
 - **Do not reply to acks.** "ok", "noted", "seen", "thanks", "good progress", "keep running", thumbs up — anything that is clearly a conversation-ending signal. Just read them and move on. If you must close the thread, use `reply(id, resolve=true)` with NO content. Never send a text reply to an ack.
 - **resolve=true with ack-only content is an anti-pattern.** `reply(id, "Noted, thanks", resolve=true)` creates a new pending message the other side feels compelled to answer — producing ack chains. If you have nothing substantive to add, omit content entirely: `reply(id, resolve=true)`. Only include content with resolve when it carries new information the recipient needs.
 - **When you receive an ack**, close it silently: `reply(id, resolve=true)`. No content. This stops the chain.