patchcord 0.6.9 → 0.6.11

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.6.9",
+  "version": "0.6.11",
   "author": {
     "name": "ppravdin"
   },

package/bin/patchcord.mjs

@@ -10,6 +10,7 @@ const HOME = homedir();
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pluginRoot = join(__dirname, "..");
+import { resolveProjectBearer, harnessContext } from "../scripts/lib/resolve-project-bearer.mjs";
 const cmd = process.argv[2];
 
 if (cmd === "--version" || cmd === "-v") {
@@ -42,30 +43,6 @@ function isSafeId(s) {
   return /^[A-Za-z0-9_\-]+$/.test(s) && s.length < 100;
 }
 
-const PROJECT_MARKERS = [
-  ".git", "package.json", "package-lock.json", "Cargo.toml", "go.mod", "go.sum",
-  "pyproject.toml", "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
-  "Gemfile", "composer.json", "mix.exs", "requirements.txt", "setup.py",
-  ".claude", ".codex", ".cursor", ".grok", ".vscode", ".kimi", ".openclaw",
-];
-
-function detectFolder(dir) {
-  if (dir === HOME || dir === HOME + "/" || dir === "/") return "HOME";
-  for (const m of PROJECT_MARKERS) {
-    if (existsSync(join(dir, m))) return "PROJECT";
-  }
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch { return "UNKNOWN"; }
-  if (entries.length === 0) return "EMPTY";
-  const files = entries.filter(e => e.isFile());
-  const dirs = entries.filter(e => e.isDirectory());
-  if (files.length === 0 && dirs.length >= 2) return "CONTAINER";
-  return "UNKNOWN";
-}
-
-
 // A trailing --help/-h on ANY subcommand must show help and exit — never run the
 // command. (patchcord orchestrator --help used to PROVISION an orchestrator;
 // patchcord login --help hung on the browser login. Side-effecting --help is a
@@ -158,13 +135,7 @@ if (cmd === "plugin-path") {
 // opencode (per-project) + windsurf, gemini, zed, openclaw, antigravity,
 // cline, kimi (global). Each tool stores the bearer in its own shape.
 function _kimiContextRequested(options = {}) {
-  const forceTool = (process.env.PATCHCORD_FORCE_TOOL || process.env.PATCHCORD_TOOL || "").toLowerCase();
-  return options.preferKimi === true
-    || forceTool === "kimi"
-    || Boolean(process.env.KIMI_CLI)
-    || Boolean(process.env.KIMI_SESSION_ID)
-    || Boolean(process.env.KIMI_CONFIG_FILE)
-    || Boolean(process.env.KIMI_MCP_CONFIG_FILE);
+  return harnessContext(process.env, options).preferKimi;
 }
 
 // Strip legacy Python kimi-cli per-project artifacts. Kimi Code (Node) uses
@@ -292,7 +263,9 @@ function readGrokTomlShape(path) {
 
 async function _resolveBearer(options = {}) {
   const { readFileSync } = await import("fs");
-  const preferKimi = _kimiContextRequested(options);
+
+  const projectFound = resolveProjectBearer(process.cwd(), options);
+  if (projectFound) return projectFound;
 
   // Strict JSON first; fall back to JSONC stripping for zed/gemini-style
   // settings (which allow // /* */ trailing commas). The fallback strips
@@ -381,30 +354,6 @@ async function _resolveBearer(options = {}) {
     } catch { return null; }
   };
 
-  // Per-project (walk up from cwd). First win.
-  const kimiProjectReader = (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
-  const kimiCodeProjectReader = (cwd) => readJsonAt(join(cwd, ".kimi-code", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
-  const defaultProjectReaders = [
-    (cwd) => readJsonAt(join(cwd, ".mcp.json"), ["mcpServers", "patchcord"], "claude_code"),
-    (cwd) => readJsonAt(join(cwd, ".cursor", "mcp.json"), ["mcpServers", "patchcord"], "cursor"),
-    (cwd) => readJsonAt(join(cwd, ".vscode", "mcp.json"), ["servers", "patchcord"], "vscode"),
-    (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "patchcord"], "opencode"),
-    (cwd) => readJsonAt(join(cwd, ".agents", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity"),
-    (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml")),
-    (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml")),
-  ];
-  const projectReaders = preferKimi
-    ? [kimiProjectReader, kimiCodeProjectReader, ...defaultProjectReaders]
-    : [...defaultProjectReaders, kimiProjectReader, kimiCodeProjectReader];
-  let dir = process.cwd();
-  while (dir && dir !== "/") {
-    for (const r of projectReaders) {
-      const found = r(dir);
-      if (found) { found.scope = "project"; return found; }
-    }
-    dir = dirname(dir);
-  }
-
   // Global fallbacks. Order by likelihood for current install base.
   const zedPath = process.platform === "darwin"
     ? join(HOME, "Library", "Application Support", "Zed", "settings.json")
@@ -929,8 +878,8 @@ if (cmd === "subscribe") {
 // ── main flow: global setup + project setup (or just install/agent for back-compat) ──
 // Any --flag enters this branch so equals-form (--token=foo, --tool=foo, --server=foo)
 // works the same as the space-form (--token foo). The internal flag parsing below
-// supports both. Non-flag commands (init, skill, help, plugin-path) have
-// their own branches above and below.
+// supports both. Non-flag commands (skill, help, plugin-path) have their own
+// branches above and below.
 // ── CLI account auth + orchestrator/team/provisioning/schedule ─────────────
 // These commands act on the user's ACCOUNT, so they require CLI login. The
 // account token (user-level, tied to NO agent) lives at ~/.patchcord/auth.json
@@ -1635,17 +1584,6 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     return out.replace(/,(\s*[}\]])/g, "$1");
   }
 
-  function safeReadJson(filePath) {
-    try {
-      const raw = readFileSync(filePath, "utf-8");
-      // Try strict JSON first (avoids corrupting URLs with //)
-      try { return JSON.parse(raw); } catch {}
-      // Fall back to JSONC stripping for Zed/Gemini-style configs
-      const cleaned = _stripJsoncOutsideStrings(raw);
-      return cleaned.trim() ? JSON.parse(cleaned) : {};
-    } catch { return null; }
-  }
-
   // Read+merge+write a JSON config file. If the file exists but its contents
   // can't be parsed, REFUSE to write — silently overwriting would erase
   // unrelated MCP servers, settings, or hand-edits the user has in there.
@@ -2270,7 +2208,8 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
 
-  // Tool picker only shown for --token bypass. Browser flow gets tool from web.
+  // Harness choice: --tool=<slug>, browser connect client_type, or existing-token
+  // refresh. There is no terminal tool picker — dashboard / connect page picks once.
   let choice = "";
 
   const CLIENT_TYPE_MAP = {
@@ -2306,8 +2245,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   // web UI; the installer skips its terminal picker, and the
   // `&tool=<slug>` query param appended to the browser connectUrl below
   // makes the web /connect page skip its picker too.
-  // Unknown slugs (incl. `replit`, `unknown`) silently fall through —
-  // the existing interactive flow takes over.
+  // Unknown slugs fall through; browser connect may default harness to Claude Code.
   const toolFlag = flags.find(f => f.startsWith("--tool="))?.split("=")[1]
     || (flags.includes("--tool") ? flags[flags.indexOf("--tool") + 1] : "");
   let toolSlug = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "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/scripts/lib/resolve-project-bearer.mjs

@@ -0,0 +1,200 @@
+// Shared per-project bearer resolution for patchcord.mjs and subscribe.mjs.
+// When multiple tool configs exist in one directory (common: .mcp.json from
+// Claude Code + .cursor/mcp.json from Cursor), pick the config matching the
+// invoking harness instead of always preferring .mcp.json first.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function stripJsoncOutsideStrings(raw) {
+  let out = "";
+  let i = 0;
+  let inStr = false;
+  let strCh = "";
+  let prev = "";
+  while (i < raw.length) {
+    const c = raw[i];
+    if (inStr) {
+      out += c;
+      if (c === strCh && prev !== "\\") inStr = false;
+      prev = c;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inStr = true;
+      strCh = c;
+      out += c;
+      prev = c;
+      i++;
+      continue;
+    }
+    if (c === "/" && raw[i + 1] === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && raw[i + 1] === "*") {
+      i += 2;
+      while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    prev = c;
+    i++;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+}
+
+function parseJsonc(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {}
+  return JSON.parse(stripJsoncOutsideStrings(raw));
+}
+
+function extractBearer(entry) {
+  if (!entry) return null;
+  const auth = entry?.headers?.Authorization;
+  const url = entry.url || entry.httpUrl || entry.serverUrl;
+  if (!auth || !url) return null;
+  return {
+    token: auth.replace(/^Bearer\s+/i, ""),
+    baseUrl: url.replace(/\/mcp(\/bearer)?$/, ""),
+  };
+}
+
+function readJsonAt(path, keyPath, tool) {
+  if (!existsSync(path)) return null;
+  try {
+    const obj = parseJsonc(readFileSync(path, "utf-8"));
+    const entry = keyPath.reduce((o, k) => o?.[k], obj);
+    const b = extractBearer(entry);
+    return b ? { ...b, configFile: path, tool } : null;
+  } catch {
+    return null;
+  }
+}
+
+function readCodexTomlShape(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf-8");
+    const block = content.match(/\[mcp_servers\.patchcord[-\w]*\]([\s\S]*?)(?=\n\[|$)/);
+    if (!block) return null;
+    const urlMatch = block[1].match(/url\s*=\s*"([^"]+)"/);
+    const tokenMatch = block[1].match(/Bearer\s+([^\s"]+)/);
+    if (!urlMatch || !tokenMatch) return null;
+    return {
+      token: tokenMatch[1],
+      baseUrl: urlMatch[1].replace(/\/mcp(\/bearer)?$/, ""),
+      configFile: path,
+      tool: "codex",
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readGrokTomlShape(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf-8");
+    const header = content.match(/^\[mcp_servers\.patchcord(?:[-\w]*)?\]\s*$/m);
+    if (!header) return null;
+    const rest = content.slice(header.index + header[0].length);
+    const nextSection = rest.search(/^\[(?!mcp_servers\.patchcord(?:\.|[-\w]*\]))/m);
+    const block = nextSection === -1 ? rest : rest.slice(0, nextSection);
+    const urlMatch = block.match(/^\s*url\s*=\s*["']([^"']+)["']/m);
+    const tokenMatch = block.match(/["']?Authorization["']?\s*=\s*["']Bearer\s+([^"']+)["']/i);
+    if (!urlMatch || !tokenMatch) return null;
+    return {
+      token: tokenMatch[1],
+      baseUrl: urlMatch[1].replace(/\/mcp(\/bearer)?$/, ""),
+      configFile: path,
+      tool: "grok",
+    };
+  } catch {
+    return null;
+  }
+}
+
+const claudeReader = (cwd) => readJsonAt(join(cwd, ".mcp.json"), ["mcpServers", "patchcord"], "claude_code");
+const cursorReader = (cwd) => readJsonAt(join(cwd, ".cursor", "mcp.json"), ["mcpServers", "patchcord"], "cursor");
+const vscodeReader = (cwd) => readJsonAt(join(cwd, ".vscode", "mcp.json"), ["servers", "patchcord"], "vscode");
+const opencodeReader = (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "patchcord"], "opencode");
+const antigravityReader = (cwd) => readJsonAt(join(cwd, ".agents", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity");
+const grokReader = (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml"));
+const codexReader = (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml"));
+const kimiReader = (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
+const kimiCodeReader = (cwd) => readJsonAt(join(cwd, ".kimi-code", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
+
+/** Detect which harness launched this process (env + explicit overrides). */
+export function harnessContext(env = process.env, options = {}) {
+  const forceTool = (env.PATCHCORD_FORCE_TOOL || env.PATCHCORD_TOOL || "").toLowerCase();
+  const preferKimi =
+    options.preferKimi === true
+    || forceTool === "kimi"
+    || Boolean(env.KIMI_CLI)
+    || Boolean(env.KIMI_SESSION_ID)
+    || Boolean(env.KIMI_CONFIG_FILE)
+    || Boolean(env.KIMI_MCP_CONFIG_FILE);
+  const preferCursor =
+    options.preferCursor === true
+    || forceTool === "cursor"
+    || Boolean(env.CURSOR_AGENT);
+  return { forceTool, preferKimi, preferCursor };
+}
+
+/** Ordered per-project readers for the active harness. */
+export function projectReadersForContext(ctx) {
+  const defaultReaders = [
+    claudeReader,
+    cursorReader,
+    vscodeReader,
+    opencodeReader,
+    antigravityReader,
+    grokReader,
+    codexReader,
+  ];
+  const kimiReaders = [kimiReader, kimiCodeReader];
+
+  if (ctx.preferKimi) {
+    return [...kimiReaders, ...defaultReaders];
+  }
+  if (ctx.preferCursor) {
+    // Cursor CLI/IDE: .cursor/mcp.json must win over stale .mcp.json in the
+    // same repo (e.g. leftover Claude Code token from an old provision).
+    return [
+      cursorReader,
+      vscodeReader,
+      opencodeReader,
+      antigravityReader,
+      grokReader,
+      codexReader,
+      claudeReader,
+      ...kimiReaders,
+    ];
+  }
+  return [...defaultReaders, ...kimiReaders];
+}
+
+/** Walk up from startDir; return first matching project bearer or null. */
+export function resolveProjectBearer(startDir, options = {}) {
+  const ctx = harnessContext(process.env, options);
+  const readers = projectReadersForContext(ctx);
+  let dir = startDir;
+  while (dir && dir !== "/") {
+    for (const r of readers) {
+      const found = r(dir);
+      if (found) {
+        found.scope = "project";
+        return found;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/scripts/subscribe.mjs

@@ -13,6 +13,7 @@ import { request as httpRequest } from "node:http";
 import { URL } from "node:url";
 import { dirname } from "node:path";
 import { connect as wsConnect } from "./lib/ws.mjs";
+import { resolveProjectBearer } from "./lib/resolve-project-bearer.mjs";
 
 // --- Hermes webhook bridge mode -------------------------------------------
 // Default mode writes "PATCHCORD: ..." lines to stdout for Claude Code's
@@ -70,35 +71,15 @@ function die(msg, code = 1) {
 
 function readMcpConfig(cwd) {
   // Prefer env vars injected by patchcord.mjs, which already ran _resolveBearer()
-  // and supports all 12 tool configs (Claude Code, OpenCode, Codex, Cursor, Kimi, etc.).
+  // and supports all tool configs with harness-aware ordering.
   if (process.env.PATCHCORD_BASE_URL && process.env.PATCHCORD_BEARER_TOKEN) {
     return { baseUrl: process.env.PATCHCORD_BASE_URL, token: process.env.PATCHCORD_BEARER_TOKEN };
   }
-  // Fallback: direct invocation — try .mcp.json walking up from cwd.
-  let dir = cwd;
-  while (dir && dir !== "/") {
-    const path = `${dir}/.mcp.json`;
-    if (existsSync(path)) {
-      let json;
-      try {
-        json = JSON.parse(readFileSync(path, "utf8"));
-      } catch (e) {
-        die(`.mcp.json parse error: ${e.message}`);
-      }
-      const pc = json?.mcpServers?.patchcord;
-      if (!pc?.url || !pc?.headers?.Authorization) {
-        die(".mcp.json missing mcpServers.patchcord.url or Authorization");
-      }
-      let baseUrl = pc.url.replace(/\/mcp\/bearer$/, "").replace(/\/mcp$/, "");
-      const auth = pc.headers.Authorization;
-      const token = auth.startsWith("Bearer ") ? auth.slice(7) : auth;
-      return { baseUrl, token };
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+  const found = resolveProjectBearer(cwd);
+  if (!found) {
+    die(`no patchcord config found — run from a project directory or use 'patchcord subscribe'`);
   }
-  die(`no patchcord config found — run from a project directory or use 'patchcord subscribe'`);
+  return { baseUrl: found.baseUrl, token: found.token };
 }
 
 function httpJson(urlStr, { method = "GET", headers = {}, body = null } = {}) {

package/commands/subscribe.toml

@@ -1 +0,0 @@
-prompt = "Start the Patchcord background listener per the patchcord:subscribe skill. Spawn scripts/subscribe.mjs with run_in_background, attach the Monitor tool to its stdout, and when a 'PATCHCORD:' line appears, announce it briefly and call inbox() to handle any new messages."

package/per-project-skills/web/SKILL.md

@@ -1,126 +0,0 @@
----
-name: patchcord
-description: >
-  Cross-agent messaging via Patchcord MCP connector. Use when the user mentions
-  other agents, checking inbox, sending messages, who's online, or agent coordination.
----
-
-# Patchcord - cross-agent messaging
-
-You are connected to Patchcord, a message bus that lets you talk to AI agents on other machines and platforms.
-
-## Tools
-
-- **inbox(all_agents?)** - read pending messages + recent activity. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply, not whether to send.
-- **send_message(to_agent, content, thread?)** - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Supports `@username` for cross-user Gate messaging. `thread` slug starts or joins a named thread: `send_message("backend", "...", thread="deploy-review")`. Up to 50,000 characters — never summarize.
-- **reply(message_id, content?, defer?, resolve?)** - reply to a received message. Auto-inherits thread from the original. `defer=true` keeps message visible in inbox (survives context compaction). `resolve=true` closes the thread — stamps `thread_resolved_at` and notifies sender. Content optional: `reply(message_id, resolve=true)` to silently close.
-- **wait_for_message(timeout_seconds?)** - block until incoming message arrives. Default 300s. Known to error intermittently - if it fails, poll inbox() in a loop as fallback.
-- **attachment(...)** - file operations (see File sharing section below)
-- **recall(limit?, from_agent?, thread_id?)** - view recent message history including already-read messages. `from_agent` filters by sender. `thread_id` filters to a specific thread. Debugging only.
-- **unsend(message_id)** - take back a message before recipient reads it.
-
-## Chat identification
-
-You may be one of several chat sessions sharing the same Patchcord identity. To avoid confusion:
-
-**When sending messages**, always prepend a brief chat context tag:
-```
-[marketing] Here are the Q1 metrics you asked for...
-[dev-backend] The API endpoint is at /api/v2/users...
-[general] Quick question about the deployment schedule
-```
-
-Use the dominant topic of your current conversation as the tag. Keep it short (1-3 words). Be consistent within a session - pick a tag early and reuse it.
-
-**When receiving messages**, check the context tag:
-- If it matches your chat's topic — reply normally
-- If it's clearly for another chat session — `reply(message_id, "→ [tag] chat", defer=true)`. Minimal content, no explanation.
-- If there's no tag but the content is addressed to a different role (e.g. "To: claudeai (UI/UX designer)" when you're the scientific supervisor) — treat as wrong-chat. `reply(message_id, "→ other session", defer=true)`. Do not explain your role or what the other session should do.
-- If there's no tag and it's ambiguous — handle it normally
-- When a message has no context tag but is addressed "To: [role]" in the body, the role-line acts as a tag. Route accordingly.
-
-## Behavioral rules
-
-1. **Call inbox() at the start of every conversation** to see pending messages. Reply to or resolve anything actionable before doing other work.
-
-2. **Reply immediately** to pending messages. Do not ask "should I reply?" - just reply, then tell the user what you received and what you answered.
-
-3. **Cross-namespace agents**: The online list shows `agent@namespace` when multiple namespaces exist. Use `agent@namespace` syntax in send_message when targeting a specific namespace.
-
-4. **Cross-user messaging (Gate)**: To message a user outside your namespace, use `@username` as the to_agent. Example: `send_message("@maria", "hello")`. The message goes through their Gate - connection approval and guardrails apply. If the connection isn't approved yet, your message is held pending their approval (cap 5, 7-day TTL).
-
-5. **After sending or replying**, call wait_for_message() if the recipient is online. If they're offline, skip the wait - tell the human the message was sent and the agent will see it when they're active. If wait_for_message() errors, fall back to polling inbox() every 10-15 seconds.
-
-6. **Never show raw JSON** - summarize naturally.
-
-7. **Do not reply to acks**: "ok", "noted", "seen", "thanks", "good progress", thumbs up, or conversation-ending signals. If you must close the thread: `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** — "Noted, thanks" + resolve creates a new pending message that chains into more acks. Omit content when there's nothing substantive. When you receive an ack, close it silently: `reply(id, resolve=true)`. This applies even when an ack is for another session — don't defer-route acks, just silently resolve them.
-
-8. **Presence is not a delivery gate**: an agent may receive messages while absent from the online list. Always send regardless of online/offline status. Messages queue and deliver when the recipient checks inbox.
-
-9. **Blocked sends mean unread inbox.** If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
-
-10. **MCP tools are cached at session start.** New tools deployed after your session began are invisible until you open a new chat. If a tool you expect is missing, this is why.
-
-## Threads
-
-Named threads group related messages. Use them for multi-turn tasks that need their own context.
-
-- **Start**: `send_message("backend", "...", thread="auth-migration")`
-- **Reply stays in thread automatically** — `reply()` inherits the thread from the original.
-- **Close**: `reply(message_id, "done", resolve=true)` — closes thread, notifies sender.
-- **Filter history**: `recall(thread_id="<uuid>")` — only that thread's messages.
-
-`inbox()` `groups` field clusters pending messages by thread: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level (no thread).
-
-## Sending workflow
-
-1. inbox() - clear pending messages that block outbound sends. Note who's online (determines whether to wait after sending).
-2. send_message("agent_name", "[your-chat-tag] your question with context") - or "agent1, agent2" for multiple, or "@username" for cross-user. Add `thread="slug"` to group in a named thread.
-3. If recipient is online: wait_for_message() - block until response arrives. If offline: skip wait, tell the human the message is queued.
-
-ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
-
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to run `/patchcord` in their session to pick it up."
-
-## Receiving workflow
-
-Action requests older than 7d (per the `(Xd ago)` stamp): ask human before executing. Acks/FYIs silent-resolve at any age.
-
-1. Read messages from inbox(). Check `message.thread` / `message.thread_id` if present.
-2. Check the context tag - is this for your chat?
-3. If yes: do the work, then reply with the right flag:
-   - `reply(message_id, "[tag] done: [details]")` — work done, thread auto-inherited
-   - `reply(message_id, "[tag] done", resolve=true)` — work done, thread closed
-   - `reply(message_id, "[tag] ack, will do after [other task]", defer=true)` — acknowledged but work not done yet. Message stays in inbox.
-4. If no: reply(message_id, "For [other-tag] chat", defer=true)
-5. wait_for_message() - stay responsive for follow-ups
-
-When you have multiple pending messages, prioritize by urgency. Use `defer=true` for tasks you'll do later — if you reply without doing the work and don't defer, the message vanishes from your inbox and you will never remember to do it.
-
-Outdated deferred (work likely done, sender moved on): ask human "resolve [Xd]-old from [sender]?" before `reply(id, resolve=true)`. Don't unilaterally drop.
-
-## File sharing
-
-As a web agent, you CANNOT PUT to presigned URLs (egress is blocked). Two options:
-
-### Option 1: Inline base64 upload (small files only)
-```
-attachment(upload=true, filename="report.md", file_data="<base64 encoded content>")
-```
-The server uploads for you. Send the returned path to the other agent in your message. Base64 adds ~33% overhead. Keep files small - text files, configs, short docs.
-
-### Option 2: Relay from URL (preferred for public files)
-```
-attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
-```
-Server fetches the URL and stores it. You send only a URL string (~50 tokens) instead of base64 content (thousands of tokens). Always prefer relay when the file is at a public HTTPS URL.
-
-### Receiving files
-```
-attachment(path_or_url="namespace/agent/filename.ext")
-```
-Use the path from the sender's message.
-
-## Agent names
-
-Agent names change frequently. Do not memorize or hardcode them. Check inbox() for recent activity. When unsure which agent to message, ask the human. Any agent can receive messages regardless of whether it appears in the presence list.