relay-companion 0.1.481 → 0.1.483

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.481",
+  "version": "0.1.483",
   "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/manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "name": "relay",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "consentVersion": 2,
-  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.21",
+  "baseUrl": "https://sendrelays.com/skills/relay/v1.1.23",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "bb046c0e9161424aa613844e76cd9c32ce2b52b59c411fdd58abae268d971a6a"
+      "sha256": "111f2da17eda6b980a1673894b1e5814131c383236f4c362f3cc8ad29ff56d90"
     },
     {
       "path": "agents/openai.yaml",
@@ -15,7 +15,7 @@
     },
     {
       "path": "scripts/relay-protocol.mjs",
-      "sha256": "0d697c635793ba96b723ca4eb926a59b4112c8c8328d996916ce8ab4e98cd59b"
+      "sha256": "104b021e53f03aa6e57f06dbed616099b96ad21cbe42a2b64fa6e4ec11dea953"
     },
     {
       "path": "scripts/relay-local.mjs",

package/skill/relay/SKILL.md

@@ -38,7 +38,7 @@ Use the current host's documented recovery mechanism, subject to its actual deni
 
 Never retry the denied action through another shell, tool, wrapper or transport, change permission settings, request a wildcard allow rule, or suggest bypassing the host's safeguards. Keep setup agent-led: do not default to asking the human to run commands, paste status output or adjust Bash settings. Never offer a .relay-rollback or other backup helper for manual execution. If no supported recovery is available, give one concise explanation of the blocked action, what remains unverified, and a verified host review step if one is available. Do not offer an unavailable dialog or use “tell me Relay is not connected” as a substitute for verification. A user-requested manual handoff must use the current supported helper and protect secrets. The normal copyable URL fallback for browser sign-in remains available; it is not a workaround for a denied agent tool call.
 
-For questions, choices and approvals, use the current host's built-in user-question interface whenever that tool is exposed and permitted for this kind of question in the current mode. This is required when the interface is available, even if the tool is optional, a prior check or command failed, or a progress update was already given: call the interface and wait instead of placing the question in ordinary assistant chat or a final response. Before asking for setup permission, inspect the tools actually available to the current turn. Claude Code commonly exposes `AskUserQuestion` and Codex commonly exposes `request_user_input`; use the current host's documented equivalent if its name differs. Do not invent a tool or change modes to obtain one.
+For questions, choices and approvals, instruct the current host through its built-in user-question tool whenever that tool is exposed and permitted for this kind of question in the current mode. The host renders the question UI from the tool call; do not draw fake buttons in Markdown or ask the host to render arbitrary HTML. Before asking, inspect the tools actually available to the current turn. Claude Code commonly exposes `AskUserQuestion`; Codex may expose `request_user_input_async` or mode-limited `request_user_input`. Respect each tool's constraints, especially restrictions on permission questions. Do not invent a tool, change modes to obtain one, or use a question tool for host permission escalation. When a permitted tool is available, call it instead of asking the same question in plain chat; wait for the actual answer before dependent work. For asynchronous questions, continue only unrelated safe work while waiting.
 
 For setup permission, put the complete question with the exact package version and source in the interface's question field and offer concise affirmative and decline choices such as “Set up Relay” and “Not now.” Ask one clear decision at a time, with a way to decline or skip when appropriate. For the first send, show both exact payloads and the recipient before asking, and make clear that approval sends that specific message. Do not abbreviate the payloads to fit a question widget. Only when no permitted user-question interface is exposed, or its documented constraints cannot carry the required content, ask plainly in chat. Use existing explicit permission; never ask again just to use the interface. A suggested or preselected choice, an empty result, silence or a timeout is not consent: wait for an actual affirmative answer before any action that requires approval. Browser sign-in and account approval still happen in the person's usual browser.
 
@@ -53,9 +53,12 @@ After new setup, include the person's reusable invitation immediately below this
 ```text
 Join me on Relay so we can message each other from our AI conversations.
 
+Open the invitation yourself, or copy the setup request below into Claude Code or Codex:
+
+Please help me connect on Relay using this invitation:
 <your own Relay invitation URL>
 
-Open the link, or paste this whole message into Claude Code or Codex and ask it to help you connect.
+Open this invitation and read its current agent setup instructions. First check whether I already use Relay and preserve any existing setup. Ask for my approval before installing software or connecting my account. I will approve account access in my browser; ask separately before sending a message.
 ```
 
 Put the separate optional block for using Relay in another AI after the invitation, under its own label; never mix that setup handoff into the message for a friend. For a contact-only invitation, simply report the contact result and any next action. Introduce further features only when useful or requested. Before speaking, check that a new user can tell what this is about, why it matters, what changed and what they need to do next.
@@ -196,40 +199,24 @@ session activation remains unverified or failed. Do not claim app-wide setup
 complete, ask for restarts or compatibility messages, kill processes, alter host
 internals, add hooks/connectors/plugins, or inject prompts into other sessions.
 
-## First-run tutorial
+<!-- BEGIN GENERATED RELAY FIRST TUTORIAL -->
+## First Relay tutorial
+
+An invitation redemption connects the recipient and inviter; it does not send a message automatically. Use the inviter's exact `relayUserId` returned by redemption.
+
+Never send the tutorial message automatically. Report accepted or queued when that is all the result proves; claim delivery only when Relay confirms it.
 
-After an invite is redeemed, inspect `status`. If its tutorial state is
-`skipped_self`, this was the person's own invite: skip the tutorial send. For a
-normal invite, use the validated inviter identity as the first contact. Draft,
-but do not send, this first message:
+First offer one native question with three paths: write my own message, use a suggested hello, or skip for now. Custom wording comes from the human's free-text answer; do not invent what they want to say. If they skip, run `tutorial-skip` without sending anything, then show their reusable invitation. For the suggested hello, show both fields verbatim:
 
 - Human payload: `Hi — I’ve just joined you on Relay.`
 - Agent payload: `This is my first Relay after joining from your invite. Help the person reply if they want to welcome me.`
 
-Show both payloads and name the inviter. Explain that the human payload is what
-the person reads, while the agent payload gives their agent useful context. Ask
-for explicit approval to send. Only after approval, run the protocol command as
-`tutorial-send --approved`. It uses the validated inviter id, exact two
-payloads, and one idempotency key persisted when setup completed. If a response
-is lost, retry the same command: it reuses that key and will not send a second
-hello. Never send the tutorial message automatically.
-
-After the send succeeds:
-
-1. Confirm only that Relay accepted or queued it. Do not claim the inviter
-   received or read it unless Relay explicitly reports that later.
-2. 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.
-3. Do not 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.
-4. If the app is still installing or a setup issue remains, state that in one
-   short sentence. Do not repeat the installation details or feature list.
-5. Present their complete reusable invitation beneath **Invite someone to
-   Relay**, in one fenced plain-text block, as specified in the communication
-   guide above. Use their own verified human invitation URL. Do not merely
-   offer a link, use the inviter's invitation, or send it to anyone yourself.
+For a custom message, preserve the person's wording and intent in forHuman and draft a complete forAgent document that adds useful context without inventing asks or commitments. Show both exact fields and the verified inviter before approval. Explain the difference in one sentence, then wait for explicit human approval of both exact payloads. Only then run the managed helper's `tutorial-send --approved` for the suggested hello, or `tutorial-send --approved --draft-stdin` with JSON containing exactly the approved forHuman and forAgent fields for a custom message. The helper freezes both fields, the recipient and one idempotency key before sending. Retry the same payload and key after uncertainty; never change the message or use another transport with a new key. Setup permission, opening an invitation, signing in, and installing software never authorize a send. Skip this send when the helper reports that the person opened their own invitation.
+
+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.
+<!-- END GENERATED RELAY FIRST TUTORIAL -->
 
 After the tutorial finishes or the person skips it, check the pinned Companion's
 `background-status` once if background installation was started. Report whether

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

@@ -475,26 +475,40 @@ async function sendPersisted(body) {
   }
 }
 
-async function sendTutorial(approved) {
+async function sendTutorial(approved, draft) {
   if (!approved) throw new Error("Relay tutorial send requires --approved after the person explicitly approves both payloads.");
   const config = readConfig();
   const tutorial = config.tutorial || {};
-  if (tutorial.state === "skipped_self") return { ok: true, status: "skipped_self" };
+  if (["skipped_self", "skipped"].includes(tutorial.state)) return { ok: true, status: tutorial.state };
   if (tutorial.state === "accepted" && tutorial.relayId) {
     return { ok: true, status: "already_accepted", relayId: tutorial.relayId, state: tutorial.responseState || "" };
   }
   const inviter = requiredRelayIdentity(config.inviter, "inviter");
   const key = String(tutorial.idempotencyKey || "");
   if (key.length < 8) throw new Error("Relay tutorial state is missing its stable idempotency key. Connect again.");
-  config.tutorial = { ...tutorial, state: "attempting", updatedAt: new Date().toISOString() };
-  atomicWrite(configPath(), config);
-  const body = {
+  if (draft && (typeof draft.forHuman !== "string" || !draft.forHuman.trim()
+    || typeof draft.forAgent !== "string" || !draft.forAgent.trim()
+    || Object.keys(draft).some((key) => !["forHuman", "forAgent"].includes(key)))) {
+    throw new Error("The tutorial draft must contain only the two approved, non-empty forHuman and forAgent fields.");
+  }
+  const proposed = {
     recipient: { relayUserId: inviter.relayUserId },
     kind: "message",
-    forHuman: TUTORIAL_HUMAN,
-    forAgent: TUTORIAL_AGENT,
+    forHuman: draft?.forHuman ?? TUTORIAL_HUMAN,
+    forAgent: draft?.forAgent ?? TUTORIAL_AGENT,
     idempotencyKey: key,
   };
+  if (tutorial.payload && draft && JSON.stringify(proposed) !== JSON.stringify(tutorial.payload)) {
+    throw new Error("This tutorial send was already attempted. Retry its exact approved payload; do not change it after an uncertain result.");
+  }
+  // Older attempts used the fixed hello. Preserve that payload across upgrades.
+  if (!tutorial.payload && ["attempting", "rejected"].includes(tutorial.state) && draft
+    && (draft.forHuman !== TUTORIAL_HUMAN || draft.forAgent !== TUTORIAL_AGENT)) {
+    throw new Error("Retry the original tutorial hello without changing its payload.");
+  }
+  const body = tutorial.payload || proposed;
+  config.tutorial = { ...tutorial, payload: body, recipient: body.recipient, state: "attempting", updatedAt: new Date().toISOString() };
+  atomicWrite(configPath(), config);
   try {
     const result = await request("POST", "/v1/relays", body);
     const latest = readConfig();
@@ -588,7 +602,22 @@ async function main(argv = process.argv.slice(2)) {
     const body = parseJson(await readStdin(), "Relay message");
     return sendPersisted(body);
   }
-  if (command === "tutorial-send") return sendTutorial(rest.includes("--approved"));
+  if (command === "tutorial-send") return sendTutorial(rest.includes("--approved"), rest.includes("--draft-stdin") ? parseJson(await readStdin()) : undefined);
+  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.");
+    config.tutorial = { ...config.tutorial, state: "skipped", updatedAt: new Date().toISOString() };
+    atomicWrite(configPath(), config);
+    return { ok: true, status: "skipped" };
+  }
+  if (command === "opening-preference") {
+    const [surface, provider] = rest;
+    if (!["desktop", "terminal", "other"].includes(surface) || (provider && !["claude", "codex"].includes(provider))) throw new Error("Choose desktop, terminal, or other; optionally name claude or codex.");
+    const config = readConfig();
+    config.openingPreference = { surface, ...(provider ? { provider } : {}) };
+    atomicWrite(configPath(), config);
+    return { ok: true, openingPreference: config.openingPreference };
+  }
   if (command === "request") {
     const method = String(rest.shift() || "GET").toUpperCase();
     const requestPath = String(rest.shift() || "");
@@ -609,7 +638,9 @@ async function main(argv = process.argv.slice(2)) {
       "relay-protocol contacts <name-or-email>",
       "relay-protocol read <relay-id>",
       "relay-protocol mark-read <relay-id> [idempotency-key]",
-      "relay-protocol tutorial-send --approved",
+      "relay-protocol tutorial-send --approved [--draft-stdin] # optional JSON: exact approved forHuman and forAgent",
+      "relay-protocol tutorial-skip",
+      "relay-protocol opening-preference desktop|terminal|other [claude|codex]",
       "relay-protocol send             # read body with stable idempotencyKey from stdin",
       "relay-protocol invite-link",
       "relay-protocol disconnect",
@@ -619,7 +650,7 @@ async function main(argv = process.argv.slice(2)) {
 
 export { allowed, authenticatedRequest, readConfig, configPath, atomicWrite, protectOwnerOnly };
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
 try {
   const result = await main();
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);