relay-companion 0.1.509 → 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/bootstrap/relay-skill.cjs

@@ -114,6 +114,37 @@ function pathInside(parent, child) {
   return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
 }
 
+// Where the previous skill tree is kept for `relay skill rollback`. It used to
+// be a sibling of the installed skill (`.relay-rollback` inside the host's
+// skills folder), and Claude Code and Codex load any directory there that has
+// a SKILL.md, so every session saw the Relay skill twice. It now lives under
+// Relay's own state directory, keyed by the target it backs.
+function rollbackRoot({ homeDir = os.homedir(), env = process.env } = {}) {
+  return path.join(env.RELAY_CONFIG_DIR || path.join(homeDir, ".relay"), "skill-rollback");
+}
+
+function rollbackPathFor(directory, options = {}) {
+  return path.join(rollbackRoot(options), sha256(path.resolve(directory)).slice(0, 16));
+}
+
+function legacyRollbackPath(directory) {
+  return path.join(path.dirname(directory), `.${SKILL_NAME}-rollback`);
+}
+
+// A rename when both paths share a volume; a copy and remove when they do not
+// (CODEX_HOME or RELAY_CONFIG_DIR may point at another drive).
+function moveTree(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true, mode: 0o700 });
+  try {
+    fs.renameSync(from, to);
+    return;
+  } catch (error) {
+    if (error.code !== "EXDEV") throw error;
+  }
+  fs.cpSync(from, to, { recursive: true, errorOnExist: true, force: false });
+  fs.rmSync(from, { recursive: true, force: true });
+}
+
 function fileHash(file) {
   return sha256(fs.readFileSync(file));
 }
@@ -244,10 +275,12 @@ function removeSkillArtifact(directory) {
     : { ok: true, status: managed ? "removed" : "empty_debris_removed", directory };
 }
 
-function skillArtifacts(directory) {
+function skillArtifacts(directory, options = {}) {
   const parent = path.dirname(directory);
   const name = path.basename(directory);
   const artifacts = [directory];
+  const rollback = rollbackPathFor(directory, options);
+  if (fs.existsSync(rollback)) artifacts.push(rollback);
   let entries = [];
   try { entries = fs.readdirSync(parent, { withFileTypes: true }); }
   catch (error) {
@@ -270,7 +303,7 @@ function uninstallManaged(options = {}) {
   const seen = new Set();
   for (const target of targets) {
     let artifacts;
-    try { artifacts = skillArtifacts(target.directory); }
+    try { artifacts = skillArtifacts(target.directory, options); }
     catch (error) {
       results.push({ host: target.host, ok: false, status: "failed", directory: target.directory, error: error?.message || String(error) });
       continue;
@@ -345,16 +378,23 @@ async function installOne(directory, manifest, readFile, options = {}) {
 
   fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
   const staging = fs.mkdtempSync(path.join(parent, `.${SKILL_NAME}-staging-`));
-  const rollback = path.join(parent, `.${SKILL_NAME}-rollback`);
-  if (!pathInside(parent, staging) || !pathInside(parent, rollback)) throw new Error("Relay refused an unsafe skill update location.");
+  const rollback = rollbackPathFor(directory, options);
+  const legacyRollback = legacyRollbackPath(directory);
+  if (!pathInside(parent, staging) || !pathInside(rollbackRoot(options), rollback) || !pathInside(parent, legacyRollback)) {
+    throw new Error("Relay refused an unsafe skill update location.");
+  }
   try {
     await materialize(manifest, staging, readFile, options, existing);
-    if (fs.existsSync(rollback)) fs.rmSync(rollback, { recursive: true, force: true });
-    if (fs.existsSync(directory)) fs.renameSync(directory, rollback);
+    // One rollback copy per target. A copy an earlier installer left beside
+    // the skill goes too: hosts load it as a second skill.
+    for (const stale of [rollback, legacyRollback]) {
+      if (fs.existsSync(stale)) fs.rmSync(stale, { recursive: true, force: true });
+    }
+    if (fs.existsSync(directory)) moveTree(directory, rollback);
     try {
       fs.renameSync(staging, directory);
     } catch (error) {
-      if (!fs.existsSync(directory) && fs.existsSync(rollback)) fs.renameSync(rollback, directory);
+      if (!fs.existsSync(directory) && fs.existsSync(rollback)) moveTree(rollback, directory);
       throw error;
     }
     return { ok: true, status: existing ? "updated" : "installed", directory, version: manifest.version, rollback: fs.existsSync(rollback) ? rollback : null };
@@ -396,10 +436,13 @@ async function updateFromRemote(options = {}) {
   return installManifest(manifest, (entry) => fetchBytes(`${manifest.baseUrl}/${entry.path.split("/").map(encodeURIComponent).join("/")}`, options), options);
 }
 
-function rollbackOne(directory) {
+function rollbackOne(directory, options = {}) {
   const parent = path.dirname(directory);
-  const rollback = path.join(parent, `.${SKILL_NAME}-rollback`);
-  if (!pathInside(parent, rollback) || !fs.existsSync(rollback)) return { ok: false, status: "no_rollback", directory };
+  // The current location first; a copy an earlier installer left beside the
+  // skill still rolls back once.
+  const rollback = [rollbackPathFor(directory, options), legacyRollbackPath(directory)].find((candidate) => fs.existsSync(candidate));
+  if (!rollback) return { ok: false, status: "no_rollback", directory };
+  if (!pathInside(rollbackRoot(options), rollback) && !pathInside(parent, rollback)) throw new Error("Relay refused an unsafe rollback location.");
   const currentChanges = localChanges(directory);
   if (currentChanges.length) return { ok: false, status: readState(directory) ? "modified" : "unmanaged", directory, changedFiles: currentChanges };
   const rollbackChanges = localChanges(rollback);
@@ -408,7 +451,7 @@ function rollbackOne(directory) {
   if (!pathInside(parent, current)) throw new Error("Relay refused an unsafe rollback location.");
   if (fs.existsSync(directory)) fs.renameSync(directory, current);
   try {
-    fs.renameSync(rollback, directory);
+    moveTree(rollback, directory);
     if (fs.existsSync(current)) fs.rmSync(current, { recursive: true, force: true });
     return { ok: true, status: "rolled_back", directory, version: readState(directory)?.version || "" };
   } catch (error) {
@@ -430,7 +473,7 @@ async function runCli(argv = process.argv.slice(2), options = {}) {
   if (command === "install") return installBundled(common);
   if (command === "update") return updateFromRemote(common);
   if (command === "rollback") {
-    const results = defaultTargets(common).map((target) => ({ host: target.host, ...rollbackOne(target.directory) }));
+    const results = defaultTargets(common).map((target) => ({ host: target.host, ...rollbackOne(target.directory, common) }));
     return { ok: results.every((item) => item.ok), results };
   }
   if (command === "status") {
@@ -470,6 +513,7 @@ module.exports = {
   parseManifest,
   readState,
   rollbackOne,
+  rollbackPathFor,
   runCli,
   sha256,
   uninstallManaged,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.509",
+  "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

@@ -29,6 +29,120 @@ Hosted/headless agents can use the authenticated HTTPS protocol directly.
 <!-- BEGIN GENERATED RELAY VALUE -->
 <!-- END GENERATED RELAY VALUE -->
 
+<!-- BEGIN GENERATED RELAY WRITING -->
+## Writing a Relay
+
+Every regular Relay has two documents for two readers. The person is switching
+contexts and needs to understand what this is about and what it means for them.
+Their agent needs enough context to understand the whole matter and help them
+continue without making them reconstruct the sender's work. Compose the complete
+`forAgent` first, then write `forHuman`. A short human message must not mean a
+thin agent handoff. Apply these rules to drafts and previews as well as sends.
+
+### Preserve the sender's intent and voice
+
+The human's informal instructions tell you what to communicate; they are not
+usually a draft to lightly edit. Write what this person would naturally say to
+this recipient. Supply the words, never additional meaning. Preserve every ask,
+question, commitment, permission, deadline, urgency, opinion, evaluation and
+next step without adding, removing, strengthening or softening any of them.
+Keep suggestions tentative when the sender made them tentative. Include thanks
+or other sentiments the sender explicitly requested. Preserve exact text when
+the person requests a verbatim payload.
+
+Sending information or attaching a file does not imply "please review",
+"thoughts?", "let me know", or another request for a response. Do not invent a
+closing ask, "nothing needed", or implementation assignment to complete a
+template. Make ordinary wording choices yourself; ask only when a critical
+uncertainty would materially change the meaning or commitment.
+
+Use the sender's recipient-specific vocabulary, rhythm, directness, formality,
+warmth, emphasis and sign-off. When relationship context matters, `sent` and
+`chat <id>` can supply facts, referents and examples of messages the human typed.
+Learn their voice from those, not earlier agent-written messages. History cannot
+revive superseded intent. Do not copy the brevity or shorthand of messages they
+wrote while already in a conversation; this reader may need fresh orientation.
+
+### The agent document: carry the complete useful context
+
+`forAgent` is required and non-empty for a regular Relay. Write a self-contained
+document, as long and detailed as the authorized subject requires. Under-sending
+here is worse than over-sending. Preserve the useful conclusions, constraints,
+rejected options, failures, preferences, questions, next steps, sources,
+mechanisms, evidence, code, paths, logs, reproduction steps, chronology, data
+and verification guidance that are available and relevant. Use Markdown when
+it helps. Do not invent missing evidence or include unrelated private context.
+
+Retain each distinct point from the sender, its rationale when supplied, and
+the qualifications needed to interpret it. Separate observations, suggestions,
+open questions and authorized actions. Technical detail does not itself make a
+message an assignment. Give the recipient's agent substantive context, not an
+instruction to "capture these points" followed by a shorter paraphrase of the
+human message. Avoid repeating `forHuman` verbatim; enough shared context to
+make the agent document understandable is appropriate.
+
+### The human document: write for someone arriving fresh
+
+Start by plainly saying what this is about. Assume the reader has done a dozen
+other things since it last came up. Give the minimum background needed before
+the news; preserve that orientation when cutting. Do not refer to "the new
+rule", "what we settled", an unexplained thread, or a coined term. Retell the
+relevant thing in familiar words. A follow-up to an issue the recipient raised
+within the last day may need only a sentence about the result and the closing
+state the sender intended.
+
+Then convey what happened, why it matters, and any decision, opinion or action
+the sender actually wants. Keep the news to three sentences where possible;
+use a fourth only when needed to preserve the intended meaning. Stay under 95
+words by default. That is a ceiling, never a target: a small update is usually
+a line or two. There is no required length ratio between the two documents;
+their readers' needs determine the length.
+
+Use complete, spoken sentences and plain words. Read it aloud: would the sender
+say this to the recipient's face, and would the recipient understand it without
+doing the work? Put one idea at a time. Avoid fragments, clipped shorthand,
+clever lines, figures of speech, flourishes, or balanced rhetorical halves.
+Use the sender's names for things. Words the recipient encounters in the
+product or their own work are fine; avoid vocabulary learned only while doing
+the underlying investigation. Say what happened to someone: "A supplier
+charged us more than we agreed" or "People who opened the invite saw a blank
+page."
+
+Keep mechanisms, evidence, paths, commands, logs, versions, internal identifiers,
+work chronology and implementation detail in `forAgent`, unless the sender
+explicitly wants the person to read them or they change the person's decision.
+Do not pack four findings into one sentence, squeeze a checklist into prose, or
+turn the human document into an inventory of the agent document. Cut details
+the person need not read before cutting meaning or necessary background.
+Never add text just because space remains. No headings, lists, tables, code
+blocks or repetition of the title in `forHuman`.
+
+If Relay rejects an overlong draft, review it from the recipient's perspective,
+remove repetition and move supporting detail to `forAgent`. Use any supported
+length-review override only after rejection and only when the exact draft's
+extra length is necessary to preserve intent; never preemptively or merely
+because more detail is available.
+
+### Title, message kind and final review
+
+For a titled Relay, use a natural 3–6 word gist in the sender's register. Name
+the single ask, outcome, update or decision someone should recognize at a
+glance. Do not concatenate every finding or write a report headline.
+
+Classify the requested outcome: `kind: "message"` is human correspondence,
+including technical notes, suggestions, opinions and decisions. Use
+`kind: "task"` only for requested external work by the recipient's agent, such
+as inspecting, retrieving, changing, testing or verifying something. A small
+operation or one addressed as "you" is still work; dense agent context alone
+is not. Respect the account's available capabilities.
+
+Before presenting or sending, check both documents against the user's request:
+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.
+<!-- END GENERATED RELAY WRITING -->
+
 ## Agent transport
 
 <!-- BEGIN GENERATED RELAY TRANSPORT -->
@@ -327,8 +441,9 @@ result is ambiguous. Never invent an address or recipient identifier. Always
 show the proposed human and agent payloads and obtain the person's approval for
 a representational send.
 
-Before composing any Relay, apply the complete writing contract below. It is
-part of this skill for every send path; no MCP tool description is needed.
+Before composing any Relay, apply the complete writing contract in Writing a
+Relay above. It is part of this skill for every send path; no MCP tool
+description is needed.
 
 Reading or summarizing an unread Relay should mark only the surfaced message as
 read. The sequence is: run `inbox`; choose the intended Relay id; run `read`
@@ -344,120 +459,6 @@ same body and key; never generate a replacement key for a retry.
 
 Use the absolute helper path with `help` for the exact local command surface.
 
-<!-- BEGIN GENERATED RELAY WRITING -->
-## Writing a Relay
-
-Every regular Relay has two documents for two readers. The person is switching
-contexts and needs to understand what this is about and what it means for them.
-Their agent needs enough context to understand the whole matter and help them
-continue without making them reconstruct the sender's work. Compose the complete
-`forAgent` first, then write `forHuman`. A short human message must not mean a
-thin agent handoff. Apply these rules to drafts and previews as well as sends.
-
-### Preserve the sender's intent and voice
-
-The human's informal instructions tell you what to communicate; they are not
-usually a draft to lightly edit. Write what this person would naturally say to
-this recipient. Supply the words, never additional meaning. Preserve every ask,
-question, commitment, permission, deadline, urgency, opinion, evaluation and
-next step without adding, removing, strengthening or softening any of them.
-Keep suggestions tentative when the sender made them tentative. Include thanks
-or other sentiments the sender explicitly requested. Preserve exact text when
-the person requests a verbatim payload.
-
-Sending information or attaching a file does not imply "please review",
-"thoughts?", "let me know", or another request for a response. Do not invent a
-closing ask, "nothing needed", or implementation assignment to complete a
-template. Make ordinary wording choices yourself; ask only when a critical
-uncertainty would materially change the meaning or commitment.
-
-Use the sender's recipient-specific vocabulary, rhythm, directness, formality,
-warmth, emphasis and sign-off. When relationship context matters, `sent` and
-`chat <id>` can supply facts, referents and examples of messages the human typed.
-Learn their voice from those, not earlier agent-written messages. History cannot
-revive superseded intent. Do not copy the brevity or shorthand of messages they
-wrote while already in a conversation; this reader may need fresh orientation.
-
-### The agent document: carry the complete useful context
-
-`forAgent` is required and non-empty for a regular Relay. Write a self-contained
-document, as long and detailed as the authorized subject requires. Under-sending
-here is worse than over-sending. Preserve the useful conclusions, constraints,
-rejected options, failures, preferences, questions, next steps, sources,
-mechanisms, evidence, code, paths, logs, reproduction steps, chronology, data
-and verification guidance that are available and relevant. Use Markdown when
-it helps. Do not invent missing evidence or include unrelated private context.
-
-Retain each distinct point from the sender, its rationale when supplied, and
-the qualifications needed to interpret it. Separate observations, suggestions,
-open questions and authorized actions. Technical detail does not itself make a
-message an assignment. Give the recipient's agent substantive context, not an
-instruction to "capture these points" followed by a shorter paraphrase of the
-human message. Avoid repeating `forHuman` verbatim; enough shared context to
-make the agent document understandable is appropriate.
-
-### The human document: write for someone arriving fresh
-
-Start by plainly saying what this is about. Assume the reader has done a dozen
-other things since it last came up. Give the minimum background needed before
-the news; preserve that orientation when cutting. Do not refer to "the new
-rule", "what we settled", an unexplained thread, or a coined term. Retell the
-relevant thing in familiar words. A follow-up to an issue the recipient raised
-within the last day may need only a sentence about the result and the closing
-state the sender intended.
-
-Then convey what happened, why it matters, and any decision, opinion or action
-the sender actually wants. Keep the news to three sentences where possible;
-use a fourth only when needed to preserve the intended meaning. Stay under 95
-words by default. That is a ceiling, never a target: a small update is usually
-a line or two. There is no required length ratio between the two documents;
-their readers' needs determine the length.
-
-Use complete, spoken sentences and plain words. Read it aloud: would the sender
-say this to the recipient's face, and would the recipient understand it without
-doing the work? Put one idea at a time. Avoid fragments, clipped shorthand,
-clever lines, figures of speech, flourishes, or balanced rhetorical halves.
-Use the sender's names for things. Words the recipient encounters in the
-product or their own work are fine; avoid vocabulary learned only while doing
-the underlying investigation. Say what happened to someone: "A supplier
-charged us more than we agreed" or "People who opened the invite saw a blank
-page."
-
-Keep mechanisms, evidence, paths, commands, logs, versions, internal identifiers,
-work chronology and implementation detail in `forAgent`, unless the sender
-explicitly wants the person to read them or they change the person's decision.
-Do not pack four findings into one sentence, squeeze a checklist into prose, or
-turn the human document into an inventory of the agent document. Cut details
-the person need not read before cutting meaning or necessary background.
-Never add text just because space remains. No headings, lists, tables, code
-blocks or repetition of the title in `forHuman`.
-
-If Relay rejects an overlong draft, review it from the recipient's perspective,
-remove repetition and move supporting detail to `forAgent`. Use any supported
-length-review override only after rejection and only when the exact draft's
-extra length is necessary to preserve intent; never preemptively or merely
-because more detail is available.
-
-### Title, message kind and final review
-
-For a titled Relay, use a natural 3–6 word gist in the sender's register. Name
-the single ask, outcome, update or decision someone should recognize at a
-glance. Do not concatenate every finding or write a report headline.
-
-Classify the requested outcome: `kind: "message"` is human correspondence,
-including technical notes, suggestions, opinions and decisions. Use
-`kind: "task"` only for requested external work by the recipient's agent, such
-as inspecting, retrieving, changing, testing or verifying something. A small
-operation or one addressed as "you" is still work; dense agent context alone
-is not. Respect the account's available capabilities.
-
-Before presenting or sending, check both documents against the user's request:
-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.
-<!-- END GENERATED RELAY WRITING -->
-
 ## Attachments, channels and conversations
 
 Use `groups` to find a channel, `chats` to find a conversation, and `chat <id>`
@@ -468,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.38",
+  "version": "1.1.42",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.38",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.42",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "0c136dce5c24287f51728078621e7ce802f944a44b1a5b9257f0de61499a2ab5",
+      "sha256": "f014ce9fea1cc6bf12a70ada1dd0524cb08b7dc4aa92e0d95c391670f2592557",
       "variants": {
         "dev": {
           "source": "SKILL.dev.md",
-          "sha256": "77d3c871de695c1ef70fc81e312aed36eff75c8e06e131315b57c327786337ee"
+          "sha256": "0728baf3e1729f7a09b160e0ac4fada66545c03f007e454302aa7359fa9f15f6"
         }
       }
     },
@@ -21,7 +21,7 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "4ebd73f6d8ad18dd4b706b3509800783bd3a751fefb0180bfaa746263d245e7c"
+      "sha256": "66550ebe11c82cacf4d2a22d05aa9e803d5b3731de55d03ad7e45737b2f95661"
     },
     {
       "path": "scripts/relay-local.mjs",