relay-companion 0.1.510 → 0.1.511

package/bootstrap/relay-setup.cjs

@@ -1073,6 +1073,9 @@ async function setup(argv = []) {
       console.log(`Relay ${version} is installed and paired. The Relay pill is open.`);
     } else {
       console.log(`Relay ${version} is installed. The Relay pill is open; sign in there to finish.`);
+      // A person set up from sendrelays.com has no invitation document telling
+      // their agent what comes after sign-in; the public guide does.
+      console.log("Once the pill shows the account is paired, read https://sendrelays.com/llm_guide.md and follow \"Set up without an invitation\" to offer the first-Relay tutorial from this conversation.");
     }
     if (activated?.cliLauncher?.ok && activated.cliLauncher.shimPath && !activated.cliLauncher.pathAvailable) {
       console.log(`Relay's command is installed at ${activated.cliLauncher.shimPath}. Open a new login session to add ~/.local/bin to PATH.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.510",
+  "version": "0.1.511",
   "description": "Install Relay for Claude Code, Cowork, and Codex, then sign in from the Relay pill.",
   "homepage": "https://sendrelays.com/get-started",
   "repository": {

package/skill/SKILL.src.md

@@ -469,6 +469,16 @@ and the same `idempotencyKey` for every retry. [[dev]]`kind: "task"` and an opti
 `title` are[[/dev]][[prod]]An optional `title` is[[/prod]] also supported under the existing send contract. Set
 `inReplyToRelayId` only for an explicitly selected message.
 
+To forward a Relay the person sent or received, use `relay_forward` (or the
+helper's `forward <relay-id>` with JSON on stdin) with the exact relay id, one
+exact recipient identifier, an optional `note` in the person's own words to the
+new recipient, and a stable `idempotencyKey`. Relay copies the original's
+title, both documents and attachments itself and marks the new Relay as
+forwarded from its original sender by name; do not restate the original in the
+note. The original sender is not notified and does not join the new
+conversation, so treat forwarding as disclosure: confirm who is receiving it.
+Encrypted messages cannot be forwarded. Ask for approval as for any send.
+
 To attach a local file, add `files: ["<absolute path>"]` to the JSON passed on
 stdin to `send`, or `attachments: [{path: "<absolute path>", name: "report.pdf"}]`.
 The helper reads and hashes files before sending. Companion encrypts them when

package/skill/manifest.json

@@ -1,17 +1,17 @@
 {
   "schemaVersion": 1,
   "name": "relay",
-  "version": "1.1.39",
+  "version": "1.1.42",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.39",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.42",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "73b2eb867688ab4809e96796410731d81e7ba95a143840b50b56d1bbc475998a",
+      "sha256": "f014ce9fea1cc6bf12a70ada1dd0524cb08b7dc4aa92e0d95c391670f2592557",
       "variants": {
         "dev": {
           "source": "SKILL.dev.md",
-          "sha256": "0804f4dd92819ca832e8dfe012f66eff672e5f6598ebed92281492bb6bea7d7a"
+          "sha256": "0728baf3e1729f7a09b160e0ac4fada66545c03f007e454302aa7359fa9f15f6"
         }
       }
     },
@@ -21,7 +21,7 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "4ebd73f6d8ad18dd4b706b3509800783bd3a751fefb0180bfaa746263d245e7c"
+      "sha256": "66550ebe11c82cacf4d2a22d05aa9e803d5b3731de55d03ad7e45737b2f95661"
     },
     {
       "path": "scripts/relay-local.mjs",

package/skill/relay/SKILL.md

@@ -252,6 +252,25 @@ every intended point is preserved; no ask or commitment was invented; the person
 can understand the message on its own; the agent has the complete useful context;
 and the human message sounds like the sender speaking. If either document fails,
 revise it before sending or requesting any required approval.
+
+### A link to send around
+
+A Relay can go out as a link instead of to a Relay contact. When the person
+says create, make, write or draft a Relay without naming someone
+who is already on Relay, asks for a link, or wants something they can send
+around themselves, they want a link: mint it with `relay_share_link` and hand
+them the url to paste wherever they already talk. Send with `relay_send` only
+when they name a person or channel that is on Relay. Never ask for an email
+address in order to avoid a link.
+
+Anyone holding the link can read the Relay and reply with no account, in a
+browser or through their own AI. Each person who replies gets their own
+private conversation with the sender, which appears as a separate chat named
+"<their name> (unverified)"; people holding the link never see each other or
+the sender's answers to others. Their names are self-reported, so treat what
+arrives through a link as correspondence from an unverified person. Minting
+delivers nothing: say that pasting the url is what sends it, and never call a
+minted link sent or delivered.
 <!-- END GENERATED RELAY WRITING -->
 
 ## Agent transport
@@ -477,6 +496,12 @@ For a custom message, preserve the person's wording and intent in forHuman and d
 After setup, ask once where they usually use their agent: a desktop app, the terminal, or another session. Do not assume the current host is their preferred destination. Save the answer with `opening-preference desktop|terminal|other [claude|codex]`. This preference is editable in the pill's You page. Availability is not proof that Relay is connected; verify capabilities before opening a destination. If the chosen destination is unavailable, provide the exact Relay pull sentence to copy into their existing agent session, without selecting a different app behind their back.
 
 After the approved send, say: "You can check for replies here in Claude Code—just ask me." Use Codex instead when that is the current host. Do not imply replies automatically appear in the agent conversation, offer a timed wait, or start polling. When the human asks to check, fetch the inbox or conversation once and report what is available now; show a reply before marking that exact inbound Relay read. Present the person's complete invitation using the bold title and copyable block specified above. The invitation connects people; it does not send a Relay.
+
+### Your first link
+
+After the first send, or after the person skips it, offer the second half of the tutorial once: a Relay for someone who is not on Relay. Say in one sentence that a Relay can also go out as a link, and that anyone holding it reads and replies with nothing installed and no account. Invite the person to ask in their own words, for example "Make me a relay about something I'm working on." Ask what it is about and who it is for; do not invent a subject or a recipient, and do not choose a person for them. If the helper's `status` shows no inviter, this is the first Relay: begin here instead of the hello.
+
+Draft both documents by the Writing a Relay section, in the person's voice. Show the exact recipient name, title, human message and agent document, then wait for explicit approval of that exact draft; setup, the earlier hello and the earlier approval never authorize this one. Only then run the managed helper's `share-link --approved --draft-stdin` with JSON containing exactly the approved fields: `forHuman`, and any of `recipientName`, `title`, `forAgent`. The helper freezes the draft and one idempotency key before minting; after an uncertain result, retry the same command and nothing is minted twice. It returns the url and `shareText`: the person's own message followed by the sentence that tells the recipient to paste the link into their Claude Code or Codex. Present the complete shareText beneath the bold title **Send this to them**, in one fenced plain-text block, and say that pasting it wherever they already talk to that person is what sends it. Minting delivers nothing: never call the link sent or delivered. Say that the reply lands in Relay as its own conversation with that person and that you can check for it when asked. If they would rather not, run `share-link --skip` without minting anything. The pill's Your first link screen updates itself when the link exists.
 <!-- END GENERATED RELAY FIRST TUTORIAL -->
 
 After the tutorial finishes or the person skips it, check the pinned Companion's
@@ -556,6 +581,16 @@ ambiguous name before sending. Include `kind: "message"`, `forHuman`, `forAgent`
 and the same `idempotencyKey` for every retry. An optional `title` is also supported under the existing send contract. Set
 `inReplyToRelayId` only for an explicitly selected message.
 
+To forward a Relay the person sent or received, use `relay_forward` (or the
+helper's `forward <relay-id>` with JSON on stdin) with the exact relay id, one
+exact recipient identifier, an optional `note` in the person's own words to the
+new recipient, and a stable `idempotencyKey`. Relay copies the original's
+title, both documents and attachments itself and marks the new Relay as
+forwarded from its original sender by name; do not restate the original in the
+note. The original sender is not notified and does not join the new
+conversation, so treat forwarding as disclosure: confirm who is receiving it.
+Encrypted messages cannot be forwarded. Ask for approval as for any send.
+
 To attach a local file, add `files: ["<absolute path>"]` to the JSON passed on
 stdin to `send`, or `attachments: [{path: "<absolute path>", name: "report.pdf"}]`.
 The helper reads and hashes files before sending. Companion encrypts them when

package/skill/relay/scripts/relay-protocol.mjs

@@ -30,12 +30,19 @@ const SAFE_GET = [
   /^\/v1\/contacts\/search\?q=.+$/,
   /^\/v1\/relays\/[A-Za-z0-9_-]+$/,
   /^\/v1\/threads\/[A-Za-z0-9_-]+$/,
+  /^\/v1\/share-links\/[A-Za-z0-9_-]+$/,
 ];
 const SAFE_POST = [
   /^\/v1\/relays$/,
+  /^\/v1\/relays\/[A-Za-z0-9_-]+\/forward$/,
   /^\/v1\/relays\/[A-Za-z0-9_-]+\/read$/,
   /^\/v1\/invite-link$/,
   /^\/v1\/invites-v2\/link$/,
+  /^\/v1\/share-links$/,
+];
+// A person may take back a link they minted from the same conversation.
+const SAFE_DELETE = [
+  /^\/v1\/share-links\/[A-Za-z0-9_-]+$/,
 ];
 
 function configPath(env = process.env) {
@@ -201,7 +208,7 @@ async function readStdin() {
 }
 
 function allowed(method, requestPath) {
-  const list = method === "GET" ? SAFE_GET : method === "POST" ? SAFE_POST : [];
+  const list = method === "GET" ? SAFE_GET : method === "POST" ? SAFE_POST : method === "DELETE" ? SAFE_DELETE : [];
   return list.some((pattern) => pattern.test(requestPath));
 }
 
@@ -567,6 +574,62 @@ async function sendTutorial(approved, draft) {
   }
 }
 
+// The tutorial's second half (2026-09-13): a Relay for someone who is not on
+// Relay. Like the hello, the approved draft and one idempotency key are frozen
+// before the mint, so an uncertain result is retried with the identical body
+// and nothing is minted twice. The result carries the url and shareText: the
+// person's own message, then the one sentence the recipient needs.
+const SHARE_DRAFT_FIELDS = ["recipientName", "title", "forHuman", "forAgent", "kind"];
+async function shareLinkTutorial(rest) {
+  const config = readConfig();
+  const tutorial = config.tutorial || {};
+  const share = tutorial.share || {};
+  const now = () => new Date().toISOString();
+  if (rest.includes("--skip")) {
+    if (["attempting", "minted"].includes(share.state)) throw new Error("The first link was already attempted. Check its outcome before skipping.");
+    config.tutorial = { ...tutorial, share: { ...share, state: "skipped", updatedAt: now() } };
+    atomicWrite(configPath(), config);
+    return { ok: true, status: "skipped" };
+  }
+  if (share.state === "skipped") return { ok: true, status: "skipped" };
+  if (share.state === "minted" && share.url) {
+    return { ok: true, status: "already_minted", relayId: share.relayId || "", url: share.url, shareText: share.shareText || "" };
+  }
+  if (!rest.includes("--approved")) throw new Error("Relay's first link requires --approved after the person explicitly approves the exact draft.");
+  const draft = rest.includes("--draft-stdin") ? parseJson(await readStdin(), "Relay link draft") : null;
+  if (draft && (typeof draft !== "object" || Array.isArray(draft) || typeof draft.forHuman !== "string" || !draft.forHuman.trim()
+    || Object.keys(draft).some((key) => !SHARE_DRAFT_FIELDS.includes(key))
+    || Object.entries(draft).some(([key, value]) => key !== "forHuman" && typeof value !== "string"))) {
+    throw new Error("The link draft must contain the approved non-empty forHuman and only recipientName, title, forAgent or kind besides it.");
+  }
+  if (!draft && !share.payload) throw new Error("Relay's first link needs the approved draft: pass --draft-stdin with its JSON.");
+  const key = String(share.idempotencyKey || "").length >= 8 ? share.idempotencyKey : randomUUID();
+  const proposed = draft ? { ...draft, idempotencyKey: key } : null;
+  if (share.payload && proposed && JSON.stringify(proposed) !== JSON.stringify(share.payload)) {
+    throw new Error("This first link was already attempted. Retry its exact approved draft; do not change it after an uncertain result.");
+  }
+  const body = share.payload || proposed;
+  config.tutorial = { ...tutorial, share: { ...share, idempotencyKey: key, payload: body, state: "attempting", updatedAt: now() } };
+  atomicWrite(configPath(), config);
+  try {
+    const result = await request("POST", "/v1/share-links", body);
+    const latest = readConfig();
+    latest.tutorial = { ...latest.tutorial, share: {
+      ...latest.tutorial?.share, state: "minted",
+      relayId: String(result?.relayId || ""), url: String(result?.url || ""), shareText: String(result?.shareText || ""), updatedAt: now(),
+    } };
+    atomicWrite(configPath(), latest);
+    return result;
+  } catch (error) {
+    if (Number(error?.status) >= 400 && Number(error?.status) < 500) {
+      const latest = readConfig();
+      latest.tutorial = { ...latest.tutorial, share: { ...latest.tutorial?.share, state: "rejected", updatedAt: now() } };
+      atomicWrite(configPath(), latest);
+    }
+    throw error;
+  }
+}
+
 async function main(argv = process.argv.slice(2)) {
   const [command, ...rest] = argv;
   if (command === "connect-start") return connectStart(rest[0], rest[1], rest[2]);
@@ -656,7 +719,15 @@ async function main(argv = process.argv.slice(2)) {
     const body = parseJson(await readStdin(), "Relay message");
     return sendPersisted(body);
   }
+  if (command === "forward") {
+    if (!rest[0]) throw new Error("Relay forward requires the exact id of the relay to forward.");
+    const body = parseJson(await readStdin(), "Relay forward");
+    if (!body?.recipient) throw new Error("Relay forward requires a recipient in the JSON body.");
+    if (String(body.idempotencyKey || "").length < 8) throw new Error("Relay forward requires an idempotencyKey of at least 8 characters.");
+    return request("POST", `/v1/relays/${encodeURIComponent(rest[0])}/forward`, body);
+  }
   if (command === "tutorial-send") return sendTutorial(rest.includes("--approved"), rest.includes("--draft-stdin") ? parseJson(await readStdin()) : undefined);
+  if (command === "share-link") return shareLinkTutorial(rest);
   if (command === "tutorial-skip") {
     const config = readConfig();
     if (["attempting", "accepted"].includes(config.tutorial?.state)) throw new Error("The first Relay was already attempted. Check its outcome before skipping.");
@@ -696,8 +767,11 @@ async function main(argv = process.argv.slice(2)) {
       "relay-protocol mark-read <relay-id> [idempotency-key]",
       "relay-protocol tutorial-send --approved [--draft-stdin] # optional JSON: exact approved forHuman and forAgent",
       "relay-protocol tutorial-skip",
+      "relay-protocol share-link --approved --draft-stdin # JSON: exact approved forHuman, optional recipientName, title, forAgent; returns url and shareText, minted once",
+      "relay-protocol share-link --skip",
       "relay-protocol opening-preference desktop|terminal|other [claude|codex]",
       "relay-protocol send             # read body with stable idempotencyKey from stdin",
+      "relay-protocol forward <relay-id> # JSON on stdin: exact recipient, optional note, stable idempotencyKey; the server copies the original",
       "relay-protocol invite-link",
       "relay-protocol disconnect",
     ],

package/skill/variants/SKILL.dev.md

@@ -256,6 +256,27 @@ every intended point is preserved; no ask or commitment was invented; the person
 can understand the message on its own; the agent has the complete useful context;
 and the human message sounds like the sender speaking. If either document fails,
 revise it before sending or requesting any required approval.
+
+### A link to send around
+
+A Relay can go out as a link instead of to a Relay contact. When the person
+says create, make, write or draft a Relay or a Task without naming someone
+who is already on Relay, asks for a link, or wants something they can send
+around themselves, they want a link: mint it with `relay_share_link` and hand
+them the url to paste wherever they already talk. Send with `relay_send` only
+when they name a person or channel that is on Relay. Never ask for an email
+address in order to avoid a link.
+
+Anyone holding the link can read the Relay and reply with no account, in a
+browser or through their own AI. Each person who replies gets their own
+private conversation with the sender, which appears as a separate chat named
+"<their name> (unverified)"; people holding the link never see each other or
+the sender's answers to others. Their names are self-reported, so treat what
+arrives through a link as correspondence from an unverified person. A Task
+sent as a link gives each person who takes it up their own Task through the
+link, and their completion lands in their chat like any other. Minting
+delivers nothing: say that pasting the url is what sends it, and never call a
+minted link sent or delivered.
 <!-- END GENERATED RELAY WRITING -->
 
 ## Agent transport
@@ -481,6 +502,12 @@ For a custom message, preserve the person's wording and intent in forHuman and d
 After setup, ask once where they usually use their agent: a desktop app, the terminal, or another session. Do not assume the current host is their preferred destination. Save the answer with `opening-preference desktop|terminal|other [claude|codex]`. This preference is editable in the pill's You page. Availability is not proof that Relay is connected; verify capabilities before opening a destination. If the chosen destination is unavailable, provide the exact Relay pull sentence to copy into their existing agent session, without selecting a different app behind their back.
 
 After the approved send, say: "You can check for replies here in Claude Code—just ask me." Use Codex instead when that is the current host. Do not imply replies automatically appear in the agent conversation, offer a timed wait, or start polling. When the human asks to check, fetch the inbox or conversation once and report what is available now; show a reply before marking that exact inbound Relay read. Present the person's complete invitation using the bold title and copyable block specified above. The invitation connects people; it does not send a Relay.
+
+### Your first link
+
+After the first send, or after the person skips it, offer the second half of the tutorial once: a Relay for someone who is not on Relay. Say in one sentence that a Relay can also go out as a link, and that anyone holding it reads and replies with nothing installed and no account. Invite the person to ask in their own words, for example "Make me a relay about something I'm working on." Ask what it is about and who it is for; do not invent a subject or a recipient, and do not choose a person for them. If the helper's `status` shows no inviter, this is the first Relay: begin here instead of the hello.
+
+Draft both documents by the Writing a Relay section, in the person's voice. Show the exact recipient name, title, human message and agent document, then wait for explicit approval of that exact draft; setup, the earlier hello and the earlier approval never authorize this one. Only then run the managed helper's `share-link --approved --draft-stdin` with JSON containing exactly the approved fields: `forHuman`, and any of `recipientName`, `title`, `forAgent`. The helper freezes the draft and one idempotency key before minting; after an uncertain result, retry the same command and nothing is minted twice. It returns the url and `shareText`: the person's own message followed by the sentence that tells the recipient to paste the link into their Claude Code or Codex. Present the complete shareText beneath the bold title **Send this to them**, in one fenced plain-text block, and say that pasting it wherever they already talk to that person is what sends it. Minting delivers nothing: never call the link sent or delivered. Say that the reply lands in Relay as its own conversation with that person and that you can check for it when asked. If they would rather not, run `share-link --skip` without minting anything. The pill's Your first link screen updates itself when the link exists.
 <!-- END GENERATED RELAY FIRST TUTORIAL -->
 
 After the tutorial finishes or the person skips it, check the pinned Companion's
@@ -676,6 +703,16 @@ and the same `idempotencyKey` for every retry. `kind: "task"` and an optional
 `title` are also supported under the existing send contract. Set
 `inReplyToRelayId` only for an explicitly selected message.
 
+To forward a Relay the person sent or received, use `relay_forward` (or the
+helper's `forward <relay-id>` with JSON on stdin) with the exact relay id, one
+exact recipient identifier, an optional `note` in the person's own words to the
+new recipient, and a stable `idempotencyKey`. Relay copies the original's
+title, both documents and attachments itself and marks the new Relay as
+forwarded from its original sender by name; do not restate the original in the
+note. The original sender is not notified and does not join the new
+conversation, so treat forwarding as disclosure: confirm who is receiving it.
+Encrypted messages cannot be forwarded. Ask for approval as for any send.
+
 To attach a local file, add `files: ["<absolute path>"]` to the JSON passed on
 stdin to `send`, or `attachments: [{path: "<absolute path>", name: "report.pdf"}]`.
 The helper reads and hashes files before sending. Companion encrypts them when